lib/Catalyst/Engine/FastCGI.pm

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