X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FAction%2FDeserialize.pm;h=5be60f3513ff0e35dde87584ee12a4e8df81f252;hb=370367cb80b925e50a4ea1bc759b06d1466f2627;hp=2d5343fa8d9505787721a0ebc3b91b8911a68fe6;hpb=eccb21379de1fbdc65740e0cb4158d3b4d055cab;p=catagits%2FCatalyst-Action-REST.git diff --git a/lib/Catalyst/Action/Deserialize.pm b/lib/Catalyst/Action/Deserialize.pm index 2d5343f..5be60f3 100644 --- a/lib/Catalyst/Action/Deserialize.pm +++ b/lib/Catalyst/Action/Deserialize.pm @@ -1,71 +1,172 @@ -# -# Catlyst::Action::Deserialize -# Created by: Adam Jacob, Marchex, -# -# $Id$ - package Catalyst::Action::Deserialize; -use strict; -use warnings; +use Moose; +use namespace::autoclean; -use base 'Catalyst::Action'; +extends 'Catalyst::Action::SerializeBase'; use Module::Pluggable::Object; -use Catalyst::Request::REST; +use MRO::Compat; +use Moose::Util::TypeConstraints; + +has plugins => ( is => 'rw' ); + +has deserialize_http_methods => ( + traits => ['Hash'], + isa => do { + my $tc = subtype as 'HashRef[Str]'; + coerce $tc, from 'ArrayRef[Str]', + via { +{ map { ($_ => 1) } @$_ } }; + $tc; + }, + coerce => 1, + builder => '_build_deserialize_http_methods', + handles => { + deserialize_http_methods => 'keys', + _deserialize_handles_http_method => 'exists', + }, +); -__PACKAGE__->mk_accessors(qw(plugins)); +sub _build_deserialize_http_methods { [qw(POST PUT OPTIONS DELETE)] } sub execute { my $self = shift; - my ( $controller, $c, $test ) = @_; - - my $nreq = bless( $c->request, 'Catalyst::Request::REST' ); - $c->request($nreq); - - unless ( defined( $self->plugins ) ) { - my $mpo = Module::Pluggable::Object->new( - 'require' => 1, - 'search_path' => ['Catalyst::Action::Deserialize'], - ); - my @plugins = $mpo->plugins; - $self->plugins( \@plugins ); - } - my $content_type = $c->request->content_type; - my $sclass = 'Catalyst::Action::Deserialize::'; - my $sarg; - my $map = $controller->serialize->{'map'}; - if ( exists( $map->{$content_type} ) ) { - my $mc; - if ( ref( $map->{$content_type} ) eq "ARRAY" ) { - $mc = $map->{$content_type}->[0]; - $sarg = $map->{$content_type}->[1]; - } else { - $mc = $map->{$content_type}; - } - $sclass .= $mc; - if ( !grep( /^$sclass$/, @{ $self->plugins } ) ) { - die "Cannot find plugin $sclass for $content_type!"; - } - } else { - if ( exists( $controller->serialize->{'default'} ) ) { - $sclass .= $controller->serialize->{'default'}; - } else { - die "I cannot find a default serializer!"; - } - } + my ( $controller, $c ) = @_; - my @demethods = qw(POST PUT OPTIONS); - my $method = $c->request->method; - if ( grep /^$method$/, @demethods ) { + if ( !defined($c->req->data) && $self->_deserialize_handles_http_method($c->request->method) ) { + my ( $sclass, $sarg, $content_type ) = + $self->_load_content_plugins( 'Catalyst::Action::Deserialize', + $controller, $c ); + return 1 unless defined($sclass); + my $rc; if ( defined($sarg) ) { - $sclass->execute( $controller, $c, $sarg ); + $rc = $sclass->execute( $controller, $c, $sarg ); } else { - $sclass->execute( $controller, $c ); + $rc = $sclass->execute( $controller, $c ); + } + if ( $rc eq "0" ) { + return $self->unsupported_media_type( $c, $content_type ); + } elsif ( $rc ne "1" ) { + return $self->serialize_bad_request( $c, $content_type, $rc ); } - $self->NEXT::execute( @_, ); - } else { - $self->NEXT::execute(@_); } + + $self->maybe::next::method(@_); + + return 1; } -1; +__PACKAGE__->meta->make_immutable; + +=head1 NAME + +Catalyst::Action::Deserialize - Deserialize Data in a Request + +=head1 SYNOPSIS + + package Foo::Controller::Bar; + + __PACKAGE__->config( + 'default' => 'text/x-yaml', + 'stash_key' => 'rest', + 'map' => { + 'text/x-yaml' => 'YAML', + 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ], + }, + ); + + sub begin :ActionClass('Deserialize') {} + +=head1 DESCRIPTION + +This action will deserialize HTTP POST, PUT, OPTIONS and DELETE requests. +It assumes that the body of the HTTP Request is a serialized object. +The serializer is selected by introspecting the requests content-type +header. + +If you want deserialize any other HTTP method besides POST, PUT, +OPTIONS and DELETE you can do this by setting the +C<< deserialize_http_methods >> list via C<< action_args >>. +Just modify the config in your controller and define a list of HTTP +methods the deserialization should happen for: + + __PACKAGE__->config( + action_args => { + '*' => { + deserialize_http_methods => [qw(POST PUT OPTIONS DELETE GET)] + } + } + ); + +See also L. + +The specifics of deserializing each content-type is implemented as +a plugin to L. You can see a list +of currently implemented plugins in L. + +The results of your Deserializing will wind up in $c->req->data. +This is done through the magic of L. + +While it is common for this Action to be called globally as a +C method, there is nothing stopping you from using it on a +single routine: + + sub foo :Local :Action('Deserialize') {} + +Will work just fine. + +When you use this module, the request class will be changed to +L. + +=head1 RFC 7231 Compliance Mode + +To maintain backwards compatibility with the module's original functionality, +where it was assumed the deserialize and serialize content types are the same, +an optional compliance mode can be enabled to break this assumption. + + __PACKAGE__->config( + 'compliance_mode' => 1, + 'default' => 'text/x-yaml', + 'stash_key' => 'rest', + 'map' => { + 'text/x-yaml' => 'YAML', + 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ], + }, + 'deserialize_default => 'application/json', + 'deserialize_map' => { + 'application/json' => 'JSON', + }, + ); + +Three extra keys are added to the controller configuration. compliance_mode, a +boolean to enable the mode. And a parallel set of content type mappings +'deserialize_default' and 'deserialize_map' to mirror the default/map +configuration keys. + +The module will use the default/map keys when negotiating the serializing +content type specified by the client in the Accept header. And will use the +deserialize_default/deserialize_map in conjunction with the Content-Type +header where the client is giving the content type being sent in the request. + +=head1 CUSTOM ERRORS + +For building custom error responses when de-serialization fails, you can create +an ActionRole (and use L to apply it to the +C action) which overrides C and/or C +methods. + +=head1 SEE ALSO + +You likely want to look at L, which implements +a sensible set of defaults for a controller doing REST. + +L, L + +=head1 AUTHORS + +See L for authors. + +=head1 LICENSE + +You may distribute this code under the same terms as Perl itself. + +=cut