Clarify psgi proxy behaviour in PROXY SUPPORT

diff --git a/Changes b/Changes
index f369bde..da9054f 100644 (file)
--- a/Changes
+++ b/Changes
@@ -6,6 +6,12 @@
      application authors to add custom options to their scripts then
      get them passed through to the application.
 
+  Doumentation:
+   - Clarify that if you manually write your own .psgi file, then optional
+     proxy support (via the using_frontend_proxy config value) will not be
+     enabled unless you explicitly apply the default middlewares from
+     Catalyst, or you apply the middleware manually.
+
   Bug fixes:
    - Add '1;' to all classes which were relying on the ->make_immutable
      call to return a true value. Due to perl internals bugs in 5.8 and

diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index ed77ef8..f69afe0 100644 (file)
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -3157,7 +3157,26 @@ headers.
 
 If you do not wish to use the proxy support at all, you may set:
 
-    MyApp->config(ignore_frontend_proxy => 1);
+    MyApp->config(ignore_frontend_proxy => 0);
+
+=head2 Note about psgi files
+
+Note that if you supply your own .psgi file, calling
+C<< MyApp->psgi_app(@_); >>, then B<this will not happen automatically>.
+
+You either need to apply L<Plack::Middleware::ReverseProxy> yourself
+in your psgi, for example:
+
+    builder {
+        enable "Plack::Middleware::ReverseProxy";
+        MyApp->psgi_app
+    };
+
+This will unconditionally add the ReverseProxy support, or you need to call
+C<< $app = MyApp->apply_default_middlewares($app) >> (to conditionally
+apply the support depending upon your config).
+
+See L<Catalyst::PSGI> for more information.
 
 =head1 THREAD SAFETY
 

diff --git a/lib/Catalyst/PSGI.pod b/lib/Catalyst/PSGI.pod
index bdd2ae9..a05e002 100644 (file)
--- a/lib/Catalyst/PSGI.pod
+++ b/lib/Catalyst/PSGI.pod
@@ -74,8 +74,6 @@ in:
 
 =item L<Plack::Middleware::IIS6ScriptNameFix>
 
-=item nginx - local to Catalyst
-
 =back
 
 If you override the default by providing your own C<< .psgi >> file,
@@ -88,6 +86,15 @@ An apply_default_middlewares method is supplied to wrap your application
 in the default middlewares if you want this behaviour and you are providing
 your own .psgi file.
 
+This means that the auto-generated (no .psgi file) code looks something
+like this:
+
+    use strict;
+    use warnings;
+    use TestApp;
+
+    my $app = TestApp->apply_default_middlewares(TestApp->psgi_app(@_));
+
 =head1 SEE ALSO
 
 L<Catalyst::Upgrading>, L<Plack>, L<PSGI::FAQ>, L<PSGI>.