blink-trade-sdk 0.1.0

package/dist/managed-ws.js

@@ -0,0 +1,475 @@
+import { WsTransport } from './ws-transport.js';
+import { WS_PROTOCOL_VERSION, WsSession } from './ws.js';
+/**
+ * Gateway websocket protocol v1 (`/v1/ws`, docs/v1/websocket.md).
+ *
+ * One physical socket per tab. Channel strings carry their own parameters and
+ * are both the server subscription identity and the client routing key, so a
+ * channel is subscribed at most once no matter how many consumers share it.
+ */
+export const BLINK_WS_PROTOCOL_VERSION = WS_PROTOCOL_VERSION;
+const MAX_RECONNECT_MS = 10_000;
+/** A subscribed channel that has not produced its snapshot by then is replaced. */
+const SNAPSHOT_TIMEOUT_MS = 15_000;
+const WATCHDOG_MS = 5_000;
+/** Delay before re-subscribing a channel the server closed with `503`. */
+const STREAM_RETRY_MS = 1_000;
+/** Used until the server hello advertises its own keepalive contract. */
+const DEFAULT_KEEPALIVE_TIMEOUT_MS = 120_000;
+const SOCKET_CONNECTING = 0;
+const SOCKET_OPEN = 1;
+export class BlinkSocketManager {
+    url;
+    options;
+    socket = null;
+    session = new WsSession();
+    channels = new Map();
+    statusHandlers = new Set();
+    diagnosticHandlers = new Set();
+    diagnostics = [];
+    status = 'idle';
+    connectScheduled = false;
+    reconnectTimer = null;
+    watchdogTimer = null;
+    reconnectAttempt = 0;
+    generation = 0;
+    helloAccepted = false;
+    protocolRejected = false;
+    keepaliveTimeoutMs = DEFAULT_KEEPALIVE_TIMEOUT_MS;
+    constructor(url, options = {}) {
+        this.url = url;
+        this.options = options;
+    }
+    /**
+     * Attach a consumer to a channel. The first consumer subscribes the channel
+     * on the server; further consumers share it. A consumer that attaches after
+     * the channel's snapshot was installed cannot rebuild that snapshot from
+     * deltas, so the server subscription is replaced and every consumer receives
+     * a fresh lifecycle (`reset`, then a snapshot `update`).
+     */
+    subscribe(channel, handler) {
+        let state = this.channels.get(channel);
+        const isNew = !state;
+        if (!state) {
+            state = {
+                channel,
+                handlers: new Map(),
+                awaitingSnapshot: true,
+                subscribedAt: null,
+                retryTimer: null,
+                failed: false,
+            };
+            this.channels.set(channel, state);
+        }
+        const existingHandler = state.handlers.has(handler);
+        if (!isNew && !existingHandler && (!state.awaitingSnapshot || state.failed)) {
+            // Replace before attaching: existing consumers get the `reset`, the new
+            // one starts at the fresh snapshot.
+            this.replaceSubscription(state, state.failed ? 'retrying a rejected channel for a new consumer' : 'consumer attached after the snapshot');
+        }
+        state.handlers.set(handler, (state.handlers.get(handler) ?? 0) + 1);
+        this.ensureConnection();
+        if (isNew) {
+            // `ensureConnection` does nothing on an already connected socket, so a
+            // channel appearing later (wallet login, market switch) is sent now.
+            this.sendSubscribe(state);
+        }
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            const current = this.channels.get(channel);
+            if (!current)
+                return;
+            const refs = current.handlers.get(handler) ?? 0;
+            if (refs <= 1)
+                current.handlers.delete(handler);
+            else
+                current.handlers.set(handler, refs - 1);
+            if (current.handlers.size === 0)
+                this.removeChannel(current);
+        };
+    }
+    /** Replace one channel's server subscription so it re-installs a snapshot. */
+    resubscribe(channel, reason) {
+        const state = this.channels.get(channel);
+        if (!state)
+            return;
+        this.replaceSubscription(state, reason);
+    }
+    onStatus(handler) {
+        this.statusHandlers.add(handler);
+        handler(this.status);
+        return () => this.statusHandlers.delete(handler);
+    }
+    onDiagnostic(handler) {
+        this.diagnosticHandlers.add(handler);
+        return () => this.diagnosticHandlers.delete(handler);
+    }
+    getDiagnostics() {
+        return this.diagnostics;
+    }
+    getStatus() {
+        return this.status;
+    }
+    /** Exposed for diagnostics and focused unit tests. */
+    debugState() {
+        let awaitingSnapshot = 0;
+        for (const state of this.channels.values()) {
+            if (state.awaitingSnapshot)
+                awaitingSnapshot += 1;
+        }
+        return {
+            channels: this.channels.size,
+            awaitingSnapshot,
+            keepaliveTimeoutMs: this.keepaliveTimeoutMs,
+            status: this.status,
+        };
+    }
+    dispose() {
+        this.protocolRejected = true;
+        this.clearTimers();
+        for (const state of this.channels.values())
+            this.clearRetry(state);
+        this.channels.clear();
+        this.generation += 1;
+        this.socket?.close(1000, 'manager disposed');
+        this.socket = null;
+        this.helloAccepted = false;
+        this.setStatus('idle');
+    }
+    ensureConnection() {
+        if (this.protocolRejected ||
+            this.channels.size === 0 ||
+            this.socket ||
+            this.connectScheduled ||
+            this.reconnectTimer) {
+            return;
+        }
+        this.connectScheduled = true;
+        queueMicrotask(() => {
+            this.connectScheduled = false;
+            if (this.channels.size > 0)
+                this.connect();
+        });
+    }
+    connect() {
+        if (this.socket || this.protocolRejected || this.channels.size === 0)
+            return;
+        const generation = ++this.generation;
+        let socket;
+        try {
+            socket = new WsTransport(this.url, {
+                ...this.options,
+                onMessage: (frame) => {
+                    if (generation === this.generation)
+                        this.handleMessage(frame);
+                },
+                onError: (error) => {
+                    if (generation === this.generation)
+                        this.addDiagnostic('warning', 'SOCKET_ERROR', 'WebSocket transport error', error);
+                },
+                onDiagnostic: (code, message, detail) => {
+                    if (generation === this.generation)
+                        this.addDiagnostic('warning', code, message, detail);
+                },
+                onProtocolError: (error) => {
+                    if (generation === this.generation)
+                        this.rejectProtocol(error.message, error);
+                },
+                onClose: (event) => this.handleClose(generation, event),
+            });
+        }
+        catch (error) {
+            this.addDiagnostic('error', 'CONNECT_FAILED', 'WebSocket creation failed', error);
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        this.session = new WsSession();
+        this.helloAccepted = false;
+        this.setStatus(this.reconnectAttempt > 0 ? 'reconnecting' : 'connecting');
+    }
+    handleClose(generation, event) {
+        if (generation !== this.generation)
+            return;
+        this.socket = null;
+        this.helloAccepted = false;
+        this.stopWatchdog();
+        for (const state of this.channels.values()) {
+            this.clearRetry(state);
+            state.awaitingSnapshot = true;
+            state.subscribedAt = null;
+            state.failed = false;
+            this.dispatch(state, {
+                type: 'reset',
+                channel: state.channel,
+                reason: 'socket closed',
+            });
+        }
+        if (this.protocolRejected)
+            return;
+        this.addDiagnostic('warning', 'SOCKET_CLOSED', 'WebSocket disconnected', {
+            code: event.code,
+            reason: event.reason,
+        });
+        this.scheduleReconnect();
+    }
+    handleMessage(frame) {
+        if (frame.type === 'hello') {
+            this.keepaliveTimeoutMs = frame.keepalive_timeout_ms;
+            this.helloAccepted = true;
+            this.reconnectAttempt = 0;
+            this.setStatus('connected');
+            this.startWatchdog();
+            for (const state of this.channels.values())
+                this.sendSubscribe(state);
+            return;
+        }
+        switch (frame.type) {
+            case 'update': {
+                const state = this.channels.get(frame.channel);
+                if (state)
+                    this.handleUpdate(state, frame);
+                return;
+            }
+            case 'error':
+                this.session.ingest(frame);
+                this.handleError(frame);
+                return;
+            case 'unsubscribed':
+                this.session.ingest(frame);
+                return;
+            case 'pong':
+                return;
+        }
+    }
+    handleUpdate(state, frame) {
+        // Stateful channels carry `previous_sequence`/`sequence`; stateless ones
+        // (candles, bbo) carry neither and are continuous by construction.
+        const hasSequence = 'sequence' in frame || 'previous_sequence' in frame;
+        const sequence = typeof frame.sequence === 'string' ? frame.sequence : null;
+        const previous = typeof frame.previous_sequence === 'string' ? frame.previous_sequence : null;
+        // Old in-flight deltas must not trigger repeated resubscriptions while
+        // the replacement snapshot is already pending.
+        if (state.awaitingSnapshot && hasSequence && previous !== null) {
+            this.addDiagnostic('info', 'STALE_FRAME', 'Dropping a delta that arrived before the snapshot', {
+                channel: state.channel,
+                previous_sequence: previous,
+                sequence,
+            });
+            return;
+        }
+        const snapshot = state.awaitingSnapshot;
+        const event = this.session.ingest(frame);
+        if (event.type === 'resubscribe_required') {
+            this.addDiagnostic('warning', 'SEQUENCE_GAP', 'Channel sequence is discontinuous', event.reason);
+            this.replaceSubscription(state, 'sequence gap');
+            return;
+        }
+        state.awaitingSnapshot = false;
+        state.subscribedAt = null;
+        state.failed = false;
+        const { type: _type, channel: _channel, timestamp_ns, sequence: _sequence, previous_sequence: _previous, ...data } = frame;
+        this.dispatch(state, {
+            type: 'update',
+            channel: state.channel,
+            snapshot,
+            sequence,
+            previous_sequence: previous,
+            timestamp_ns: typeof timestamp_ns === 'string' ? timestamp_ns : null,
+            data,
+        });
+    }
+    handleError(frame) {
+        const code = typeof frame.code === 'number' ? frame.code : null;
+        const message = typeof frame.message === 'string' ? frame.message : 'WebSocket server error';
+        if (typeof frame.channel !== 'string') {
+            this.addDiagnostic('error', `SERVER_${code ?? 'ERROR'}`, message, frame);
+            return;
+        }
+        const state = this.channels.get(frame.channel);
+        if (!state)
+            return;
+        if (code === 503) {
+            // The server closed only this channel (stream unavailable / indexer
+            // rollback). Re-subscribing requests a fresh snapshot.
+            this.addDiagnostic('warning', 'STREAM_UNAVAILABLE', message, {
+                channel: state.channel,
+            });
+            this.clearRetry(state);
+            state.awaitingSnapshot = true;
+            state.subscribedAt = null;
+            this.dispatch(state, {
+                type: 'reset',
+                channel: state.channel,
+                reason: 'server closed the stream',
+            });
+            state.retryTimer = (this.options.schedule ?? setTimeout)(() => {
+                state.retryTimer = null;
+                if (this.channels.get(state.channel) === state)
+                    this.sendSubscribe(state);
+            }, STREAM_RETRY_MS);
+            return;
+        }
+        if (code === 409) {
+            this.replaceSubscription(state, 'server reports the channel already subscribed');
+            return;
+        }
+        state.failed = true;
+        state.awaitingSnapshot = true;
+        state.subscribedAt = null;
+        this.addDiagnostic('error', `SERVER_${code ?? 'ERROR'}`, message, {
+            channel: state.channel,
+        });
+        this.dispatch(state, {
+            type: 'error',
+            channel: state.channel,
+            code,
+            message,
+        });
+    }
+    rejectProtocol(message, detail) {
+        this.protocolRejected = true;
+        this.addDiagnostic('error', 'PROTOCOL_MISMATCH', message, detail);
+        this.setStatus('incompatible');
+    }
+    sendSubscribe(state) {
+        if (!this.canSend())
+            return;
+        state.awaitingSnapshot = true;
+        state.failed = false;
+        state.subscribedAt = this.now();
+        this.session.subscribe(state.channel);
+        this.send({ type: 'subscribe', channel: state.channel });
+    }
+    replaceSubscription(state, reason) {
+        this.clearRetry(state);
+        this.addDiagnostic('warning', 'CLIENT_RESYNC', reason, {
+            channel: state.channel,
+        });
+        state.awaitingSnapshot = true;
+        state.failed = false;
+        state.subscribedAt = null;
+        this.dispatch(state, { type: 'reset', channel: state.channel, reason });
+        if (!this.canSend())
+            return;
+        this.session.unsubscribe(state.channel);
+        this.send({ type: 'unsubscribe', channel: state.channel });
+        this.sendSubscribe(state);
+    }
+    removeChannel(state) {
+        this.clearRetry(state);
+        this.channels.delete(state.channel);
+        if (this.canSend()) {
+            this.session.unsubscribe(state.channel);
+            this.send({ type: 'unsubscribe', channel: state.channel });
+        }
+        if (this.channels.size === 0) {
+            this.clearTimers();
+            this.generation += 1;
+            this.socket?.close(1000, 'no active subscriptions');
+            this.socket = null;
+            this.helloAccepted = false;
+            this.setStatus('idle');
+        }
+    }
+    clearRetry(state) {
+        if (state.retryTimer !== null) {
+            (this.options.cancelSchedule ?? clearTimeout)(state.retryTimer);
+            state.retryTimer = null;
+        }
+    }
+    /** Replace subscriptions whose snapshot never arrived. */
+    startWatchdog() {
+        this.stopWatchdog();
+        this.watchdogTimer = (this.options.repeat ?? setInterval)(() => {
+            const now = this.now();
+            for (const state of [...this.channels.values()]) {
+                if (state.awaitingSnapshot && state.subscribedAt !== null && now - state.subscribedAt > SNAPSHOT_TIMEOUT_MS) {
+                    this.replaceSubscription(state, 'snapshot timeout');
+                }
+            }
+        }, WATCHDOG_MS);
+    }
+    stopWatchdog() {
+        if (this.watchdogTimer !== null) {
+            (this.options.cancelRepeat ?? clearInterval)(this.watchdogTimer);
+            this.watchdogTimer = null;
+        }
+    }
+    clearTimers() {
+        this.stopWatchdog();
+        if (this.reconnectTimer !== null) {
+            (this.options.cancelSchedule ?? clearTimeout)(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    scheduleReconnect() {
+        if (this.protocolRejected || this.reconnectTimer || this.channels.size === 0) {
+            if (this.channels.size === 0)
+                this.setStatus('idle');
+            return;
+        }
+        this.reconnectAttempt += 1;
+        this.setStatus('reconnecting');
+        const exponential = 250 * 2 ** Math.min(this.reconnectAttempt - 1, 8);
+        const jitter = 0.5 + (this.options.random ?? Math.random)();
+        const delay = Math.min(MAX_RECONNECT_MS, exponential * jitter);
+        this.reconnectTimer = (this.options.schedule ?? setTimeout)(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    canSend() {
+        return this.helloAccepted && this.socket != null && this.socket.canSend();
+    }
+    send(value) {
+        this.socket.send(value);
+    }
+    dispatch(state, frame) {
+        // Freeze the recipient set: a handler may synchronously attach another
+        // consumer, which must start at the replacement snapshot rather than
+        // receive the tail of the lifecycle that is ending.
+        for (const handler of [...state.handlers.keys()]) {
+            try {
+                handler(frame);
+            }
+            catch (error) {
+                this.addDiagnostic('error', 'HANDLER_FAILED', 'A subscription consumer rejected a frame', {
+                    error,
+                    channel: state.channel,
+                    frameType: frame.type,
+                });
+            }
+        }
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    setStatus(status) {
+        if (this.status === status)
+            return;
+        this.status = status;
+        for (const handler of this.statusHandlers)
+            handler(status);
+    }
+    addDiagnostic(level, code, message, detail) {
+        const diagnostic = { at: this.now(), level, code, message, detail };
+        this.diagnostics.push(diagnostic);
+        if (this.diagnostics.length > 100)
+            this.diagnostics.shift();
+        for (const handler of this.diagnosticHandlers)
+            handler(diagnostic);
+    }
+}
+export function gatewayWebSocketUrl(apiUrl) {
+    return `${apiUrl.replace(/^http/, 'ws').replace(/\/+$/, '')}/v1/ws`;
+}
+export const __testing = {
+    SOCKET_CONNECTING,
+    SOCKET_OPEN,
+    SNAPSHOT_TIMEOUT_MS,
+    STREAM_RETRY_MS,
+};