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 =over 4
  21
  22 =item $self->run($c, $listen, { option => value, ... })
  23
  24 Starts the FastCGI server.  If C<$listen> is set, then it specifies a
  25 location to listen for FastCGI requests;
  26
  27   Form            Meaning
  28   /path           listen via Unix sockets on /path
  29   :port           listen via TCP on port on all interfaces
  30   hostname:port   listen via TCP on port bound to hostname
  31
  32 Options may also be specified;
  33
  34   Option          Meaning
  35   leave_umask     Set to 1 to disable setting umask to 0
  36                   for socket open
  37   nointr          Do not allow the listener to be
  38                   interrupted by Ctrl+C
  39   nproc           Specify a number of processes for
  40                   FCGI::ProcManager
  41   pidfile         Specify a filename for the pid file
  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     else {
  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         require FCGI::ProcManager;
  78         $options->{nproc} ||= 1;
  79
  80         $proc_manager =
  81           FCGI::ProcManager->new( { n_processes => $options->{nproc} } );
  82
  83         if ( $options->{pidfile} ) {
  84             $proc_manager->pm_write_pid_file( $options->{pidfile} );
  85         }
  86
  87         $proc_manager->pm_manage();
  88     }
  89
  90     while ( $request->Accept >= 0 ) {
  91         $proc_manager && $proc_manager->pm_pre_dispatch();
  92         $class->handle_request( env => \%env );
  93         $proc_manager && $proc_manager->pm_pre_dispatch();
  94     }
  95 }
  96
  97 =item $self->write($c, $buffer)
  98
  99 =cut
 100
 101 sub write {
 102     my ( $self, $c, $buffer ) = @_;
 103
 104     unless ( $self->{_prepared_write} ) {
 105         $self->prepare_write($c);
 106         $self->{_prepared_write} = 1;
 107     }
 108
 109     # FastCGI does not stream data properly if using 'print $handle',
 110     # but a syswrite appears to work properly.
 111     *STDOUT->syswrite($buffer);
 112 }
 113
 114 1;
 115 __END__
 116
 117 =back
 118
 119 =head1 WEB SERVER CONFIGURATIONS
 120
 121 =head2 Apache 1.x, 2.x
 122
 123 Apache requires the mod_fastcgi module.  The following config will let Apache
 124 control the running of your FastCGI processes.
 125
 126     # Launch the FastCGI processes
 127     FastCgiIpcDir /tmp
 128     FastCgiServer /var/www/MyApp/script/myapp_fastcgi.pl -idle-timeout 300 -processes 5
 129
 130     <VirtualHost *>
 131         ScriptAlias / /var/www/MyApp/script/myapp_fastcgi.pl/
 132     </VirtualHost>
 133
 134 You can also tell Apache to connect to an external FastCGI server:
 135
 136     # Start the external server (requires FCGI::ProcManager)
 137     $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5
 138
 139     # Note that the path used in FastCgiExternalServer can be any path
 140     FastCgiIpcDir /tmp
 141     FastCgiExternalServer /tmp/myapp_fastcgi.pl -socket /tmp/myapp.socket
 142
 143     <VirtualHost *>
 144         ScriptAlias / /tmp/myapp_fastcgi.pl/
 145     </VirtualHost>
 146
 147 For more information on using FastCGI under Apache, visit
 148 L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html>
 149
 150 =head2 Lighttpd
 151
 152 This configuration was tested with Lighttpd 1.4.7.
 153
 154     server.document-root = "/var/www/MyApp/root"
 155
 156     fastcgi.server = (
 157         "" => (
 158             "MyApp" => (
 159                 "socket"       => "/tmp/myapp.socket",
 160                 "check-local"  => "disable",
 161                 "bin-path"     => "/var/www/MyApp/script/myapp_fastcgi.pl",
 162                 "min-procs"    => 2,
 163                 "max-procs"    => 5,
 164                 "idle-timeout" => 20
 165             )
 166         )
 167     )
 168
 169 You can also run your application at any non-root location.
 170
 171     fastcgi.server = (
 172         "/myapp" => (
 173             "MyApp" => (
 174                 # same as above
 175             )
 176         )
 177     )
 178
 179 You can also use an external server:
 180
 181     # Start the external server (requires FCGI::ProcManager)
 182     $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5
 183
 184     server.document-root = "/var/www/MyApp/root"
 185
 186     fastcgi.server = (
 187         "" => (
 188             "MyApp" => (
 189                 "socket"      => "/tmp/myapp.socket",
 190                 "check-local" => "disable"
 191             )
 192         )
 193     )
 194
 195 For more information on using FastCGI under Lighttpd, visit
 196 L<http://www.lighttpd.net/documentation/fastcgi.html>
 197
 198 =head2 IIS
 199
 200 It is possible to run Catalyst under IIS with FastCGI, but we do not
 201 yet have detailed instructions.
 202
 203 =head1 SEE ALSO
 204
 205 L<Catalyst>, L<FCGI>.
 206
 207 =head1 AUTHORS
 208
 209 Sebastian Riedel, <sri@cpan.org>
 210
 211 Christian Hansen, <ch@ngmedia.com>
 212
 213 Andy Grundman, <andy@hybridized.org>
 214
 215 =head1 COPYRIGHT
 216
 217 This program is free software, you can redistribute it and/or modify it under
 218 the same terms as Perl itself.
 219
 220 =cut