view release on metacpan or  search on metacpan

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

    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')

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

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

  package Catalyst::Controller::Hello
  sub hello : JSONRPCPath('/say/hello') {}

=item JSONRPCRegex('foo')

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

The following example will be accessible by example methods:
C<< a.foo.method >>
C<< wedoofoohere >>