Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
JSON::RPC::Dispatcher(User Contributed Perl DocumentatJSON::RPC::Dispatcher(3)

NAME
       JSON::RPC::Dispatcher - A JSON-RPC 2.0 server.

VERSION
       version 0.0508

SYNOPSIS
       In app.psgi:

	use JSON::RPC::Dispatcher;

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

	sub add_em {
	   my @params =	@_;
	   my $sum = 0;
	   $sum	+= $_ for @params;
	   return $sum;
	}
	$rpc->register(	'sum', \&add_em	);

	$rpc->to_app;

       Then run	it:

	plackup	app.psgi

       Now you can then	call this service via a	GET like:

	http://example.com/?method=sum;params=[2,3,5];id=1

       Or by posting JSON to it	like this:

	{"jsonrpc":"2.0","method":"sum","params":[2,3,5],"id":"1"}

       And you'd get back:

	{"jsonrpc":"2.0","result":10,"id":"1"}

DESCRIPTION
       Using this app you can make any PSGI/Plack aware	server a JSON-RPC 2.0
       server. This will allow you to expose your custom functionality as a
       web service in a	relatiely tiny amount of code, as you can see above.

       This module follows the draft specficiation for JSON-RPC	2.0. More
       information can be found	at
       <http://groups.google.com/group/json-rpc/web/json-rpc-2-0>.

   Registration	Options
       The "register" method cannot be used to register	methods	that start
       with m/^rpc\./.	Per the	JSON-RPC 2.0 specification, these are reserved
       for rpc-internal	extensions.

       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
       You can also throw error	messages rather	than just "die"ing, which will
       throw an	internal server	error. To throw	a specific type	of error,
       "die", "carp", or "confess", an array reference starting	with the error
       code, then the error message, and finally ending	with error data
       (optional). When	JSON::RPC::Dispatcher detects this, it will throw that
       specific	error message rather than a standard internal server error.

	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
       JSON::RPC::Dispatcher allows for	logging	via Log::Any. This way you can
       set up logs with	Log::Dispatch, Log::Log4perl, or any other logging
       system that Log::Any supports now or in the future. It's	relatively
       easy to set up. In your app.psgi	simply add a block like	this:

	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.

PREREQS
       Moose JSON Plack	Test::More Log::Any

SUPPORT
       Repository
	   <http://github.com/plainblack/JSON-RPC-Dispatcher>

       Bug Reports
	   <http://github.com/plainblack/JSON-RPC-Dispatcher/issues>

SEE ALSO
       You may also want to check out these other modules, especially if
       you're looking for something that works with JSON-RPC 1.x.

       Dispatchers
	   Other modules that compete directly with this module, though
	   perhaps on other protocol versions.

	   JSON::RPC
	       An excellent and	fully featured both client and server for
	       JSON-RPC	1.1.

	   POE::Component::Server::JSONRPC
	       A JSON-RPC 1.0 server for POE. I	couldn't get it	to work, and
	       it doesn't look like it's maintained.

	   Catalyst::Plugin::Server::JSONRPC
	       A JSON-RPC 1.1 dispatcher for Catalyst.

	   CGI-JSONRPC
	       A CGI/Apache based JSON-RPC 1.1 dispatcher. Looks to be
	       abandoned in alpha state. Also includes Apache2::JSONRPC.

	   AnyEvent::JSONRPC::Lite
	       An AnyEvent JSON-RPC 1.x	dispatcher.

	   Sledge::Plugin::JSONRPC
	       JSON-RPC	1.0 dispatcher for Sledge MVC framework.

       Clients
	   Modules that	you'd use to access various dispatchers.

	   JSON::RPC::Common
	       A JSON-RPC client for 1.0, 1.1, and 2.0.	Haven't	used it, but
	       looks pretty feature complete.

	   RPC::JSON
	       A simple	and good looking JSON::RPC 1.x client. I haven't tried
	       it though.

AUTHOR
       JT Smith	<jt_at_plainblack_com>

LEGAL
       JSON::RPC::Dispatcher is	Copyright 2009-2010 Plain Black	Corporation
       (<http://www.plainblack.com/>) and is licensed under the	same terms as
       Perl itself.

perl v5.32.0			  2016-01-22	      JSON::RPC::Dispatcher(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | PREREQS | SUPPORT | SEE ALSO | AUTHOR | LEGAL

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=JSON::RPC::Dispatcher&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help