bare-rpc 0.2.3 → 0.2.5

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

@@ -10,7 +10,7 @@ const OutgoingStream = require('./lib/outgoing-stream')
 const CommandRouter = require('./lib/command-router')
 
 module.exports = exports = class RPC {
-  constructor(stream, onrequest) {
+  constructor(stream, onrequest = noop) {
     this._stream = stream
 
     this._id = 0
@@ -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
     }
@@ -394,3 +404,5 @@ module.exports = exports = class RPC {
 }
 
 exports.CommandRouter = CommandRouter
+
+function noop() {}

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/package.json

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