--- name: "NetSDS::App::JSRPC" section: "3pm" platform: "linux" package: "libnetsds-perl" version: "1.301-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/NetSDS::App::JSRPC" --- # NetSDS::App::JSRPC(3pm) JSON-RPC server framework ## NAME NetSDS::App::JSRPC - JSON-RPC server framework ## SYNOPSIS ``` #!/usr/bin/env perl # JSON-RPC server use 5.8.0; use warnings; use strict; JServer->run(); 1; # Server application logic package JServer; use base 'NetSDS::App::JSRPC'; # This method is available via JSON-RPC sub sum { my ($self, $param) = @_; return $$param[0] + $$param[1]; } 1; ``` ## DESCRIPTION `"NetSDS::App::JSRPC"` module implements framework for common JSON-RPC based server application. JSON-RPC is a HTTP based protocol providing remote procudure call (RPC) functionality using JSON for requests and responses incapsulation. This implementation is based on NetSDS::App::FCGI module and expected to be executed as FastCGI or CGI application. Diagram of class inheritance: ``` [NetSDS::App::JSRPC] - JSON-RPC server | [NetSDS::App::FCGI] - CGI/FCGI application | [NetSDS::App] - common application | [NetSDS::Class::Abstract] - abstract class ``` Both request and response are JSON-encoded strings represented in HTTP protocol as data of 'application/json' MIME type. ## APPLICATION DEVELOPMENT To develop new JSON-RPC server application you need to create application class inherited from `"NetSDS::App::JSRPC"`: It's just empty application: ``` #!/usr/bin/env perl JSApp->run( conf_file => '/etc/NetSDS/jsonapp.conf' ); package JSApp; use base 'NetSDS::App::JSRPC'; 1; ``` Alsoe you may want to add some specific code for application startup: ``` sub start { my ($self) = @_; connect_to_dbms(); query_for_external_startup_config(); do_other_initialization(); } ``` And of course you need to add methods providing necessary functions: ``` sub send_sms { my ($self, $params) = @_; return $self->{kannel}->send( from => $params{'from'}, to => $params{'to'}, text => $params{'text'}, ); } sub kill_smsc { my ($self, $params) = @_; # 1M of MT SM should be enough to kill SMSC! # Otherwise we call it unbreakable :-) for (my $i=1; $<100000000; $i++) { $self->{kannel}->send( %mt_sm_parameters, ); } if (smsc_still_alive()) { return $self->error("Can't kill SMSC! Need more power!"); } } ``` ## ADVANCED FUNCTIONALITY `"NetSDS::App::JSRPC"` module provides two methods that may be used to implement more complex logic than average RPC to one class. - **can\_method()** - method availability checking By default it is just wrapper around `"UNIVERSAL::can"` function. However it may be rewritten to check for methods in other classes or even construct necessary methods on the fly. - **process\_call()** - method dispatching By default it just call local class method with the same name as in JSON-RPC call. Of course it can be overwritten and process query in some other way. This code describes logic of call processing: ``` # It's not real code if (can_method($json_method)) { process_call($json_method, $json_params); } ``` For more details read documentation below. ## CLASS API - **new(%params)** - class constructor It's internally used constructor that shouldn't be used from application directly. - **process()** - main JSON-RPC iteration This is internal method that implements JSON-RPC call processing. - **can\_method($method\_name)** - check method availability This method allows to check if some method is available for execution. By default it use `"UNIVERSAL::can"` but may be rewritten to implement more complex calls dispatcher. Paramters: method name (string) Return true if method execution allowed, false otherwise. Example: ``` # Rewrite can_method() to search in other class sub can_method { my ($self, $method) = @_; return Other::Class->can($method); } ``` - **process\_call($method, $params)** - execute method call Paramters: method name, parameters. Returns parameters from executed method as is. Example: ``` # Rewrite process_call() to use other class sub process_call { my ( $self, $method, $params ) = @_; return Other::Class->$method($params); } ``` - **\_request\_parse($post\_data)** - parse HTTP POST Paramters: HTTP POST data as string Returns: request method, parameters, id - **\_make\_result(%params)** - prepare positive response This is internal method for encoding JSON-RPC response string. Paramters: - **id** - the same as request Id (see specification) - **result** - method result Returns JSON encoded response message. - **\_make\_error(%params)** - prepare error response Internal method implementing JSON-RPC error response. Paramters: - **id** - the same as request Id (see specification) - **code** - error code (default is -32603, internal error) - **message** - error message Returns JSON encoded error message ## EXAMPLES See `"samples/app_jsrpc.fcgi"` appliction. ## SEE ALSO JSON JSON::RPC2 \ - JSON-RPC 1.0 \ - JSON-RPC 2.0 ## TODO 1\. Move error codes to constants to provide more clear code. 2\. Implement objects/classes support. ## AUTHOR Michael Bochkaryov \ ## LICENSE Copyright (C) 2008-2009 Net Style Ltd. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA