bare-rpc 0.2.2 → 0.2.4

package/README.md

@@ -6,6 +6,148 @@
 npm i bare-rpc
 ```
 
+## Usage
+
+```js
+import RPC from 'bare-rpc'
+
+const rpc = new RPC(stream, (req) => {
+  if (req.command === 42) {
+    console.log(req.data.toString()) // ping
+    req.reply('pong')
+  }
+})
+
+// On the other end
+const req = rpc.request(42)
+req.send('ping')
+
+const replyBuffer = await req.reply()
+console.log(replyBuffer.toString()) // pong
+```
+
+## API
+
+### `RPC`
+
+#### `const rpc = new RPC(stream, [onrequest])`
+
+Create an RPC instance using a duplex `stream`. `onrequest` is an optional callback run when a remote request is received. This is where processing and responding to an RPC request happens. `onrequest` receives a `RPCIncomingRequest` as an argument, for example:
+
+```js
+const rpc = new RPC(stream, (req) => {
+  if (req.command === 42) {
+    req.reply('pong')
+  }
+})
+```
+
+See [`RPCIncomingRequest`](#rpcincomingrequest) for properties and methods for processing the request.
+
+`onrequest` can also be a [`RPCCommandRouter`](#rpccommandrouter).
+
+#### `const req = rpc.request(command)`
+
+Create a request for `command`. `command` is a unique number that should be used to differentiate different requests on the remote end. Returns a `RPCOutgoingRequest`.
+
+### `RPCOutgoingRequest`
+
+#### `req.command`
+
+The command that the request was created with. A command is a unique number.
+
+#### `req.sent`
+
+A boolean for whether the request has been sent.
+
+#### `req.received`
+
+A boolean for whether the request has received a reply.
+
+#### `req.send(data, [encoding])`
+
+Send the request with the provided `data`. `data` can be a buffer or a string which will be encoded using `encoding`.
+
+`.send()` can only be called once per request.
+
+#### `const data = await req.reply([encoding])`
+
+Await the reply from the remote end to the request. `encoding` can be defined for decoding the response `data` buffer back into a string.
+
+#### `const stream = req.createRequestStream([opts])`
+
+Create a [`Writable`](https://github.com/mafintosh/streamx?tab=readme-ov-file#writable-stream) stream for sending data with the request.
+
+#### `const stream = req.createResponseStream([opts])`
+
+Create a [`Readable`](https://github.com/mafintosh/streamx?tab=readme-ov-file#readable-stream) stream for receiving data in reply to the request.
+
+### `RPCIncomingRequest`
+
+#### `req.command`
+
+The command that the request was sent as. A command is a unique number.
+
+#### `req.data`
+
+The data buffer sent with the request.
+
+#### `req.sent`
+
+A boolean for whether a reply has been sent.
+
+#### `req.received`
+
+A boolean for whether the request has been received as a stream. See [`req.createRequestStream()`](#const-stream--reqcreaterequeststream) for receiving requests as a stream.
+
+#### `req.reply(data, [encoding])`
+
+Reply to the request with the provided `data`. `data` can be a buffer or a string which will be encoded using `encoding`.
+
+#### `const stream = req.createRequestStream([opts])`
+
+Create a `Readable` stream for receiving data from the request.
+
+#### `const stream = req.createResponseStream([opts])`
+
+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, [opts], 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.
+
+`opts` can include:
+
+```
+{
+  requestEncoding: c.raw, // Encoding for decoding incoming request
+  responseEncoding: c.raw, // Encoding for outgoing response
+}
+```
+
 ## License
 
 Apache-2.0

package/index.d.ts

@@ -50,7 +50,7 @@ interface RPCOutgoingRequest {
 
   send(data: Buffer | string, encoding?: BufferEncoding): void
 
-  reply(encoding?: BufferEncoding): Promise<Buffer>
+  reply(encoding?: BufferEncoding): Promise<Buffer | string>
 
   createRequestStream(opts?: WritableOptions): RPCOutgoingStream
   createResponseStream(opts?: ReadableOptions): RPCIncomingStream

package/index.js

@@ -154,7 +154,7 @@ module.exports = exports = class RPC {
   }
 
   _onafterframe() {
-    if (this._frame === -1 || this._buffered < this._frame) return
+    if (this._buffered < this._frame) return
 
     const buffer =
       this._buffer.length === 1 ? this._buffer[0] : b4a.concat(this._buffer)
@@ -169,7 +169,7 @@ module.exports = exports = class RPC {
     this._onbeforeframe()
   }
 
-  _onmessage(buffer) {
+  async _onmessage(buffer) {
     let message
     try {
       message = m.message.decode(c.state(0, buffer.length, buffer))
@@ -189,7 +189,7 @@ module.exports = exports = class RPC {
         )
 
         try {
-          this._onrequest(request)
+          await this._onrequest(request)
         } catch (err) {
           safetyCatch(err)
 
@@ -248,6 +248,11 @@ module.exports = exports = class RPC {
       }
 
       stream = request._requestStream
+
+      if (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) {
@@ -256,6 +261,11 @@ module.exports = exports = class RPC {
       }
 
       stream = request._responseStream
+
+      if (stream._pendingOpen === null) {
+        this._pendingResponses.add(message.id)
+        return
+      }
     } else {
       return
     }

package/lib/incoming-stream.js

@@ -9,8 +9,6 @@ module.exports = class RPCIncomingStream extends Readable {
     this._request = request
     this._type = type
     this._mask = type === t.REQUEST ? s.REQUEST : s.RESPONSE
-
-    this._pendingOpen = null
   }
 
   _open(cb) {

package/lib/messages.js

@@ -53,16 +53,20 @@ const response = {
     c.bool.encode(state, !!m.error)
     c.uint.encode(state, m.stream)
 
-    if (m.error) error.encode(state, m)
+    if (m.error) error.encode(state, m.error)
     else if (m.stream === 0) c.buffer.encode(state, m.data)
   },
   decode(state) {
-    const error = c.bool.decode(state)
+    const err = c.bool.decode(state)
     const stream = c.uint.decode(state)
 
-    if (error) return { stream, error: error.decode(state), data: null }
-    if (stream === 0)
+    if (err) {
+      return { stream, error: error.decode(state), data: null }
+    }
+
+    if (stream === 0) {
       return { stream, error: null, data: c.buffer.decode(state) }
+    }
 
     return { stream, error: null, data: null }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-rpc",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "librpc ABI compatible RPC for Bare",
   "exports": {
     ".": {
@@ -39,6 +39,7 @@
   },
   "devDependencies": {
     "bare-buffer": "^3.0.1",
+    "bare-ipc": "^1.1.0",
     "brittle": "^3.2.1",
     "prettier": "^3.4.2",
     "prettier-config-standard": "^7.0.0"