#jsonrpc API reference

JSON-RPC 2.0 (https://www.jsonrpc.org/specification) over HTTP: a client that calls remote methods, and a transport-agnostic server handle that dispatches an incoming request to the entry program's methods by name, via meta.callMain - the method name arrives on the wire, so it is resolved as a runtime string, not a func value. Built on json for the wire format and http for the client transport, so it needs the default jennifer binary.

params and a call's result are json.Values: the caller builds params with the json write API (json.list / json.map + json.append / json.set) and reads the result with the json accessors. Any client-side failure - a JSON-RPC error reply, a transport error (connection refused / timeout), or a malformed reply - surfaces as a single catchable Error{kind: "jsonrpc"}.

Server security. handle dispatches each request's method to a top-level func of that name in the entry program, so every top-level method taking one json.Value parameter is remotely reachable - there is no separate route registry. Name RPC handlers deliberately (a shared prefix, a dedicated dispatch file) and do not co-locate a handle-served program with privileged one-argument helpers. Authentication is the transport's job: gate on a header / token before calling handle. A handler that throws yields a generic -32603 reply (the thrown message is not put on the wire), so raise errors freely without leaking internals.

Import with import "jsonrpc.j" as jsonrpc;. See the jsonrpc guide for prose and examples.

#Functions

#jsonrpc.call(client as Client, method as string, params as json.Value)

Call a remote method and return its result. Any failure - a JSON-RPC error reply, a transport error (connection refused / timeout / malformed HTTP), or a malformed reply (no result, no error, or an id that does not match the request) - throws a catchable Error{kind: "jsonrpc"}.

Parameters

• client {Client} - the endpoint client
• method {string} - the method name
• params {json.Value} - the params (a json.list array or a json.map object; pass json.list() for a method that takes no arguments)

Returns {json.Value} - the result member of the reply

#jsonrpc.client(endpoint as string)

Build a client for a JSON-RPC endpoint.

Parameters

• endpoint {string} - the endpoint URL

Returns {Client} - a configured client

#jsonrpc.clientWith(endpoint as string, headers as map of string to string)

Build a client with extra request headers (e.g. Authorization).

Parameters

• endpoint {string} - the endpoint URL
• headers {map of string to string} - headers sent with every request

Returns {Client} - a configured client

#jsonrpc.handle(requestBody as string)

Dispatch a JSON-RPC request body and return the reply body (transport- agnostic: wire it to httpd / net however you serve). Each request's method names a top-level method func NAME(params as json.Value) in the program that imported this module; it is called with the request's params and must return a json.Value or a scalar (int / float / string / bool / null) as its result. A missing method is a -32601 reply, a thrown error a generic -32603 reply. A single request yields a single reply; a notification (no id) yields no reply (""); a batch (a JSON array) yields an array reply with the notification entries omitted ("" when the batch is all notifications).

Security. Every top-level one-json.Value-argument method is reachable by name (there is no route allow-list); the module-level doc explains how to scope handlers and where authentication belongs. A thrown handler error's message is not echoed to the client (only the generic -32603 text is), so internal detail does not leak.

Parameters

• requestBody {string} - the raw request JSON

Returns {string} - the reply JSON, or "" when no reply is owed

#jsonrpc.notify(client as Client, method as string, params as json.Value)

Send a notification: a request with no id, for which the server returns no reply. A delivered notification says nothing about whether the method ran, but a transport error (connection refused / timeout) still throws Error{kind: "jsonrpc"} - it means the request never reached the server.

Parameters

• client {Client} - the endpoint client
• method {string} - the method name
• params {json.Value} - the params (see call)

#Structs

#jsonrpc.Client

A client bound to a JSON-RPC HTTP endpoint. Value-semantic; build with client / clientWith.