bare-rpc

Reference for bare-rpc: a librpc ABI-compatible RPC layer for Bare that frames typed requests and replies over a duplex stream.

stable

bare-rpc is a librpc ABI-compatible RPC layer for Bare. It frames requests and replies over any duplex stream—an IPC pipe, a TCP socket, or a Bare Kit worklet channel—identifying each method by a unique command number. It's pure JavaScript. For the end-to-end pattern with generated types, see Type a native RPC bridge.

npm i bare-rpc

Usage

const RPC = require('bare-rpc')

const SEND_MESSAGE = 1

// Responder
const rpc = new RPC(stream, (req) => {
  if (req.command === SEND_MESSAGE) {
    console.log(req.data.toString())
    req.reply('ok')
  }
})

// Caller
const req = rpc.request(SEND_MESSAGE)
req.send('ping')
console.log((await req.reply()).toString())

API

RPC

`const rpc = new RPC(stream[, onrequest])`

Create an RPC instance over a duplex stream. onrequest is called with an RPCIncomingRequest whenever a remote request arrives (it may also be an RPCCommandRouter).

`const req = rpc.request(command)`

Create an outgoing request for command (a unique number). Returns an RPCOutgoingRequest.

RPCOutgoingRequest

Properties: req.command, req.sent, req.received.

`req.send([data[, encoding]])`

Send the request with data (a buffer or a string encoded with encoding). Callable once per request.

`const data = await req.reply([encoding])`

Await the remote reply, optionally decoding the buffer with encoding.

`req.createRequestStream([options])` · `req.createResponseStream([options])`

Create a writable stream for sending request data, or a readable stream for receiving streamed replies—the basis for the request-stream, response-stream, and duplex patterns.

RPCIncomingRequest

The object passed to onrequest: req.command, req.data, req.reply([data]), and the same createRequestStream / createResponseStream helpers for streaming responses.

RPCCommandRouter

An alternative way to define commands and their handlers. Pass a router as the onrequest argument to new RPC() instead of a plain callback.

`const router = new RPC.CommandRouter()`

Create a new command router.

`router.respond(command[, options], async (req, data) => {})`

Register a handler for command. The callback receives the RPCIncomingRequest as req and the decoded data. Returning a value from the callback sends it as the reply; if req.reply() is called inside the callback, the return value is ignored.

Options:

{
  requestEncoding: c.raw,   // compact-encoding for incoming data (default: raw buffer)
  responseEncoding: c.raw   // compact-encoding for outgoing reply (default: raw buffer)
}

Example:

const router = new RPC.CommandRouter()

router.respond(42, (req, data) => {
  console.log(data.toString()) // ping
  return Buffer.from('pong')
})

const rpc = new RPC(stream, router)

const req = rpc.request(42)
req.send('ping')

Builds on bare-stream. Pairs with hyperschema and compact-encoding to generate typed message codecs.