solana_kit_rpc_subscriptions_channel_websocket 0.5.0

WebSocket channel for RPC subscriptions for the Solana Kit Dart SDK.

solana_kit_rpc_subscriptions_channel_websocket

WebSocket channel transport for Solana RPC subscriptions in the Solana Kit Dart SDK.

This is the Dart port of @solana/rpc-subscriptions-channel-websocket from the Solana TypeScript SDK.

Installation

Install the package directly:

dart pub add solana_kit_rpc_subscriptions_channel_websocket

If your app uses several Solana Kit packages together, you can also depend on the umbrella package instead:

dart pub add solana_kit

Inside this monorepo, Dart workspace resolution uses the local package automatically.

Documentation

• Package page: https://pub.dev/packages/solana_kit_rpc_subscriptions_channel_websocket
• API reference: https://pub.dev/documentation/solana_kit_rpc_subscriptions_channel_websocket/latest/
• Workspace docs: https://openbudgetfun.github.io/solana_kit/
• Package catalog entry: https://openbudgetfun.github.io/solana_kit/reference/package-catalog#solana_kit_rpc_subscriptions_channel_websocket
• Source code: https://github.com/openbudgetfun/solana_kit/tree/main/packages/solana_kit_rpc_subscriptions_channel_websocket

For architecture notes, getting-started guides, and cross-package examples, start with the workspace docs site and then drill down into the package README and API reference.

Usage

Creating a WebSocket channel

The createWebSocketChannel function opens a WebSocket connection and returns an RpcSubscriptionsChannel that supports the DataPublisher interface for receiving messages and errors.

import 'package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart';

void main() async {
  final controller = AbortController();

  final channel = await createWebSocketChannel(
    WebSocketChannelConfig(
      url: Uri.parse('wss://api.devnet.solana.com'),
      signal: controller.signal,
    ),
  );

  // Subscribe to incoming messages.
  channel.on('message', (data) {
    print('Received: $data');
  });

  // Subscribe to errors.
  channel.on('error', (error) {
    print('Error: $error');
  });

  // Send a message through the channel.
  await channel.send('{"jsonrpc":"2.0","id":1,"method":"slotSubscribe"}');

  // Later, close the channel.
  controller.abort();
}

Abort lifecycle management

The AbortController and AbortSignal classes manage the lifecycle of WebSocket connections. When you abort the signal, the WebSocket is closed with a normal closure code (1000).

import 'package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart';

void main() async {
  final controller = AbortController();

  // Check signal state.
  print(controller.signal.isAborted); // false

  // Open a channel with the signal.
  final channel = await createWebSocketChannel(
    WebSocketChannelConfig(
      url: Uri.parse('wss://api.devnet.solana.com'),
      signal: controller.signal,
    ),
  );

  // Abort with a reason.
  controller.abort('User cancelled');

  print(controller.signal.isAborted); // true
  print(controller.signal.reason); // 'User cancelled'

  // Sending on a closed channel throws SolanaError with code
  // rpcSubscriptionsChannelConnectionClosed.
}

Waiting for abort asynchronously

The AbortSignal provides a future that completes when the signal is aborted. This is useful for composing with other async operations.

import 'package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart';

void main() async {
  final controller = AbortController();

  // Wait for the signal to fire.
  controller.signal.future.then((_) {
    print('Signal was aborted!');
  });

  // Abort after some delay.
  await Future<void>.delayed(Duration(seconds: 5));
  controller.abort();
  // Prints: 'Signal was aborted!'
}

Configuring the send buffer

The sendBufferHighWatermark parameter controls how much data is allowed into the WebSocket's send buffer before messages are queued on the client.

import 'package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart';

void main() async {
  final controller = AbortController();

  final channel = await createWebSocketChannel(
    WebSocketChannelConfig(
      url: Uri.parse('wss://api.devnet.solana.com'),
      sendBufferHighWatermark: 256 * 1024, // 256KB buffer.
      signal: controller.signal,
    ),
  );

  // Use the channel...
  controller.abort();
}

Error handling

The function throws SolanaError in several situations:

import 'package:solana_kit_errors/solana_kit_errors.dart';
import 'package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart';

void main() async {
  final controller = AbortController();

  try {
    final channel = await createWebSocketChannel(
      WebSocketChannelConfig(
        url: Uri.parse('wss://invalid-host.example.com'),
        signal: controller.signal,
      ),
    );
  } on SolanaError catch (e) {
    if (isSolanaError(e, SolanaErrorCode.rpcSubscriptionsChannelFailedToConnect)) {
      print('Connection failed');
    }
  }

  // Already-aborted signals prevent connection.
  final abortedController = AbortController()..abort();
  try {
    await createWebSocketChannel(
      WebSocketChannelConfig(
        url: Uri.parse('wss://api.devnet.solana.com'),
        signal: abortedController.signal,
      ),
    );
  } on SolanaError catch (e) {
    if (isSolanaError(
      e,
      SolanaErrorCode.rpcSubscriptionsChannelConnectionClosed,
    )) {
      print('Channel was already closed');
    }
  }
}

API Reference

Functions

Function	Description
createWebSocketChannel(WebSocketChannelConfig config)	Opens a WebSocket connection and returns Future<RpcSubscriptionsChannel>.

Classes

Class	Description
RpcSubscriptionsChannel	An interface extending DataPublisher with a send(Object) method for outgoing messages. Supports on('message', ...) and on('error', ...).
WebSocketChannelConfig	Configuration: url (Uri), sendBufferHighWatermark (int, default 128KB), signal (AbortSignal?).
AbortController	Creates and manages an AbortSignal. Call abort([reason]) to fire the signal.
AbortSignal	Represents an abort signal. Properties: isAborted, reason, future.

Constants

Constant	Description
normalClosureCode	1000 -- the RFC 6455 normal closure code used when aborting a channel.

Example

Use example/main.dart as a runnable starting point for solana_kit_rpc_subscriptions_channel_websocket.

• Import path: package:solana_kit_rpc_subscriptions_channel_websocket/solana_kit_rpc_subscriptions_channel_websocket.dart
• This section is centrally maintained with mdt to keep package guidance aligned.
• After updating shared docs templates, run docs:update from the repo root.

Maintenance

• Validate docs in CI and locally with docs:check.
• Keep examples focused on one workflow and reference package README sections for deeper API details.