Registration Options

The "register" method takes a third argument which is a hash reference of named options that effects how the code should be handled.

with_plack_request

The first argument passed into the function will be a reference to the Plack::Request object, which is great for getting environment variables, and HTTP headers if you need those things in processing your RPC.

 $rpc->register( 'some_func', \&some_func, { with_plack_request => 1 });

 sub some_func {
     my ($plack_request, $other_arg) = @_;
     ...
 }

TIP: Before using this option consider whether you might be better served by a Plack::Middleware component. For example, if you want to do HTTP Basic Auth on your requests, use Plack::Middleware::Basic::Auth instead.

log_request_as

This is a filter function for manipulating the parameters before being logged. This is especially useful for code that accepts passwords.

The first parameter to the code ref here will be the method name, the second is the parameter array reference. The code ref is expected to return the modified param, but be careful. The array ref being passed in has had the plack_request removed, and so the array ref is a copy of the one that will be eventually passed to the handler function, so modifying the array is safe. However, if an element of the array is another reference, that is not a copy, and so modifying that will require extra care.

    sub {
        my ($method, $params) = @_;
        $params->[1] = 'xxx'; # works
        $params->[0]{password} = 'xxx'; # broken
        $params->[0] = { %{$params->[0]}, password => 'xxx' }; # works.

        return $params; # required
    }

Advanced Error Handling

 use JSON::RPC::Dispatcher;
 my $rpc = JSON::RPC::Dispatcher->new;

 sub guess {
     my ($guess) = @_;
    if ($guess == 10) {
            return 'Correct!';
    }
    elsif ($guess > 10) {
        die [986, 'Too high.'];
    }
    else {
        die [987, 'Too low.'];
    }
 }

 $rpc->register( 'guess', \&guess );

 $rpc->to_app;

NOTE: If you don't care about setting error codes and just want to set an error message, you can simply "die" in your RPC and your die message will be inserted into the "error_data" method.

Logging

 use Log::Any::Adapter;
 use Log::Log4perl;
 Log::Log4perl::init('/path/to/log4perl.conf');
 Log::Any::Adapter->set('Log::Log4perl');

That's how easy it is to start logging. You'll of course still need to configure the log4perl.conf file, which goes well beyond the scope of this document. And you'll also need to install Log::Any::Adapter::Log4perl to use this example.

JSON::RPC::Dispatcher logs the following:

INFO

Requests and responses.

DEBUG

In the case when there is an unhandled exception, anything other than the error message will be put into a debug log entry.

TRACE

If an exception is thrown that has a "trace" method, then its contents will be put into a trace log entry.

ERROR

All errors that are gracefully handled by the system will be put into an error log entry.

FATAL

All errors that are not gracefully handled by the system will be put into a fatal log entry. Most of the time this means there's something wrong with the request document itself.