Minimalist RPC library.
npm install rpc-engine javascript
import Rpc from 'rpc-engine'const a = new Rpc()
a.methods.add = (a, b) => {
return a + b
}
const b = new Rpc()
b.methods.hello = async () => {
await new Promise(s => setTimeout(s, 100))
return 'world'
}
// in real life you'll have some transport in between
// but that's outside the scope of this module
b.send = a.receive
a.send = b.receive
// not all transports require manual serialization (e.g. we should have
// structured clone in browserland), but if yours does, go nuts:
import msgpack from 'msgpack-lite/index.js'
a.serialize = JSON.stringify
a.deserialize = msgpack.decode
b.serialize = msgpack.encode
b.deserialize = JSON.parse
console.log(await b.call('add', 1, 1336)) // => 1337
console.log(await a.call('hello')) // => world
// JSON-RPC defines a notification mechanism that can
// be used directly for primitive pub-sub systems
a.methods.event = evt => {
console.log(evt) // => 42
}
b.notify('event', 42)
`Test
sh
$ npm run test
$ npm run test-browser # visit http://localhost:7357/test
`API
$3
* An optional Object. All key-value pairs are copied to the instance.$3
Throw an instance of this error during method handler execution when the intended audience is the remote caller. Alternatively myExistingError.insecureRpc = true can be set before rethrowing an existing error. Note that only { message, code, data } properties of errors are actually passed to the transport.Methods
$3
Invokes a method on the remote side.
* method A String.
* params Anything the transport (or rpc.serialize()) can handle. Optional.$3
Invokes a method on the remote side without sending a message id.
* method A String.
* params Anything the transport (or rpc.serialize()) can handle. Optional.$3
Messages destined for the remote site are passed to this method after processing. Consumers of this module are responsible for providing an implementation.
* message Whatever format the transport likes. See rpc.serialize() to control this.$3
Messages originating from the remote side must be passed to this method for processing. Consumers of this module are responsible for invoking this method somehow.
* message An Object or something rpc.deserialize() can handle.$3
This method is an optional hook consumers of this module may implement to convert outgoing messages into something compatible with the transport being used.
* message An Object.$3
This method is an optional hook consumers of this module may implement to convert raw a incoming message into an Object.
* message Whatever format the transport uses.$3
This method can be invoked (for example, when the transport is closed) to immediately cancel any outstanding requests.Properties
$3
An Object representing the interface available to the remote peer. Keys are method names, values are functions.$3
A Function. If implemented, this method will be invoked for any incoming message or notification that does not match an explicit handler in rpc.methods.$3
A Boolean. RpcEngine defaults to passing parameters as an Array of positional arguments. Setting this property to true will pass them as key-value pairs instead. This is frequently needed for interop with other JSON-RPC implementations.$3
A Boolean. When true, all errors thrown during method handler execution are returned to remote callers. To opt-in to sending a specific error to remote callers, set err.insecureRpc = true before throwing or throw an instance of RpcEngine.Error.Events
$3
Dispatched when something goes wrong while processing an incoming message.Releases
* 12.0.0
* Change default back to not sending method handler errors and add rpc.insecureErrors and RpcEngine.Error as opt-in mechanisms
* 11.0.0
* Allow errors generated during method handler execution to be sent to peers. This is risky in a promise environment because the programmer must opt-out of sending potentially sensitive error data to peers, but the benefits probably outweigh the risks
* 10.0.0
* Simplify, modernize
* 9.0.0
* Add promise support
* 8.0.0
* Convert to ES module
* Switch from EventEmitter to EventTarget
* 7.0.0
* Make default method invocation context the instance rather than the interface
* 6.0.0
* Require manipulation of interfaces to be done via method calls so that interface-{add,remove} can be emitted reliably.
* Always emit 'error' when send operations fail and no callback was passed.
* 5.0.0
* Move pub-sub code out to separate module rpc-events
* Rename constructor to RpcEngine
* Rename property to interface
* method should cancel pending requests immediately
* Complete API documentation
* 4.0.0
* Allow path delimited method and event names
* Add feeds property and implement {un}subscribe() on the receive side
* Change onmessage to receive (breaking change)
* 3.1.0
* Switch license to MIT
* 3.0.0
* Inherit from EventEmitter
* Use emit('error', error) rather than the onerror property (this is a breaking change)
* Add lightweight remote event subscription mechanism
* Switch to Math.random() for generating callback ids
* 2.1.0
* Handle parse errors as described in the spec
* 2.0.0
* Renamed to rpc-engine
* 1.1.0
* Bug fix (message results should be result)
* Handle parse and send errors
* Add timeout feature
* Add objectMode property for working with remotes that pass params, result` as objects instead of arrays