ic-websocket-js/lib/esm/ic-websocket.d.ts

IC WebSocket on the Internet Computer

import { ActorSubclass, SignIdentity } from "@dfinity/agent";
import { Principal } from "@dfinity/principal";
import { GetApplicationMessageType, _WS_CANISTER_SERVICE } from "./idl";
/**
 * The maximum communication latency allowed between the client and the canister (same as in the canister).
 *
 * Used to determine the ack message timeout.
 */
export declare const COMMUNICATION_LATENCY_BOUND_MS = 30000;
/**
 * Interface to create a new IcWebSocketConfig. For a simple configuration, use {@link createWsConfig}.
 */
export interface IcWebSocketConfig<S extends _WS_CANISTER_SERVICE> {
    /**
     * The canister id of the canister to open the WebSocket to.
     */
    canisterId: string | Principal;
    /**
     * The canister actor used to serialize and deserialize the application messages.
     */
    canisterActor: ActorSubclass<S>;
    /**
     * The identity to use for signing messages.
     * If you don't want to use an identity (e.g. your users are anonymous), you can use the `generateRandomIdentity`
     * helper function exported by this package to generate a new temporary identity.
     */
    identity: SignIdentity;
    /**
     * The IC network url to use for the underlying agent. It can be a local replica URL (e.g. http://localhost:4943) or the IC mainnet URL (https://icp-api.io).
     */
    networkUrl: string;
    /**
     * The interval (in milliseconds) at which the canister sends an ack message.
     * This parameter must be **equal** to the canister's send ack interval.
     *
     * @default 300_000 (default send ack period on the canister)
     */
    ackMessageIntervalMs?: number;
    /**
     * The maximum age of the certificate received from the canister, in minutes. You won't likely need to set this parameter. Used in tests.
     *
     * @default 5 (5 minutes)
     */
    maxCertificateAgeInMinutes?: number;
}
/**
 * Creates a new {@link IcWebSocketConfig} from arguments.
 */
export declare const createWsConfig: <S extends _WS_CANISTER_SERVICE>(c: IcWebSocketConfig<S>) => IcWebSocketConfig<S>;
type WsParameters = ConstructorParameters<typeof WebSocket>;
export declare class IcWebSocket<S extends _WS_CANISTER_SERVICE, ApplicationMessageType = GetApplicationMessageType<S>> {
    readonly canisterId: Principal;
    private readonly _canisterActor;
    private readonly _applicationMessageIdl;
    private readonly _httpAgent;
    private _wsAgent;
    private readonly _wsInstance;
    private readonly _identity;
    private _incomingSequenceNum;
    private _outgoingSequenceNum;
    private _isHandshakeCompleted;
    private _isConnectionEstablished;
    private _incomingMessagesQueue;
    private _outgoingMessagesQueue;
    private _ackMessagesQueue;
    private _clientKey;
    private _gatewayPrincipal;
    private _maxCertificateAgeInMinutes;
    private _openTimeout;
    onclose: ((this: IcWebSocket<S, ApplicationMessageType>, ev: CloseEvent) => any) | null;
    onerror: ((this: IcWebSocket<S, ApplicationMessageType>, ev: ErrorEvent) => any) | null;
    onmessage: ((this: IcWebSocket<S, ApplicationMessageType>, ev: MessageEvent<ApplicationMessageType>) => any) | null;
    onopen: ((this: IcWebSocket<S, ApplicationMessageType>, ev: Event) => any) | null;
    /**
     * Returns the state of the WebSocket object's connection.
     */
    get readyState(): number;
    readonly CLOSED: 3;
    readonly CLOSING: 2;
    readonly CONNECTING: 0;
    readonly OPEN: 1;
    /**
     * Creates a new IcWebSocket instance, waiting **30 seconds** for the WebSocket to be open.
     * @param url The gateway address.
     * @param protocols The protocols to use in the WebSocket.
     * @param config The IcWebSocket configuration. Use {@link createWsConfig} to create a new configuration.
     */
    constructor(url: WsParameters[0], protocols: WsParameters[1], config: IcWebSocketConfig<S>);
    send(message: ApplicationMessageType): void;
    getPrincipal(): Principal;
    close(): void;
    isConnectionEstablished(): boolean;
    private _bindWsEvents;
    private _onWsOpen;
    private _onWsMessage;
    private _startOpenTimeout;
    private _cancelOpenTimeout;
    private _handleHandshakeMessage;
    private _initializeWsAgent;
    private _sendOpenMessage;
    private _processIncomingMessage;
    private _handleServiceMessage;
    private _handleAckMessageFromCanister;
    private _handleCloseMessageFromCanister;
    private _sendKeepAliveMessage;
    private _onAckMessageTimeout;
    private _onWsClose;
    private _onWsError;
    private _sendMessageFromQueue;
    /**
     * Sends a message to the canister via WebSocket, using a method that uses the {@link WsAgent}.
     * @param message
     * @returns {boolean} `true` if the message was sent successfully, `false` otherwise.
     */
    private _sendMessageToCanister;
    /**
     * CBOR decodes the incoming message from an ArrayBuffer and returns an object.
     *
     * @param {ArrayBuffer} buf - The ArrayBuffer containing the encoded message.
     * @returns {any} The decoded object.
     */
    private _decodeIncomingMessage;
    private _isIncomingMessageValid;
    private _decodeIncomingMessageContent;
    private _isWebsocketMessageSequenceNumberValid;
    private _inspectWebsocketMessageTimestamp;
    private _makeWsMessageArguments;
    private _callOnOpenCallback;
    private _callOnMessageCallback;
    private _callOnErrorCallback;
    private _callOnCloseCallback;
}
export {};