Catalyst-Plugin-Server-JSONRPC
view release on metacpan or search on metacpan
JSONRPC Plugin for Catalyst which we tried to make compatible with the
way Catalyst works with URLS. Main features are:
* Split JSONRPC methodNames by STRING to find out Controller.
* Single entrypoint for JSONRPC calls, like http://host.tld/rpc
* DispatchTypes (attributes) which work much the same as Catalyst
attrs
* JSONRPC Parameter handling transparent to Catalyst parameter
handling
HOW IT WORKS
The default behaviour will handle JSONRPC Requests sent to "/rpc" by
creating an OBJECT containing JSONRPC specific parameters in
"$c->req->jsonrpc".
Directly after, it will find out the Path of the Action to dispatch to,
by splitting methodName by ".":
Server Accessors
The following accessors are always available, whether you're in a
jsonrpc specific request or not
$c->server->jsonrpc->list_methods
Returns a HASHREF containing the available jsonrpc methods in
Catalyst as a key, and the "Catalyst::Action" object as a value.
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:
"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.
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
}
$c->req->parameters
Because JSONRPC parameters are a LIST, we can't 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.
$c->req->params
Alias of $c->req->parameters
$c->req->param
TODO
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.
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.
SEE ALSO
Catalyst::Manual, Catalyst::Request, Catalyst::Response,
JSON::RPC::Common,
ACKNOWLEDGEMENTS
For the original implementation of this module:
Marcus Ramberg "mramberg@cpan.org" Christian Hansen Yoshinori Sano Jos
Boumans (kane@cpan.org) Michiel Ootjers (michiel@cpan.org)
lib/Catalyst/Plugin/Server/JSONRPC.pm view on Meta::CPAN
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<.>:
lib/Catalyst/Plugin/Server/JSONRPC.pm view on Meta::CPAN
=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.
lib/Catalyst/Plugin/Server/JSONRPC.pm view on Meta::CPAN
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
lib/Catalyst/Plugin/Server/JSONRPC.pm view on Meta::CPAN
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
( run in 0.598 second using v1.01-cache-2.11-cpan-0a6323c29d9 )