bare-rpc 1.3.8 → 1.4.0

package/README.md

@@ -29,126 +29,19 @@ console.log(replyBuffer.toString()) // pong
 
 ## API
 
-### `RPC`
+See the [`bare-rpc` reference](https://docs.pears.com/reference/bare/modules/bare-rpc).
 
-#### `const rpc = new RPC(stream[, onrequest])`
+## Untrusted peers
 
-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:
+`bare-rpc` does not trust the remote end to send valid frames. If a frame is larger than `maxFrameSize`, cannot be decoded, or breaks the protocol, the connection fails: `stream` is destroyed with an `RPCError`, and every request and stream in flight is rejected or destroyed with that error. The error code tells you why:
 
-```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.
+- `FRAME_TOO_LARGE`: The length prefix is larger than `maxFrameSize`. This is checked before the rest of the frame is read.
+- `UNKNOWN_MESSAGE`: The frame has a message type that `bare-rpc` does not know.
+- `INVALID_MESSAGE`: The frame cannot be decoded, the stream ends partway through a frame, or the frame is one that a valid peer never sends. Examples are a response or stream message with an id of 0, a stream message with an invalid set of flags, and a new request that reuses the id of a request that is still in flight.
 
-#### `req.data`
+A frame that refers to a request or stream that has already finished, or that was never known, is ignored. The same goes for frames that arrive for a stream that has already ended or been destroyed.
 
-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
-}
-```
+If you read the response to a request as a stream but the remote end replies without one, the reply arrives on the response stream as a single chunk, unless it is empty, and the stream then ends. An error reply destroys the response stream with that error.
 
 ## 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,62 @@ 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. If the remote end replies without a stream, the reply
+   * arrives as a single chunk, unless it is empty, and the stream then ends.
+   * @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 +175,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 +191,113 @@ 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. A
+   * request for a command with no handler is answered with an error whose code is
+   * `UNKNOWN_COMMAND`, and an event for such a command is dropped.
+   * @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 RPCOptions {
+  /**
+   * The largest frame to accept from the remote end, in bytes, counting the 4-byte length prefix. A
+   * larger frame fails the connection with `FRAME_TOO_LARGE` as soon as its length prefix arrives.
+   * Defaults to 16 MiB.
+   */
+  maxFrameSize?: number
+}
+
 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.
+   * @param opts - Options for the connection.
+   *
+   * The remote end is not trusted to send valid frames. A frame that is too large, cannot be
+   * decoded, or breaks the protocol fails the connection: `stream` is destroyed with an `RPCError`
+   * whose code is `FRAME_TOO_LARGE`, `UNKNOWN_MESSAGE` or `INVALID_MESSAGE`, and every request and
+   * stream in flight is rejected or destroyed with it. A frame that refers to a request or stream
+   * that has already finished, or that was never known, is ignored.
+   */
+  constructor(
+    stream: Duplex,
+    onrequest?: ((req: RPCIncomingRequest) => void | Promise<void>) | RPCCommandRouter,
+    opts?: RPCOptions
+  )
 }
 
+/**
+ * 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 +305,13 @@ 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,
+    type RPCOptions as Options
   }
 }
 

package/index.js

@@ -1,6 +1,7 @@
 const safetyCatch = require('safety-catch')
 const b4a = require('b4a')
 const c = require('compact-encoding')
+const { isEnding } = require('bare-stream')
 const m = require('./lib/messages')
 const errors = require('./lib/errors')
 const { type: t, stream: s } = require('./lib/constants')
@@ -12,17 +13,42 @@ const OutgoingRequest = require('./lib/outgoing-request')
 const OutgoingStream = require('./lib/outgoing-stream')
 const CommandRouter = require('./lib/command-router')
 
+const DEFAULT_MAX_FRAME_SIZE = 16 * 1024 * 1024
+const MAX_PENDING_RESPONSES = 1024
+
+const streamFlags = new Set()
+
+for (const direction of [s.REQUEST, s.RESPONSE]) {
+  for (const action of [
+    s.OPEN,
+    s.CLOSE,
+    s.CLOSE | s.ERROR,
+    s.PAUSE,
+    s.RESUME,
+    s.DATA,
+    s.END,
+    s.DESTROY,
+    s.DESTROY | s.ERROR
+  ]) {
+    streamFlags.add(direction | action)
+  }
+}
+
 module.exports = exports = class RPC {
-  constructor(stream, onrequest = noop) {
+  constructor(stream, onrequest = noop, opts = {}) {
+    const { maxFrameSize = DEFAULT_MAX_FRAME_SIZE } = opts
+
     this._stream = stream
+    this._maxFrameSize = maxFrameSize
     this._id = 0
 
     this._outgoingRequests = new Map()
     this._outgoingResponses = new Map()
     this._incomingRequests = new Map()
     this._incomingResponses = new Map()
-    this._pendingRequests = new Set()
     this._pendingResponses = new Set()
+    this._unansweredRequests = new Set()
+    this._highestRequestId = 0
 
     this._buffer = []
     this._buffered = 0
@@ -42,12 +68,14 @@ module.exports = exports = class RPC {
     this._onerror = this._onerror.bind(this)
     this._onclose = this._onclose.bind(this)
     this._ondata = this._ondata.bind(this)
+    this._onend = this._onend.bind(this)
     this._ondrain = this._ondrain.bind(this)
 
     this._stream
       .on('error', this._onerror)
       .on('close', this._onclose)
       .on('data', this._ondata)
+      .on('end', this._onend)
       .on('drain', this._ondrain)
   }
 
@@ -59,7 +87,6 @@ module.exports = exports = class RPC {
       this._outgoingResponses.size === 0 &&
       this._incomingRequests.size === 0 &&
       this._incomingResponses.size === 0 &&
-      this._pendingRequests.size === 0 &&
       this._pendingResponses.size === 0
     )
   }
@@ -85,7 +112,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)
@@ -149,6 +176,8 @@ module.exports = exports = class RPC {
     // settle.
     if (this._closed) return
 
+    this._onanswered(request)
+
     this._sendMessage({
       type: t.RESPONSE,
       id: request.id,
@@ -168,6 +197,8 @@ module.exports = exports = class RPC {
 
       this._outgoingResponses.set(request.id, request)
 
+      if (this._onanswered(request)) request._responseStream._continueOpen()
+
       request._responseStream.on('close', () => this._outgoingResponses.delete(request.id))
     } else {
       request._responseStream = new IncomingStream(this, request, t.RESPONSE, opts)
@@ -186,15 +217,23 @@ module.exports = exports = class RPC {
   }
 
   _sendError(request, err) {
+    this._onanswered(request)
+
     this._sendMessage({
       type: t.RESPONSE,
       id: request.id,
       stream: 0,
-      error: err,
+      error: m.toError(err),
       data: null
     })
   }
 
+  // Returns whether the remote end had already opened its response stream.
+  _onanswered(request) {
+    this._unansweredRequests.delete(request.id)
+    return this._pendingResponses.delete(request.id)
+  }
+
   _gcOutgoingRequest(request) {
     // The entry must stay reachable for as long as an incoming message might
     // still target it; until the response has settled and, if the request was
@@ -255,13 +294,19 @@ module.exports = exports = class RPC {
     this._outgoingResponses.clear()
     this._incomingRequests.clear()
     this._incomingResponses.clear()
-    this._pendingRequests.clear()
     this._pendingResponses.clear()
+    this._unansweredRequests.clear()
 
     for (const stream of streams) stream.destroy(err)
   }
 
+  _fail(err) {
+    this._stream.destroy(err)
+  }
+
   _ondata(data) {
+    if (this._stream.destroying) return
+
     this._buffer.push(data)
     this._buffered += data.byteLength
 
@@ -272,20 +317,39 @@ module.exports = exports = class RPC {
     }
   }
 
-  _onbeforeframe() {
-    if (this._buffered < 4) return
+  _onend() {
+    if (this._buffered > 0) this._fail(errors.INVALID_MESSAGE('Truncated frame'))
+  }
 
-    const buffer = this._buffer.length === 1 ? this._buffer[0] : b4a.concat(this._buffer)
+  _onbeforeframe() {
+    while (this._buffered >= 4 && !this._stream.destroying) {
+      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))
+
+      if (this._frame > this._maxFrameSize) {
+        return this._fail(
+          errors.FRAME_TOO_LARGE(
+            `Frame of ${this._frame} bytes exceeds the limit of ${this._maxFrameSize} bytes`
+          )
+        )
+      }
 
-    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
@@ -295,55 +359,74 @@ module.exports = exports = class RPC {
     this._frame = -1
 
     this._onmessage(buffer.subarray(0, frame))
-    this._onbeforeframe()
   }
 
-  async _onmessage(buffer) {
+  _onmessage(buffer) {
     let message
     try {
       message = m.message.decode(c.state(0, buffer.length, buffer))
     } catch (err) {
-      safetyCatch(err)
-
-      return this._stream.destroy(err)
+      return this._fail(
+        err instanceof errors ? err : errors.INVALID_MESSAGE(`Malformed message: ${err.message}`)
+      )
     }
 
-    switch (message.type) {
-      case t.REQUEST: {
-        const request =
-          message.id === 0
-            ? new IncomingEvent(this, message.command, message.data)
-            : new IncomingRequest(this, message.id, message.command, message.data)
-
-        try {
-          await this._onrequest(request)
-        } catch (err) {
-          safetyCatch(err)
-
-          if (message.id) this._sendError(request, err)
-          else this._stream.destroy(err)
-        }
-        break
-      }
-      case t.RESPONSE:
-        try {
+    const violation = protocolViolation(message)
+
+    if (violation !== null) return this._fail(errors.INVALID_MESSAGE(violation))
+
+    // Handling a message can run user code, such as stream listeners, so route
+    // anything it throws through the connection failure path rather than let it
+    // escape into the underlying stream.
+    try {
+      switch (message.type) {
+        case t.REQUEST:
+          this._onrequestmessage(message)
+          break
+        case t.RESPONSE:
           this._onresponse(message)
-        } catch (err) {
-          safetyCatch(err)
-        }
-        break
-      case t.STREAM:
-        try {
+          break
+        case t.STREAM:
           this._onstream(message)
-        } catch (err) {
-          safetyCatch(err)
-        }
+      }
+    } catch (err) {
+      this._fail(err)
     }
   }
 
-  _onresponse(message) {
-    if (message.id === 0) return
+  async _onrequestmessage(message) {
+    // A repeated id can only be caught while its request is tracked here, which
+    // is also the only time it could corrupt any state.
+    if (
+      this._unansweredRequests.has(message.id) ||
+      this._incomingRequests.has(message.id) ||
+      this._outgoingResponses.has(message.id)
+    ) {
+      return this._fail(errors.INVALID_MESSAGE(`Request '${message.id}' is already in flight`))
+    }
+
+    let request
+
+    if (message.id === 0) {
+      request = new IncomingEvent(this, message.command, message.data)
+    } else {
+      request = new IncomingRequest(this, message.id, message.command, message.data)
+
+      this._unansweredRequests.add(message.id)
+      this._highestRequestId = Math.max(this._highestRequestId, message.id)
+    }
 
+    try {
+      await this._onrequest(request)
+    } catch (err) {
+      safetyCatch(err)
+
+      if (message.id) this._sendError(request, err)
+      else this._stream.destroy(err)
+    }
+  }
+
+  _onresponse(message) {
     const request = this._outgoingRequests.get(message.id)
     if (request === undefined) return
 
@@ -352,17 +435,36 @@ module.exports = exports = class RPC {
       this._gcOutgoingRequest(request)
 
       request._reject(message.error)
+
+      if (request._responseStream !== null) request._responseStream.destroy(message.error)
+
+      this._releaseRequestStream(request, message.error)
     } else if (message.stream === 0) {
       request._responded = true
       this._gcOutgoingRequest(request)
 
       request._resolve(message.data)
+
+      const stream = request._responseStream
+
+      if (isPushable(stream)) {
+        if (message.data.byteLength > 0) stream.push(message.data)
+        stream.push(null)
+      }
+
+      this._releaseRequestStream(request, null)
     }
   }
 
-  _onstream(message) {
-    if (message.id === 0) return
+  // Once the request is answered, a request stream that the remote end never
+  // opened will never be read, and would otherwise wait for its open forever.
+  _releaseRequestStream(request, err) {
+    const stream = request._requestStream
+
+    if (stream !== null && !stream._acknowledged) stream.destroy(err)
+  }
 
+  _onstream(message) {
     if (message.stream & s.OPEN) this._onstreamopen(message)
     else if (message.stream & s.CLOSE) this._onstreamclose(message)
     else if (message.stream & s.PAUSE) this._onstreampause(message)
@@ -373,123 +475,56 @@ module.exports = exports = class RPC {
   }
 
   _onstreamopen(message) {
-    let stream
-
     if (message.stream & s.REQUEST) {
-      const request = this._outgoingRequests.get(message.id)
-      if (request === undefined) {
-        this._pendingRequests.add(message.id)
-        return
-      }
+      const stream = this._outgoingStream(message)
+      if (stream !== null) stream._continueOpen()
+    } else {
+      const request = this._outgoingResponses.get(message.id)
 
-      stream = request._requestStream
+      if (request !== undefined) return request._responseStream._continueOpen()
 
-      if (stream === null || stream._pendingOpen === null) {
-        this._pendingRequests.add(message.id)
-        return
-      }
-    } else if (message.stream & s.RESPONSE) {
-      const request = this._outgoingResponses.get(message.id)
-      if (request === undefined) {
-        this._pendingResponses.add(message.id)
+      // The remote end opens its response stream as soon as it is created,
+      // which may be before its request arrives or before the handler here
+      // creates the response stream. Remember the open until the response
+      // stream is created, the request is answered, or the remote end destroys
+      // its stream. Any other open is for a request that has already been
+      // answered.
+      if (this._pendingResponses.has(message.id)) return
+
+      if (!this._unansweredRequests.has(message.id) && message.id <= this._highestRequestId) {
         return
       }
 
-      stream = request._responseStream
-
-      if (stream === null || stream._pendingOpen === null) {
-        this._pendingResponses.add(message.id)
-        return
+      if (this._pendingResponses.size >= MAX_PENDING_RESPONSES) {
+        return this._fail(errors.INVALID_MESSAGE('Too many response streams opened early'))
       }
-    } else {
-      return
-    }
 
-    stream._continueOpen()
+      this._pendingResponses.add(message.id)
+    }
   }
 
   _onstreamclose(message) {
-    let stream
-
-    if (message.stream & s.REQUEST) {
-      const request = this._incomingRequests.get(message.id)
-      if (request === undefined) return
-
-      stream = request._requestStream
-    } else if (message.stream & s.RESPONSE) {
-      const request = this._incomingResponses.get(message.id)
-      if (request === undefined) return
-
-      stream = request._responseStream
-    } else {
-      return
-    }
-
+    const stream = this._incomingStream(message)
     if (stream === null) return
+
     if (message.error) stream.destroy(message.error)
     else stream.push(null)
   }
 
   _onstreampause(message) {
-    let stream
-
-    if (message.stream & s.REQUEST) {
-      const request = this._outgoingRequests.get(message.id)
-      if (request === undefined) return
-
-      stream = request._requestStream
-    } else if (message.stream & s.RESPONSE) {
-      const request = this._outgoingResponses.get(message.id)
-      if (request === undefined) return
-
-      stream = request._responseStream
-    } else {
-      return
-    }
-
-    if (stream === null) return
-    stream.cork()
+    const stream = this._outgoingStream(message)
+    if (stream !== null) stream.cork()
   }
 
   _onstreamresume(message) {
-    let stream
-
-    if (message.stream & s.REQUEST) {
-      const request = this._outgoingRequests.get(message.id)
-      if (request === undefined) return
-
-      stream = request._requestStream
-    } else if (message.stream & s.RESPONSE) {
-      const request = this._outgoingResponses.get(message.id)
-      if (request === undefined) return
-
-      stream = request._responseStream
-    } else {
-      return
-    }
-
-    if (stream === null) return
-    stream.uncork()
+    const stream = this._outgoingStream(message)
+    if (stream !== null) stream.uncork()
   }
 
   _onstreamdata(message) {
-    let stream
-
-    if (message.stream & s.REQUEST) {
-      const request = this._incomingRequests.get(message.id)
-      if (request === undefined) return
-
-      stream = request._requestStream
-    } else if (message.stream & s.RESPONSE) {
-      const request = this._incomingResponses.get(message.id)
-      if (request === undefined) return
+    const stream = this._incomingStream(message)
+    if (!isPushable(stream)) return
 
-      stream = request._responseStream
-    } else {
-      return
-    }
-
-    if (stream === null) return
     if (stream.push(message.data) === false) {
       this._sendMessage({
         type: t.STREAM,
@@ -502,45 +537,23 @@ module.exports = exports = class RPC {
   }
 
   _onstreamend(message) {
-    let stream
-
-    if (message.stream & s.REQUEST) {
-      const request = this._incomingRequests.get(message.id)
-      if (request === undefined) return
-
-      stream = request._requestStream
-    } else if (message.stream & s.RESPONSE) {
-      const request = this._incomingResponses.get(message.id)
-      if (request === undefined) return
-
-      stream = request._responseStream
-    } else {
-      return
-    }
-
-    if (stream === null) return
-    stream.push(null)
+    const stream = this._incomingStream(message)
+    if (stream !== null) stream.push(null)
   }
 
   _onstreamdestroy(message) {
-    let stream
-
-    if (message.stream & s.REQUEST) {
-      const request = this._outgoingRequests.get(message.id)
-      if (request === undefined) return
+    if (message.stream & s.RESPONSE) this._pendingResponses.delete(message.id)
 
-      stream = request._requestStream
-    } else if (message.stream & s.RESPONSE) {
-      const request = this._outgoingResponses.get(message.id)
-      if (request === undefined) return
+    const stream = this._outgoingStream(message)
+    if (stream !== null) stream.destroy(message.error)
+  }
 
-      stream = request._responseStream
-    } else {
-      return
-    }
+  _incomingStream(message) {
+    return findStream(message, this._incomingRequests, this._incomingResponses)
+  }
 
-    if (stream === null) return
-    stream.destroy(message.error)
+  _outgoingStream(message) {
+    return findStream(message, this._outgoingRequests, this._outgoingResponses)
   }
 
   _ondrain(err = null) {
@@ -554,4 +567,43 @@ module.exports = exports = class RPC {
 
 exports.CommandRouter = CommandRouter
 
+// Messages that decode cleanly but that no valid peer ever sends, as derived
+// from what the outgoing side encodes.
+function protocolViolation(message) {
+  switch (message.type) {
+    case t.REQUEST:
+      if (message.stream === 0) return null
+      if (message.stream !== s.OPEN) return `Invalid request stream flags '${message.stream}'`
+      if (message.id === 0) return 'Stream request without an id'
+      return null
+
+    case t.RESPONSE:
+      if (message.id === 0) return 'Response without an id'
+      if (message.stream === 0) return null
+      if (message.stream !== s.OPEN || message.error) {
+        return `Invalid response stream flags '${message.stream}'`
+      }
+      return null
+
+    case t.STREAM:
+      if (message.id === 0) return 'Stream message without an id'
+      if (!streamFlags.has(message.stream)) return `Invalid stream flags '${message.stream}'`
+      return null
+  }
+}
+
+function findStream(message, requests, responses) {
+  if (message.stream & s.REQUEST) {
+    const request = requests.get(message.id)
+    return request === undefined ? null : request._requestStream
+  }
+
+  const request = responses.get(message.id)
+  return request === undefined ? null : request._responseStream
+}
+
+function isPushable(stream) {
+  return stream !== null && !stream.destroying && !isEnding(stream)
+}
+
 function noop() {}

package/lib/command-router.js

@@ -1,4 +1,5 @@
 const c = require('compact-encoding')
+const errors = require('./errors')
 
 module.exports = class RPCCommandRouter {
   constructor(opts = {}) {
@@ -30,7 +31,11 @@ module.exports = class RPCCommandRouter {
   async _onrequest(req) {
     const responder = this._responders.get(req.command)
 
-    if (responder === undefined) return
+    if (responder === undefined) {
+      if (req.id === undefined) return
+
+      throw errors.UNKNOWN_COMMAND(`Unknown command ${req.command}`)
+    }
 
     const { onrequest, requestEncoding, responseEncoding } = responder
 

package/lib/errors.d.ts

@@ -1,5 +1,8 @@
 declare class RPCError extends Error {
   static UNKNOWN_MESSAGE(msg: string): RPCError
+  static UNKNOWN_COMMAND(msg: string): RPCError
+  static INVALID_MESSAGE(msg: string): RPCError
+  static FRAME_TOO_LARGE(msg: string): RPCError
   static ALREADY_SENT(msg: string): RPCError
   static ALREADY_RECEIVED(msg: string): RPCError
   static CHANNEL_CLOSED(msg: string): RPCError

package/lib/errors.js

@@ -16,6 +16,18 @@ module.exports = class RPCError extends Error {
     return new RPCError(msg, 'UNKNOWN_MESSAGE', RPCError.UNKNOWN_MESSAGE)
   }
 
+  static UNKNOWN_COMMAND(msg) {
+    return new RPCError(msg, 'UNKNOWN_COMMAND', RPCError.UNKNOWN_COMMAND)
+  }
+
+  static INVALID_MESSAGE(msg) {
+    return new RPCError(msg, 'INVALID_MESSAGE', RPCError.INVALID_MESSAGE)
+  }
+
+  static FRAME_TOO_LARGE(msg) {
+    return new RPCError(msg, 'FRAME_TOO_LARGE', RPCError.FRAME_TOO_LARGE)
+  }
+
   static ALREADY_SENT(msg) {
     return new RPCError(msg, 'ALREADY_SENT', RPCError.ALREADY_SENT)
   }

package/lib/incoming-stream.js

@@ -1,5 +1,6 @@
 const { Readable } = require('bare-stream')
 const { type: t, stream: s } = require('./constants')
+const { toError } = require('./messages')
 
 module.exports = class RPCIncomingStream extends Readable {
   constructor(rpc, request, type, opts) {
@@ -41,7 +42,7 @@ module.exports = class RPCIncomingStream extends Readable {
           type: t.STREAM,
           id: this._request.id,
           stream: this._mask | s.DESTROY | s.ERROR,
-          error: err,
+          error: toError(err),
           data: null
         },
         cb

package/lib/messages.js

@@ -21,19 +21,36 @@ const error = {
   }
 }
 
+exports.toError = function toError(err) {
+  if (typeof err === 'object' && err !== null && typeof err.message === 'string') return err
+  return new Error(String(err))
+}
+
+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 +58,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 +79,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 +90,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

@@ -16,6 +16,8 @@ module.exports = class RPCOutgoingRequest {
       this._reject = reject
     })
 
+    this._promise.catch(noop)
+
     this._requestStream = null
     this._responseStream = null
   }
@@ -79,3 +81,5 @@ module.exports = class RPCOutgoingRequest {
     return this._responseStream
   }
 }
+
+function noop() {}

package/lib/outgoing-stream.js

@@ -1,5 +1,6 @@
 const { Writable } = require('bare-stream')
 const { type: t, stream: s } = require('./constants')
+const { toError } = require('./messages')
 
 module.exports = class RPCOutgoingStream extends Writable {
   constructor(rpc, request, type, opts) {
@@ -11,25 +12,18 @@ module.exports = class RPCOutgoingStream extends Writable {
     this._mask = type === t.REQUEST ? s.REQUEST : s.RESPONSE
 
     this._pendingOpen = null
+    this._acknowledged = false
+    this._ended = false
   }
 
   _open(cb) {
-    let pending
-
     const onflushed = () => {
-      if (pending.has(this._request.id)) {
-        pending.delete(this._request.id)
-
-        cb(null)
-      } else {
-        this._pendingOpen = cb
-      }
+      if (this._acknowledged) cb(null)
+      else this._pendingOpen = cb
     }
 
     switch (this._type) {
       case t.REQUEST:
-        pending = this._rpc._pendingRequests
-
         this._rpc._sendMessage(
           {
             type: t.REQUEST,
@@ -43,8 +37,6 @@ module.exports = class RPCOutgoingStream extends Writable {
         break
 
       case t.RESPONSE:
-        pending = this._rpc._pendingResponses
-
         this._rpc._sendMessage(
           {
             type: t.RESPONSE,
@@ -60,12 +52,19 @@ module.exports = class RPCOutgoingStream extends Writable {
   }
 
   _continueOpen() {
+    this._acknowledged = true
+
     if (this._pendingOpen === null) return
+
     const cb = this._pendingOpen
     this._pendingOpen = null
     cb()
   }
 
+  _predestroy() {
+    this._continueOpen()
+  }
+
   _write(data, encoding, cb) {
     this._rpc._sendMessage(
       {
@@ -80,6 +79,8 @@ module.exports = class RPCOutgoingStream extends Writable {
   }
 
   _final(cb) {
+    this._ended = true
+
     this._rpc._sendMessage(
       {
         type: t.STREAM,
@@ -93,13 +94,15 @@ module.exports = class RPCOutgoingStream extends Writable {
   }
 
   _destroy(err, cb) {
-    if (err) {
+    if (this._ended) {
+      cb(null)
+    } else if (err) {
       this._rpc._sendMessage(
         {
           type: t.STREAM,
           id: this._request.id,
           stream: this._mask | s.CLOSE | s.ERROR,
-          error: err,
+          error: toError(err),
           data: null
         },
         cb

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-rpc",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "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",