Hyperswarm RPC

Simple RPC over the Hyperswarm DHT, backed by Protomux.

``sh
npm install @hyperswarm/rpc
`

Usage

`js
const RPC = require('@hyperswarm/rpc')

const rpc = new RPC()

const server = rpc.createServer()
await server.listen()

server.respond('echo', (req) => req)

const client = rpc.connect(server.publicKey)
await client.request('echo', Buffer.from('hello world'))
//
`

API

#### const rpc = new RPC([options])

Construct a new RPC instance.

Options include:

`js
{
// Optional default value encoding.
valueEncoding: encoding,
// A Noise keypair that will be used by default to listen/connect on the DHT.
// Defaults to a new key pair.
keyPair,
// A unique, 32-byte, random seed that can be used to deterministically
// generate the key pair.
seed: buffer,
// Optionally overwrite the default bootstrap servers. Not used if a DHT
// instance is passed instead.
bootstrap: ['host:port'],
// A DHT instance. Defaults to a new instance.
dht
}
`

#### await rpc.destroy([options])

Fully destroy this RPC instance.

This will also close any running servers. If you want to force close the instance without waiting for the servers to close pass { force: true }.

If a DHT instance was passed when constructing the RPC instance, this DHT will not be destroyed; the RPC instance will only destroy DHT instances that it itself has constructed.

$3

#### const client = rpc.connect(publicKey[, options])

Options are the same as dht.connect().

#### client.dht

The DHT instance used by the client.

#### client.rpc

The ProtomuxRPC instance used by the client.

#### client.closed

Whether or not the RPC channel is closed.

#### client.mux

The muxer used by the channel.

#### client.stream

The stream used by the channel.

#### const response = await client.request(method, value[, options])

Perform an RPC request, returning a promise that will resolve with the value returned by the request handler or reject with an error.

Options include:

`js
{
// Optional encoding for both requests and responses, defaults to raw
valueEncoding: encoding,
requestEncoding: encoding, // Optional encoding for requests
responseEncoding: encoding // Optional encoding for responses
}
`

#### client.event(method, value[, options])

Perform an RPC request but don't wait for a response.

Options are the same as client.request().

#### client.cork()

Cork the underlying channel. See channel.cork() for more information.

#### client.uncork()

Uncork the underlying channel. See channel.uncork() for more information.

#### await client.end()

Gracefully end the RPC channel, waiting for all inflights requests before closing.

#### client.destroy([err])

Forcefully close the RPC channel, rejecting any inflight requests.

#### client.on('open', [handshake])

Emitted when the remote side adds the RPC protocol.

#### client.on('close')

Emitted when the RPC channel closes, i.e. when the remote side closes or rejects the RPC protocol or we closed it.

#### client.on('destroy')

Emitted when the RPC channel is destroyed, i.e. after close when all pending promises has resolved.

$3

#### const response = await rpc.request(publicKey, method, value[, options])

Same as client.request but allocates a client in the internal pool that is auto closed after 10s of inactivity or rpc destruction.

#### rpc.event(publicKey, method, value[, options])

Same as client.event but allocates a client in the internal pool that is auto closed after 10s of inactivity or rpc destruction.

$3

#### const server = rpc.createServer([options])

Create a new RPC server for responding to requests.

Options are the same as dht.createServer().

#### server.dht

The DHT instance used by the server.

#### await server.listen([keyPair])

Make the server listen on a key pair, defaulting to rpc.defaultKeyPair. To connect to this server use keyPair.publicKey as the connect address.

#### server.respond(method[, options], handler)

Register a handler for an RPC method. The handler has the signature handler(request, rpc) and must either return the response value or throw an error. rpc is a ProtomuxRPC instance.

Note that rpc.stream is a HyperswarmSecretStream instance, from which you can get information about the connection. For example, rpc.stream.remotePublicKey returns the public key of the initiator of the request.

Only a single handler may be active for any given method; any previous handler is overwritten when registering a new one.

Options include:

`js
{
// Optional encoding for both requests and responses, defaults to raw
valueEncoding: encoding,
requestEncoding: encoding, // Optional encoding for requests
responseEncoding: encoding // Optional encoding for responses
}
`

#### server.unrespond(method)

Remove a handler for an RPC method.

#### await server.close()

Stop listening.

#### server.address()

Returns an object containing the address of the server:

`js
{
host, // External IP of the server,
port, // External port of the server if predictable,
publicKey // Public key of the server
}
`

#### server.on('listening')

Emitted when the server is fully listening on a key pair.

#### server.on('connection', rpc)

Emitted when an RPC client connects. rpc is a ProtomuxRPC instance.

#### server.on('close')`

Emitted when the server is fully closed.

License

Apache-2.0