Catalyst-Plugin-Server-JSONRPC

 view release on metacpan or  search on metacpan

lib/Catalyst/Plugin/Server/JSONRPC.pm  view on Meta::CPAN

=head1 NAME

Catalyst::Plugin::Server::JSONRPC -- Catalyst JSONRPC Server Plugin

=head1 SYNOPSIS

    package MyApp;
    use Catalyst qw/Server Server::JSONRPC/;

    package MyApp::Controller::Example;
    use base 'Catalyst::Controller';

    sub echo : JSONRPC {                     # available as: example.echo
        my ( $self, $c, @args ) = @_;
        $c->stash->{jsonrpc} = join ', ', @args;
    }

    sub ping : JSONRPCPath('/ping') {        # available as: ping
        my ( $self, $c ) = @_;
        $c->stash->{jsonrpc} = 'Pong';
    }

    sub world : JSONRPCRegex(/hello/) {      # available as: *hello*
        my ($self, $c) = @_;
        $c->stash->{jsonrpc} = 'World';
    }

    sub echo : JSONRPCLocal {                # available as: example.echo
        my ( $self, $c, @args ) = @_;
        $c->stash->{jsonrpc} = join ', ', @args;
    }

    sub ping : JSONRPCGlobal {               # available as: ping
        my ( $self, $c ) = @_;
        $c->stash->{jsonrpc} = 'Pong';
    }

=head1 DESCRIPTION

JSONRPC Plugin for Catalyst which we tried to make compatible with the
way Catalyst works with URLS. Main features are:

=over 4

=item * Split JSONRPC methodNames by STRING to find out Controller.

=item * Single entrypoint for JSONRPC calls, like http://host.tld/rpc

=item * DispatchTypes (attributes) which work much the same as Catalyst attrs

=item * JSONRPC Parameter handling transparent to Catalyst parameter handling

=back

=head1 HOW IT WORKS

The default behaviour will handle JSONRPC Requests sent to C</rpc> by creating
an OBJECT containing JSONRPC specific parameters in C<< $c->req->jsonrpc >>.

Directly after, it will find out the Path of the Action to dispatch to, by
splitting methodName by C<.>:

  methodName: hello.world
  path      : /hello/world

From this point, it will dispatch to '/hello/world' when it exists,
like Catalyst Urls would do. What means: you will be able to set Regexes,
Paths etc on subroutines to define the endpoint.

We discuss these custom JSONRPC attributes below.

When the request is dispatched, we will return $c->stash->{jsonrpc} to the
jsonrpc client, or, when it is not available, it will return $c->stash to
the client. There is also a way of defining $c->stash keys to be send back
to the client.

=head1 ATTRIBUTES

You can mark any method in your Catalyst application as being
available remotely by using one of the following attributes,
which can be added to any existing attributes, except Private.
Remember that one of the mentioned attributes below are automatically
also Privates...

=over 4

=item JSONRPC

Make this method accessible via JSONRPC, the same way as Local does
when using catalyst by URL.

The following example will be accessible by method C<< hello.world >>:

  package Catalyst::Controller::Hello
  sub world : JSONRPC {}

=item JSONRPCLocal

Identical version of attribute C<JSONRPC>

=item JSONRPCGlobal

Make this method accessible via JSONRPC, the same way as GLOBAL does
when using catalyst by URL.

The following example will be accessible by method C<< ping >>:

  package Catalyst::Controller::Hello
  sub ping : JSONRPCGlobal {}

=item JSONRPCPath('/say/hello')

lib/Catalyst/Plugin/Server/JSONRPC.pm  view on Meta::CPAN

=back

=head1 ACCESSORS

Once you've used the plugin, you'll have an $c->request->jsonrpc accessor
which will return an C<Catalyst::Plugin::Server::JSONRPC> object.

You can query this object as follows:

=over 4

=item $c->req->jsonrpc->is_jsonrpc_request

Boolean indicating whether the current request has been initiated
via JSONRPC

=item $c->req->jsonrpc->config

Returns a C<Catalyst::Plugin::Server::JSONRPC::Config> object. See the 
C<CONFIGURATION> below on how to use and configure it.

=item $c->req->jsonrpc->body

The body of the original JSONRPC call

=item $c->req->jsonrpc->method

The name of the original method called via JSONRPC

=item $c->req->jsonrpc->args

A list of parameters supplied by the JSONRPC call

=item $c->req->jsonrpc->result_as_string

The JSON body that will be sent back to the JSONRPC client

=item $c->req->jsonrpc->error

Allows you to set jsonrpc fault code and message

=back

=head1 Server Accessors

The following accessors are always available, whether you're in a jsonrpc
specific request or not

=over 4

=item $c->server->jsonrpc->list_methods

Returns a HASHREF containing the available jsonrpc methods in Catalyst as
a key, and the C<Catalyst::Action> object as a value.

=back

=head1 CATALYST REQUEST

To make things transparent, we try to put JSONRPC params into the Request
object of Catalyst. But first we will explain something about the JSONRPC
specifications.

A full draft of these specifications can be found on:
C<http://www.jsonrpc.com/spec>

In short, a jsonrpc-request consists of a methodName, like a subroutine
name, and a list of parameters. This list of parameters may contain strings
(STRING), arrays (LIST) and structs (HASH). Off course, these can be nested.

=over 4

=item $c->req->arguments

We will put the list of arguments into $c->req->arguments, thisway you can
fetch this list within your dispatched-to-subroutine:

  sub echo : JSONRPC {
      my ($self, $c, @args) = @_;
      $c->log->debug($arg[0]);              # Prints first JSONRPC parameter
                                            # to debug log
  }

=item $c->req->parameters

Because JSONRPC parameters are a LIST, we can't B<just> fill
$c->req->paremeters. To keep things transparent, we made an extra config
option what tells the JSONRPC server we can assume the following conditions
on all JSONRPC requests:
- There is only one JSONRPC parameter
- This JSONRPC parameter is a struct (HASH)

We will put this STRUCT as key-value pairs into $c->req->parameters.

=item $c->req->params

Alias of $c->req->parameters

=item $c->req->param

Alias of $c->req->parameters

=back

=cut

{

    package Catalyst::Plugin::Server::JSONRPC;

    our $VERSION = "0.07";

    use strict;
    use warnings;
    use attributes ();

    use Data::Dumper;
    use JSON::RPC::Common::Procedure::Return;
    use JSON::RPC::Common::Marshal::HTTP;
    use MRO::Compat;

    my $ServerClass = 'Catalyst::Plugin::Server::JSONRPC::Backend';

    ### only for development dumps!
    my $Debug = 0;

    ###
    ### Catalyst loading and dispatching
    ###

    ### Loads our jsonrpc backend class in $c->server->jsonrpc
    sub setup_engine {
        my $class = shift;
        $class->server->register_server( 'jsonrpc' => $ServerClass->new($class) );
        $class->next::method(@_);
    }
    
    sub setup {
        my $class = shift;
        ### config is not yet loaded on setup_engine so load it here
        $class->server->jsonrpc->config( Catalyst::Plugin::Server::JSONRPC::Config->new($class) );
        $class->next::method(@_);
    }
    
    ### Will load our customized DispatchTypes into Catalyst
    sub setup_dispatcher {
        my $class = shift;

lib/Catalyst/Plugin/Server/JSONRPC.pm  view on Meta::CPAN

a hierarchy in your method calls.

For example, with a separator of C<.> the method call C<demo.echo>
would be forwarded to C</demo/echo>.  To make C<demo_echo> forward to the
same path, you would change the separator to C<_>,

The default is C<.>, splitting methods on a single C<.>

=item convert_params

Make the arguments in C<< $c->req->jsonrpc->params >> available as
C<< $c->req->params >>. 

Defaults to true.

=item show_errors

Make system errors in C<< $c->error >> public to the rpc-caller in a JSON-RPC
faultString. When show_errors is false, and your catalyst app generates a
fault, it will return an JSON-RPC fault containing error number 500 and error
string: "Internal Server Error".

Defaults to false.

=back

=head1 DIAGNOSTICS

=over 4

=item Invalid JSONRPC request: No such method

There is no corresponding method in your application that can be
forwarded to.

=item Invalid JSONRPC request %s

There was an error parsing the JSONRPC request

=item Invalid JSONRPC request: Unknown error

An unexpected error occurred

=back

=head1 TODO

=over 4

=item Make error messages configurable/filterable

Right now, whatever ends up on $c->error gets returned to the client.
It would be nice to have a way to filter/massage these messages before
they are sent back to the client.

=item Make stash filterable before returning

Just like the error messages, it would be nice to be able to filter the
stash before returning so you can filter out keys you don't want to 
return to the client, or just return a certain list of keys. 
This all to make transparent use of JSONRPC and web easier.

=back

=head1 SEE ALSO

L<Catalyst::Manual>, 
L<Catalyst::Request>, L<Catalyst::Response>,  L<JSON::RPC::Common>, 

=head1 ACKNOWLEDGEMENTS

For the original implementation of this module:

Marcus Ramberg C<mramberg@cpan.org>
Christian Hansen
Yoshinori Sano
Jos Boumans (kane@cpan.org)
Michiel Ootjers (michiel@cpan.org)

=head1 AUTHORS

Original Author: Sergey Nosenko (darknos@cpan.org)

Actual Maintainer: Jose Luis Martinez Torres JLMARTIN (jlmartinez@capside.com)

L<http://code.google.com/p/catalyst-server-jsonrpc>

=head1 BUG REPORTS

Please submit all bugs regarding C<Catalyst::Plugin::Server::JSONRPC> to
C<http://code.google.com/p/catalyst-server-jsonrpc/issues/entry>

=head1 LICENSE

This library is free software, you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut