clamator-protocol 0.1.3

Polyglot RPC protocol layer (pre-1.0; API may break in minor versions).

clamator-protocol

Pure JSON-RPC 2.0 protocol primitives plus Pydantic-derived envelope types for clamator. No I/O, ever — anything that touches a network, filesystem, or process belongs in a transport adapter. Requires Pydantic v2 (pinned >=2.5); v1 is not supported.

Install

pip install clamator-protocol

When you reach for this

• Defining a Contract (in tests, in custom tooling).
• Building a custom transport adapter that needs the wire-envelope models, the Transport and Dispatcher interfaces, or the reserved JSON-RPC error codes.

If you only consume generated clients and servers, you don't import this package directly — your transport package (clamator-over-memory, clamator-over-redis) re-exports the few symbols you need.

Defining a contract

The Python counterpart of a Zod contract is a Contract with MethodEntry rows that bind Pydantic models to handler attribute names:

arith = Contract(
    service="arith",
    methods={
        "add": MethodEntry(params_model=AddP, result_model=AddR, handler_attr="add"),
        "ping": MethodEntry(params_model=PingP, result_model=None, handler_attr="ping"),
    },
)

(Verbatim from py/packages/over-memory/tests/test_loopback.py:22-28.)

When clamator-protocol is consumed alongside generated wrappers from @clamator/codegen, the Contract and MethodEntry values are produced by codegen — the snippet above is what direct authors of test contracts or custom tooling write.

The single methods dict holds both methods and notifications. A MethodEntry with result_model=None declares a notification (the snippet's ping is one); there is no separate notifications= kwarg. handler_attr is the attribute the dispatcher resolves on the registered handler instance — it is independent of the wire-side method name (the dict key) and is conventionally snake_case.

Key exports

• Contract, MethodEntry — declare a service's methods and notifications with Pydantic models for params and results.
• RpcError — the error type you raise from a handler to surface a structured JSON-RPC error to the caller.
• ClamatorProtocolError, ClamatorTransportError — distinguishable error classes for protocol-level vs. transport-level failures.
• Transport, Dispatcher — interfaces a custom transport adapter implements.

Codegen workflow

clamator's codegen is an npm package (@clamator/codegen) regardless of which language consumes the output. For a Py-only project, run the CLI against your Zod contract source and emit the Python wrappers into your package's source tree:

npx @clamator/codegen --src contracts --out-py src/myapp/_generated

Commit the emitted files alongside your code — they are vendored generated artifacts. Re-run codegen on contract changes; for drift detection, also pass --manifest and diff the manifest in CI (see @clamator/codegen for the full pattern).

The Python package then imports AddParams, AddResult, ArithClient, ArithService, and arith_contract from myapp._generated.arith.

Method or notification?

Both methods and notifications send a request envelope; only methods produce a response envelope. Pick by the caller's needs, not the handler's.

• Use a method when the caller needs to know whether the operation succeeded, get a value back, surface a structured RpcError, or sequence subsequent calls on completion. Methods carry a request id and the caller waits for the matching response or a timeout.
• Use a notification when the caller is doing fire-and-forget work where neither success/failure nor a return value matters in the moment — telemetry, cache-busting, status pings. Notifications have no request id and produce no response; the caller cannot tell whether the handler ran, succeeded, or threw.

If you would otherwise add a method that returns nothing solely to confirm delivery, prefer a method returning an empty Pydantic model over a notification — the response envelope is the confirmation. Pick a notification only when "did this run?" is genuinely not a question the caller will ever ask.

Errors

Raise RpcError from a handler to surface a structured JSON-RPC error to the caller. The constructor takes a code, a message, and an optional data payload:

from clamator_protocol import RpcError

RPC_FORBIDDEN = -32001  # application-defined; outside the reserved -32600..-32099 range


def test_rpc_error_construction():
    err = RpcError(RPC_FORBIDDEN, "forbidden", {"reason": "no-token"})
    assert err.code == RPC_FORBIDDEN
    assert err.message == "forbidden"
    assert err.data == {"reason": "no-token"}

(Verbatim from py/packages/protocol/tests/test_rpc_error.py:1-10.)

Reserved JSON-RPC error codes (-32600 to -32603 for protocol-level errors, -32000 to -32099 reserved for transport implementations) are owned by the protocol layer; pick application-specific codes outside that range.

What the client sees:

• A handler that raises RpcError(code, message, data) produces an error response carrying that exact code/message/data on the client side; the proxy method re-raises an RpcError with the same fields.
• A handler that raises any other exception is caught by the protocol layer and wrapped: clients receive RpcError(code=-32603, message="Internal error", data={...}) with exception details in data.
• A client-side call that exceeds default_timeout_ms raises clamator_protocol.ClamatorTransportError("call timeout") from the transport layer, NOT asyncio.TimeoutError. The same exception class surfaces when no server is consuming the request stream — there is no distinct "no consumer" error.
• Envelope-level parse and validation failures use the JSON-RPC reserved codes: -32700 (parse error), -32600 (invalid request), -32601 (method not found), -32602 (invalid params), -32603 (internal error).

Authorization

clamator has no authorization at the protocol or transport layer. Any process that can reach the underlying transport — a Redis instance for over-redis, the parent process for over-memory — can call any registered method or send any notification on any registered service.

Apply caller-identity checks at the boundary: a gateway (typically an HTTP server in front of the typed proxy) enforces who-can-call-what before invoking the proxy method. For network-substrate transports, deploy the substrate behind a network you trust (TLS, AUTH, ACLs, private VPC).

Links

• Sibling (TypeScript): @clamator/protocol
• Codegen: @clamator/codegen (run from TS side; consume the generated Python output)
• Design spec: docs/2026-05-07-clamator-design.md
• Agent rules: AGENTS.md