Catalyst::Plugin::Server::JSONRPC -- Catalyst JSONRPC Server Plugin
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'; }
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
The default behaviour will handle JSONRPC Requests sent to /rpc by creating an OBJECT containing JSONRPC specific parameters in $c->req->jsonrpc.
/rpc
$c->req->jsonrpc
Directly after, it will find out the Path of the Action to dispatch to, by splitting methodName by .:
.
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.
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...
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 hello.world:
hello.world
package Catalyst::Controller::Hello sub world : JSONRPC {}
Identical version of attribute JSONRPC
JSONRPC
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 ping:
ping
package Catalyst::Controller::Hello sub ping : JSONRPCGlobal {}
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 say.hello:
say.hello
package Catalyst::Controller::Hello sub hello : JSONRPCPath('/say/hello') {}
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: a.foo.method wedoofoohere foo.getaround
a.foo.method
wedoofoohere
foo.getaround
package Catalyst::Controller::Hello sub hello : JSONRPCPath('foo') {}
Once you've used the plugin, you'll have an $c->request->jsonrpc accessor which will return an Catalyst::Plugin::Server::JSONRPC object.
Catalyst::Plugin::Server::JSONRPC
You can query this object as follows:
Boolean indicating whether the current request has been initiated via JSONRPC
Returns a Catalyst::Plugin::Server::JSONRPC::Config object. See the CONFIGURATION below on how to use and configure it.
Catalyst::Plugin::Server::JSONRPC::Config
CONFIGURATION
The body of the original JSONRPC call
The name of the original method called via JSONRPC
A list of parameters supplied by the JSONRPC call
The JSON body that will be sent back to the JSONRPC client
Allows you to set jsonrpc fault code and message
The following accessors are always available, whether you're in a jsonrpc specific request or not
Returns a HASHREF containing the available jsonrpc methods in Catalyst as a key, and the Catalyst::Action object as a value.
Catalyst::Action
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
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.
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 }
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.
Alias of $c->req->parameters
The following system functions are available to the public.,
returns a list of available RPC methods.
The JSON-RPC response must contain a single parameter, which may contain an array (LIST), struct (HASH) or a string (STRING). To define the return values in your subroutine, you can alter $c->stash in three different ways.
When defining $c->stash->{jsonrpc}, the JSONRPC server will return these values to the client.
When there is no $c->stash->{jsonrpc} set, it will return the complete $c->stash
$c->stash->{jsonrpc}
$c->stash
The JSONRPC Plugin accepts the following configuration options, which can be set in the standard Catalyst way (See perldoc Catalyst for details):
perldoc Catalyst
Your::App->config( jsonrpc => { key => value } );
You can look up any of the config parameters this package uses at runtime by calling:
$c->server->jsonrpc->config->KEY
This specifies the entry point for your jsonrpc server; all requests are dispatched from there. This is the url any JSONRCP client should post to. You can change this to any Regex wish.
Regex
The default is: qr!^(/?)rpc(/|$)!i, which matches on a top-level path begining with rpc preceeded or followed by an optional /, like this:
qr!^(/?)rpc(/|$)!i
rpc
/
http://your-host.tld/rpc
This specifies the prefix of the forward url.
For example, with a prefix of rpc, and a method foo, the forward path would be come /rpc/foo.
foo
/rpc/foo
The default is '' (empty).
This is a STRING used to split your method on, allowing you to use a hierarchy in your method calls.
For example, with a seperator of . the method call demo.echo would be forwarded to /demo/echo. To make demo_echo forward to the same path, you would change the seperator to _,
demo.echo
/demo/echo
demo_echo
_
The default is ., splitting methods on a single .
Make the arguments in $c->req->jsonrpc->params available as $c->req->params.
$c->req->jsonrpc->params
$c->req->params
Defaults to true.
Make system errors in $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".
$c->error
Defaults to false.
There is no corresponding method in your application that can be forwarded to.
There was an error parsing the JSONRPC request
An unexpected error occurred
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.
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.
Catalyst::Manual, Catalyst::Request, Catalyst::Response, JSON::RPC::Common,
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)
mramberg@cpan.org
Sergey Nosenko (darknos@cpan.org)
Please submit all bugs regarding Catalyst::Plugin::Server::JSONRPC to bug-catalyst-plugin-server-jsonrpc@rt.cpan.org
bug-catalyst-plugin-server-jsonrpc@rt.cpan.org
This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
To install Catalyst::Plugin::Server::JSONRPC, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Catalyst::Plugin::Server::JSONRPC
CPAN shell
perl -MCPAN -e shell install Catalyst::Plugin::Server::JSONRPC
For more information on module installation, please visit the detailed CPAN module installation guide.