bare-rpc 1.3.7 → 1.3.9

package/README.md

@@ -29,126 +29,7 @@ console.log(replyBuffer.toString()) // pong
 
 ## API
 
-### `RPC`
-
-#### `const rpc = new RPC(stream[, onrequest])`
-
-Create an RPC instance using a duplex `stream`. `onrequest` is an optional callback run when a remote request is received. This is where processing and responding to an RPC request happens. `onrequest` receives a `RPCIncomingRequest` as an argument, for example:
-
-```js
-const rpc = new RPC(stream, (req) => {
-  if (req.command === 42) {
-    req.reply('pong')
-  }
-})
-```
-
-See [`RPCIncomingRequest`](#rpcincomingrequest) for properties and methods for processing the request.
-
-`onrequest` can also be a [`RPCCommandRouter`](#rpccommandrouter).
-
-#### `const req = rpc.request(command)`
-
-Create a request for `command`. `command` is a unique number that should be used to differentiate different requests on the remote end. Returns a `RPCOutgoingRequest`.
-
-### `RPCOutgoingRequest`
-
-#### `req.command`
-
-The command that the request was created with. A command is a unique number.
-
-#### `req.sent`
-
-A boolean for whether the request has been sent.
-
-#### `req.received`
-
-A boolean for whether the request has received a reply.
-
-#### `req.send([data[, encoding]])`
-
-Send the request with the provided `data`. `data` can be a buffer or a string which will be encoded using `encoding`.
-
-`.send()` can only be called once per request.
-
-#### `const data = await req.reply([encoding])`
-
-Await the reply from the remote end to the request. `encoding` can be defined for decoding the response `data` buffer back into a string.
-
-#### `const stream = req.createRequestStream([options])`
-
-Create a [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream for sending data with the request.
-
-#### `const stream = req.createResponseStream([options])`
-
-Create a [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream for receiving data in reply to the request.
-
-### `RPCIncomingRequest`
-
-#### `req.command`
-
-The command that the request was sent as. A command is a unique number.
-
-#### `req.data`
-
-The data buffer sent with the request.
-
-#### `req.sent`
-
-A boolean for whether a reply has been sent.
-
-#### `req.received`
-
-A boolean for whether the request has been received as a stream. See [`req.createRequestStream()`](#const-stream--reqcreaterequeststream) for receiving requests as a stream.
-
-#### `req.reply([data, [encoding]])`
-
-Reply to the request with the provided `data`. `data` can be a buffer or a string which will be encoded using `encoding`.
-
-#### `const stream = req.createRequestStream([options])`
-
-Create a `Readable` stream for receiving data from the request.
-
-#### `const stream = req.createResponseStream([options])`
-
-Create a `Writable` stream for sending data in reply to the request.
-
-### `RPCCommandRouter`
-
-An alternative way to define commands and handlers for receiving them.
-
-#### `const router = new RPC.CommandRouter()`
-
-Create a new command router. This router can then be used when creating an `rpc`. For example:
-
-```js
-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')
-```
-
-#### `router.respond(command[, options], async (req, data) => {})`
-
-Define a command and the handler for it. The callback for a command receives both the request (`req`) and the `data` buffer and can return a value to respond. If the request is responded to in the callback, the return value is ignored.
-
-Options include:
-
-```js
-options = {
-  // Encoding for incoming request
-  requestEncoding: c.raw,
-  // Encoding for outgoing response
-  responseEncoding: c.raw
-}
-```
+See the [`bare-rpc` reference](https://docs.pears.com/reference/bare/modules/bare-rpc).
 
 ## License
 

package/index.d.ts

@@ -19,11 +19,18 @@ declare const constants: {
 
 interface RPCIncomingEvent {
   readonly rpc: RPC
+  /** The command that the request was created with. A command is a unique number. */
   readonly command: number
+  /** The data buffer sent with the request. */
   readonly data: Buffer | null
 }
 
 declare class RPCIncomingEvent {
+  /**
+   * @param rpc - The `RPC` instance the event arrived on.
+   * @param command - The command number the event was sent with.
+   * @param data - The payload buffer sent with the event.
+   */
   constructor(rpc: RPC, command: number, data: Buffer)
 }
 
@@ -32,16 +39,45 @@ interface RPCIncomingRequest {
   readonly id: number
   readonly command: number
   readonly data: Buffer | null
+  /** A boolean for whether the request has been sent. */
   readonly sent: boolean
+  /** A boolean for whether the request has received a reply. */
   readonly received: boolean
 
+  /**
+   * Send a reply to the request. `data` may be a buffer or a string encoded using `encoding`.
+   * @param data - The payload to send: a `Buffer`, or a string encoded using `encoding`. Omit to
+   * send no data.
+   * @param encoding - The encoding used when `data` is a string (defaults to `utf8`).
+   * @throws {ALREADY_SENT} a response has already been sent for this request.
+   */
   reply(data?: Buffer | string | null, encoding?: BufferEncoding): void
 
+  /**
+   * Create a [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream for sending
+   * the streamed reply to the request.
+   * @param opts - Options for the returned
+   * [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream.
+   * @throws {ALREADY_SENT} a response has already been sent for this request.
+   */
   createResponseStream(opts?: WritableOptions): RPCOutgoingStream
+  /**
+   * Create a [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream for
+   * receiving the request's streamed data.
+   * @param opts - Options for the returned
+   * [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream.
+   * @throws {ALREADY_RECEIVED} the request has already been received.
+   */
   createRequestStream(opts?: ReadableOptions): RPCIncomingStream
 }
 
 declare class RPCIncomingRequest {
+  /**
+   * @param rpc - The `RPC` instance the request arrived on.
+   * @param id - The request id, used to correlate the reply with the request.
+   * @param command - The command number the request was sent with.
+   * @param data - The payload buffer sent with the request.
+   */
   constructor(rpc: RPC, id: number, command: number, data: Buffer)
 }
 
@@ -50,10 +86,20 @@ interface RPCOutgoingEvent {
   readonly command: number
   readonly sent: boolean
 
+  /**
+   * @param data - The payload to send: a `Buffer`, or a string encoded using `encoding`. Omit to
+   * send no data.
+   * @param encoding - The encoding used when `data` is a string (defaults to `utf8`).
+   * @throws {ALREADY_SENT} the event has already been sent.
+   */
   send(data?: Buffer | string | null, encoding?: BufferEncoding): void
 }
 
 declare class RPCOutgoingEvent {
+  /**
+   * @param rpc - The `RPC` instance to send the event on.
+   * @param command - The command number to send.
+   */
   constructor(rpc: RPC, command: number)
 }
 
@@ -64,19 +110,61 @@ interface RPCOutgoingRequest {
   readonly sent: boolean
   readonly received: boolean
 
+  /**
+   * @param data - The payload to send: a `Buffer`, or a string encoded using `encoding`. Omit to
+   * send no data.
+   * @param encoding - The encoding used when `data` is a string (defaults to `utf8`).
+   * @throws {ALREADY_SENT} the request has already been sent.
+   */
   send(data?: Buffer | string | null, encoding?: BufferEncoding): void
 
+  /**
+   * Await the reply from the remote end to the request. `encoding` can be defined for decoding the
+   * response `data` buffer back into a string.
+   * @param encoding - If given, decodes the reply payload to a string using this encoding; omit to
+   * receive the raw `Buffer`.
+   * @returns a promise that resolves with the remote end's reply payload, or rejects with the
+   * channel's teardown error if it closes before a reply arrives.
+   * @throws {ALREADY_RECEIVED} a reply is already being received for this request.
+   */
   reply(encoding?: BufferEncoding): Promise<Buffer | string | null>
 
+  /**
+   * Create a [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream for sending
+   * data with the request.
+   * @param opts - Options for the returned
+   * [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream.
+   * @throws {ALREADY_SENT} the request has already been sent.
+   */
   createRequestStream(opts?: WritableOptions): RPCOutgoingStream
+  /**
+   * Create a [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream for
+   * receiving data in reply to the request.
+   * @param opts - Options for the returned
+   * [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream.
+   * @throws {ALREADY_RECEIVED} the response has already been received.
+   */
   createResponseStream(opts?: ReadableOptions): RPCIncomingStream
 }
 
 declare class RPCOutgoingRequest {
+  /**
+   * @param rpc - The `RPC` instance to send the request on.
+   * @param id - The request id, used to correlate the reply with the request.
+   * @param command - The command number to send.
+   */
   constructor(rpc: RPC, id: number, command: number)
 }
 
 declare class RPCIncomingStream extends Readable {
+  /**
+   * @param rpc - The `RPC` instance the stream belongs to.
+   * @param request - The request the stream carries data for.
+   * @param type - Whether the stream carries the request body (`constants.type.REQUEST`) or the
+   * response body (`constants.type.RESPONSE`).
+   * @param opts - Options for the underlying
+   * [`Readable`](https://github.com/mafintosh/streamx#readable-stream) stream.
+   */
   constructor(
     rpc: RPC,
     request: RPCIncomingRequest | RPCOutgoingRequest,
@@ -86,6 +174,14 @@ declare class RPCIncomingStream extends Readable {
 }
 
 declare class RPCOutgoingStream extends Writable {
+  /**
+   * @param rpc - The `RPC` instance the stream belongs to.
+   * @param request - The request the stream carries data for.
+   * @param type - Whether the stream carries the request body (`constants.type.REQUEST`) or the
+   * response body (`constants.type.RESPONSE`).
+   * @param opts - Options for the underlying
+   * [`Writable`](https://github.com/mafintosh/streamx#writable-stream) stream.
+   */
   constructor(
     rpc: RPC,
     request: RPCIncomingRequest | RPCOutgoingRequest,
@@ -94,17 +190,94 @@ declare class RPCOutgoingStream extends Writable {
   )
 }
 
+/** A [`compact-encoding`](https://github.com/holepunchto/compact-encoding) encoding, such as `c.raw`. */
+interface RPCValueEncoding {
+  preencode(state: unknown, value: unknown): void
+  encode(state: unknown, value: unknown): void
+  decode(state: unknown): unknown
+}
+
+interface RPCCommandRouterOptions {
+  /** The encoding of request and response data for commands that set none (defaults to `c.raw`). */
+  valueEncoding?: RPCValueEncoding
+}
+
+interface RPCRespondOptions {
+  /** The encoding of both the request and the response data. */
+  valueEncoding?: RPCValueEncoding
+  /** The encoding to decode the request data with, or `null` to pass the raw buffer. */
+  requestEncoding?: RPCValueEncoding | null
+  /** The encoding to encode the response data with, or `null` to reply with the value as is. */
+  responseEncoding?: RPCValueEncoding | null
+}
+
+/**
+ * @param req - The incoming request.
+ * @param data - The request data, decoded with the request encoding of the command.
+ * @returns the response data, encoded with the response encoding of the command and sent as the
+ * reply unless the handler has already replied.
+ */
+type RPCRequestHandler = (req: RPCIncomingRequest, data: any) => unknown
+
+interface RPCCommandRouter {
+  /**
+   * Answer requests for `command` with `onrequest`, in place of any handler registered before.
+   * @param command - The command number to answer.
+   * @param opts - The encodings of the command.
+   * @param onrequest - The handler of the requests.
+   */
+  respond(command: number, onrequest: RPCRequestHandler): void
+  respond(command: number, opts: RPCRespondOptions, onrequest: RPCRequestHandler): void
+}
+
+declare class RPCCommandRouter {
+  /**
+   * @param opts - The default encodings of the commands.
+   */
+  constructor(opts?: RPCCommandRouterOptions)
+}
+
 interface RPC {
+  /**
+   * Whether there are no requests or responses currently in flight. Useful for determining when it
+   * is safe to tear down the underlying stream.
+   */
   readonly idle: boolean
 
+  /**
+   * @param command - A unique number identifying the event; the remote end differentiates events by
+   * it.
+   * @returns an `RPCOutgoingEvent`; call `send()` on it to dispatch the one-way event.
+   */
   event(command: number): RPCOutgoingEvent
+  /**
+   * @param command - A unique number identifying the request; the remote end differentiates
+   * requests by it.
+   * @returns an `RPCOutgoingRequest`; call `send()` on it to dispatch the request and `await
+   * reply()` for the response.
+   */
   request(command: number): RPCOutgoingRequest
 }
 
 declare class RPC {
-  constructor(stream: Duplex, onrequest: (req: RPCIncomingRequest) => void | Promise<void>)
+  /**
+   * @param stream - The duplex stream to frame RPC messages over, such as a pipe or socket.
+   * @param onrequest - Callback run for each incoming request or event, receiving an
+   * `RPCIncomingRequest` (or `RPCIncomingEvent`) to inspect and `reply()` to, or an
+   * `RPCCommandRouter` that answers each request with the handler of its command. Defaults to a
+   * no-op.
+   */
+  constructor(
+    stream: Duplex,
+    onrequest?: ((req: RPCIncomingRequest) => void | Promise<void>) | RPCCommandRouter
+  )
 }
 
+/**
+ * Create an RPC instance using a duplex `stream`. `onrequest` is an optional callback run when a
+ * remote request is received. This is where processing and responding to an RPC request happens.
+ * `onrequest` receives a `RPCIncomingRequest` as an argument.
+ */
 declare namespace RPC {
   export {
     type RPCIncomingEvent as IncomingEvent,
@@ -112,7 +285,12 @@ declare namespace RPC {
     type RPCIncomingRequest as IncomingRequest,
     type RPCOutgoingRequest as OutgoingRequest,
     type RPCIncomingStream as IncomingStream,
-    type RPCOutgoingStream as OutgoingStream
+    type RPCOutgoingStream as OutgoingStream,
+    RPCCommandRouter as CommandRouter,
+    type RPCCommandRouterOptions as CommandRouterOptions,
+    type RPCRespondOptions as RespondOptions,
+    type RPCRequestHandler as RequestHandler,
+    type RPCValueEncoding as ValueEncoding
   }
 }
 

package/index.js

@@ -29,6 +29,9 @@ module.exports = exports = class RPC {
     this._frame = -1
     this._draining = []
 
+    this._closed = false
+    this._error = null
+
     if (typeof onrequest === 'function') {
       onrequest = onrequest.bind(this)
     } else {
@@ -82,7 +85,7 @@ module.exports = exports = class RPC {
 
     let flushed = this._stream.write(header)
 
-    if (message.data) flushed = this._stream.write(message.data)
+    if (message.data && m.hasData(message)) flushed = this._stream.write(message.data)
 
     if (cb) {
       if (flushed) cb(null)
@@ -101,6 +104,11 @@ module.exports = exports = class RPC {
   }
 
   _sendRequest(request, data = null) {
+    // Once the channel has been torn down there is nowhere left to send the
+    // request. Skip registering it so that it never leaks into the maps; the
+    // awaiting reply is rejected through `RPCOutgoingRequest.reply()` instead.
+    if (this._closed) return
+
     this._outgoingRequests.set(request.id, request)
 
     this._sendMessage({
@@ -114,21 +122,33 @@ module.exports = exports = class RPC {
 
   _createRequestStream(request, isInitiator, opts) {
     if (isInitiator) {
-      this._outgoingRequests.set(request.id, request)
-
       request._requestStream = new OutgoingStream(this, request, t.REQUEST, opts)
 
+      // Once the channel has been torn down there is nowhere left to open the
+      // stream, so destroy it right away rather than leave it hanging.
+      if (this._closed) return request._requestStream.destroy(this._error)
+
+      this._outgoingRequests.set(request.id, request)
+
       request._requestStream.on('close', () => this._gcOutgoingRequest(request))
     } else {
-      this._incomingRequests.set(request.id, request)
-
       request._requestStream = new IncomingStream(this, request, t.REQUEST, opts)
 
+      if (this._closed) return request._requestStream.destroy(this._error)
+
+      this._incomingRequests.set(request.id, request)
+
       request._requestStream.on('close', () => this._incomingRequests.delete(request.id))
     }
   }
 
   _sendResponse(request, data) {
+    // Once the channel has been torn down there is nowhere left to send the
+    // response, so drop it rather than encode and write a message that would
+    // only be discarded. The reply is fire-and-forget, so there is nothing to
+    // settle.
+    if (this._closed) return
+
     this._sendMessage({
       type: t.RESPONSE,
       id: request.id,
@@ -140,16 +160,22 @@ module.exports = exports = class RPC {
 
   _createResponseStream(request, isInitiator, opts) {
     if (isInitiator) {
-      this._outgoingResponses.set(request.id, request)
-
       request._responseStream = new OutgoingStream(this, request, t.RESPONSE, opts)
 
+      // Once the channel has been torn down there is nowhere left to open the
+      // stream, so destroy it right away rather than leave it hanging.
+      if (this._closed) return request._responseStream.destroy(this._error)
+
+      this._outgoingResponses.set(request.id, request)
+
       request._responseStream.on('close', () => this._outgoingResponses.delete(request.id))
     } else {
-      this._incomingResponses.set(request.id, request)
-
       request._responseStream = new IncomingStream(this, request, t.RESPONSE, opts)
 
+      if (this._closed) return request._responseStream.destroy(this._error)
+
+      this._incomingResponses.set(request.id, request)
+
       request._responseStream.on('close', () => {
         this._incomingResponses.delete(request.id)
 
@@ -192,6 +218,11 @@ module.exports = exports = class RPC {
   }
 
   _teardown(err) {
+    // Mark the channel as closed so that any calls made from here on are
+    // rejected or destroyed immediately rather than left hanging.
+    this._closed = true
+    this._error = err
+
     this._ondrain(err)
 
     // Reject any request awaiting a plain reply. Requests whose response is
@@ -242,19 +273,26 @@ module.exports = exports = class RPC {
   }
 
   _onbeforeframe() {
-    if (this._buffered < 4) return
+    while (this._buffered >= 4) {
+      const buffer = this._buffer.length === 1 ? this._buffer[0] : b4a.concat(this._buffer)
 
-    const buffer = this._buffer.length === 1 ? this._buffer[0] : b4a.concat(this._buffer)
+      this._buffer = [buffer]
+      this._frame = 4 + c.uint32.decode(c.state(0, 4, buffer))
 
-    this._buffer = [buffer]
-    this._frame = 4 + c.uint32.decode(c.state(0, 4, buffer))
+      if (this._buffered < this._frame) return
 
-    this._onafterframe()
+      this._onframe()
+    }
   }
 
   _onafterframe() {
     if (this._buffered < this._frame) return
 
+    this._onframe()
+    this._onbeforeframe()
+  }
+
+  _onframe() {
     const buffer = this._buffer.length === 1 ? this._buffer[0] : b4a.concat(this._buffer)
 
     const frame = this._frame
@@ -264,7 +302,6 @@ module.exports = exports = class RPC {
     this._frame = -1
 
     this._onmessage(buffer.subarray(0, frame))
-    this._onbeforeframe()
   }
 
   async _onmessage(buffer) {

package/lib/messages.js

@@ -21,19 +21,31 @@ const error = {
   }
 }
 
+function hasData(m) {
+  switch (m.type) {
+    case t.REQUEST:
+      return m.stream === 0
+    case t.RESPONSE:
+      return !m.error && m.stream === 0
+    case t.STREAM:
+      return (m.stream & s.ERROR) === 0 && (m.stream & s.DATA) !== 0
+    default:
+      return false
+  }
+}
+
+exports.hasData = hasData
+
 exports.header = {
   preencode(state, m) {
     c.uint32.preencode(state, 0) // Frame
     c.uint.preencode(state, m.type)
     c.uint.preencode(state, m.id)
 
-    let hasData = false
-
     switch (m.type) {
       case t.REQUEST:
         c.uint.preencode(state, m.command)
         c.uint.preencode(state, m.stream)
-        if (m.stream === 0) hasData = true
         break
 
       case t.RESPONSE:
@@ -41,18 +53,16 @@ exports.header = {
         c.uint.preencode(state, m.stream)
 
         if (m.error) error.preencode(state, m.error)
-        else if (m.stream === 0) hasData = true
         break
 
       case t.STREAM:
         c.uint.preencode(state, m.stream)
 
         if (m.stream & s.ERROR) error.preencode(state, m.error)
-        else if (m.stream & s.DATA) hasData = true
         break
     }
 
-    if (hasData) c.uint.preencode(state, m.data ? m.data.byteLength : 0)
+    if (hasData(m)) c.uint.preencode(state, m.data ? m.data.byteLength : 0)
   },
   encode(state, m) {
     const frame = state.start
@@ -64,13 +74,10 @@ exports.header = {
     c.uint.encode(state, m.type)
     c.uint.encode(state, m.id)
 
-    let hasData = false
-
     switch (m.type) {
       case t.REQUEST:
         c.uint.encode(state, m.command)
         c.uint.encode(state, m.stream)
-        if (m.stream === 0) hasData = true
         break
 
       case t.RESPONSE:
@@ -78,24 +85,24 @@ exports.header = {
         c.uint.encode(state, m.stream)
 
         if (m.error) error.encode(state, m.error)
-        else if (m.stream === 0) hasData = true
         break
 
       case t.STREAM:
         c.uint.encode(state, m.stream)
 
         if (m.stream & s.ERROR) error.encode(state, m.error)
-        else if (m.stream & s.DATA) hasData = true
         break
     }
 
-    if (hasData) c.uint.encode(state, m.data ? m.data.byteLength : 0)
+    const data = hasData(m)
+
+    if (data) c.uint.encode(state, m.data ? m.data.byteLength : 0)
 
     const end = state.start
 
     state.start = frame
 
-    c.uint32.encode(state, end - start + (hasData && m.data ? m.data.byteLength : 0))
+    c.uint32.encode(state, end - start + (data && m.data ? m.data.byteLength : 0))
 
     state.start = end
   }

package/lib/outgoing-request.js

@@ -46,6 +46,12 @@ module.exports = class RPCOutgoingRequest {
 
     this.received = true
 
+    // If the channel was torn down before a response arrived there is nothing
+    // left to await, so reject with the teardown error rather than hang. This
+    // covers both requests sent after teardown and requests still awaiting a
+    // reply when teardown happens.
+    if (this.rpc._closed && !this._responded) this._reject(this.rpc._error)
+
     return encoding ? this._promise.then((data) => c.decode(encoding, data)) : this._promise
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-rpc",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "description": "librpc ABI compatible RPC for Bare",
   "exports": {
     ".": {
@@ -44,6 +44,7 @@
   "devDependencies": {
     "bare-buffer": "^3.0.1",
     "bare-ipc": "^1.1.0",
+    "bare-rpc-test": "^0.1.0",
     "brittle": "^3.2.1",
     "lunte": "^1.7.0",
     "prettier": "^3.4.2",