| 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 |
|