use Carp qw/croak carp shortmess/;
use Try::Tiny;
use Safe::Isa;
+use Moose::Util 'find_meta';
use Plack::Middleware::Conditional;
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');
my $self = shift;
my %p = ( _log => $self->log );
$p{_uploadtmp} = $self->_uploadtmp if $self->_has_uploadtmp;
+ $p{data_handlers} = {$self->registered_data_handlers};
+ $p{_use_hash_multivalue} = $self->config->{use_hash_multivalue_in_request}
+ if $self->config->{use_hash_multivalue_in_request};
\%p;
}
__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 trace_level trace_logger/;
__PACKAGE__->dispatcher_class('Catalyst::Dispatcher');
__PACKAGE__->request_class('Catalyst::Request');
# Remember to update this in Catalyst::Runtime as well!
-our $VERSION = '5.90030';
+our $VERSION = '5.90069_002';
sub import {
my ( $class, @arguments ) = @_;
=head2 $c->forward( $class, $method, [, \@arguments ] )
-Forwards processing to another action, by its private name. If you give a
+This is one way of calling another action (method) in the same or
+a different controller. You can also use C<< $self->my_method($c, @args) >>
+in the same controller or C<< $c->controller('MyController')->my_method($c, @args) >>
+in a different controller.
+The main difference is that 'forward' uses some of the Catalyst request
+cycle overhead, including debugging, which may be useful to you. On the
+other hand, there are some complications to using 'forward', restrictions
+on values returned from 'forward', and it may not handle errors as you prefer.
+Whether you use 'forward' or not is up to you; it is not considered superior to
+the other ways to call a method.
+
+'forward' calls another action, by its private name. If you give a
class name but no method, C<process()> is called. You may also optionally
pass arguments in an arrayref. The action will receive the arguments in
C<@_> and C<< $c->req->args >>. Upon returning from the function,
=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
$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(@_);
$class->setup_log( delete $flags->{log} );
$class->setup_plugins( delete $flags->{plugins} );
+ $class->setup_trace();
+
+ $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");
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;
$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};
? $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 } ) {
}
$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
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;
}
# Support skipping finalize for psgix.io style 'jailbreak'. Used to support
# stuff like cometd and websockets
- if($c->request->has_io_fh) {
+ if($c->request->_has_io_fh) {
$c->log_response;
return;
}
$c->finalize_headers unless $c->response->finalized_headers;
- # HEAD request
- if ( $c->request->method eq 'HEAD' ) {
- $c->response->body('');
- }
-
$c->finalize_body;
}
$c->log_response;
if ($c->use_stats) {
- my $elapsed = sprintf '%f', $c->stats->elapsed;
+ my $elapsed = $c->stats->elapsed;
my $av = $elapsed == 0 ? '??' : sprintf '%.3f', 1 / $elapsed;
$c->log->info(
"Request took ${elapsed}s ($av/s)\n" . $c->stats->report . "\n" );
=head2 $c->finalize_error
-Finalizes error.
+Finalizes error. If there is only one error in L</error> and it is an object that
+does C<as_psgi> or C<code> 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
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");
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <title>Moved</title>
- </head>
- <body>
- <p>This item has moved <a href="$encoded_location">here</a>.</p>
- </body>
-</html>
-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;
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"/);
};
sub _make_immutable_if_needed {
my $class = shift;
- my $meta = Class::MOP::get_metaclass_by_name($class);
+ my $meta = find_meta($class);
my $isa_ca = $class->isa('Class::Accessor::Fast') || $class->isa('Class::Accessor');
if (
$meta->is_immutable
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;
}
$dispatcher = $class->dispatcher_class;
}
- Class::MOP::load_class($dispatcher);
+ load_class($dispatcher);
# dispatcher instance
$class->dispatcher( $dispatcher->new );
# Don't really setup_engine -- see _setup_psgi_app for explanation.
return if $class->loading_psgi_file;
- Class::MOP::load_class($engine);
+ load_class($engine);
if ($ENV{MOD_PERL}) {
my $apache = $class->engine_loader->auto;
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) = @_;
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) = @_;
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 trace_level
+
+Class attribute which is a positive number and defines the noiseness of the
+application trace. See L</TRACING>.
+
+=head2 trace_logger
+
+Class attribute which is a handler for reporting your traces. See L</TRACING>.
+
+=head2 $c->setup_trace
+
+Examples your %ENV, configuation and application settings to setup how and if
+application tracing is enabled. See L</TRACING>.
+
+=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</TRACING>.
+
+=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
my ( $proto, $plugin, $instant ) = @_;
my $class = ref $proto || $proto;
- Class::MOP::load_class( $plugin );
+ load_class( $plugin );
$class->log->warn( "$plugin inherits from 'Catalyst::Component' - this is deprecated and will not work in 5.81" )
if $plugin->isa( 'Catalyst::Component' );
my $plugin_meta = Moose::Meta::Class->create($plugin);
() }
: $_
} @$plugins ];
- unshift @$plugins, $class->_default_plugins;
+ push @$plugins, $class->_default_plugins;
$plugins = Data::OptList::mkopt($plugins || []);
my @plugins = map {
} @{ $plugins };
for my $plugin ( reverse @plugins ) {
- Class::MOP::load_class($plugin->[0], $plugin->[1]);
+ load_class($plugin->[0], $plugin->[1]);
my $meta = find_meta($plugin->[0]);
next if $meta && $meta->isa('Moose::Meta::Role');
$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<Plack::Middleware> 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<psgi_middleware> or
+from passed @args.
+
+See under L</CONFIGURATION> information regarding C<psgi_middleware> and how
+to use it to enable L<Plack::Middleware>
+
+This method is automatically called during 'setup' of your application, so
+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<Plack::Builder> or if you previously used the plugin
+L<Catalyst::Plugin::EnableMiddleware> (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 (
+ 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 = shift;
+ my @middleware_definitions = @_ ?
+ reverse(@_) : 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;
+ }
+ }
+
+ my @existing = @{$class->_psgi_middleware || []};
+ $class->_psgi_middleware([@middleware,@existing,]);
+}
+
+=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<data_handlers> or
+from passed @args.
+
+See under L</CONFIGURATION> information regarding C<data_handlers>.
+
+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 Handlers that come bundled with L<Catalyst>. Currently there are
+only two default data handlers, for 'application/json' and an alternative to
+'application/x-www-form-urlencoded' which supposed nested form parameters via
+L<CGI::Struct> or via L<CGI::Struct::XS> IF you've installed it.
+
+The 'application/json' data handler is used to parse incoming JSON into a Perl
+data structure. It used either L<JSON::MaybeXS> or L<JSON>, depending on which
+is installed. This allows you to fail back to L<JSON:PP>, which is a Pure Perl
+JSON decoder, and has the smallest dependency impact.
+
+Because we don't wish to add more dependencies to L<Catalyst>, if you wish to
+use this new feature we recommend installing L<JSON> or L<JSON::MaybeXS> in
+order to get the best performance. You should add either to your dependency
+list (Makefile.PL, dist.ini, cpanfile, etc.)
+
+=cut
+
+sub registered_data_handlers {
+ my $class = shift;
+ if(my $data_handlers = $class->_data_handlers) {
+ return %$data_handlers;
+ } else {
+ $class->setup_data_handlers;
+ return $class->registered_data_handlers;
+ }
+}
+
+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/x-www-form-urlencoded' => sub {
+ my ($fh, $req) = @_;
+ my $params = $req->_use_hash_multivalue ? $req->body_parameters->mixed : $req->body_parameters;
+ Class::Load::load_first_existing_class('CGI::Struct::XS', 'CGI::Struct')
+ ->can('build_cgi_struct')->($params);
+ },
+ 'application/json' => sub {
+ Class::Load::load_first_existing_class('JSON::MaybeXS', 'JSON')
+ ->can('decode_json')->(do { local $/; $_->getline });
+ },
+ };
}
=head2 $c->stack
at other URIs than that which the app is 'normally' based at with C<mod_rewrite>), the resolution of
C<< $c->request->base >> will be incorrect.
-=back
+=back
=item *
C<encoding> - See L</ENCODING>
-=back
+=item *
-=item abort_chain_on_error_fix => 1
+C<abort_chain_on_error_fix>
When there is an error in an action chain, the default behavior is to continue
processing the remaining actions and then catch the error upon chain end. This
chain when there is an error raised in any action (thus terminating the chain
early.)
+use like:
+
+ __PACKAGE__->config(abort_chain_on_error_fix => 1);
+
In the future this might become the default behavior.
+=item *
+
+C<use_hash_multivalue_in_request>
+
+In L<Catalyst::Request> the methods C<query_parameters>, C<body_parametes>
+and C<parameters> return a hashref where values might be scalar or an arrayref
+depending on the incoming data. In many cases this can be undesirable as it
+leads one to writing defensive code like the following:
+
+ my ($val) = ref($c->req->parameters->{a}) ?
+ @{$c->req->parameters->{a}} :
+ $c->req->parameters->{a};
+
+Setting this configuration item to true will make L<Catalyst> populate the
+attributes underlying these methods with an instance of L<Hash::MultiValue>
+which is used by L<Plack::Request> and others to solve this very issue. You
+may prefer this behavior to the default, if so enable this option (be warned
+if you enable it in a legacy application we are not sure if it is completely
+backwardly compatible).
+
+=item *
+
+C<psgi_middleware> - See L</PSGI MIDDLEWARE>.
+
+=item *
+
+C<data_handlers> - See L</DATA HANDLERS>.
+
+=item *
+
+trace_level - This sets your application trace level - See L</TRACING>.
+
+=item *
+
+trace_logger - This sets your application trace logger - See L</TRACING>.
+
+=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<Try::Tiny> or by reviewing the L</error> stack, it
+will eventually reach L</finalize_errors> and return either the debugging
+error stack page, or the default error page. However, if your exception
+can be caught by L<Plack::Middleware::HTTPExceptions>, L<Catalyst> 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>,
modules you are using must also be thread-safe. Some modules, most notably
L<DBD::SQLite>, are not thread-safe.
+=head1 DATA HANDLERS
+
+The L<Catalyst::Request> object uses L<HTTP::Body> 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<Catalyst> defines a global configuration
+option, C<data_handlers>, 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<Catalyst> comes with a generic JSON data handler similar to the
+example given above, which uses L<JSON::Maybe> to provide either L<JSON::PP>
+(a pure Perl, dependency free JSON parser) or L<Cpanel::JSON::XS> 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<data_handlers> 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.
+
+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<Plack::Middleware> or a compatible
+interface in configuration. Your middleware definitions are in the form of an
+arrayref under the configuration key C<psgi_middleware>. 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<Plack::Builder>:
+
+Alternatively, you may also define middleware by calling the L</setup_middleware>
+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
+
+=item Middleware Object
+
+An already initialized object that conforms to the L<Plack::Middleware>
+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<Plack::Middleware> 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<Plack::Middleware> 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<HashRef> is used as arguments
+to initialize the middleware object.
+
+ __PACKAGE__->config(
+ 'psgi_middleware', [
+ 'Session' => {store => 'File'},
+ ]);
+
+=back
+
+Please see L<PSGI> for more on middleware.
+
+=head1 TRACING
+
+B<NOTE> Tracing replaces the functionality of L<Debug>. 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<Catalyst>
+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<Debug>) in
+the following way. If debugging is true, we automatically set
+C<trace_level=1> and set the C<trace_logger> to your the debug method of your
+defined log object (basically it works just as described in L<Debug>). In this
+case $c->debug will also be set to true.
+
+Please note that if you set C<trace_level> 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<Catalyst> 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
Ulf Edvinsson
+vanstyn: Henry Van Styn <vanstyn@cpan.org>
+
Viljo Marrandi C<vilts@yahoo.com>
Will Hawes C<info@whawes.co.uk>
dd070: Dhaval Dhanani <dhaval070@gmail.com>
+Upasana <me@upasana.me>
+
=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