Make getting to a PSGI app saner

All the user should ever need to call is ->psgi_app (previously raw_psgi_app),
to get an unwrapped psgi app as provided by the engine. This is what should be
used when writing .psgi files.

For all other ways of running catalyst apps there's no need to be able to get to
the psgi application that'll actually run, so here we're making everything
that's responsible for reading .psgi files to run them with Catalyst::Script::*
or for wrapping the plain psgi code ref with back-compat middleware private.

Unfortunately this removes some of the docs about the automatic .psgi
loading. These should be added again elsewhere. Also the Upgrading docs need
updating after this.

diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm
index d70d4c4..cec982f 100644 (file)
--- a/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@ -2407,7 +2407,7 @@ Starts the engine.
 
 =cut
 
-sub run { my $c = shift; return $c->engine->run( $c, $c->psgi_app, @_ ) }
+sub run { my $c = shift; return $c->engine->run( $c, $c->_finalized_psgi_app, @_ ) }
 
 =head2 $c->set_action( $action, $code, $namespace, $attrs )
 
@@ -2619,44 +2619,18 @@ sub setup_engine {
     return;
 }
 
-=head2 $c->psgi_app
-
-Builds a PSGI application coderef for the catalyst application C<$c> using
-L</"$c->setup_psgi_app">, stores it internally, and returns it. On the next call
-to this method, C<setup_psgi_app> won't be invoked again, but its persisted
-return value of it will be returned.
-
-This is the top-level entrypoint for things that need a full blown Catalyst PSGI
-app. If you only need the raw PSGI application, without any middlewares, use
-L</"$c->raw_psgi_app"> instead.
-
-=cut
-
-sub psgi_app {
+sub _finalized_psgi_app {
     my ($app) = @_;
 
     unless ($app->_psgi_app) {
-        my $psgi_app = $app->setup_psgi_app;
+        my $psgi_app = $app->_setup_psgi_app;
         $app->_psgi_app($psgi_app);
     }
 
     return $app->_psgi_app;
 }
 
-=head2 $c->setup_psgi_app
-
-Builds a PSGI application coderef for the catalyst application C<$c>.
-
-If we're able to locate a C<${myapp}.psgi> file in the applications home
-directory, we'll use that to obtain our code reference.
-
-Otherwise the raw psgi app, without any middlewares is created using
-C<raw_psgi_app> and wrapped into L<Plack::Middleware::ReverseProxy>
-conditionally. See L</"PROXY SUPPORT">.
-
-=cut
-
-sub setup_psgi_app {
+sub _setup_psgi_app {
     my ($app) = @_;
 
     if (my $home = Path::Class::Dir->new($app->config->{home})) {
@@ -2668,12 +2642,18 @@ sub setup_psgi_app {
             if -e $psgi_file;
     }
 
-    # Note - this is for back compatibility. Catalyst should not know
-    #        or care about how it's deployed. The recommended way of
-    #        configuring this is now to use the ReverseProxy middleware
-    #        yourself if you want it in a .psgi file.
+    return $app->_wrapped_legacy_psgi_app;
+}
+
+# Note - this is for back compatibility. Catalyst should not know or care about
+#        how it's deployed. The recommended way of configuring this is now to
+#        use the ReverseProxy middleware yourself if you want it in a .psgi
+#        file.
+sub _wrapped_legacy_psgi_app {
+    my ($app) = @_;
+
     return Plack::Middleware::Conditional->wrap(
-        $app->raw_psgi_app,
+        $app->psgi_app,
         builder   => sub { Plack::Middleware::ReverseProxy->wrap($_[0]) },
         condition => sub {
             my ($env) = @_;
@@ -2684,16 +2664,18 @@ sub setup_psgi_app {
     );
 }
 
-=head2 $c->raw_psgi_app
+=head2 $c->psgi_app
 
 Returns a PSGI application code reference for the catalyst application
 C<$c>. This is the bare application without any middlewares
-applied. C<${myapp}.psgi> is not taken into account. See
-L</"$c->setup_psgi_app">.
+applied. C<${myapp}.psgi> is not taken into account.
+
+This is what you want to be using to retrieve the PSGI application code
+reference of your Catalyst application for use in F<.psgi> files.
 
 =cut
 
-sub raw_psgi_app {
+sub psgi_app {
     my ($app) = @_;
     return $app->engine->build_psgi_app($app);
 }

diff --git a/lib/Catalyst/Test.pm b/lib/Catalyst/Test.pm
index f037a0d..36d23ed 100644 (file)
--- a/lib/Catalyst/Test.pm
+++ b/lib/Catalyst/Test.pm
@@ -241,7 +241,7 @@ Simulate a request using L<HTTP::Request::AsCGI>.
 sub local_request {
     my $class = shift;
 
-    my $app = ref($class) eq "CODE" ? $class : $class->psgi_app;
+    my $app = ref($class) eq "CODE" ? $class : $class->_finalized_psgi_app;
 
     my $request = Catalyst::Utils::request(shift);
     my %extra_env;

diff --git a/t/aggregate/psgi_file.t b/t/aggregate/psgi_file.t
index c7a0e36..5b62cf2 100644 (file)
--- a/t/aggregate/psgi_file.t
+++ b/t/aggregate/psgi_file.t
@@ -16,7 +16,7 @@ use strict;
 use warnings;
 use TestApp;
 
-TestApp->raw_psgi_app;
+TestApp->psgi_app;
 };
 close($psgi);
 # Check we wrote out something that compiles
@@ -37,10 +37,10 @@ my $failed = 0;
 eval {
     # Catch infinite recursion (or anything else)
     local $SIG{__WARN__} = sub { warn(@_); $failed = 1; die; };
-    TestApp->psgi_app;
+    TestApp->_finalized_psgi_app;
 };
 ok(!$@, 'No exception')
     or diag $@;
-ok(!$failed, 'TestApp->setup_psgi_app works');
+ok(!$failed, 'TestApp->_finalized_psgi_app works');
 
 done_testing;