rpc

import rpc

JSON-RPC 2.0: calling methods on another program, and answering its calls, over HTTP, WebSockets, sockets, pipes, or any stream of bytes.

JSON-RPC is a small, stateless protocol for calling methods in another program. It defines the messages and nothing more: which methods exist is up to the programs using it, and the messages travel over whatever connects them. A message is a small JSON object: a request names a method and carries its parameters and an id, the response carries the same id and a result or an error, and a notification is a request nobody answers. Either side may send any of them, so the protocol has no fixed client and server.

The module is built in layers, each usable on its own:

• Request, Notification, Response and RpcError are the messages, and encode(), decode() and read() turn them to and from JSON, checking every rule of the specification.
• A Service holds the handler for each method a program serves, and answers every message it is given with them.
• Over HTTP, http_handler() serves a service from a route of an http server, and HttpClient calls one.
• HeaderFraming, LineFraming and MessageFraming tell messages apart in a stream: by a Content-Length header in front of each, one to a line, or one to each read of a transport that keeps them apart itself.
• A transport carries the bytes of a connection: StdioTransport over the program’s own standard streams, SocketTransport over a socket, ProcessTransport to a child process, WebSocketTransport over a WebSocket, and the two ends of a pipe() between isolates.
• An Endpoint is a service on a connection: it answers what arrives, and calls the other side with requests and notifications of its own.
• serve() gives every connection to a listening socket an endpoint of its own, across a pool of isolates.

import rpc
import isolate

var ends = rpc.pipe()

isolate.spawn(@(transport) {
  import rpc

  rpc.endpoint(transport)
    .on_request('greet', @(params) => 'Hello, ${params.name}!')
    .serve()
}, ends[1])

var client = rpc.endpoint(ends[0])

echo client.request('greet', { name: 'Zuri' })  # Hello, Zuri!
client.close()

The rpc API

Every public name in rpc, wherever it is declared. Each links to the page that documents it.

Submodules

Functions

endpoint()

rpc.endpoint(transport) -> Endpoint

A new Endpoint over transport, framing its messages with a HeaderFraming.

Parameters

• transport (any) — A transport; see {rpc.transport}.

Returns Endpoint

stdio()

rpc.stdio() -> StdioTransport

A transport over the program’s own standard input and output.

Returns StdioTransport

socket()

rpc.socket(socket) -> SocketTransport

A transport over a connected socket from net.

Parameters

• socket (any) — A connected TcpStream, UnixStream or TlsStream.

Returns SocketTransport

process()

rpc.process(child) -> ProcessTransport

A transport to a child process, over its standard input and output.

Parameters

• child (os.Process) — A child spawned with stdin and stdout both 'pipe'.

Returns ProcessTransport

websocket()

rpc.websocket(socket) -> WebSocketTransport

A transport over a WebSocket from http.websocket.

Parameters

• socket (http.websocket.WebSocket) — An open WebSocket, from websocket.accept() or websocket.connect().

Returns WebSocketTransport

2026, Richard Ore and Zuri contributors