Debian Codegraph @

README

raw
1 NAME
2
3 FCGI::EV - Implement FastCGI protocol for use in EV-based applications
4
5 VERSION
6
7 This document describes FCGI::EV version v2.0.1
8
9 SYNOPSIS
10
11 use FCGI::EV;
12 use Some::FCGI::EV::Handler;
13
14 # while in EV::loop, accept incoming connection from web server into
15 # $sock, then start handling FastCGI protocol on that connection,
16 # using Some::FCGI::EV::Handler for processing CGI requests:
17 FCGI::EV->new($sock, 'Some::FCGI::EV::Handler');
18
19
20 #
21 # EXAMPLE: complete FastCGI server (without error handling code)
22 # use FCGI::EV::Std handler (download separately from CPAN)
23 #
24
25 use Socket;
26 use Fcntl;
27 use EV;
28 use FCGI::EV;
29 use FCGI::EV::Std;
30
31 my $path = '/tmp/fastcgi.sock';
32
33 socket my $srvsock, AF_UNIX, SOCK_STREAM, 0;
34 unlink $path;
35 my $umask = umask 0; # ensure 0777 perms for unix socket
36 bind $srvsock, sockaddr_un($path);
37 umask $umask;
38 listen $srvsock, SOMAXCONN;
39 fcntl $srvsock, F_SETFL, O_NONBLOCK;
40
41 my $w = EV::io $srvsock, EV::READ, sub {
42 accept my($sock), $srvsock;
43 fcntl $sock, F_SETFL, O_NONBLOCK;
44 FCGI::EV->new($sock, 'FCGI::EV::Std');
45 };
46
47 EV::loop;
48
49 DESCRIPTION
50
51 This module implement FastCGI protocol for use in EV-based
52 applications. (That mean you have to run EV::loop in your application
53 or this module will not work.)
54
55 It receive and parse data from web server, pack and send data to web
56 server, but it doesn't process CGI requests received from web server -
57 instead it delegate this work to another module called 'handler'. For
58 one example of such handler, see FCGI::EV::Std.
59
60 FCGI::EV work using non-blocking sockets and initially was designed to
61 use in event-based CGI applications (which able to handle multiple
62 parallel CGI requests in single process without threads/fork). This
63 require from CGI to avoid any operations which may block, like using
64 SQL database - instead CGI should delegate all such tasks to remote
65 services and talk to these services in non-blocking mode.
66
67 It also possible to use it to run usual CGI.pm-based applications. If
68 you will do this using FCGI::EV::Std handler, then only one CGI request
69 will be executed at a time (which is probably not what you expect from
70 FastCGI!), because FCGI::EV::Std doesn't implement any process-manager.
71 But it's possible to develop another handlers for FCGI::EV, which will
72 support process-management and so will handle multiple CGI request in
73 parallel.
74
75 This module doesn't require from user to use CGI.pm - any module for
76 parsing CGI params can be used in general (details depends on used
77 FCGI::EV handler module).
78
79 INTERFACE
80
81 new
82
83 FCGI::EV->new( $sock, $class );
84
85 Start talking FastCGI protocol on $sock (which should be socket open to
86 just-connected web server), and use $class to handle received CGI
87 requests.
88
89 Module $class should implement "FCGI::EV handler" interface. You can
90 use either FCGI::EV::Std from CPAN or develop your own.
91
92 Return nothing. (Created FCGI::EV object will work in background and
93 will be automatically destroyed after finishing I/O with web server.)
94
95 HANDLER CLASS INTERFACE
96
97 Handler class (which name provided in $class parameter to
98 FCGI::EV->new()) must implement this interface:
99
100 new( $server, \%env )
101
102 When FCGI::EV object receive initial part of CGI request (environment
103 variables) it will call $handler_class->new() to create handler
104 object which should process that CGI request.
105
106 Parameter $server is FCGI::EV object itself. It's required to send
107 CGI reply. WARNING! Handler may keep only weaken() reference to
108 $server!
109
110 After calling new() FCGI::EV object ($server) will continue receiving
111 STDIN content from web server and will call $handler->stdin() each
112 time it get next part of STDIN.
113
114 stdin( $data, $is_eof )
115
116 The $data is next chunk of STDIN received from web server. Flag
117 $is_eof will be true if $data was last part of STDIN.
118
119 Usually handler shouldn't begin processing CGI request until all
120 content of STDIN will be received.
121
122 DESTROY
123
124 This method is optional. It will be called when connection to web
125 server is closed and FCGI::EV object going to die (but it's still
126 exists when DESTROY is called - except if DESTROY was called while
127 global destruction stage).
128
129 Handler object may use DESTROY to interrupt current CGI request if
130 web server close connection before CGI send it reply.
131
132 SENDING CGI REPLY
133
134 After handler got %env (in new()) and complete STDIN (in one or more
135 calls of stdin()) it may start handling this CGI request and prepare
136 reply to send to web server. To send this data it should use method
137 $server->stdout(), where $server is object given to new() while
138 creating handler object (it should keep weak reference to $server
139 inside to be able to reply).
140
141 stdout( $data, $is_eof )
142
143 CGI may send reply in one or more parts. Last part should have
144 $is_eof set to true. DESTROY method of handler object will be called
145 shortly after handler object will do $server->stdout( $data, 1 ).
146
147 HANDLER EXAMPLE
148
149 This handler will process CGI requests one-by-one (i.e. in blocking
150 mode). On request function main::main() will be executed. That function
151 may use standard CGI.pm module to get request parameters and send it
152 reply using usual print to STDOUT.
153
154 There no error-handling code in this example, see FCGI::EV::Std for
155 more details.
156
157 package FCGI::EV::ExampleHandler;
158
159 use Scalar::Util qw( weaken );
160 use CGI::Stateless; # needed to re-init CGI.pm state between requests
161
162 sub new {
163 my ($class, $server, $env) = @_;
164 my $self = bless {
165 server => $server,
166 env => $env,
167 stdin => q{},
168 }, $class;
169 weaken($self->{server});
170 return $self;
171 }
172
173 sub stdin {
174 my ($self, $stdin, $is_eof) = @_;
175 $self->{stdin} .= $stdin;
176 if ($is_eof) {
177 local *STDIN;
178 open STDIN, '<', \$self->{stdin};
179 local %ENV = %{ $self->{env} };
180 local $CGI::Q = CGI::Stateless->new();
181 local *STDOUT;
182 my $reply = q{};
183 open STDOUT, '>', \$reply;
184 main::main();
185 $self->{server}->stdout($reply, 1);
186 }
187 return;
188 }
189
190 DIAGNOSTICS
191
192 There no errors returned in any way by this module, but there few
193 warning messages may be printed:
194
195 FCGI::EV: IO: %s
196
197 While doing I/O with web server error %s happened and connection was
198 closed.
199
200 FCGI::EV: %s
201
202 While parsing data from web server error %s happened and connection
203 was closed. (That error probably mean bug either in web server or
204 this module.)
205
206 SUPPORT
207
208 Bugs / Feature Requests
209
210 Please report any bugs or feature requests through the issue tracker at
211 https://github.com/powerman/perl-FCGI-EV/issues. You will be notified
212 automatically of any progress on your issue.
213
214 Source Code
215
216 This is open source software. The code repository is available for
217 public review and contribution under the terms of the license. Feel
218 free to fork the repository and submit pull requests.
219
220 https://github.com/powerman/perl-FCGI-EV
221
222 git clone https://github.com/powerman/perl-FCGI-EV.git
223
224 Resources
225
226 * MetaCPAN Search
227
228 https://metacpan.org/search?q=FCGI-EV
229
230 * CPAN Ratings
231
232 http://cpanratings.perl.org/dist/FCGI-EV
233
234 * AnnoCPAN: Annotated CPAN documentation
235
236 http://annocpan.org/dist/FCGI-EV
237
238 * CPAN Testers Matrix
239
240 http://matrix.cpantesters.org/?dist=FCGI-EV
241
242 * CPANTS: A CPAN Testing Service (Kwalitee)
243
244 http://cpants.cpanauthors.org/dist/FCGI-EV
245
246 AUTHOR
247
248 Alex Efros <[email protected]>
249
250 COPYRIGHT AND LICENSE
251
252 This software is Copyright (c) 2009- by Alex Efros <[email protected]>.
253
254 This is free software, licensed under:
255
256 The MIT (X11) License
257