Urchin.JSONRPC (Urchin v0.2.0)

Encoding, decoding and classification of JSON-RPC 2.0 messages.

The 2025-11-25 revision carries exactly one JSON-RPC message per transport frame (HTTP request batching was removed), so this module operates on single messages.

Decoded messages are returned as tagged tuples so callers can branch on the kind without re-inspecting the map:

{:request, id, method, params}
{:notification, method, params}
{:response, id, result}
{:error_response, id, error}

Summary

Types

decoded()

id()

Functions

classify(term)

Classifies an already-decoded JSON term (a map) into a tagged message.

decode(binary)

Parses a JSON binary into a single classified JSON-RPC message.

encode!(message)

Encodes a message map to a JSON binary.

error_response(id, error)

Builds a JSON-RPC error response map. id may be nil for errors that cannot be associated with a request (e.g. parse errors), serialized as JSON null.

notification(method, params \\ nil)

Builds a JSON-RPC notification map.

request(id, method, params \\ nil)

Builds a JSON-RPC request map.

result(id, result)

Builds a successful JSON-RPC response map.

Types

decoded()

@type decoded() ::
  {:request, id(), String.t(), map()}
  | {:notification, String.t(), map()}
  | {:response, id(), term()}
  | {:error_response, id() | nil, map()}

id()

@type id() :: String.t() | integer()

Functions

classify(term)

@spec classify(term()) :: {:ok, decoded()} | {:error, Urchin.Error.t()}

Classifies an already-decoded JSON term (a map) into a tagged message.

Arrays are rejected: this revision does not support JSON-RPC batching.

decode(binary)

@spec decode(binary()) :: {:ok, decoded()} | {:error, Urchin.Error.t()}

Parses a JSON binary into a single classified JSON-RPC message.

Returns {:ok, decoded} or {:error, Urchin.Error.t()}. Malformed JSON yields a parse error; structurally invalid messages yield an invalid-request error.

encode!(message)

@spec encode!(map()) :: binary()

Encodes a message map to a JSON binary.

error_response(id, error)

@spec error_response(id() | nil, Urchin.Error.t()) :: map()

Builds a JSON-RPC error response map. id may be nil for errors that cannot be associated with a request (e.g. parse errors), serialized as JSON null.

notification(method, params \\ nil)

@spec notification(String.t(), map() | nil) :: map()

Builds a JSON-RPC notification map.

request(id, method, params \\ nil)

@spec request(id(), String.t(), map() | nil) :: map()

Builds a JSON-RPC request map.

result(id, result)

@spec result(id(), term()) :: map()

Builds a successful JSON-RPC response map.