X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst.pm;h=1eb3821e28a2aca260f06fbcc305bea92276f989;hp=310eafe6e5eef3255ce25c9db847dd33faeb27b8;hb=7cd7116d8f47d62b1e6d6d13b2a06c05cb644ae6;hpb=707988f842f6f62769eb5451b9c450ec8af48433 diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm old mode 100644 new mode 100755 index 310eafe..1eb3821 --- a/lib/Catalyst.pm +++ b/lib/Catalyst.pm @@ -41,13 +41,19 @@ use Plack::Middleware::ReverseProxy; use Plack::Middleware::IIS6ScriptNameFix; use Plack::Middleware::IIS7KeepAliveFix; use Plack::Middleware::LighttpdScriptNameFix; +use Plack::Middleware::ContentLength; +use Plack::Middleware::Head; +use Plack::Middleware::HTTPExceptions; +use Plack::Middleware::FixMissingBodyInRedirect; +use Plack::Middleware::MethodOverride; +use Plack::Middleware::RemoveRedundantBody; +use Catalyst::Middleware::Stash; use Plack::Util; use Class::Load 'load_class'; BEGIN { require 5.008003; } has stack => (is => 'ro', default => sub { [] }); -has stash => (is => 'rw', default => sub { {} }); has state => (is => 'rw', default => 0); has stats => (is => 'rw'); has action => (is => 'rw'); @@ -111,7 +117,7 @@ __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 _psgi_middleware - _data_handlers/; + _data_handlers trace_level trace_logger/; __PACKAGE__->dispatcher_class('Catalyst::Dispatcher'); __PACKAGE__->request_class('Catalyst::Request'); @@ -120,7 +126,7 @@ __PACKAGE__->stats_class('Catalyst::Stats'); # Remember to update this in Catalyst::Runtime as well! -our $VERSION = '5.90051'; +our $VERSION = '5.90069_002'; sub import { my ( $class, @arguments ) = @_; @@ -490,21 +496,18 @@ Catalyst). =cut -around stash => sub { - my $orig = shift; - my $c = shift; - my $stash = $orig->($c); - if (@_) { - my $new_stash = @_ > 1 ? {@_} : $_[0]; - croak('stash takes a hash or hashref') unless ref $new_stash; - foreach my $key ( keys %$new_stash ) { - $stash->{$key} = $new_stash->{$key}; - } +sub stash { + my $c = shift; + my $stash = Catalyst::Middleware::Stash->get($c->req->env); + if(@_) { + my $new_stash = @_ > 1 ? {@_} : $_[0]; + croak('stash takes a hash or hashref') unless ref $new_stash; + foreach my $key ( keys %$new_stash ) { + $stash->{$key} = $new_stash->{$key}; } - - return $stash; -}; - + } + return $stash; +} =head2 $c->error @@ -558,6 +561,14 @@ sub clear_errors { $c->error(0); } +=head2 $c->has_errors + +Returns true if you have errors + +=cut + +sub has_errors { scalar(@{shift->error}) ? 1:0 } + sub _comp_search_prefixes { my $c = shift; return map $c->components->{ $_ }, $c->_comp_names_search_prefixes(@_); @@ -1126,7 +1137,8 @@ sub setup { $class->setup_log( delete $flags->{log} ); $class->setup_plugins( delete $flags->{plugins} ); - $class->setup_middleware(); + $class->setup_trace(); + $class->setup_data_handlers(); $class->setup_dispatcher( delete $flags->{dispatcher} ); if (my $engine = delete $flags->{engine}) { @@ -1159,6 +1171,21 @@ You are running an old script! EOF } + # Call plugins setup, this is stupid and evil. + # Also screws C3 badly on 5.10, hack to avoid. + { + no warnings qw/redefine/; + local *setup = sub { }; + $class->setup unless $Catalyst::__AM_RESTARTING; + } + + $class->setup_middleware(); + + # Initialize our data structure + $class->components( {} ); + + $class->setup_components; + if ( $class->debug ) { my @plugins = map { "$_ " . ( $_->VERSION || '' ) } $class->registered_plugins; @@ -1202,22 +1229,7 @@ EOF ? $class->log->debug(qq/Found home "$home"/) : $class->log->debug(qq/Home "$home" doesn't exist/) : $class->log->debug(q/Couldn't find home/); - } - - # Call plugins setup, this is stupid and evil. - # Also screws C3 badly on 5.10, hack to avoid. - { - no warnings qw/redefine/; - local *setup = sub { }; - $class->setup unless $Catalyst::__AM_RESTARTING; - } - # Initialize our data structure - $class->components( {} ); - - $class->setup_components; - - if ( $class->debug ) { my $column_width = Catalyst::Utils::term_width() - 8 - 9; my $t = Text::SimpleTable->new( [ $column_width, 'Class' ], [ 8, 'Type' ] ); for my $comp ( sort keys %{ $class->components } ) { @@ -1246,10 +1258,11 @@ EOF } $class->setup_finalize; - # Should be the last thing we do so that user things hooking - # setup_finalize can log.. + + # Flush the log for good measure (in case something turned off 'autoflush' early) $class->log->_flush() if $class->log->can('_flush'); - return 1; # Explicit return true as people have __PACKAGE__->setup as the last thing in their class. HATE. + + return $class || 1; # Just in case someone named their Application 0... } =head2 $app->setup_finalize @@ -1732,6 +1745,16 @@ sub execute { my $last = pop( @{ $c->stack } ); if ( my $error = $@ ) { + #rethow if this can be handled by middleware + if(blessed $error && ($error->can('as_psgi') || $error->can('code'))) { + foreach my $err (@{$c->error}) { + $c->log->error($err); + } + $c->clear_errors; + $c->log->_flush if $c->log->can('_flush'); + + $error->can('rethrow') ? $error->rethrow : croak $error; + } if ( blessed($error) and $error->isa('Catalyst::Exception::Detach') ) { $error->rethrow if $c->depth > 1; } @@ -1858,11 +1881,6 @@ sub finalize { $c->finalize_headers unless $c->response->finalized_headers; - # HEAD request - if ( $c->request->method eq 'HEAD' ) { - $c->response->body(''); - } - $c->finalize_body; } @@ -1896,11 +1914,31 @@ sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) } =head2 $c->finalize_error -Finalizes error. +Finalizes error. If there is only one error in L and it is an object that +does C or C we rethrow the error and presume it caught by middleware +up the ladder. Otherwise we return the debugging error page (in debug mode) or we +return the default error page (production mode). =cut -sub finalize_error { my $c = shift; $c->engine->finalize_error( $c, @_ ) } +sub finalize_error { + my $c = shift; + if($#{$c->error} > 0) { + $c->engine->finalize_error( $c, @_ ); + } else { + my ($error) = @{$c->error}; + if( + blessed $error && + ($error->can('as_psgi') || $error->can('code')) + ) { + # In the case where the error 'knows what it wants', becauses its PSGI + # aware, just rethow and let middleware catch it + $error->can('rethrow') ? $error->rethrow : croak $error; + } else { + $c->engine->finalize_error( $c, @_ ) + } + } +} =head2 $c->finalize_headers @@ -1920,50 +1958,10 @@ sub finalize_headers { if ( my $location = $response->redirect ) { $c->log->debug(qq/Redirecting to "$location"/) if $c->debug; $response->header( Location => $location ); - - if ( !$response->has_body ) { - # Add a default body if none is already present - my $encoded_location = encode_entities($location); - $response->body(<<"EOF"); - - - - Moved - - -

This item has moved here.

- - -EOF - $response->content_type('text/html; charset=utf-8'); - } } - # Content-Length - if ( defined $response->body && length $response->body && !$response->content_length ) { - - # get the length from a filehandle - if ( blessed( $response->body ) && $response->body->can('read') || ref( $response->body ) eq 'GLOB' ) - { - my $size = -s $response->body; - if ( $size ) { - $response->content_length( $size ); - } - else { - $c->log->warn('Serving filehandle without a content-length'); - } - } - else { - # everything should be bytes at this point, but just in case - $response->content_length( length( $response->body ) ); - } - } - - # Errors - if ( $response->status =~ /^(1\d\d|[23]04)$/ ) { - $response->headers->remove_header("Content-Length"); - $response->body(''); - } + # Remove incorrectly added body and content related meta data when returning + # an information response, or a response the is required to not include a body $c->finalize_cookies; @@ -2032,8 +2030,11 @@ sub handle_request { my $c = $class->prepare(@arguments); $c->dispatch; $status = $c->finalize; - } - catch { + } catch { + #rethow if this can be handled by middleware + if(blessed $_ && ($_->can('as_psgi') || $_->can('code'))) { + $_->can('rethrow') ? $_->rethrow : croak $_; + } chomp(my $error = $_); $class->log->error(qq/Caught exception in engine "$error"/); }; @@ -2604,18 +2605,15 @@ sub locate_components { my $class = shift; my $config = shift; - my @paths = qw( ::Controller ::C ::Model ::M ::View ::V ); + my @paths = qw( ::M ::Model ::V ::View ::C ::Controller ); my $extra = delete $config->{ search_extra } || []; - push @paths, @$extra; + unshift @paths, @$extra; - my $locator = Module::Pluggable::Object->new( - search_path => [ map { s/^(?=::)/$class/; $_; } @paths ], - %$config - ); - - # XXX think about ditching this sort entirely - my @comps = sort { length $a <=> length $b } $locator->plugins; + my @comps = map { sort { length($a) <=> length($b) } Module::Pluggable::Object->new( + search_path => [ map { s/^(?=::)/$class/; $_; } ($_) ], + %$config + )->plugins } @paths; return @comps; } @@ -2903,6 +2901,78 @@ sub psgi_app { return $app->Catalyst::Utils::apply_registered_middleware($psgi); } + +=head2 trace_level + +Class attribute which is a positive number and defines the noiseness of the +application trace. See L. + +=head2 trace_logger + +Class attribute which is a handler for reporting your traces. See L. + +=head2 $c->setup_trace + +Examples your %ENV, configuation and application settings to setup how and if +application tracing is enabled. See L. + +=head2 $c->trace + +Accepts a string $message and level for a trace message. The configured +trace level must equal or exceed the level given. Level is required and should +be a positive integer. For more see L. + +=cut + +sub setup_trace { + my ($app, @args) = @_; + + # first we look for %ENV + if(my $trace = Catalyst::Utils::env_value( $app, 'TRACE' )) { + # extract a file path if it exists; + my ($level,$op, $path) = ($trace=~m/^(.+)(\=|\+\=)(.+)$/); + if($level && $op && $path) { + open(my $fh, '>', $path) + ||die "Cannot open trace file at $path: $!"; + $app->trace_logger($fh); + $app->trace_level($level); + } else { + $app->trace_level($trace); + } + } + + # Next, we look at config + $app->trace_level($app->config->{trace_level}) unless defined($app->trace_level); + $app->trace_logger($app->config->{trace_logger}) unless defined($app->trace_logger); + + # We do setup_trace AFTER setup_log, so this stuff should be all good to + # use by this point in application setup. For BackCompat, we will try to + # respect ->debug + + if($app->debug) { + $app->trace_level(1) unless defined($app->trace_level); + $app->trace_logger(sub { shift->log->debug }) unless defined($app->trace_logger); + } + + # Last, we set defaults if the settings are still emtpy + # Setup the defaults + + $app->trace_level(0) unless defined($app->trace_level); + $app->trace_logger(sub { shift->log->debug }) unless defined($app->trace_logger); + + return; +} + +sub trace { + my ($class, $message, $level) = @_; + die "Level is required" unless defined $level; + if($class->trace_level >= $level) { + ref($class->trace_logger) eq 'CODE' ? + $class->trace_logger->($class, $message, $level) : + $class->trace_logger->print($message); + } +} + =head2 $c->setup_home Sets up the home directory. @@ -3103,28 +3173,48 @@ 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. +you really don't need to invoke it. However you may do so if you find the idea +of loading middleware via configuration weird :). For example: + + package MyApp; + + use Catalyst; + + __PACKAGE__->setup_middleware('Head'); + __PACKAGE__->setup; 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) +So basically your middleware handles an incoming request from the first +registered middleware, down and handles the response from the last middleware +up. + =cut sub registered_middlewares { my $class = shift; if(my $middleware = $class->_psgi_middleware) { - return @$middleware; + return ( + Catalyst::Middleware::Stash->new, + Plack::Middleware::HTTPExceptions->new, + Plack::Middleware::RemoveRedundantBody->new, + Plack::Middleware::FixMissingBodyInRedirect->new, + Plack::Middleware::ContentLength->new, + Plack::Middleware::MethodOverride->new, + Plack::Middleware::Head->new, + @$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 $class = shift; + my @middleware_definitions = @_ ? + reverse(@_) : reverse(@{$class->config->{'psgi_middleware'}||[]}); my @middleware = (); while(my $next = shift(@middleware_definitions)) { @@ -3146,7 +3236,8 @@ sub setup_middleware { } } - $class->_psgi_middleware(\@middleware); + my @existing = @{$class->_psgi_middleware || []}; + $class->_psgi_middleware([@middleware,@existing,]); } =head2 registered_data_handlers @@ -3189,7 +3280,8 @@ sub registered_data_handlers { if(my $data_handlers = $class->_data_handlers) { return %$data_handlers; } else { - die "You cannot call ->registered_data_handlers until data_handers has been setup"; + $class->setup_data_handlers; + return $class->registered_data_handlers; } } @@ -3428,14 +3520,44 @@ backwardly compatible). =item * -C - See L. +C - See L. + +=item * + +C - See L. + +=item * + +trace_level - This sets your application trace level - See L. =item * -C - See L. +trace_logger - This sets your application trace logger - See L. =back +=head1 EXCEPTIONS + +Generally when you throw an exception inside an Action (or somewhere in +your stack, such as in a model that an Action is calling) that exception +is caught by Catalyst and unless you either catch it yourself (via eval +or something like L or by reviewing the L stack, it +will eventually reach L and return either the debugging +error stack page, or the default error page. However, if your exception +can be caught by L, L will +instead rethrow it so that it can be handled by that middleware (which +is part of the default middleware). For example this would allow + + use HTTP::Throwable::Factory 'http_throw'; + + sub throws_exception :Local { + my ($self, $c) = @_; + + http_throw(SeeOther => { location => + $c->uri_for($self->action_for('redirect')) }); + + } + =head1 INTERNAL ACTIONS Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>, @@ -3556,7 +3678,7 @@ example given above, which uses L to provide either L 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 +The C configuration 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. @@ -3604,6 +3726,23 @@ So the general form is: 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: + +Alternatively, you may also define middleware by calling the L +package method: + + package MyApp::Web; + + use Catalyst; + + __PACKAGE__->setup_middleware( \@middleware_definitions); + __PACKAGE__->setup; + +In the case where you do both (use 'setup_middleware' and configuration) the +package call to setup_middleware will be applied earlier (in other words its +middleware will wrap closer to the application). Keep this in mind since in +some cases the order of middleware is important. + +The two approaches are not exclusive. =over 4 @@ -3690,6 +3829,160 @@ to initialize the middleware object. Please see L for more on middleware. +=head1 TRACING + +B Tracing replaces the functionality of L. For now both +interfaces will be supported but it is suggested that you become familiar with +the new interface and begin using it. + +Application tracing is debugging information about the state of your L +application and a request / response cycle. This is often used when you want a +peek into the 'Catalyst Black Box' without needing to actually hack into the +core code and add debugging statements. Examples of application tracing include +startup information about loaded plugins, middleware, models, controllers and +views. It also includes details about how a request is dispatched (what actions +in what controllers are hit, and approximately how long each took) and how a +response is generated. Additional trace information includes details about errors +and some basic statistics on your running application. + +It is often the case when running an application in a development environment +for development purposes that you will enable tracing to assist you in your work. +However, application tracing is not strictly tied to environment so trace levels +are not automatically enabled based on any environment settings (although you are +allowed to set trace levels via configuration, which can be environment specific, +if you choose so). + +Application tracing is also not the same thing as logging. Logging is custom messages +that you've added to your custom application for the purposes of better understanding +your application and how effective your application is in achieving its goals. +Often logging is extended, unstructured meta data around your core business logic +such as details about when a user account is created or failed to be created, what +types of validation issues are occuring in your forms, page views, user engagement +and timestamps to help you understand your application performance. Basically this +is often information of business value that doesn't cleanly or meaningfully fit +into a database. Catalyst provides an interface for adding various kinds of +Loggers which can assist you in these tasks. Most Loggers allow one to log +messages at different levels of priority, such as debug, warning, critical, etc. +This is a useful feature since it permits one to turn the logging level down in +high traffic environments. In the past Catalyst tracing (previously called +'Debug') was conflated with log levels of debug, in that in order to enable +application tracing (or debugging) one was required to turn log level debug on +globally. Additionally, the Catalyst application tracing (or debugging) used +the defined logger to 'record' its messages. Neither is ideal since it leads +one to be forced to accept more logging than may be wished, and it also does +not allow one to separate development tracing from application debug logging. + +Application tracing fixes this issues by allowing you to turn on tracing +independently of setting your log level. It also lets you define a trace +log message handler separately from your logger. So for example you might +wish to send trace messages to STDOUT, but send your logging to Elasticsearch. +Here's an example: + + package MyApp; + + use Catalyst; + + __PACKAGE__->trace_level(1); + __PACKAGE__->trace_logger(sub { my $class = shift; ...}); + __PACKAGE__->setup; + +You may also configure tracing via configuration: + + package MyApp; + + use Catalyst; + + __PACKAGE__->config({ + trace_level => 1, + trace_logger => sub { my $class = shift; ...}, + }); + + __PACKAGE__->setup; + +Or, you may set tracing via environment varables, for example: + + CATALYST_TRACE=1 perl script/myapp_server.pl + MYAPP_TRACE=1 perl script/myapp_server.pl + MYAPP_TRACE=1=/var/log/traces perl script/myapp_server.pl + +The order of precidence is that custom application environment variables +('MYAPP_TRACE') come first, followed by global environment variables +('CATALYST_TRACE'), followed by configuration settings and lastly application +defaults. + +For backwards compatiblity, we respect classic Catalyst debugging (L) in +the following way. If debugging is true, we automatically set +C and set the C to your the debug method of your +defined log object (basically it works just as described in L). In this +case $c->debug will also be set to true. + +Please note that if you set C but not debugging then debugging +($c->debug) will NOT be set to true. + +Please note that if you set BOTH trace_level and 'class' debugging, your trace +level and trace configuation is respected at a high priority, however the state +of the debug method will be set as requested (although overridden). This is +done for backcompatibility with applications that overloaded the debug method +in custom applications. + +Please note that when setting trace levels via environment, you may use an +extended form of the value, which opens a filehandled to a specified path +and sends all trace information there: + + MYAPP_TRACE=1=/var/log/traces perl script/myapp_server.pl + +This would override any other settings for L<\trace_logger>. I + +=head2 trace_level + +This is a number that defaults to 0. It indicates the level of application +tracing that is desired. Larger numbers indicate greater level of tracing. +Currently trace levels are defined, although at this time respect is limited, +as this is a new feature. + +Levels 1,2 and 3 are reserved for Catalyst core code (code that is part of the +L distribution). + +Levels 4,5 and 6 are reserved for Catalyst extended ecosystem (Catalyst plugins, +models, views and distributions under the CatalystX namespace). + +Levels 7,8 and 9 are reserved but not currently defined. + +Levels 10 and higher are reserved for local (not on CPAN) application use. + +=head2 trace_logger + +This handles a trace message, if it is determined that one should be sent based +on the running L<\trace_level>. This can accept the following values + +=over 4 + +=item a CodeRef + +This is a code reference that gets the application class (your Catalyst.pm +subclass) as argument0, the message as argument1 and the level as argument3. +The message is expected to be a string. For example: + + __PACKAGE__->trace_logger( sub { + my ($app, $message, $level) = @_; + $app->log->debug($message); + }); + +Would send trace messages to the debug log handler (This is currently the +default behavior). + +=item A Filehandle or Object + +This must be an open filehandle setup to received output. We really +just look for a 'print' method, so strictly speaking this could be +any object that satisfies the duck type. + +=item A String + +A path that be be resolved as a file that we open a filehandle to. + +=back + =head1 ENCODING On request, decodes all params from encoding into a sequence of @@ -3904,6 +4197,8 @@ t0m: Tomas Doran Ulf Edvinsson +vanstyn: Henry Van Styn + Viljo Marrandi C Will Hawes C @@ -3918,9 +4213,11 @@ rainboxx: Matthias Dietrich, C dd070: Dhaval Dhanani +Upasana + =head1 COPYRIGHT -Copyright (c) 2005, the above named PROJECT FOUNDER and CONTRIBUTORS. +Copyright (c) 2005-2014, the above named PROJECT FOUNDER and CONTRIBUTORS. =head1 LICENSE