NAME

Catalyst::Plugin::JSONRPC::Server::Dispatcher - pure JSON-RPC 2.0 protocol engine

DESCRIPTION

The Catalyst-free engine behind Catalyst::Plugin::JSONRPC::Server: it parses and validates JSON-RPC 2.0 envelopes (single and batch), routes to registered handlers, and produces spec-compliant result/error responses. It has no knowledge of Catalyst or of any application domain.

METHODS

register( $method => $coderef )

Register a handler for a JSON-RPC method name (a non-empty string). The handler is invoked as $coderef->($params). Return the result; to signal a JSON-RPC error throw a Catalyst::Plugin::JSONRPC::Server::Error (or die with a { code, message, data } hashref). A plain die, or any unrecognised exception, becomes -32603 and its text is not leaked. Croaks on a bad method name or non-coderef handler. Returns the dispatcher (chainable).

dispatch( $json_text )

Parse and dispatch a JSON-RPC 2.0 request (a single object or a batch array). Returns a response hashref for a single call, an arrayref for a batch, or undef when there is nothing to send (a lone notification or an all-notification batch). Never dies: malformed JSON yields a -32700 parse-error response.

encode( $data )

Encode a response data structure to canonical UTF-8 JSON text. Dies if $data contains a value the JSON codec cannot serialize; prefer encode_safe for untrusted handler output.

encode_safe( $data )

Like encode, but never dies: any response element that will not serialize (a blessed object without TO_JSON, a coderef, a cyclic structure) is replaced by a -32603 "Internal error" (its id preserved), so one bad handler result cannot 500 the whole request or corrupt a batch.

ATTRIBUTES

max_batch

Maximum number of elements accepted in a batch array (default 1000; 0 = unlimited). A batch beyond this is rejected with a single -32600 "Batch too large".