bare-rpc 1.4.0 → 2.0.0

package/README.md

@@ -8,40 +8,153 @@ npm i bare-rpc
 
 ## Usage
 
+This example wires two peers together over IPC and makes one request:
+
 ```js
+import IPC from 'bare-ipc'
 import RPC from 'bare-rpc'
 
-// On one end
-const rpc = new RPC(stream, (req) => {
-  if (req.command === 42) {
-    console.log(req.data.toString()) // ping
-    req.reply('pong')
-  }
+const [a, b] = IPC.open().map((port) => port.connect())
+
+const server = new RPC(a, (req) => req.reply('pong'))
+
+const client = new RPC(b)
+
+const req = client.request(1)
+req.send('ping')
+
+console.log((await req.reply()).toString()) // pong
+
+a.destroy()
+b.destroy()
+```
+
+`new RPC(stream, onrequest, opts)` runs a session over a duplex `stream`, such as a pipe, a socket or an IPC port. `onrequest` is a function that is called with each request and event of the peer, or a `CommandRouter`. `opts` takes `maxFrameSize` and `maxBufferedBytes`, as described under [Untrusted peers](#untrusted-peers).
+
+See the [`bare-rpc` reference](https://docs.pears.com/reference/bare/modules/bare-rpc) for the full API.
+
+## Command routing
+
+A `CommandRouter` sends each request and event to the handler registered for its command. Pass it to `RPC` as `onrequest`:
+
+```js
+const router = new RPC.CommandRouter()
+
+router.respond(1, (req, data) => Buffer.from('pong'))
+router.respond(2, (req, data) => console.log(req.command))
+
+const rpc = new RPC(stream, router)
+```
+
+A handler is called with the request and its data, and returns the data to reply with, unless it has answered the request itself. Events for a command go to the same handler, and its return value is ignored. A request for a command with no handler is rejected with the code `UNKNOWN_COMMAND`. An event for a command with no handler is dropped.
+
+The data is decoded and the reply encoded with a [compact-encoding](https://github.com/holepunchto/compact-encoding), `c.raw` by default. Pass `valueEncoding` to `new CommandRouter()` to change the default, or `valueEncoding`, `requestEncoding` and `responseEncoding` to `respond(command, opts, handler)` for one command.
+
+## Requests and responses
+
+`rpc.request(command)` returns a request. Call `send(data)` on it to send it, and `await reply()` to get its reply. `rpc.event(command)` returns an event, which gets no reply. Call `send(data)` on it to send it. Each can be sent once, and a reply can be read once. Sending again throws an `RPCError` with the code `ALREADY_SENT`, and reading again throws one with the code `ALREADY_RECEIVED`.
+
+Data can be a buffer, or a string that `send(data, encoding)` and `reply(data, encoding)` encode with `encoding`, `utf8` by default. `reply(encoding)` on a request you sent decodes the reply to a string.
+
+A request of the peer is answered once, with `reply()` or `createResponseStream()`. Answering again throws an `RPCError` with the code `ALREADY_SENT`, and `req.sent` tells whether the request has been answered. Events reach `onrequest` as requests without `reply()`. Each request and event of the peer is handled on its own, so a slow async handler does not hold back the others.
+
+If a request handler throws before it answers, the request is rejected with the `message` of the error, and its `code` and `errno` if it has them. If the handler had opened a response stream, the stream is destroyed with the error instead.
+
+When the peer rejects a request, `reply()` rejects with an `Error` with the `message`, `code` and `errno` of the peer.
+
+Without `onrequest`, every request is rejected with the code `UNKNOWN_COMMAND`, and events are dropped.
+
+## Streaming requests and responses
+
+A request can stream its body, its reply, or both:
+
+- `createRequestStream()` returns a `Writable` for the body, and `await reply()` gets a single reply.
+- `send(data)` sends a plain request, and `createResponseStream()` returns a `Readable` for the reply.
+- `createRequestStream()` and `createResponseStream()` together stream both.
+
+On the answering side, `req.createRequestStream()` returns a `Readable` for the body, and `req.createResponseStream()` returns a `Writable` for the reply. This handler echoes the body back:
+
+```js
+const server = new RPC(stream, (req) => {
+  req.createRequestStream().pipe(req.createResponseStream())
 })
 
-// On the other end
-const req = rpc.request(42)
+const req = client.request(1)
+const outgoing = req.createRequestStream()
+const incoming = req.createResponseStream()
+
+outgoing.end('ping')
+
+for await (const chunk of incoming) console.log(chunk.toString()) // ping
+```
+
+A stream only carries data once both ends have opened it, so data written before then is held back until the peer has opened its end. The handler opens the body when it calls `req.createRequestStream()`. If the peer answers before it opens the body, the body is destroyed, with the error of the reply if it has one.
+
+An incoming stream asks the peer to pause once it buffers its `highWaterMark`, which is 16 KiB by default, and to resume once it is read. While the peer has paused an outgoing stream, its writes are held back. If the peer keeps sending anyway, an incoming stream holds at most `maxBufferedBytes`, 16 MiB by default, before the session fails with an `RPCError` with the code `STREAM_OVERFLOW`.
+
+The body of a request and the reply to a request can each be read once. Calling `createRequestStream()` on a request of the peer again, or `createResponseStream()` or `reply()` on a request you sent again, throws an `RPCError` with the code `ALREADY_RECEIVED`.
+
+## Cancellation
+
+A request you sent can be cancelled with `req.cancel(reason)`. Its reply rejects with `reason`, its streams are destroyed with it, and the peer is told to stop handling the request. `reason` defaults to an `RPCError` with the code `CANCELLED`. Cancelling a request that has finished does nothing, and cancelling one that has not been sent yet keeps it from being sent. A request has finished once its answer has arrived: a reply, an error, or the end of a streamed reply, whether it ends cleanly or with an error. A request stream that is still open then stays open, so destroy it to stop it. Destroying the response stream before the answer has arrived cancels the request, with the error it was destroyed with if there is one.
+
+The peer receives the `message`, `code` and `errno` of `reason`. If `reason` has no `code`, the peer receives the code `TIMEOUT` when `reason` is a `TimeoutError`, such as the reason of a signal from `AbortSignal.timeout()`, and `CANCELLED` otherwise. This only changes what the peer receives; the reply still rejects with `reason` as is.
+
+`rpc.request(command, opts)` can also cancel the request for you:
+
+- `signal`: An `AbortSignal` that cancels the request with its reason when it aborts.
+- `timeout`: Milliseconds after the request is sent to cancel it with an `RPCError` with the code `TIMEOUT`.
+
+```js
+const req = rpc.request(1, { timeout: 5000 })
 req.send('ping')
 
-const replyBuffer = await req.reply()
-console.log(replyBuffer.toString()) // pong
+await req.reply() // Rejects with the code TIMEOUT if no reply arrives within 5 seconds
+```
+
+On the answering side, `req.signal` is an `AbortSignal` that aborts when the peer cancels the request, with the `message`, `code` and `errno` it cancelled with. It also aborts when the session ends while the handler still runs, with the error it ended with, even if the handler has already replied. Events have a `signal` too, which only aborts when the session ends. Once the peer has cancelled the request, its streams are destroyed with that error, `reply()` sends nothing, and an error thrown by the handler is not sent either.
+
+`RPC` does not create signals on its own. Pass an `AbortController` class as the `AbortController` option, such as the one from [`bare-abort-controller`](https://github.com/holepunchto/bare-abort-controller). Without it, `req.signal` is `null`.
+
+```js
+const AbortController = require('bare-abort-controller')
+
+const rpc = new RPC(stream, router, { AbortController })
+
+router.respond(1, async (req, data) => {
+  return await search(data, { signal: req.signal })
+})
 ```
 
-## API
+Cancelling a request needs a peer that supports it. A peer without support fails the session with the code `UNKNOWN_MESSAGE` when it receives a cancel.
+
+## Termination
+
+The session ends with an `RPCError` with the code `CHANNEL_CLOSED` when `stream` closes. It fails with an error instead when:
 
-See the [`bare-rpc` reference](https://docs.pears.com/reference/bare/modules/bare-rpc).
+- `stream` emits an error, with that error.
+- `stream` ends partway through a frame, with the code `INVALID_MESSAGE`.
+- An event handler throws, with that error.
+- The peer sends a bad frame, as described under [Untrusted peers](#untrusted-peers).
+
+Pending replies then reject with the error, and so do later replies. Open streams are destroyed with it, and so are streams created later. The signals of requests and events still being handled abort with it. Events sent after the end are dropped.
+
+`RPC` does not close `stream` when the session ends cleanly. When it fails for any reason but an error of `stream`, `RPC` destroys `stream` with the error, so the frames still queued in it are not written. To end the session yourself, destroy `stream`. `rpc.idle` tells whether no requests or streams are in flight, so that it is safe to do so.
 
 ## Untrusted peers
 
-`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:
+`RPC` does not trust the peer to send valid frames. If a frame is larger than `maxFrameSize`, cannot be decoded, or breaks the protocol, the session fails with an `RPCError`. The code tells you why:
 
-- `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.
+- `FRAME_TOO_LARGE`: The frame, with its 4-byte length prefix, is larger than `maxFrameSize`, 16 MiB by default. This is checked as soon as the length prefix arrives, before the rest of the frame is read.
+- `UNKNOWN_MESSAGE`: The frame has a message type that `RPC` does not know.
+- `INVALID_MESSAGE`: The frame cannot be decoded, `stream` ends partway through a frame, or the frame is one that a valid peer never sends. Examples are a response, stream or cancel 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.
+- `STREAM_OVERFLOW`: An incoming stream holds more than `maxBufferedBytes` of data that has not been read. This only happens when the peer keeps sending after it was asked to pause.
 
 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.
 
-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.
+If you read the reply as a stream but the peer replies without one, the reply arrives on the stream as a single chunk, unless it is empty, and the stream then ends. An error reply destroys the stream with the error instead.
+
+If you expect a plain reply but the peer replies with a stream, `reply()` rejects with an `RPCError` with the code `UNEXPECTED_STREAM`. The session destroys the stream toward the peer and stays open.
 
 ## License
 

package/index.d.ts

@@ -1,8 +1,9 @@
+import AbortController, { AbortSignal } from 'bare-abort-controller'
 import Buffer, { BufferEncoding } from 'bare-buffer'
 import { Readable, ReadableOptions, Writable, WritableOptions, Duplex } from 'bare-stream'
 
 declare const constants: {
-  type: { REQUEST: 1; RESPONSE: 2; STREAM: 3 }
+  type: { REQUEST: 1; RESPONSE: 2; STREAM: 3; CANCEL: 4 }
   stream: {
     OPEN: number
     CLOSE: number
@@ -23,6 +24,11 @@ interface RPCIncomingEvent {
   readonly command: number
   /** The data buffer sent with the request. */
   readonly data: Buffer | null
+  /**
+   * Aborted when the connection ends while the event is still being handled, with the error it
+   * ended with. `null` unless `RPC` was given an `AbortController`.
+   */
+  readonly signal: AbortSignal | null
 }
 
 declare class RPCIncomingEvent {
@@ -43,11 +49,17 @@ interface RPCIncomingRequest {
   readonly sent: boolean
   /** A boolean for whether the request has received a reply. */
   readonly received: boolean
+  /**
+   * Aborted when the remote end cancels the request, with the error it cancelled with, or when the
+   * connection ends, with the error it ended with. `null` unless `RPC` was given an
+   * `AbortController`.
+   */
+  readonly signal: AbortSignal | null
 
   /**
    * 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.
+   * send no data. Once the remote end has cancelled the request, nothing is sent.
    * @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.
    */
@@ -124,7 +136,9 @@ interface RPCOutgoingRequest {
    * @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.
+   * channel's teardown error if it closes before a reply arrives. If the remote end replies with a
+   * stream, the promise rejects with an error whose code is `UNEXPECTED_STREAM`, the remote end's
+   * stream is destroyed, and the connection stays open.
    * @throws {ALREADY_RECEIVED} a reply is already being received for this request.
    */
   reply(encoding?: BufferEncoding): Promise<Buffer | string | null>
@@ -137,6 +151,15 @@ interface RPCOutgoingRequest {
    * @throws {ALREADY_SENT} the request has already been sent.
    */
   createRequestStream(opts?: WritableOptions): RPCOutgoingStream
+  /**
+   * Cancel the request. The reply rejects with `reason`, the streams of the request are destroyed
+   * with it, and the remote end is told to stop handling the request. Does nothing once the request
+   * has finished, which it has once its answer has arrived, even while its request stream is open.
+   * @param reason - The error to cancel with (defaults to an `RPCError` with the code `CANCELLED`).
+   * If it has no `code`, the remote end receives the code `TIMEOUT` when it is a `TimeoutError` and
+   * `CANCELLED` otherwise.
+   */
+  cancel(reason?: unknown): void
   /**
    * 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
@@ -213,18 +236,20 @@ interface RPCRespondOptions {
 }
 
 /**
- * @param req - The incoming request.
+ * @param req - The incoming request. For an event, this is an `RPCIncomingEvent`.
  * @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.
+ * reply unless the handler has already replied. For an event, the return value is ignored and
+ * nothing is sent.
  */
 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.
+   * Answer requests for `command` with `onrequest`, in place of any handler registered before.
+   * Events for `command` are also passed to `onrequest`, but are never answered. 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.
@@ -247,6 +272,31 @@ interface RPCOptions {
    * Defaults to 16 MiB.
    */
   maxFrameSize?: number
+  /**
+   * The most data, in bytes, that one incoming stream may hold before it is read. A remote end that
+   * keeps sending past this limit, rather than stop when asked to pause, fails the connection with
+   * `STREAM_OVERFLOW`. Defaults to 16 MiB.
+   */
+  maxBufferedBytes?: number
+  /**
+   * The `AbortController` class to create the `signal` of each incoming request with. Without it,
+   * `signal` is `null`.
+   */
+  AbortController?: typeof AbortController
+}
+
+interface RPCRequestOptions {
+  /**
+   * Cancels the request with the reason of the signal when it aborts. If the reason has no `code`,
+   * the remote end receives the code `TIMEOUT` when it is a `TimeoutError`, as from
+   * `AbortSignal.timeout()`, and `CANCELLED` otherwise.
+   */
+  signal?: AbortSignal
+  /**
+   * Cancels the request with an `RPCError` with the code `TIMEOUT` if its answer has not arrived
+   * this many milliseconds after it is sent. Defaults to no timeout.
+   */
+  timeout?: number
 }
 
 interface RPC {
@@ -265,10 +315,11 @@ interface RPC {
   /**
    * @param command - A unique number identifying the request; the remote end differentiates
    * requests by it.
+   * @param opts - Options for cancelling the request.
    * @returns an `RPCOutgoingRequest`; call `send()` on it to dispatch the request and `await
    * reply()` for the response.
    */
-  request(command: number): RPCOutgoingRequest
+  request(command: number, opts?: RPCRequestOptions): RPCOutgoingRequest
 }
 
 declare class RPC {
@@ -276,19 +327,23 @@ declare class RPC {
    * @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.
+   * `RPCCommandRouter` that answers each request with the handler of its command. If it throws, the
+   * request is answered with the error, or, if it has already created a response stream, that
+   * stream is destroyed with the error. If it has already replied, nothing more is sent. If
+   * omitted, every request is answered with an error whose code is `UNKNOWN_COMMAND` and every
+   * event is dropped.
    * @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
+   * decoded, or breaks the protocol fails the connection, and so does a stream that holds more
+   * unread data than `maxBufferedBytes`: `stream` is destroyed with an `RPCError` whose code is
+   * `FRAME_TOO_LARGE`, `UNKNOWN_MESSAGE`, `INVALID_MESSAGE` or `STREAM_OVERFLOW`, 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,
+    onrequest?: ((req: RPCIncomingRequest) => void | Promise<void>) | RPCCommandRouter | null,
     opts?: RPCOptions
   )
 }
@@ -309,6 +364,7 @@ declare namespace RPC {
     RPCCommandRouter as CommandRouter,
     type RPCCommandRouterOptions as CommandRouterOptions,
     type RPCRespondOptions as RespondOptions,
+    type RPCRequestOptions as RequestOptions,
     type RPCRequestHandler as RequestHandler,
     type RPCValueEncoding as ValueEncoding,
     type RPCOptions as Options

package/index.js

@@ -14,6 +14,7 @@ const OutgoingStream = require('./lib/outgoing-stream')
 const CommandRouter = require('./lib/command-router')
 
 const DEFAULT_MAX_FRAME_SIZE = 16 * 1024 * 1024
+const DEFAULT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024
 const MAX_PENDING_RESPONSES = 1024
 
 const streamFlags = new Set()
@@ -35,11 +36,17 @@ for (const direction of [s.REQUEST, s.RESPONSE]) {
 }
 
 module.exports = exports = class RPC {
-  constructor(stream, onrequest = noop, opts = {}) {
-    const { maxFrameSize = DEFAULT_MAX_FRAME_SIZE } = opts
+  constructor(stream, onrequest = null, opts = {}) {
+    const {
+      maxFrameSize = DEFAULT_MAX_FRAME_SIZE,
+      maxBufferedBytes = DEFAULT_MAX_BUFFERED_BYTES,
+      AbortController = null
+    } = opts
 
     this._stream = stream
     this._maxFrameSize = maxFrameSize
+    this._maxBufferedBytes = maxBufferedBytes
+    this._AbortController = AbortController
     this._id = 0
 
     this._outgoingRequests = new Map()
@@ -47,7 +54,8 @@ module.exports = exports = class RPC {
     this._incomingRequests = new Map()
     this._incomingResponses = new Map()
     this._pendingResponses = new Set()
-    this._unansweredRequests = new Set()
+    this._handling = new Set()
+    this._unansweredRequests = new Map()
     this._highestRequestId = 0
 
     this._buffer = []
@@ -58,6 +66,10 @@ module.exports = exports = class RPC {
     this._closed = false
     this._error = null
 
+    if (onrequest === null) {
+      onrequest = new CommandRouter()
+    }
+
     if (typeof onrequest === 'function') {
       onrequest = onrequest.bind(this)
     } else {
@@ -95,8 +107,8 @@ module.exports = exports = class RPC {
     return new OutgoingEvent(this, command)
   }
 
-  request(command) {
-    return new OutgoingRequest(this, ++this._id, command)
+  request(command, opts) {
+    return new OutgoingRequest(this, ++this._id, command, opts)
   }
 
   _sendMessage(message, cb) {
@@ -131,12 +143,13 @@ 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
+    // Once the channel has been torn down or the request cancelled there is
+    // nowhere left to send the request. Skip registering it so that it never
+    // leaks into the maps; the reply has already been rejected by the cancel,
+    // or is rejected through `RPCOutgoingRequest.reply()` after teardown.
+    if (this._requestError(request) !== null) return
 
-    this._outgoingRequests.set(request.id, request)
+    this._trackOutgoingRequest(request)
 
     this._sendMessage({
       type: t.REQUEST,
@@ -151,17 +164,24 @@ module.exports = exports = class RPC {
     if (isInitiator) {
       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)
+      // Once the channel has been torn down or the request cancelled there is
+      // nowhere left to open the stream, so destroy it right away rather than
+      // leave it hanging.
+      const err = this._requestError(request)
+      if (err !== null) return request._requestStream.destroy(err)
 
-      this._outgoingRequests.set(request.id, request)
+      this._trackOutgoingRequest(request)
+
+      // Announce the stream right away rather than when it opens, so that the
+      // remote end also learns of a stream that is destroyed before it opens.
+      request._requestStream._sendOpen()
 
       request._requestStream.on('close', () => this._gcOutgoingRequest(request))
     } else {
       request._requestStream = new IncomingStream(this, request, t.REQUEST, opts)
 
-      if (this._closed) return request._requestStream.destroy(this._error)
+      const err = this._requestError(request)
+      if (err !== null) return request._requestStream.destroy(err)
 
       this._incomingRequests.set(request.id, request)
 
@@ -170,11 +190,11 @@ module.exports = exports = class RPC {
   }
 
   _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
+    // Once the channel has been torn down or the request cancelled there is
+    // no one left to read the response, so drop it rather than write a message
+    // that would only be discarded. The reply is fire-and-forget, so there is
+    // nothing to settle.
+    if (!this._isUnanswered(request)) return
 
     this._onanswered(request)
 
@@ -191,32 +211,40 @@ module.exports = exports = class RPC {
     if (isInitiator) {
       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)
+      // Once the channel has been torn down or the request cancelled there is
+      // nowhere left to open the stream, so destroy it right away rather than
+      // leave it hanging.
+      const err = this._requestError(request)
+      if (err !== null) return request._responseStream.destroy(err)
 
       this._outgoingResponses.set(request.id, request)
 
+      request._responseStream._sendOpen()
+
       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)
 
-      if (this._closed) return request._responseStream.destroy(this._error)
+      const err = this._requestError(request)
+      if (err !== null) return request._responseStream.destroy(err)
 
       this._incomingResponses.set(request.id, request)
 
       request._responseStream.on('close', () => {
         this._incomingResponses.delete(request.id)
 
-        request._responded = true
-        this._gcOutgoingRequest(request)
+        // A response stream destroyed before the answer has arrived leaves no
+        // way to read it, so the request is cancelled.
+        request.cancel(request._responseStream.errored)
       })
     }
   }
 
   _sendError(request, err) {
+    if (!this._isUnanswered(request)) return
+
     this._onanswered(request)
 
     this._sendMessage({
@@ -228,23 +256,68 @@ module.exports = exports = class RPC {
     })
   }
 
+  _isUnanswered(request) {
+    return this._unansweredRequests.get(request.id) === request
+  }
+
   // Returns whether the remote end had already opened its response stream.
   _onanswered(request) {
     this._unansweredRequests.delete(request.id)
     return this._pendingResponses.delete(request.id)
   }
 
+  _onresponded(request) {
+    request._responded = true
+    request._detach()
+    this._gcOutgoingRequest(request)
+  }
+
   _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
     // streamed, until the outgoing request stream has closed. Either can be the
     // last to arrive, so only remove the entry once both have completed.
     if (!request._responded) return
+
     if (request._requestStream !== null && !request._requestStream.destroyed) return
 
     this._outgoingRequests.delete(request.id)
   }
 
+  _trackOutgoingRequest(request) {
+    this._outgoingRequests.set(request.id, request)
+
+    request._attach()
+  }
+
+  // The error that keeps a request from using the channel, or `null` if it may.
+  _requestError(request) {
+    return this._closed ? this._error : request._reason
+  }
+
+  _cancelRequest(request, reason) {
+    // A request that has its answer has finished, even while its request stream
+    // is still open, and so has one that was sent but is no longer tracked.
+    if (request._reason !== null || request._responded) return
+    if (request.sent && this._outgoingRequests.get(request.id) !== request) return
+
+    request._reason = reason
+
+    if (request.sent) {
+      request._cancelled = true
+
+      this._outgoingRequests.delete(request.id)
+
+      request._detach()
+
+      this._sendMessage({ type: t.CANCEL, id: request.id, error: cancelError(reason), data: null })
+    }
+
+    request._reject(reason)
+
+    destroyStreams(request, reason)
+  }
+
   _onerror(err) {
     this._teardown(err)
   }
@@ -267,9 +340,16 @@ module.exports = exports = class RPC {
     // Reject any request awaiting a plain reply. Requests whose response is
     // delivered over a stream are torn down through that stream below.
     for (const request of this._outgoingRequests.values()) {
+      request._detach()
+
       if (request.received && request._responseStream === null) request._reject(err)
     }
 
+    for (const request of this._unansweredRequests.values()) request._abort(err)
+    for (const request of this._handling) request._abort(err)
+    for (const request of this._incomingRequests.values()) request._abort(err)
+    for (const request of this._outgoingResponses.values()) request._abort(err)
+
     // Collect the streams first, deduplicating as a single request may appear
     // in more than one map, then destroy them once the maps have been cleared.
     const streams = new Set()
@@ -388,6 +468,9 @@ module.exports = exports = class RPC {
           break
         case t.STREAM:
           this._onstream(message)
+          break
+        case t.CANCEL:
+          this._oncancel(message)
       }
     } catch (err) {
       this._fail(err)
@@ -412,17 +495,22 @@ module.exports = exports = class RPC {
     } else {
       request = new IncomingRequest(this, message.id, message.command, message.data)
 
-      this._unansweredRequests.add(message.id)
+      this._unansweredRequests.set(message.id, request)
       this._highestRequestId = Math.max(this._highestRequestId, message.id)
     }
 
+    this._handling.add(request)
+
     try {
       await this._onrequest(request)
     } catch (err) {
       safetyCatch(err)
 
-      if (message.id) this._sendError(request, err)
-      else this._stream.destroy(err)
+      if (message.id === 0) this._stream.destroy(err)
+      else if (request._responseStream !== null) request._responseStream.destroy(err)
+      else if (!request.sent) this._sendError(request, err)
+    } finally {
+      this._handling.delete(request)
     }
   }
 
@@ -431,19 +519,13 @@ module.exports = exports = class RPC {
     if (request === undefined) return
 
     if (message.error) {
-      request._responded = true
-      this._gcOutgoingRequest(request)
-
-      request._reject(message.error)
+      this._settle(request, message.error, null)
 
       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)
+      this._settle(request, null, message.data)
 
       const stream = request._responseStream
 
@@ -453,9 +535,30 @@ module.exports = exports = class RPC {
       }
 
       this._releaseRequestStream(request, null)
+    } else if (request._responseStream === null) {
+      const err = errors.UNEXPECTED_STREAM(`Request '${request.id}' was answered with a stream`)
+
+      this._settle(request, err, null)
+
+      this._sendMessage({
+        type: t.STREAM,
+        id: request.id,
+        stream: s.RESPONSE | s.DESTROY,
+        error: null,
+        data: null
+      })
+
+      this._releaseRequestStream(request, err)
     }
   }
 
+  _settle(request, err, data) {
+    this._onresponded(request)
+
+    if (err) request._reject(err)
+    else request._resolve(data)
+  }
+
   // 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) {
@@ -464,6 +567,23 @@ module.exports = exports = class RPC {
     if (stream !== null && !stream._acknowledged) stream.destroy(err)
   }
 
+  _oncancel(message) {
+    const request =
+      this._unansweredRequests.get(message.id) ??
+      this._incomingRequests.get(message.id) ??
+      this._outgoingResponses.get(message.id)
+
+    if (request === undefined) return
+
+    request._cancelled = true
+
+    this._onanswered(request)
+
+    request._abort(message.error)
+
+    destroyStreams(request, message.error)
+  }
+
   _onstream(message) {
     if (message.stream & s.OPEN) this._onstreamopen(message)
     else if (message.stream & s.CLOSE) this._onstreamclose(message)
@@ -507,6 +627,8 @@ module.exports = exports = class RPC {
     const stream = this._incomingStream(message)
     if (stream === null) return
 
+    this._onstreamfinish(stream)
+
     if (message.error) stream.destroy(message.error)
     else stream.push(null)
   }
@@ -525,7 +647,17 @@ module.exports = exports = class RPC {
     const stream = this._incomingStream(message)
     if (!isPushable(stream)) return
 
-    if (stream.push(message.data) === false) {
+    const flushed = stream.push(message.data)
+
+    if (stream._readableState.buffered > this._maxBufferedBytes) {
+      return this._fail(
+        errors.STREAM_OVERFLOW(
+          `Stream buffered more than the limit of ${this._maxBufferedBytes} bytes`
+        )
+      )
+    }
+
+    if (flushed === false) {
       this._sendMessage({
         type: t.STREAM,
         id: stream._request.id,
@@ -538,7 +670,17 @@ module.exports = exports = class RPC {
 
   _onstreamend(message) {
     const stream = this._incomingStream(message)
-    if (stream !== null) stream.push(null)
+    if (stream === null) return
+
+    this._onstreamfinish(stream)
+
+    stream.push(null)
+  }
+
+  // A streamed reply has its answer once its end arrives, even if the response
+  // stream has not been read to the end yet.
+  _onstreamfinish(stream) {
+    if (stream._type === t.RESPONSE) this._onresponded(stream._request)
   }
 
   _onstreamdestroy(message) {
@@ -589,9 +731,30 @@ function protocolViolation(message) {
       if (message.id === 0) return 'Stream message without an id'
       if (!streamFlags.has(message.stream)) return `Invalid stream flags '${message.stream}'`
       return null
+
+    case t.CANCEL:
+      if (message.id === 0) return 'Cancel without an id'
+      return null
   }
 }
 
+function cancelError(reason) {
+  const err = m.toError(reason)
+
+  if (typeof err.code === 'string' && err.code !== '') return err
+
+  return {
+    message: err.message,
+    code: err.name === 'TimeoutError' ? 'TIMEOUT' : 'CANCELLED',
+    errno: err.errno
+  }
+}
+
+function destroyStreams(request, err) {
+  if (request._requestStream !== null) request._requestStream.destroy(err)
+  if (request._responseStream !== null) request._responseStream.destroy(err)
+}
+
 function findStream(message, requests, responses) {
   if (message.stream & s.REQUEST) {
     const request = requests.get(message.id)
@@ -605,5 +768,3 @@ function findStream(message, requests, responses) {
 function isPushable(stream) {
   return stream !== null && !stream.destroying && !isEnding(stream)
 }
-
-function noop() {}

package/lib/command-router.js

@@ -31,24 +31,31 @@ module.exports = class RPCCommandRouter {
   async _onrequest(req) {
     const responder = this._responders.get(req.command)
 
-    if (responder === undefined) {
-      if (req.id === undefined) return
-
-      throw errors.UNKNOWN_COMMAND(`Unknown command ${req.command}`)
+    if (req.id === undefined) {
+      if (responder !== undefined) await this._dispatch(responder, req)
+      return
     }
 
-    const { onrequest, requestEncoding, responseEncoding } = responder
-
-    let data = req.data
+    if (responder === undefined) throw errors.UNKNOWN_COMMAND(`Unknown command ${req.command}`)
 
-    if (requestEncoding) data = c.decode(requestEncoding, data)
+    let data = await this._dispatch(responder, req)
 
-    data = await onrequest(req, data)
+    if (req.sent || req._reason !== null) return
 
-    if (req.sent) return
+    const { responseEncoding } = responder
 
     if (responseEncoding) data = c.encode(responseEncoding, data)
 
     req.reply(data)
   }
+
+  _dispatch(responder, req) {
+    const { onrequest, requestEncoding } = responder
+
+    let data = req.data
+
+    if (requestEncoding) data = c.decode(requestEncoding, data)
+
+    return onrequest(req, data)
+  }
 }

package/lib/constants.js

@@ -2,7 +2,8 @@ module.exports = {
   type: {
     REQUEST: 1,
     RESPONSE: 2,
-    STREAM: 3
+    STREAM: 3,
+    CANCEL: 4
   },
   stream: {
     OPEN: 0x1,

package/lib/errors.d.ts

@@ -6,6 +6,10 @@ declare class RPCError extends Error {
   static ALREADY_SENT(msg: string): RPCError
   static ALREADY_RECEIVED(msg: string): RPCError
   static CHANNEL_CLOSED(msg: string): RPCError
+  static UNEXPECTED_STREAM(msg: string): RPCError
+  static STREAM_OVERFLOW(msg: string): RPCError
+  static CANCELLED(msg: string): RPCError
+  static TIMEOUT(msg: string): RPCError
 }
 
 export = RPCError

package/lib/errors.js

@@ -39,4 +39,20 @@ module.exports = class RPCError extends Error {
   static CHANNEL_CLOSED(msg) {
     return new RPCError(msg, 'CHANNEL_CLOSED', RPCError.CHANNEL_CLOSED)
   }
+
+  static UNEXPECTED_STREAM(msg) {
+    return new RPCError(msg, 'UNEXPECTED_STREAM', RPCError.UNEXPECTED_STREAM)
+  }
+
+  static STREAM_OVERFLOW(msg) {
+    return new RPCError(msg, 'STREAM_OVERFLOW', RPCError.STREAM_OVERFLOW)
+  }
+
+  static CANCELLED(msg) {
+    return new RPCError(msg, 'CANCELLED', RPCError.CANCELLED)
+  }
+
+  static TIMEOUT(msg) {
+    return new RPCError(msg, 'TIMEOUT', RPCError.TIMEOUT)
+  }
 }

package/lib/incoming-event.js

@@ -1,6 +1,9 @@
-module.exports = class RPCIncomingEvent {
+const RPCIncoming = require('./incoming')
+
+module.exports = class RPCIncomingEvent extends RPCIncoming {
   constructor(rpc, command, data) {
-    this.rpc = rpc
+    super(rpc)
+
     this.command = command
     this.data = data
   }

package/lib/incoming-request.js

@@ -1,9 +1,11 @@
 const c = require('compact-encoding')
 const errors = require('./errors')
+const RPCIncoming = require('./incoming')
 
-module.exports = class RPCIncomingRequest {
+module.exports = class RPCIncomingRequest extends RPCIncoming {
   constructor(rpc, id, command, data) {
-    this.rpc = rpc
+    super(rpc)
+
     this.id = id
     this.command = command
     this.data = data
@@ -12,6 +14,8 @@ module.exports = class RPCIncomingRequest {
 
     this._requestStream = null
     this._responseStream = null
+
+    this._cancelled = false
   }
 
   reply(data, encoding) {

package/lib/incoming-stream.js

@@ -10,9 +10,13 @@ module.exports = class RPCIncomingStream extends Readable {
     this._request = request
     this._type = type
     this._mask = type === t.REQUEST ? s.REQUEST : s.RESPONSE
+
+    this._opened = false
   }
 
   _open(cb) {
+    this._opened = true
+
     this._rpc._sendMessage(
       {
         type: t.STREAM,
@@ -36,7 +40,11 @@ module.exports = class RPCIncomingStream extends Readable {
   }
 
   _destroy(err, cb) {
-    if (err) {
+    // A request cancelled before it was sent only has to take back an open
+    // that already went out, as the remote end never learns of the cancel.
+    if (this._request._reason !== null && (this._request._cancelled || !this._opened)) {
+      cb(null)
+    } else if (err) {
       this._rpc._sendMessage(
         {
           type: t.STREAM,

package/lib/incoming.js

@@ -0,0 +1,30 @@
+module.exports = class RPCIncoming {
+  constructor(rpc) {
+    this.rpc = rpc
+
+    this._reason = null
+    this._controller = null
+  }
+
+  get signal() {
+    const { _AbortController: AbortController } = this.rpc
+
+    if (AbortController === null) return null
+
+    if (this._controller === null) {
+      this._controller = new AbortController()
+
+      if (this._reason !== null) this._controller.abort(this._reason)
+    }
+
+    return this._controller.signal
+  }
+
+  _abort(reason) {
+    if (this._reason !== null) return
+
+    this._reason = reason
+
+    if (this._controller !== null) this._controller.abort(reason)
+  }
+}

package/lib/messages.js

@@ -65,6 +65,10 @@ exports.header = {
 
         if (m.stream & s.ERROR) error.preencode(state, m.error)
         break
+
+      case t.CANCEL:
+        error.preencode(state, m.error)
+        break
     }
 
     if (hasData(m)) c.uint.preencode(state, m.data ? m.data.byteLength : 0)
@@ -97,6 +101,10 @@ exports.header = {
 
         if (m.stream & s.ERROR) error.encode(state, m.error)
         break
+
+      case t.CANCEL:
+        error.encode(state, m.error)
+        break
     }
 
     const data = hasData(m)
@@ -160,6 +168,9 @@ exports.message = {
         return { type, id, stream, error: null, data: null }
       }
 
+      case t.CANCEL:
+        return { type, id, error: error.decode(state), data: null }
+
       default:
         throw errors.UNKNOWN_MESSAGE(`Unknown message '${type}'`)
     }

package/lib/outgoing-request.js

@@ -2,7 +2,9 @@ const c = require('compact-encoding')
 const errors = require('./errors')
 
 module.exports = class RPCOutgoingRequest {
-  constructor(rpc, id, command) {
+  constructor(rpc, id, command, opts = {}) {
+    const { signal = null, timeout = 0 } = opts
+
     this.rpc = rpc
     this.id = id
     this.command = command
@@ -10,6 +12,13 @@ module.exports = class RPCOutgoingRequest {
     this.received = false
 
     this._responded = false
+    this._reason = null
+    this._cancelled = false
+
+    this._signal = signal
+    this._timeout = timeout
+    this._timer = null
+    this._onabort = signal === null ? null : () => this.cancel(signal.reason)
 
     this._promise = new Promise((resolve, reject) => {
       this._resolve = resolve
@@ -34,11 +43,17 @@ module.exports = class RPCOutgoingRequest {
           ? c.raw.utf8
           : null
 
+    this._abortIfSignalled()
+
     this.sent = true
 
     this.rpc._sendRequest(this, encoding ? c.encode(encoding, data) : data)
   }
 
+  cancel(reason) {
+    this.rpc._cancelRequest(this, reason ?? errors.CANCELLED('Request was cancelled'))
+  }
+
   reply(encoding) {
     if (this.received) {
       throw errors.ALREADY_RECEIVED('Response is already being received')
@@ -62,6 +77,8 @@ module.exports = class RPCOutgoingRequest {
       throw errors.ALREADY_SENT('Request has already been sent')
     }
 
+    this._abortIfSignalled()
+
     this.sent = true
 
     this.rpc._createRequestStream(this, true, opts)
@@ -80,6 +97,29 @@ module.exports = class RPCOutgoingRequest {
 
     return this._responseStream
   }
+
+  _abortIfSignalled() {
+    if (this._signal !== null && this._signal.aborted) this._onabort()
+  }
+
+  _attach() {
+    if (this._signal !== null) this._signal.addEventListener('abort', this._onabort)
+
+    if (this._timeout > 0) this._timer = setTimeout(ontimeout, this._timeout, this)
+  }
+
+  _detach() {
+    if (this._signal !== null) this._signal.removeEventListener('abort', this._onabort)
+
+    if (this._timer !== null) {
+      clearTimeout(this._timer)
+      this._timer = null
+    }
+  }
+}
+
+function ontimeout(request) {
+  request.cancel(errors.TIMEOUT(`Request timed out after ${request._timeout} ms`))
 }
 
 function noop() {}

package/lib/outgoing-stream.js

@@ -12,14 +12,15 @@ module.exports = class RPCOutgoingStream extends Writable {
     this._mask = type === t.REQUEST ? s.REQUEST : s.RESPONSE
 
     this._pendingOpen = null
+    this._flushed = false
     this._acknowledged = false
     this._ended = false
   }
 
-  _open(cb) {
+  _sendOpen() {
     const onflushed = () => {
-      if (this._acknowledged) cb(null)
-      else this._pendingOpen = cb
+      this._flushed = true
+      this._finishOpen()
     }
 
     switch (this._type) {
@@ -51,14 +52,22 @@ module.exports = class RPCOutgoingStream extends Writable {
     }
   }
 
+  _open(cb) {
+    this._pendingOpen = cb
+    this._finishOpen()
+  }
+
   _continueOpen() {
     this._acknowledged = true
+    this._finishOpen()
+  }
 
-    if (this._pendingOpen === null) return
+  _finishOpen() {
+    if (!this._flushed || !this._acknowledged || this._pendingOpen === null) return
 
     const cb = this._pendingOpen
     this._pendingOpen = null
-    cb()
+    cb(null)
   }
 
   _predestroy() {
@@ -94,7 +103,7 @@ module.exports = class RPCOutgoingStream extends Writable {
   }
 
   _destroy(err, cb) {
-    if (this._ended) {
+    if (this._ended || this._request._reason !== null) {
       cb(null)
     } else if (err) {
       this._rpc._sendMessage(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-rpc",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "description": "librpc ABI compatible RPC for Bare",
   "exports": {
     ".": {
@@ -42,6 +42,7 @@
     "safety-catch": "^1.0.2"
   },
   "devDependencies": {
+    "bare-abort-controller": "^1.1.2",
     "bare-buffer": "^3.0.1",
     "bare-ipc": "^1.1.0",
     "bare-rpc-test": "^0.1.0",
@@ -51,9 +52,13 @@
     "prettier-config-holepunch": "^2.0.0"
   },
   "peerDependencies": {
+    "bare-abort-controller": "*",
     "bare-buffer": "*"
   },
   "peerDependenciesMeta": {
+    "bare-abort-controller": {
+      "optional": true
+    },
     "bare-buffer": {
       "optional": true
     }