X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst.pm;h=0e2fdbd23bae24606be1ba3f9056f36957296cbf;hp=1c7d830741343630b1f916d841488d36363b44d8;hb=35b3434762d426e0cd5e04eb735291f8ca7ea08e;hpb=dd5b1dc47018c241cafda7f2b565d6a39257a1bf diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm index 1c7d830..0e2fdbd 100644 --- a/lib/Catalyst.pm +++ b/lib/Catalyst.pm @@ -41,6 +41,7 @@ use Plack::Middleware::ReverseProxy; use Plack::Middleware::IIS6ScriptNameFix; use Plack::Middleware::IIS7KeepAliveFix; use Plack::Middleware::LighttpdScriptNameFix; +use Plack::Util; use Class::Load 'load_class'; BEGIN { require 5.008003; } @@ -63,6 +64,7 @@ sub _build_request_constructor_args { my $self = shift; my %p = ( _log => $self->log ); $p{_uploadtmp} = $self->_uploadtmp if $self->_has_uploadtmp; + $p{data_handlers} = {$self->registered_data_handlers}; \%p; } @@ -106,7 +108,8 @@ our $GO = Catalyst::Exception::Go->new; __PACKAGE__->mk_classdata($_) for qw/components arguments dispatcher engine log dispatcher_class engine_loader context_class request_class response_class stats_class - setup_finished _psgi_app loading_psgi_file run_options/; + setup_finished _psgi_app loading_psgi_file run_options _psgi_middleware + _data_handlers/; __PACKAGE__->dispatcher_class('Catalyst::Dispatcher'); __PACKAGE__->request_class('Catalyst::Request'); @@ -115,7 +118,7 @@ __PACKAGE__->stats_class('Catalyst::Stats'); # Remember to update this in Catalyst::Runtime as well! -our $VERSION = '5.90042'; +our $VERSION = '5.90049_002'; sub import { my ( $class, @arguments ) = @_; @@ -1121,6 +1124,8 @@ sub setup { $class->setup_log( delete $flags->{log} ); $class->setup_plugins( delete $flags->{plugins} ); + $class->setup_middleware(); + $class->setup_data_handlers(); $class->setup_dispatcher( delete $flags->{dispatcher} ); if (my $engine = delete $flags->{engine}) { $class->log->warn("Specifying the engine in ->setup is no longer supported, see Catalyst::Upgrading"); @@ -1162,6 +1167,27 @@ EOF $class->log->debug( "Loaded plugins:\n" . $t->draw . "\n" ); } + my @middleware = map { + ref $_ eq 'CODE' ? + "Inline Coderef" : + (ref($_) .' '. ($_->can('VERSION') ? $_->VERSION || '' : '') + || '') } $class->registered_middlewares; + + if (@middleware) { + my $column_width = Catalyst::Utils::term_width() - 6; + my $t = Text::SimpleTable->new($column_width); + $t->row($_) for @middleware; + $class->log->debug( "Loaded PSGI Middleware:\n" . $t->draw . "\n" ); + } + + my %dh = $class->registered_data_handlers; + if (my @data_handlers = keys %dh) { + my $column_width = Catalyst::Utils::term_width() - 6; + my $t = Text::SimpleTable->new($column_width); + $t->row($_) for @data_handlers; + $class->log->debug( "Loaded Request Data Handlers:\n" . $t->draw . "\n" ); + } + my $dispatcher = $class->dispatcher; my $engine = $class->engine; my $home = $class->config->{home}; @@ -2739,6 +2765,11 @@ sub setup_engine { return; } +## This exists just to supply a prebuild psgi app for mod_perl and for the +## build in server support (back compat support for pre psgi port behavior). +## This is so that we don't build a new psgi app for each request when using +## the mod_perl handler or the built in servers (http and fcgi, etc). + sub _finalized_psgi_app { my ($app) = @_; @@ -2750,6 +2781,12 @@ sub _finalized_psgi_app { return $app->_psgi_app; } +## Look for a psgi file like 'myapp_web.psgi' (if the app is MyApp::Web) in the +## home directory and load that and return it (just assume it is doing the +## right thing :) ). If that does not exist, call $app->psgi_app, wrap that +## in default_middleware and return it ( this is for backward compatibility +## with pre psgi port behavior ). + sub _setup_psgi_app { my ($app) = @_; @@ -2860,7 +2897,8 @@ reference of your Catalyst application for use in F<.psgi> files. sub psgi_app { my ($app) = @_; - return $app->engine->build_psgi_app($app); + my $psgi = $app->engine->build_psgi_app($app); + return $app->Catalyst::Utils::apply_registered_middleware($psgi); } =head2 $c->setup_home @@ -3044,6 +3082,128 @@ the plugin name does not begin with C. $class => @roles ) if @roles; } +} + +=head2 registered_middlewares + +Read only accessor that returns an array of all the middleware in the order +that they were added (which is the REVERSE of the order they will be applied). + +The values returned will be either instances of L or of a +compatible interface, or a coderef, which is assumed to be inlined middleware + +=head2 setup_middleware (?@middleware) + +Read configuration information stored in configuration key C or +from passed @args. + +See under L information regarding C and how +to use it to enable L + +This method is automatically called during 'setup' of your application, so +you really don't need to invoke it. + +When we read middleware definitions from configuration, we reverse the list +which sounds odd but is likely how you expect it to work if you have prior +experience with L or if you previously used the plugin +L (which is now considered deprecated) + +=cut + +sub registered_middlewares { + my $class = shift; + if(my $middleware = $class->_psgi_middleware) { + return @$middleware; + } else { + die "You cannot call ->registered_middlewares until middleware has been setup"; + } +} + +sub setup_middleware { + my ($class, @middleware_definitions) = @_; + push @middleware_definitions, reverse( + @{$class->config->{'psgi_middleware'}||[]}); + + my @middleware = (); + while(my $next = shift(@middleware_definitions)) { + if(ref $next) { + if(Scalar::Util::blessed $next && $next->can('wrap')) { + push @middleware, $next; + } elsif(ref $next eq 'CODE') { + push @middleware, $next; + } elsif(ref $next eq 'HASH') { + my $namespace = shift @middleware_definitions; + my $mw = $class->Catalyst::Utils::build_middleware($namespace, %$next); + push @middleware, $mw; + } else { + die "I can't handle middleware definition ${\ref $next}"; + } + } else { + my $mw = $class->Catalyst::Utils::build_middleware($next); + push @middleware, $mw; + } + } + + $class->_psgi_middleware(\@middleware); +} + +=head2 registered_data_handlers + +A read only copy of registered Data Handlers returned as a Hash, where each key +is a content type and each value is a subref that attempts to decode that content +type. + +=head2 setup_data_handlers (?@data_handler) + +Read configuration information stored in configuration key C or +from passed @args. + +See under L information regarding C. + +This method is automatically called during 'setup' of your application, so +you really don't need to invoke it. + +=head2 default_data_handlers + +Default Data Handler that come bundled with L. Currently there is +only one default data handler, for 'application/json'. This uses L +which uses the dependency free L OR L if you have +installed it. If you don't mind the XS dependency, you should add the faster +L to you dependency list (in your Makefile.PL or dist.ini, or +cpanfile, etc.) + +L is loaded the first time you ask for it (so if you never ask +for it, its never used). + +=cut + +sub registered_data_handlers { + my $class = shift; + if(my $data_handlers = $class->_data_handlers) { + return %$data_handlers; + } else { + die "You cannot call ->registered_data_handlers until data_handers has been setup"; + } +} + +sub setup_data_handlers { + my ($class, %data_handler_callbacks) = @_; + %data_handler_callbacks = ( + %{$class->default_data_handlers}, + %{$class->config->{'data_handlers'}||+{}}, + %data_handler_callbacks); + + $class->_data_handlers(\%data_handler_callbacks); +} + +sub default_data_handlers { + my ($class) = @_; + return +{ + 'application/json' => sub { + local $/; + Class::Load::load_class("JSON::MaybeXS"); + JSON::MaybeXS::decode_json $_->getline }, + }; } =head2 $c->stack @@ -3233,6 +3393,14 @@ use like: In the future this might become the default behavior. +=item * + +C - See L. + +=item * + +C - See L. + =back =head1 INTERNAL ACTIONS @@ -3324,6 +3492,171 @@ If you plan to operate in a threaded environment, remember that all other modules you are using must also be thread-safe. Some modules, most notably L, are not thread-safe. +=head1 DATA HANDLERS + +The L object uses L to populate 'classic' HTML +form parameters and URL search query fields. However it has become common +for various alternative content types to be PUT or POSTed to your controllers +and actions. People working on RESTful APIs, or using AJAX often use JSON, +XML and other content types when communicating with an application server. In +order to better support this use case, L defines a global configuration +option, C, which lets you associate a content type with a coderef +that parses that content type into something Perl can readily access. + + package MyApp::Web; + + use Catalyst; + use JSON::Maybe; + + __PACKAGE__->config( + data_handlers => { + 'application/json' => sub { local $/; decode_json $_->getline }, + }, + ## Any other configuration. + ); + + __PACKAGE__->setup; + +By default L comes with a generic JSON data handler similar to the +example given above, which uses L to provide either L +(a pure Perl, dependency free JSON parser) or L if you have +it installed (if you want the faster XS parser, add it to you project Makefile.PL +or dist.ini, cpanfile, etc.) + +The C configuation is a hashref whose keys are HTTP Content-Types +(matched against the incoming request type using a regexp such as to be case +insensitive) and whose values are coderefs that receive a localized version of +C<$_> which is a filehandle object pointing to received body. + +This feature is considered an early access release and we reserve the right +to alter the interface in order to provide a performant and secure solution to +alternative request body content. Your reports welcomed! + +=head1 PSGI MIDDLEWARE + +You can define middleware, defined as L or a compatible +interface in configuration. Your middleware definitions are in the form of an +arrayref under the configuration key C. Here's an example +with details to follow: + + package MyApp::Web; + + use Catalyst; + use Plack::Middleware::StackTrace; + + my $stacktrace_middleware = Plack::Middleware::StackTrace->new; + + __PACKAGE__->config( + 'psgi_middleware', [ + 'Debug', + '+MyApp::Custom', + $stacktrace_middleware, + 'Session' => {store => 'File'}, + sub { + my $app = shift; + return sub { + my $env = shift; + $env->{myapp.customkey} = 'helloworld'; + $app->($env); + }, + }, + ], + ); + + __PACKAGE__->setup; + +So the general form is: + + __PACKAGE__->config(psgi_middleware => \@middleware_definitions); + +Where C<@middleware> is one or more of the following, applied in the REVERSE of +the order listed (to make it function similarly to L: + +=over 4 + +=item Middleware Object + +An already initialized object that conforms to the L +specification: + + my $stacktrace_middleware = Plack::Middleware::StackTrace->new; + + __PACKAGE__->config( + 'psgi_middleware', [ + $stacktrace_middleware, + ]); + + +=item coderef + +A coderef that is an inlined middleware: + + __PACKAGE__->config( + 'psgi_middleware', [ + sub { + my $app = shift; + return sub { + my $env = shift; + if($env->{PATH_INFO} =~m/forced/) { + Plack::App::File + ->new(file=>TestApp->path_to(qw/share static forced.txt/)) + ->call($env); + } else { + return $app->($env); + } + }, + }, + ]); + + + +=item a scalar + +We assume the scalar refers to a namespace after normalizing it using the +following rules: + +(1) If the scalar is prefixed with a "+" (as in C<+MyApp::Foo>) then the full string +is assumed to be 'as is', and we just install and use the middleware. + +(2) If the scalar begins with "Plack::Middleware" or your application namespace +(the package name of your Catalyst application subclass), we also assume then +that it is a full namespace, and use it. + +(3) Lastly, we then assume that the scalar is a partial namespace, and attempt to +resolve it first by looking for it under your application namespace (for example +if you application is "MyApp::Web" and the scalar is "MyMiddleware", we'd look +under "MyApp::Web::Middleware::MyMiddleware") and if we don't find it there, we +will then look under the regular L namespace (i.e. for the +previous we'd try "Plack::Middleware::MyMiddleware"). We look under your application +namespace first to let you 'override' common L locally, should +you find that a good idea. + +Examples: + + package MyApp::Web; + + __PACKAGE__->config( + 'psgi_middleware', [ + 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap + 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap + '+MyApp::Custom', ## MyApp::Custom->wrap + ], + ); + +=item a scalar followed by a hashref + +Just like the previous, except the following C is used as arguments +to initialize the middleware object. + + __PACKAGE__->config( + 'psgi_middleware', [ + 'Session' => {store => 'File'}, + ]); + +=back + +Please see L for more on middleware. + =head1 ENCODING On request, decodes all params from encoding into a sequence of