.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "NetSDS::App::JSRPC 3pm" .TH NetSDS::App::JSRPC 3pm "2021-12-26" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" NetSDS::App::JSRPC \- JSON\-RPC server framework .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& #!/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 \*(AqNetSDS::App::JSRPC\*(Aq; \& \& # This method is available via JSON\-RPC \& sub sum { \& my ($self, $param) = @_; \& return $$param[0] + $$param[1]; \& } \& \& 1; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`NetSDS::App::JSRPC\*(C'\fR module implements framework for common JSON-RPC based server application. JSON-RPC is a \s-1HTTP\s0 based protocol providing remote procudure call (\s-1RPC\s0) functionality using \s-1JSON\s0 for requests and responses incapsulation. .PP This implementation is based on NetSDS::App::FCGI module and expected to be executed as FastCGI or \s-1CGI\s0 application. .PP Diagram of class inheritance: .PP .Vb 7 \& [NetSDS::App::JSRPC] \- JSON\-RPC server \& | \& [NetSDS::App::FCGI] \- CGI/FCGI application \& | \& [NetSDS::App] \- common application \& | \& [NetSDS::Class::Abstract] \- abstract class .Ve .PP Both request and response are JSON-encoded strings represented in \s-1HTTP\s0 protocol as data of 'application/json' \s-1MIME\s0 type. .SH "APPLICATION DEVELOPMENT" .IX Header "APPLICATION DEVELOPMENT" To develop new JSON-RPC server application you need to create application class inherited from \f(CW\*(C`NetSDS::App::JSRPC\*(C'\fR: .PP It's just empty application: .PP .Vb 1 \& #!/usr/bin/env perl \& \& JSApp\->run( \& conf_file => \*(Aq/etc/NetSDS/jsonapp.conf\*(Aq \& ); \& \& package JSApp; \& \& use base \*(AqNetSDS::App::JSRPC\*(Aq; \& \& 1; .Ve .PP Alsoe you may want to add some specific code for application startup: .PP .Vb 2 \& sub start { \& my ($self) = @_; \& \& connect_to_dbms(); \& query_for_external_startup_config(); \& do_other_initialization(); \& \& } .Ve .PP And of course you need to add methods providing necessary functions: .PP .Vb 2 \& sub send_sms { \& my ($self, $params) = @_; \& \& return $self\->{kannel}\->send( \& from => $params{\*(Aqfrom\*(Aq}, \& to => $params{\*(Aqto\*(Aq}, \& text => $params{\*(Aqtext\*(Aq}, \& ); \& } \& \& 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\*(Aqt kill SMSC! Need more power!"); \& } \& } .Ve .SH "ADVANCED FUNCTIONALITY" .IX Header "ADVANCED FUNCTIONALITY" \&\f(CW\*(C`NetSDS::App::JSRPC\*(C'\fR module provides two methods that may be used to implement more complex logic than average \s-1RPC\s0 to one class. .IP "\fB\fBcan_method()\fB\fR \- method availability checking" 4 .IX Item "can_method() - method availability checking" By default it is just wrapper around \f(CW\*(C`UNIVERSAL::can\*(C'\fR function. However it may be rewritten to check for methods in other classes or even construct necessary methods on the fly. .IP "\fB\fBprocess_call()\fB\fR \- method dispatching" 4 .IX Item "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. .PP This code describes logic of call processing: .PP .Vb 1 \& # It\*(Aqs not real code \& \& if (can_method($json_method)) { \& process_call($json_method, $json_params); \& } .Ve .PP For more details read documentation below. .SH "CLASS API" .IX Header "CLASS API" .IP "\fBnew(%params)\fR \- class constructor" 4 .IX Item "new(%params) - class constructor" It's internally used constructor that shouldn't be used from application directly. .IP "\fB\fBprocess()\fB\fR \- main JSON-RPC iteration" 4 .IX Item "process() - main JSON-RPC iteration" This is internal method that implements JSON-RPC call processing. .IP "\fBcan_method($method_name)\fR \- check method availability" 4 .IX Item "can_method($method_name) - check method availability" This method allows to check if some method is available for execution. By default it use \f(CW\*(C`UNIVERSAL::can\*(C'\fR but may be rewritten to implement more complex calls dispatcher. .Sp Paramters: method name (string) .Sp Return true if method execution allowed, false otherwise. .Sp Example: .Sp .Vb 5 \& # Rewrite can_method() to search in other class \& sub can_method { \& my ($self, $method) = @_; \& return Other::Class\->can($method); \& } .Ve .IP "\fBprocess_call($method, \f(CB$params\fB)\fR \- execute method call" 4 .IX Item "process_call($method, $params) - execute method call" Paramters: method name, parameters. .Sp Returns parameters from executed method as is. .Sp Example: .Sp .Vb 5 \& # Rewrite process_call() to use other class \& sub process_call { \& my ( $self, $method, $params ) = @_; \& return Other::Class\->$method($params); \& } .Ve .IP "\fB_request_parse($post_data)\fR \- parse \s-1HTTP POST\s0" 4 .IX Item "_request_parse($post_data) - parse HTTP POST" Paramters: \s-1HTTP POST\s0 data as string .Sp Returns: request method, parameters, id .IP "\fB_make_result(%params)\fR \- prepare positive response" 4 .IX Item "_make_result(%params) - prepare positive response" This is internal method for encoding JSON-RPC response string. .Sp Paramters: .RS 4 .IP "\fBid\fR \- the same as request Id (see specification)" 4 .IX Item "id - the same as request Id (see specification)" .PD 0 .IP "\fBresult\fR \- method result" 4 .IX Item "result - method result" .RE .RS 4 .PD .Sp Returns \s-1JSON\s0 encoded response message. .RE .IP "\fB_make_error(%params)\fR \- prepare error response" 4 .IX Item "_make_error(%params) - prepare error response" Internal method implementing JSON-RPC error response. .Sp Paramters: .RS 4 .IP "\fBid\fR \- the same as request Id (see specification)" 4 .IX Item "id - the same as request Id (see specification)" .PD 0 .IP "\fBcode\fR \- error code (default is \-32603, internal error)" 4 .IX Item "code - error code (default is -32603, internal error)" .IP "\fBmessage\fR \- error message" 4 .IX Item "message - error message" .RE .RS 4 .PD .Sp Returns \s-1JSON\s0 encoded error message .RE .SH "EXAMPLES" .IX Header "EXAMPLES" See \f(CW\*(C`samples/app_jsrpc.fcgi\*(C'\fR appliction. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1JSON\s0 .PP \&\s-1JSON::RPC2\s0 .PP \- JSON-RPC 1.0 .PP \- JSON-RPC 2.0 .SH "TODO" .IX Header "TODO" 1. Move error codes to constants to provide more clear code. .PP 2. Implement objects/classes support. .SH "AUTHOR" .IX Header "AUTHOR" Michael Bochkaryov .SH "LICENSE" .IX Header "LICENSE" Copyright (C) 2008\-2009 Net Style Ltd. .PP This program is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, \s-1MA\s0 02111\-1307 \s-1USA\s0