X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FController%2FREST.pm;h=54609186cfa79053c0da89dbb68abd15264ab097;hb=d0822465cc09629df95ad9c522bce758f2badc8c;hp=43e781c125c650898061d52bcfdc0224f3e4d7bf;hpb=10bcd217c37d68aabbb0db8a5a7e233e679cb945;p=catagits%2FCatalyst-Action-REST.git

diff --git a/lib/Catalyst/Controller/REST.pm b/lib/Catalyst/Controller/REST.pm
index 43e781c..5460918 100644
--- a/lib/Catalyst/Controller/REST.pm
+++ b/lib/Catalyst/Controller/REST.pm
@@ -1,8 +1,8 @@
 package Catalyst::Controller::REST;
-use strict;
-use warnings;
+use Moose;
+use namespace::autoclean;
 
-our $VERSION = '0.79';
+our $VERSION = '1.02';
 $VERSION = eval $VERSION;
 
 =head1 NAME
@@ -14,7 +14,7 @@ Catalyst::Controller::REST - A RESTful controller
     package Foo::Controller::Bar;
     use Moose;
     use namespace::autoclean;
-    
+
     BEGIN { extends 'Catalyst::Controller::REST' }
 
     sub thing : Local : ActionClass('REST') { }
@@ -36,16 +36,18 @@ Catalyst::Controller::REST - A RESTful controller
 
     # Answer PUT requests to "thing"
     sub thing_PUT {
-        $radiohead = $req->data->{radiohead};
-        
+        my ( $self, $c ) = @_;
+
+        $radiohead = $c->req->data->{radiohead};
+
         $self->status_created(
             $c,
-            location => $c->req->uri->as_string,
+            location => $c->req->uri,
             entity => {
                 radiohead => $radiohead,
             }
         );
-    }     
+    }
 
 =head1 DESCRIPTION
 
@@ -79,7 +81,7 @@ which are described below.
 
 "The HTTP POST, PUT, and OPTIONS methods will all automatically
 L<deserialize|Catalyst::Action::Deserialize> the contents of
-C<< $c->request->body >> into the C<< $c->request->data >> hashref", based on 
+C<< $c->request->body >> into the C<< $c->request->data >> hashref", based on
 the request's C<Content-type> header. A list of understood serialization
 formats is L<below|/AVAILABLE SERIALIZERS>.
 
@@ -138,7 +140,7 @@ Returns YAML generated by L<YAML::Syck>.
 =item * C<text/html> => C<YAML::HTML>
 
 This uses L<YAML::Syck> and L<URI::Find> to generate YAML with all URLs turned
-to hyperlinks.  Only useable for Serialization.
+to hyperlinks.  Only usable for Serialization.
 
 =item * C<application/json> => C<JSON>
 
@@ -146,6 +148,21 @@ Uses L<JSON> to generate JSON output.  It is strongly advised to also have
 L<JSON::XS> installed.  The C<text/x-json> content type is supported but is
 deprecated and you will receive warnings in your log.
 
+You can also add a hash in your controller config to pass options to the json object.
+For instance, to relax permissions when deserializing input, add:
+  __PACKAGE__->config(
+    json_options => { relaxed => 1 }
+  )
+
+=item * C<text/javascript> => C<JSONP>
+
+If a callback=? parameter is passed, this returns javascript in the form of: $callback($serializedJSON);
+
+Note - this is disabled by default as it can be a security risk if you are unaware.
+
+The usual MIME types for this serialization format are: 'text/javascript', 'application/x-javascript',
+'application/javascript'.
+
 =item * C<text/x-data-dumper> => C<Data::Serializer>
 
 Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
@@ -208,7 +225,7 @@ Your views should have a C<process> method like this:
       $c->response->body( $output );
       return 1;  # important
   }
-  
+
   sub serialize {
       my ( $self, $data ) = @_;
 
@@ -217,9 +234,28 @@ Your views should have a C<process> method like this:
       return $serialized;
   }
 
+=item * Callback
+
+For infinite flexibility, you can provide a callback for the
+deserialization/serialization steps.
+
+  __PACKAGE__->config(
+      map => {
+          'text/xml'  => [ 'Callback', { deserialize => \&parse_xml, serialize => \&render_xml } ],
+      }
+  );
+
+The C<deserialize> callback is passed a string that is the body of the
+request and is expected to return a scalar value that results from
+the deserialization.  The C<serialize> callback is passed the data
+structure that needs to be serialized and must return a string suitable
+for returning in the HTTP response.  In addition to receiving the scalar
+to act on, both callbacks are passed the controller object and the context
+(i.e. C<$c>) as the second and third arguments.
+
 =back
 
-By default, L<Catalyst::Controller::REST> will return a 
+By default, L<Catalyst::Controller::REST> will return a
 C<415 Unsupported Media Type> response if an attempt to use an unsupported
 content-type is made.  You can ensure that something is always returned by
 setting the C<default> config option:
@@ -232,12 +268,12 @@ C<text/x-yaml>.
 =head1 CUSTOM SERIALIZERS
 
 Implementing new Serialization formats is easy!  Contributions
-are most welcome!  If you would like to implement a custom serializer, 
+are most welcome!  If you would like to implement a custom serializer,
 you should create two new modules in the L<Catalyst::Action::Serialize>
 and L<Catalyst::Action::Deserialize> namespace.  Then assign your new
 class to the content-type's you want, and you're done.
 
-See L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize> 
+See L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>
 for more information.
 
 =head1 STATUS HELPERS
@@ -255,7 +291,7 @@ such require you pass the current context ($c) as the first argument.
 
 =cut
 
-use base 'Catalyst::Controller';
+BEGIN { extends 'Catalyst::Controller' }
 use Params::Validate qw(SCALAR OBJECT);
 
 __PACKAGE__->mk_accessors(qw(serialize));
@@ -316,7 +352,7 @@ Example:
 
   $self->status_created(
     $c,
-    location => $c->req->uri->as_string,
+    location => $c->req->uri,
     entity => {
         radiohead => "Is a good band!",
     }
@@ -338,14 +374,8 @@ sub status_created {
         },
     );
 
-    my $location;
-    if ( ref( $p{'location'} ) ) {
-        $location = $p{'location'}->as_string;
-    } else {
-        $location = $p{'location'};
-    }
     $c->response->status(201);
-    $c->response->header( 'Location' => $location );
+    $c->response->header( 'Location' => $p{location} );
     $self->_set_entity( $c, $p{'entity'} );
     return 1;
 }
@@ -353,11 +383,13 @@ sub status_created {
 =item status_accepted
 
 Returns a "202 ACCEPTED" response.  Takes an "entity" to serialize.
+Also takes optional "location" for queue type scenarios.
 
 Example:
 
   $self->status_accepted(
     $c,
+    location => $c->req->uri,
     entity => {
         status => "queued",
     }
@@ -368,9 +400,16 @@ Example:
 sub status_accepted {
     my $self = shift;
     my $c    = shift;
-    my %p    = Params::Validate::validate( @_, { entity => 1, }, );
+    my %p    = Params::Validate::validate(
+        @_,
+        {
+            location => { type => SCALAR | OBJECT, optional => 1 },
+            entity   => 1,
+        },
+    );
 
     $c->response->status(202);
+    $c->response->header( 'Location' => $p{location} ) if exists $p{location};
     $self->_set_entity( $c, $p{'entity'} );
     return 1;
 }
@@ -386,7 +425,55 @@ sub status_no_content {
     my $c    = shift;
     $c->response->status(204);
     $self->_set_entity( $c, undef );
-    return 1.;
+    return 1;
+}
+
+=item status_multiple_choices
+
+Returns a "300 MULTIPLE CHOICES" response. Takes an "entity" to serialize, which should
+provide list of possible locations. Also takes optional "location" for preferred choice.
+
+=cut
+
+sub status_multiple_choices {
+    my $self = shift;
+    my $c    = shift;
+    my %p    = Params::Validate::validate(
+        @_,
+        {
+            entity => 1,
+            location => { type     => SCALAR | OBJECT, optional => 1 },
+        },
+    );
+
+    $c->response->status(300);
+    $c->response->header( 'Location' => $p{location} ) if exists $p{'location'};
+    $self->_set_entity( $c, $p{'entity'} );
+    return 1;
+}
+
+=item status_found
+
+Returns a "302 FOUND" response. Takes an "entity" to serialize.
+Also takes optional "location".
+
+=cut
+
+sub status_found {
+    my $self = shift;
+    my $c    = shift;
+    my %p    = Params::Validate::validate(
+        @_,
+        {
+            entity => 1,
+            location => { type     => SCALAR | OBJECT, optional => 1 },
+        },
+    );
+
+    $c->response->status(302);
+    $c->response->header( 'Location' => $p{location} ) if exists $p{'location'};
+    $self->_set_entity( $c, $p{'entity'} );
+    return 1;
 }
 
 =item status_bad_request
@@ -415,6 +502,32 @@ sub status_bad_request {
     return 1;
 }
 
+=item status_forbidden
+
+Returns a "403 FORBIDDEN" response.  Takes a "message" argument
+as a scalar, which will become the value of "error" in the serialized
+response.
+
+Example:
+
+  $self->status_forbidden(
+    $c,
+    message => "access denied",
+  );
+
+=cut
+
+sub status_forbidden {
+    my $self = shift;
+    my $c    = shift;
+    my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
+
+    $c->response->status(403);
+    $c->log->debug( "Status Forbidden: " . $p{'message'} ) if $c->debug;
+    $self->_set_entity( $c, { error => $p{'message'} } );
+    return 1;
+}
+
 =item status_not_found
 
 Returns a "404 NOT FOUND" response.  Takes a "message" argument
@@ -520,35 +633,44 @@ L<Catalyst::Action::Serialize>.
 The C<begin> method uses L<Catalyst::Action::Deserialize>.  The C<end>
 method uses L<Catalyst::Action::Serialize>.  If you want to override
 either behavior, simply implement your own C<begin> and C<end> actions
-and use MRO::Compat:
+and forward to another action with the Serialize and/or Deserialize
+action classes:
 
   package Foo::Controller::Monkey;
   use Moose;
   use namespace::autoclean;
-  
+
   BEGIN { extends 'Catalyst::Controller::REST' }
 
-  sub begin :Private {
+  sub begin : Private {
     my ($self, $c) = @_;
     ... do things before Deserializing ...
-    $self->maybe::next::method($c);
+    $c->forward('deserialize');
     ... do things after Deserializing ...
   }
 
+  sub deserialize : ActionClass('Deserialize') {}
+
   sub end :Private {
     my ($self, $c) = @_;
     ... do things before Serializing ...
-    $self->maybe::next::method($c);
+    $c->forward('serialize');
     ... do things after Serializing ...
   }
 
+  sub serialize : ActionClass('Serialize') {}
+
+If you need to deserialize multipart requests (i.e. REST data in
+one part and file uploads in others) you can do so by using the
+L<Catalyst::Action::DeserializeMultiPart> action class.
+
 =back
 
 =head1 A MILD WARNING
 
 I have code in production using L<Catalyst::Controller::REST>.  That said,
 it is still under development, and it's possible that things may change
-between releases.  I promise to not break things unneccesarily. :)
+between releases.  I promise to not break things unnecessarily. :)
 
 =head1 SEE ALSO
 
@@ -573,4 +695,6 @@ You may distribute this code under the same terms as Perl itself.
 
 =cut
 
+__PACKAGE__->meta->make_immutable;
+
 1;