++ed by:

1 non-PAUSE user.

Abe Timmerman

NAME

Dancer::Plugin::RPC::JSONRPC - Dancer Plugin to register jsonrpc2 methods.

SYNOPSIS

In the Controler-bit:

    use Dancer::Plugin::RPC::JSONRPC;
    jsonrpc '/endpoint' => {
        publish   => 'pod',
        arguments => ['MyProject::Admin']
    };

and in the Model-bit (MyProject::Admin):

    package MyProject::Admin;
    
    =for jsonrpc rpc.abilities rpc_show_abilities
    
    =cut
    
    sub rpc_show_abilities {
        return {
            # datastructure
        };
    }
    1;

DESCRIPTION

This plugin lets one bind an endpoint to a set of modules with the new jsonrpc keyword.

jsonrpc '/endpoint' => \%publisher_arguments;

\%publisher_arguments

callback => $coderef [optional]

The callback will be called just before the actual rpc-code is called from the dispatch table. The arguments are positional: (full_request, method_name).

    my Dancer::RPCPlugin::CallbackResult $continue = $callback
        ? $callback->(request(), $method_name, @method_args)
        : callback_success();

The callback should return a Dancer::RPCPlugin::CallbackResult instance:

  • on_success

        callback_success()
  • on_failure

        callback_fail(
            error_code    => <numeric_code>,
            error_message => <error message>
        )
code_wrapper => $coderef [optional]

The codewrapper will be called with these positional arguments:

1. $call_coderef
2. $package (where $call_coderef is)
3. $method_name
4. @arguments

The default code_wrapper-sub is:

    sub {
        my $code = shift;
        my $pkg  = shift;
        $code->(@_);
    };
publisher => <config | pod | \&code_ref>

The publiser key determines the way one connects the rpc-method name with the actual code.

publisher => 'config'

This way of publishing requires you to create a dispatch-table in the app's config YAML:

    plugins:
        "RPC::JSONRPC":
            '/endpoint':
                'MyProject::Admin':
                    admin.someFunction: rpc_admin_some_function_name
                'MyProject::User':
                    user.otherFunction: rpc_user_other_function_name

The Config-publisher doesn't use the arguments value of the %publisher_arguments hash.

publisher => 'pod'

This way of publishing enables one to use a special POD directive =for jsonrpc to connect the rpc-method name to the actual code. The directive must be in the same file as where the code resides.

    =for jsonrpc admin.someFunction rpc_admin_some_function_name

The POD-publisher needs the arguments value to be an arrayref with package names in it.

publisher => \&code_ref

This way of publishing requires you to write your own way of building the dispatch-table. The code_ref you supply, gets the arguments value of the %publisher_arguments hash.

A dispatch-table looks like:

    return {
        'admin.someFuncion' => dispatch_item(
            package => 'MyProject::Admin',
            code    => MyProject::Admin->can('rpc_admin_some_function_name'),
        ),
        'user.otherFunction' => dispatch_item(
            package => 'MyProject::User',
            code    => MyProject::User->can('rpc_user_other_function_name'),
        ),
    }
arguments => <anything>

The value of this key depends on the publisher-method chosen.

=for jsonrpc jsonrpc-method-name sub-name

This special POD-construct is used for coupling the jsonrpc-methodname to the actual sub-name in the current package.

INTERNAL

unjson

Deserializes the string as Perl-datastructure.

jsonrpc_error_response

Returns a jsonrpc error response as a hashref.

jsonrpc_response

Returns a jsonrpc response as a hashref.

build_dispatcher_from_config

Creates a (partial) dispatch table from data passed from the (YAML)-config file.

build_dispatcher_from_pod

Creates a (partial) dispatch table from data provided in POD.

COPYRIGHT

(c) MMXVI - Abe Timmerman <abeltje@cpan.org>.