@solana/rpc-subscriptions-channel-websocket

@solana/rpc-subscriptions-channel-websocket

This package allows developers to create custom RPC Subscriptions channels. Using these primitives, developers can create custom channels that perform transforms on messages sent and received, perform autopings, and implement custom channel pooling strategies.

Functions

createWebSocketChannel()

Creates an object that represents an open channel to a WebSocket server.

You can use it to send messages by calling its send() function and you can receive them by subscribing to the RpcSubscriptionChannelEvents it emits.

import { createWebSocketChannel } from '@solana/rpc-subscriptions-channel-websocket';

const abortController = new AbortController();
const webSocketChannel = await createWebSocketChannel({
    sendBufferHighWatermark: Number.POSITIVE_INFINITY,
    signal: abortController.signal,
    url: 'wss://api.mainnet-beta.solana.com',
});
const channel = {
    ...webSocketChannel,
    on(type, listener, options) {
        if (type !== 'message') {
            return webSocketChannel.on(type, listener, options);
        }
        return webSocketChannel.on(
            'message',
            function deserializingListener(message: string) {
                const deserializedMessage = JSON.parse(message);
                listener(deserializedMessage);
            },
            options,
        );
    },
    send(message) {
        const serializedMessage = JSON.stringify(message);
        return webSocketChannel.send(serializedMessage);
    },
} as RpcSubscriptionsChannel<unknown, unknown>;
channel.on(
    'error',
    e => {
        console.log('Received error', e);
        abortController.abort();
    },
    { signal: abortController.signal },
);
channel.on(
    'message',
    m => {
        console.log('Received message', m);
        abortController.abort();
    },
    { signal: abortController.signal },
);
await channel.send({ id: 1, jsonrpc: '2.0', method: 'getSlot' });

Config

sendBufferHighWatermark

The number of bytes to admit into the WebSocket's send buffer before queueing messages on the client.

When you call send() on a WebSocket the runtime might add the message to a buffer rather than send it right away. In the event that socket.bufferedAmount exceeds the value configured here, messages will be added to a queue in your application code instead of being sent to the WebSocket, until such time as the bufferedAmount falls back below the high watermark.

signal

An AbortSignal to fire when you want to explicitly close the WebSocket.

If the channel is open it will be closed with the code 1000, representing a normal closure. If the channel has not been established yet, firing this signal will result in the AbortError being thrown to the caller who was trying to open the channel.

url

A string representing the target endpoint. In Node, it must be an absolute URL using the ws or wss protocol.