NAME ==== `Cro::RPC::JSON` - convenience shortcut for JSON-RPC 2.0 SYNOPSIS ======== use Cro::HTTP::Server; use Cro::HTTP::Router; use Cro::RPC::JSON; class JRPC-Actor is export { method foo ( Int :$a, Str :$b ) is json-rpc { return "$b and $a"; } proto method bar (|) is json-rpc { * } multi method bar ( Str :$a! ) { "single named Str param" } multi method bar ( Int $i, Num $n, Str $s ) { "Int, Num, Str positionals" } multi method bar ( *%options ) { [ "slurpy hash:", %options ] } method non-json (|) { "I won't be called!" } } sub routes is export { route { post -> "api" { my $actor = JRPC-Actor.new; json-rpc $actor; } post -> "api2" { json-rpc -> Cro::RPC::JSON::Request $jrpc-req { { to-user => "a string", num => pi } } } } } DESCRIPTION =========== This module provides a convenience shortcut for handling JSON-RPC requests by exporting `json-rpc` function to be used inside a [Cro::HTTP::Router](https://cro.services/docs/reference/cro-http-router) `post` handler. The function takes one argument which could either be a [`Code`](https://docs.perl6.org/type/Code.html) object or an instantiated class. When code object is used: json-rpc -> $jrpc-request { ... } sub jrpc-handler ( Cro::RPC::JSON::Request $jrpc-request ) { ... } json-rpc -> &jrpc-handler; it is supplied with parsed JSON-RPC request (`Cro::RPC::JSON::Request`). When a class instance is used a JSON-RPC call is mapped on a class method with the same name as in RPC request. The class method must have `is json-rpc` trait applied (see [SYNOPSIS](#SYNOPSIS) example). Methods without the trait are not considered part of JSON-RPC API and calling such method would return -32601 error code back to the caller. The class implementing the API is called *JSON-RPC actor class* or just *actor*. If the only parameter of a JSON-RPC method has `Cro::RPC::JSON::Request` type then the method will receive the JSON-RPC request object as parameter. Otherwise `params` object of JSON-RPC request is used and matched against actor class method signature. If `params` is an object then it is considered a set of named parameters. If it's an array then all params are passed as positionals. For example: params => { a => 1, b => "aa" } will match to method foo ( Int :$a, Str :$b ) { ... } Whereas params => [ 1, "aa" ] will match to method foo( Int $a, Str $b ) { ... } If parameters fail to match to the method signature then -32601 error would be returned. To handle various set of parameters one could use either slurpy parameters or `multi` methods. In second case the `is json-rpc` trait must be applied to method's `proto` declaration. **NOTE** that `multi` method cannot have the request object as a parameter. This is due to possible ambiguity in a situation when there is a match to one `multi` candidate by parameters and by the request object to another. SEE ALSO ======== [Cro](https://cro.services) AUTHOR ====== Vadim Belman LICENSE ======= Artistic License 2.0 See the LICENSE file in this distribution.