lib/Catalyst/Engine/FastCGI.pm

   1 package Catalyst::Engine::FastCGI;
   2
   3 use strict;
   4 use base 'Catalyst::Engine::CGI';
   5 eval "use FCGI";
   6 die "Please install FCGI\n" if $@;
   7
   8 =head1 NAME
   9
  10 Catalyst::Engine::FastCGI - FastCGI Engine
  11
  12 =head1 DESCRIPTION
  13
  14 This is the FastCGI engine.
  15
  16 =head1 OVERLOADED METHODS
  17
  18 This class overloads some methods from C<Catalyst::Engine::CGI>.
  19
  20 =head2 $self->run($c, $listen, { option => value, ... })
  21
  22 Starts the FastCGI server.  If C<$listen> is set, then it specifies a
  23 location to listen for FastCGI requests;
  24
  25   Form            Meaning
  26   /path           listen via Unix sockets on /path
  27   :port           listen via TCP on port on all interfaces
  28   hostname:port   listen via TCP on port bound to hostname
  29
  30 Options may also be specified;
  31
  32   Option          Meaning
  33   leave_umask     Set to 1 to disable setting umask to 0
  34                   for socket open
  35   nointr          Do not allow the listener to be
  36                   interrupted by Ctrl+C
  37   nproc           Specify a number of processes for
  38                   FCGI::ProcManager
  39   pidfile         Specify a filename for the pid file
  40   manager         Specify a FCGI::ProcManager sub-class
  41   detach          Detach from console
  42
  43 =cut
  44
  45 sub run {
  46     my ( $self, $class, $listen, $options ) = @_;
  47
  48     my $sock;
  49     if ($listen) {
  50         my $old_umask = umask;
  51         unless ( $options->{leave_umask} ) {
  52             umask(0);
  53         }
  54         $sock = FCGI::OpenSocket( $listen, 100 )
  55           or die "failed to open FastCGI socket; $!";
  56         unless ( $options->{leave_umask} ) {
  57             umask($old_umask);
  58         }
  59     }
  60     elsif ( $^O ne 'MSWin32' ) {
  61         -S STDIN
  62           or die "STDIN is not a socket; specify a listen location";
  63     }
  64
  65     $options ||= {};
  66
  67     my %env;
  68
  69     my $request =
  70       FCGI::Request( \*STDIN, \*STDOUT, \*STDERR, \%env, $sock,
  71         ( $options->{nointr} ? 0 : &FCGI::FAIL_ACCEPT_ON_INTR ),
  72       );
  73
  74     my $proc_manager;
  75
  76     if ($listen) {
  77         $options->{manager} ||= "FCGI::ProcManager";
  78         $options->{nproc}   ||= 1;
  79
  80         $self->daemon_fork() if $options->{detach};
  81
  82         if ( $options->{manager} ) {
  83             eval "use $options->{manager}; 1" or die $@;
  84
  85             $proc_manager = $options->{manager}->new(
  86                 {
  87                     n_processes => $options->{nproc},
  88                     pid_fname   => $options->{pidfile},
  89                 }
  90             );
  91
  92             # detach *before* the ProcManager inits
  93             $self->daemon_detach() if $options->{detach};
  94
  95             $proc_manager->pm_manage();
  96         }
  97         elsif ( $options->{detach} ) {
  98             $self->daemon_detach();
  99         }
 100     }
 101
 102     while ( $request->Accept >= 0 ) {
 103         $proc_manager && $proc_manager->pm_pre_dispatch();
 104         $class->handle_request( env => \%env );
 105         $proc_manager && $proc_manager->pm_pre_dispatch();
 106     }
 107 }
 108
 109 =head2 $self->write($c, $buffer)
 110
 111 =cut
 112
 113 sub write {
 114     my ( $self, $c, $buffer ) = @_;
 115
 116     unless ( $self->{_prepared_write} ) {
 117         $self->prepare_write($c);
 118         $self->{_prepared_write} = 1;
 119     }
 120
 121     # FastCGI does not stream data properly if using 'print $handle',
 122     # but a syswrite appears to work properly.
 123     *STDOUT->syswrite($buffer);
 124 }
 125
 126 =head2 $self->daemon_fork()
 127
 128 Performs the first part of daemon initialisation.  Specifically,
 129 forking.  STDERR, etc are still connected to a terminal.
 130
 131 =cut
 132
 133 sub daemon_fork {
 134     require POSIX;
 135     fork && exit;
 136 }
 137
 138 =head2 $self->daemon_detach( )
 139
 140 Performs the second part of daemon initialisation.  Specifically,
 141 disassociates from the terminal.
 142
 143 However, this does B<not> change the current working directory to "/",
 144 as normal daemons do.  It also does not close all open file
 145 descriptors (except STDIN, STDOUT and STDERR, which are re-opened from
 146 F</dev/null>).
 147
 148 =cut
 149
 150 sub daemon_detach {
 151     my $self = shift;
 152     print "FastCGI daemon started (pid $$)\n";
 153     open STDIN,  "+</dev/null" or die $!;
 154     open STDOUT, ">&STDIN"     or die $!;
 155     open STDERR, ">&STDIN"     or die $!;
 156     POSIX::setsid();
 157 }
 158
 159 1;
 160 __END__
 161
 162 =head1 WEB SERVER CONFIGURATIONS
 163
 164 =head2 Standalone FastCGI Server
 165
 166 In server mode the application runs as a standalone server and accepts
 167 connections from a web server.  The application can be on the same machine as
 168 the web server, on a remote machine, or even on multiple remote machines.
 169 Advantages of this method include running the Catalyst application as a
 170 different user than the web server, and the ability to set up a scalable
 171 server farm.
 172
 173 To start your application in server mode, install the FCGI::ProcManager
 174 module and then use the included fastcgi.pl script.
 175
 176     $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5
 177
 178 Command line options for fastcgi.pl include:
 179
 180     -d -daemon     Daemonize the server.
 181     -p -pidfile    Write a pidfile with the pid of the process manager.
 182     -l -listen     Listen on a socket path, hostname:port, or :port.
 183     -n -nproc      The number of processes started to handle requests.
 184
 185 See below for the specific web server configurations for using the external
 186 server.
 187
 188 =head2 Apache 1.x, 2.x
 189
 190 Apache requires the mod_fastcgi module.  The same module supports both
 191 Apache 1 and 2.
 192
 193 There are three ways to run your application under FastCGI on Apache: server,
 194 static, and dynamic.
 195
 196 =head3 Standalone server mode
 197
 198     FastCgiExternalServer /tmp/myapp -socket /tmp/myapp.socket
 199     Alias /myapp/ /tmp/myapp/
 200
 201     # Or, run at the root
 202     Alias / /tmp/myapp/
 203
 204     # Optionally, rewrite the path when accessed without a trailing slash
 205     RewriteRule ^/myapp$ myapp/ [R]
 206
 207 The FastCgiExternalServer directive tells Apache that when serving /tmp/myapp
 208 to use the FastCGI application listenting on the socket /tmp/mapp.socket.
 209 Note that /tmp/myapp does not need to exist -- it's a virtual file name.
 210
 211 It's likely that Apache is not configured to serve files in /tmp, so the
 212 Alias directive maps the url path /myapp/ to the (virtual) file that runs the
 213 FastCGI application. The trailing slashes are important as their use will
 214 correctly set the PATH_INFO environment variable used by Catalyst to
 215 determine the request path.  If you would like to be able to access your app
 216 without a trailing slash (http://server/myapp), you can use the above
 217 RewriteRule directive.
 218
 219 =head3 Static mode
 220
 221 The term 'static' is misleading, but in static mode Apache uses its own
 222 FastCGI Process Manager to start the application processes.  This happens at
 223 Apache startup time.  In this case you do not run your application's
 224 fastcgi.pl script -- that is done by Apache. Apache then maps URIs to the
 225 FastCGI script to run your application.
 226
 227     FastCgiServer /path/to/myapp/script/myapp_fastcgi.pl -processes 3
 228     Alias /myapp/ /path/to/myapp/script/myapp_fastcgi.pl/
 229
 230 FastCgiServer tells Apache to start three processes of your application at
 231 startup.  The Alias command maps a path to the FastCGI application. Again,
 232 the trailing slashes are important.
 233
 234 =head3 Dynamic mode
 235
 236 In FastCGI dynamic mode, Apache will run your application on demand,
 237 typically by requesting a file with a specific extension (e.g. .fcgi).  ISPs
 238 often use this type of setup to provide FastCGI support to many customers.
 239
 240 In this mode it is often enough to place or link your *_fastcgi.pl script in
 241 your cgi-bin directory with the extension of .fcgi.  In dynamic mode Apache
 242 must be able to run your application as a CGI script so ExecCGI must be
 243 enabled for the directory.
 244
 245     AddHandler fastcgi-script .fcgi
 246
 247 The above tells Apache to run any .fcgi file as a FastCGI application.
 248
 249 Here is a complete example:
 250
 251     <VirtualHost *:80>
 252         ServerName www.myapp.com
 253         DocumentRoot /path/to/MyApp
 254
 255         # Allow CGI script to run
 256         <Directory /path/to/MyApp>
 257             Options +ExecCGI
 258         </Directory>
 259
 260         # Tell Apache this is a FastCGI application
 261         <Files myapp_fastcgi.pl>
 262             SetHandler fastcgi-script
 263         </Files>
 264     </VirtualHost>
 265
 266 Then a request for /script/myapp_fastcgi.pl will run the
 267 application.
 268
 269 For more information on using FastCGI under Apache, visit
 270 L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html>
 271
 272 =head2 Lighttpd
 273
 274 These configurations were tested with Lighttpd 1.4.7.
 275
 276 =head3 Standalone server mode
 277
 278     server.document-root = "/var/www/MyApp/root"
 279
 280     fastcgi.server = (
 281         "" => (
 282             "MyApp" => (
 283                 "socket"      => "/tmp/myapp.socket",
 284                 "check-local" => "disable"
 285             )
 286         )
 287     )
 288
 289 =head3 Static mode
 290
 291     server.document-root = "/var/www/MyApp/root"
 292
 293     fastcgi.server = (
 294         "" => (
 295             "MyApp" => (
 296                 "socket"       => "/tmp/myapp.socket",
 297                 "check-local"  => "disable",
 298                 "bin-path"     => "/var/www/MyApp/script/myapp_fastcgi.pl",
 299                 "min-procs"    => 2,
 300                 "max-procs"    => 5,
 301                 "idle-timeout" => 20
 302             )
 303         )
 304     )
 305
 306 Note that in newer versions of lighttpd, the min-procs and idle-timeout
 307 values are disabled.  The above example would start 5 processes.
 308
 309 =head3 Non-root configuration
 310
 311 You can also run your application at any non-root location with either of the
 312 above modes.
 313
 314     fastcgi.server = (
 315         "/myapp" => (
 316             "MyApp" => (
 317                 # same as above
 318             )
 319         )
 320     )
 321
 322 For more information on using FastCGI under Lighttpd, visit
 323 L<http://www.lighttpd.net/documentation/fastcgi.html>
 324
 325 =head2 IIS
 326
 327 It is possible to run Catalyst under IIS with FastCGI, but we do not
 328 yet have detailed instructions.
 329
 330 =head1 SEE ALSO
 331
 332 L<Catalyst>, L<FCGI>.
 333
 334 =head1 AUTHORS
 335
 336 Sebastian Riedel, <sri@cpan.org>
 337
 338 Christian Hansen, <ch@ngmedia.com>
 339
 340 Andy Grundman, <andy@hybridized.org>
 341
 342 =head1 THANKS
 343
 344 Bill Moseley, for documentation updates and testing.
 345
 346 =head1 COPYRIGHT
 347
 348 This program is free software, you can redistribute it and/or modify it under
 349 the same terms as Perl itself.
 350
 351 =cut