Index: FastCGI.pm
===================================================================
--- FastCGI.pm	(revision 4931)
+++ FastCGI.pm	(working copy)
@@ -327,6 +327,148 @@
 It is possible to run Catalyst under IIS with FastCGI, but we do not
 yet have detailed instructions.
 
+=head1 FASTCGI PATH PROBLEMS (AND SOLUTIONS)
+
+=head Overview
+
+There appears to be a problem with the way that FastCGI passes some of the
+required environment variables to the application.  This may (depending on
+your configuration) manifest itself in any of the following ways:
+
+=over 4
+
+=item *
+
+URLs that end with a / being incorrectly handled by the Root index action.
+
+=item *
+
+C<< $c->request->arguments >>, C<< $c->request->path >>, and C<< $c->request->base >> having incorrect values.  Generally in this case what you see is where
+you should have had:
+
+  $c->request->base      /
+  $c->request->path      foo/bar/
+  $c->request->arguments [ "foo", "bar" ]
+
+You instead end up with:
+
+  $c->request->base      /foo
+  $c->request->path      bar/
+  $c->request->arguments [ "bar" ]
+
+=item *
+
+Paths being handled differently under L<Catalyst::Engine::FastCGI> than they
+are under L<Catalyst::Engine::HTTP>.
+
+=back
+
+=head2 Explanation
+
+This appears to be caused by the way that FastCGI sets up some of the
+environment variables that are used to determine the base URL for the
+application (primarily C<$SCRIPT_NAME> and C<$PATH_INFO>.)  This is also
+very difficult to fix in the Engine itself because there are no other
+(programmatic) ways to determine some of the information that is needed to
+setup these variables, without some severe ugliness involving letting
+Catalyst read and parse your web server configuration files.
+
+More information on the problem can be found at:
+
+=over 4
+
+=item L<http://lists.rawmode.org/pipermail/catalyst/2006-June/008361.html>
+
+=item L<http://lists.rawmode.org/pipermail/catalyst/2006-August/009413.html>
+
+=item L<http://trac.lighttpd.net/trac/ticket/448>
+
+=item L<http://trac.lighttpd.net/trac/ticket/729>
+
+=item L<http://bugs.php.net/bug.php?id=19656>
+
+=back
+
+=head2 Solutions
+
+=head3 Lighttpd and FastCGI
+
+Mark Blythe contributed this plugin which addresses the problem when using
+FastCGI under Lighttpd:
+
+  package Catalyst::Plugin::Lighttpd;
+  use strict;
+  
+  sub handle_request {
+    my ($class, %args) = @_;
+  
+    if (exists $args{env}) {
+      # lighttpd seems to report these backward
+      $args{env}{PATH_INFO} ||= delete $args{env}{SCRIPT_NAME};
+    }
+  
+    $class->NEXT::handle_request(%args);
+  }
+  
+  1;
+  
+  =head1 NAME
+  
+  Catalyst::Plugin::Lighttpd - Fix Lighttpd path info
+  
+  =head1 SYNOPSIS
+  
+    use Catalyst qw(Lighttpd);
+  
+  =head1 DESCRIPTION
+  
+  Lighttpd seems to report PATH_INFO and SCRIPT_NAME differently than
+  Apache and most other web servers.  This causes Catalyst to always
+  route URLs with trailing slashes to the application's default action.
+  
+  This plugin will fix that.
+
+=head3 Apache and mod_fastcgi
+
+The problem seems a little more complex under Apache, but it can be addressed
+by subclassing L<Catalyst::Engine::FastCGI>, as reported by Jason Kohles:
+
+  package Catalyst::Engine::RootFastCGI;
+  use base qw( Catalyst::Engine::FastCGI );
+  use strict;
+  use warnings;
+  use NEXT;
+
+  sub prepare_request {
+    my ( $self, $c, %args ) = @_;
+  
+    $self->NEXT::prepare_request( $c, %args );
+    my $env = $self->env;
+    my $name = $env->{ 'SCRIPT_NAME' };
+  
+    $env->{ 'SCRIPT_FILENAME' } =~ s/$name$//;
+    $env->{ 'PATH_INFO' } = $name.$env->{ 'PATH_INFO' };
+    $env->{ 'PATH_TRANSLATED' } = $env->{ 'SCRIPT_FILENAME' }.
+      $env->{ 'PATH_INFO' };
+    $env->{ 'SCRIPT_NAME' } = '/';
+  }
+
+  =head1 NAME
+  
+  Catalyst::Engine::RootFastCGI - Fix mod_fastcgi problem when run at /
+  
+  =head1 DESCRIPTION
+  
+  This subclass of L<Catalyst::Engine::FastCGI> works around a
+  problem with mod_fastcgi that occurs when your application is run
+  from the root of the url, rather than a subdirectory.  To use it
+  either set the C<$CATALYST_ENGINE> environment variable to
+  'RootFastCGI' before starting the fastcgi server, or modify
+  myapp-fastcgi.pl to use RootFastCGI.
+  
+  This may work for applications not running at the root, but you
+  will have to adjust the value that it sets C<$SCRIPT_NAME> to.
+
 =head1 SEE ALSO
 
 L<Catalyst>, L<FCGI>.