bare-rpc 1.4.0 → 1.5.0

package/README.md

@@ -8,40 +8,119 @@ 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'))
 
-// On the other end
-const req = rpc.request(42)
+const client = new RPC(b)
+
+const req = client.request(1)
 req.send('ping')
 
-const replyBuffer = await req.reply()
-console.log(replyBuffer.toString()) // pong
+console.log((await req.reply()).toString()) // pong
+
+a.destroy()
+b.destroy()
 ```
 
-## API
+`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.
 
-See the [`bare-rpc` reference](https://docs.pears.com/reference/bare/modules/bare-rpc).
+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())
+})
+
+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`.
+
+## Termination
+
+The session ends with an `RPCError` with the code `CHANNEL_CLOSED` when `stream` closes. It fails with an error instead when:
+
+- `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. 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 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.
+- `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

@@ -124,7 +124,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>
@@ -213,18 +215,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 +251,12 @@ 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
 }
 
 interface RPC {
@@ -276,19 +286,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
   )
 }

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,13 @@ 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 } =
+      opts
 
     this._stream = stream
     this._maxFrameSize = maxFrameSize
+    this._maxBufferedBytes = maxBufferedBytes
     this._id = 0
 
     this._outgoingRequests = new Map()
@@ -58,6 +61,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 {
@@ -157,6 +164,10 @@ module.exports = exports = class RPC {
 
       this._outgoingRequests.set(request.id, 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)
@@ -197,6 +208,8 @@ module.exports = exports = class RPC {
 
       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))
@@ -421,8 +434,9 @@ module.exports = exports = class RPC {
     } 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)
     }
   }
 
@@ -431,19 +445,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 +461,31 @@ 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) {
+    request._responded = true
+    this._gcOutgoingRequest(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) {
@@ -525,7 +555,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,
@@ -605,5 +645,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)
-
-    data = await onrequest(req, data)
+    let data = await this._dispatch(responder, req)
 
     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/errors.d.ts

@@ -6,6 +6,8 @@ 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
 }
 
 export = RPCError

package/lib/errors.js

@@ -39,4 +39,12 @@ 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)
+  }
 }

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() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-rpc",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "librpc ABI compatible RPC for Bare",
   "exports": {
     ".": {