lib/Catalyst/Action/Deserialize.pm

   1 package Catalyst::Action::Deserialize;
   2
   3 use Moose;
   4 use namespace::autoclean;
   5
   6 extends 'Catalyst::Action::SerializeBase';
   7 use Module::Pluggable::Object;
   8 use MRO::Compat;
   9 use Moose::Util::TypeConstraints;
  10
  11 our $VERSION = '1.02';
  12 $VERSION = eval $VERSION;
  13
  14 has plugins => ( is => 'rw' );
  15
  16 has deserialize_http_methods => (
  17     traits  => ['Hash'],
  18     isa     => do {
  19         my $tc = subtype as 'HashRef[Str]';
  20         coerce $tc, from 'ArrayRef[Str]',
  21             via { +{ map { ($_ => 1) } @$_ } };
  22         $tc;
  23     },
  24     coerce  => 1,
  25     builder => '_build_deserialize_http_methods',
  26     handles => {
  27         deserialize_http_methods         => 'keys',
  28         _deserialize_handles_http_method => 'exists',
  29     },
  30 );
  31
  32 sub _build_deserialize_http_methods { [qw(POST PUT OPTIONS DELETE)] }
  33
  34 sub execute {
  35     my $self = shift;
  36     my ( $controller, $c ) = @_;
  37
  38     if ( !defined($c->req->data) && $self->_deserialize_handles_http_method($c->request->method) ) {
  39         my ( $sclass, $sarg, $content_type ) =
  40           $self->_load_content_plugins( 'Catalyst::Action::Deserialize',
  41             $controller, $c );
  42         return 1 unless defined($sclass);
  43         my $rc;
  44         if ( defined($sarg) ) {
  45             $rc = $sclass->execute( $controller, $c, $sarg );
  46         } else {
  47             $rc = $sclass->execute( $controller, $c );
  48         }
  49         if ( $rc eq "0" ) {
  50             return $self->unsupported_media_type( $c, $content_type );
  51         } elsif ( $rc ne "1" ) {
  52             return $self->serialize_bad_request( $c, $content_type, $rc );
  53         }
  54     }
  55
  56     $self->maybe::next::method(@_);
  57
  58     return 1;
  59 }
  60
  61 __PACKAGE__->meta->make_immutable;
  62
  63 =head1 NAME
  64
  65 Catalyst::Action::Deserialize - Deserialize Data in a Request
  66
  67 =head1 SYNOPSIS
  68
  69     package Foo::Controller::Bar;
  70
  71     __PACKAGE__->config(
  72         'default'   => 'text/x-yaml',
  73         'stash_key' => 'rest',
  74         'map'       => {
  75             'text/x-yaml'        => 'YAML',
  76             'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
  77         },
  78     );
  79
  80     sub begin :ActionClass('Deserialize') {}
  81
  82 =head1 DESCRIPTION
  83
  84 This action will deserialize HTTP POST, PUT, OPTIONS and DELETE requests.
  85 It assumes that the body of the HTTP Request is a serialized object.
  86 The serializer is selected by introspecting the requests content-type
  87 header.
  88
  89 If you want deserialize any other HTTP method besides POST, PUT,
  90 OPTIONS and DELETE you can do this by setting the
  91 C<< deserialize_http_methods >> list via C<< action_args >>.
  92 Just modify the config in your controller and define a list of HTTP
  93 methods the deserialization should happen for:
  94
  95     __PACKAGE__->config(
  96         action_args => {
  97             '*' => {
  98                 deserialize_http_methods => [qw(POST PUT OPTIONS DELETE GET)]
  99             }
 100         }
 101     );
 102
 103 See also L<Catalyst::Controller/action_args>.
 104
 105 The specifics of deserializing each content-type is implemented as
 106 a plugin to L<Catalyst::Action::Deserialize>.  You can see a list
 107 of currently implemented plugins in L<Catalyst::Controller::REST>.
 108
 109 The results of your Deserializing will wind up in $c->req->data.
 110 This is done through the magic of L<Catalyst::Request::REST>.
 111
 112 While it is common for this Action to be called globally as a
 113 C<begin> method, there is nothing stopping you from using it on a
 114 single routine:
 115
 116    sub foo :Local :Action('Deserialize') {}
 117
 118 Will work just fine.
 119
 120 When you use this module, the request class will be changed to
 121 L<Catalyst::Request::REST>.
 122
 123 =head1 CUSTOM ERRORS
 124
 125 For building custom error responses when de-serialization fails, you can create
 126 an ActionRole (and use L<Catalyst::Controller::ActionRole> to apply it to the
 127 C<begin> action) which overrides C<unsupported_media_type> and/or C<_serialize_bad_request>
 128 methods.
 129
 130 =head1 SEE ALSO
 131
 132 You likely want to look at L<Catalyst::Controller::REST>, which implements
 133 a sensible set of defaults for a controller doing REST.
 134
 135 L<Catalyst::Action::Serialize>, L<Catalyst::Action::REST>
 136
 137 =head1 AUTHORS
 138
 139 See L<Catalyst::Action::REST> for authors.
 140
 141 =head1 LICENSE
 142
 143 You may distribute this code under the same terms as Perl itself.
 144
 145 =cut