Catalyst::Plugin::JSONRPC::Server

Generic, app-agnostic JSON-RPC 2.0 server plugin for Catalyst. It implements the protocol (envelope parsing, single + batch, notifications, the standard error codes) and knows nothing about your domain.

Synopsis

package MyApp;
use Catalyst qw/+Catalyst::Plugin::JSONRPC::Server/;
__PACKAGE__->setup;

# in a controller action:
sub rpc :Path('/rpc') :Args(0) {
    my ( $self, $c ) = @_;
    $c->jsonrpc_register( add => sub ($params) { $params->{a} + $params->{b} } );
    $c->jsonrpc_dispatch;   # reads the raw request body itself
}

Methods

• $c->jsonrpc_register($method => $coderef): register a handler. The handler is called as $coderef->($params); return the result, or throw a Catalyst::Plugin::JSONRPC::Server::Error (or die with { code, message, data }) to return a JSON-RPC error. A plain die becomes -32603 without leaking the message.
• $c->jsonrpc_dispatch($body = undef): dispatch a JSON-RPC request. Pass the raw body, or omit it to have the plugin read the raw request body. Writes the HTTP response (200 + JSON, or 204 for a notification) and returns the data.

Author

Mike Whitaker mike@altrion.org

Built with tool assistance from Claude Code/(mostly) Opus 4.8 to accelerate code generation and maximise test coverage (and reduce typing :D).

With thanks to

• Jesse Vincent for /superpowers (https://github.com/obra/superpowers) and the AGENTS.md boilerplate
• Curtis "Ovid" Poe for /paad (https://github.com/Ovid/paad)

for providing an agentic development framework that keeps code authority firmly where it belongs.

Iteratively reviewed by Finn Kempers finn@shadow.cat with analysis from ZCode/GLM-5.2.

License

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License, as distributed with Perl.