The Electrum WebSockets Client library provides a thin wrapper on top of
WebSocket API, in order to allow building a simple JSON-based RPC
WebSocketChannel provides a thin abstraction on top of the
new WebSocketChannel(server, port, path), initializes a web socket without opening the connection.
create(url)→ splits the URL and calls the constructor; returns an instance of
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).
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.
correlator→ associated correlator.
uri→ full URI of the channel.
receiveReadyCount→ number of received messages which have not yet been read by
receiveWaitingCount→ number of receivers blocked in
receive(), 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 ensures that when bidirectional RPC is used, responses get
routed to the matching request (i.e. it correlates requests and responses,
hence its name).
new Correlator(dispatcher), initializes a correlator.
new()→ a correlation node, which has a unique
idassociated 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 associated
idwill be recycled and available for reuse.
has(id)→ true if the specified
idis an active correlation ID.
node(id)→ the node with the specified
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.
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 = 'localhost' 54321;await channel;console;channel;const echo = await channel;console;todeep;