electrum-ws-client
v2.2.2
Published
Electrum WebSockets library.
Downloads
4
Keywords
Readme
electrum-ws-client
The Electrum WebSockets Client library provides a thin wrapper on top of
the WebSocket
API, in order to allow building a simple JSON-based RPC
channel.
WebSocketChannel
The WebSocketChannel
provides a thin abstraction on top of the WebSocket
API.
Constructor:
new WebSocketChannel(server, port, path)
, initializes a web socket without opening the connection.
Static methods:
create(url)
→ splits the URL and calls the constructor; returns an instance ofWebSocketChannel
.create(url, rel)
→ same as above, adds the specified relative path to the given URL.create(url, rel, correlator)
→ same as above, configures a custom correlator (used by the synchronous RPC implementation).
Methods:
async open()
→ promise, asynchronously opens the connection.async send(obj)
→ promise, asynchronously sends obj as a JSON payload.async receive()
→ promise, asynchronously receives a JSON payload.async receive(id)
→ promise, asynchronously receives a JSON payload which matches the specified correlation ID.
Properties:
correlator
→ associated correlator.uri
→ full URI of the channel.receiveReadyCount
→ number of received messages which have not yet been read byreceive()
.receiveWaitingCount
→ number of receivers blocked inreceive()
, waiting for messages to arrive.
Note that the URL may contain a query string. This can be used to pass context along with a connection to the web socket server.
Correlator
The Correlator
ensures that when bidirectional RPC is used, responses get
routed to the matching request (i.e. it correlates requests and responses,
hence its name).
Constructor:
new Correlator(dispatcher)
, initializes a correlator.
Methods:
new()
→ a correlation node, which has a uniqueid
associated with it. The id will be used to correlate requests and responses.dispose(node)
, disposes a correlation node when it is no longer needed. The associatedid
will be recycled and available for reuse.has(id)
→ true if the specifiedid
is an active correlation ID.node(id)
→ the node with the specifiedid
.async receive()
→ promise, asynchronously receives a payload without correlation ID; this is for messages directly sent by the server to the client (i.e. messages which are not responses to a request).async receive(id)
→ promise, asynchronously receives a payload with the specified correlation ID. The associated node will be disposed as soon the message is received.dispatch(obj)
, dispatches a payload; if the payload contains a correlation ID, it will be routed to a matching receiving node; else it will be dispatched on the dispatcher provided at construction time.
Performance
Tested against a Kestrel-based WebSocket server, this library performs a dialog with an echo service in about 1ms with the following asynchronous test code:
const channel = new WebSocketChannel ('localhost', 54321);
await channel.open ();
console.time ('perf');
channel.send ({foo: 42});
const echo = await channel.receive ();
console.timeEnd ('perf');
expect (echo).to.deep.equal ({foo: 42});