@0xmonaco/core 1.0.25-develop.1fab96c → 1.0.26

package/dist/api/websocket/types.d.ts

@@ -1,15 +1,51 @@
 import type { ConditionalOrderEvent, Interval, OHLCVEvent, OrderbookEvent, OrderbookQuotationMode, OrderEvent, SessionCredentials, TradeEvent, TradingMode, UserBalanceEvent, UserMovementEvent, WebSocketStatus } from "@0xmonaco/types";
 export type StatusHandler = (status: WebSocketStatus) => void;
 export type MessageHandler<T> = (data: T) => void;
+/**
+ * Why the connection was re-established. Delivered by
+ * {@link MonacoWebSocketOptions.onResync} after the client has reconnected,
+ * re-authenticated, and re-subscribed — the point where the app should
+ * refetch REST snapshots and reconcile by `(id, updatedAt)`.
+ */
+export interface WebSocketResyncInfo {
+    /** WebSocket close code of the connection that was lost. */
+    code: number;
+    /**
+     * True when the server closed with 1013 (try again later): the client fell
+     * behind a sequential stream (orders, conditional orders, liquidations,
+     * trades, movements) and the stream has a gap. There is no wire sequence
+     * number — the 1013 close is the gap signal, and a snapshot refetch is the
+     * only safe repair.
+     */
+    slowClient: boolean;
+}
+export type ResyncHandler = (info: WebSocketResyncInfo) => void;
 export interface MonacoWebSocketOptions {
     /** Session keypair for authenticated channels (orders, balances, etc.) */
     session?: SessionCredentials;
     /** Enable auto-reconnect on disconnect (default: true) */
     autoReconnect?: boolean;
-    /** Maximum reconnection attempts (default: 5) */
+    /**
+     * Maximum reconnection attempts (default: unlimited). Retry delay is
+     * full-jitter exponential backoff capped at 30s, so unlimited retries are
+     * capped-rate, not a tight loop.
+     */
     maxReconnectAttempts?: number;
+    /** Base delay for the exponential backoff in milliseconds (default: 1000) */
+    reconnectBaseDelayMs?: number;
+    /** How long a connection attempt may stay CONNECTING before it is failed
+     * and retried, in milliseconds (default: 10000) */
+    connectionTimeoutMs?: number;
     /** Callback for connection status changes */
     onStatusChange?: StatusHandler;
+    /**
+     * Called after every automatic reconnect once the live stream is resumed
+     * (re-authenticated and re-subscribed). Refetch REST snapshots here and
+     * reconcile by `(id, updatedAt)`, last-writer-wins; events that arrived
+     * while the snapshot was in flight are newer than the snapshot rows they
+     * duplicate.
+     */
+    onResync?: ResyncHandler;
 }
 export interface MonacoWebSocket {
     /** Connect to the WebSocket server */

package/dist/api/websocket/websocket.js

@@ -6,6 +6,7 @@ import { keysToCamelCase } from "./utils";
 const CONNECTION_TIMEOUT = 10000;
 const HEARTBEAT_INTERVAL = 15000;
 const MAX_RECONNECT_DELAY = 30000;
+const RECONNECT_BASE_DELAY = 1000;
 const CONDITIONAL_ORDER_REASONS = ["created", "activated", "cancelled", "parent_cancelled", "triggered", "failed", "oco_cancelled"];
 const CONDITIONAL_ORDER_CONDITION_TYPES = ["STOP_LOSS", "TAKE_PROFIT"];
 const CONDITIONAL_ORDER_TRIGGER_SOURCES = ["MARK_PRICE"];
@@ -114,19 +115,33 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
     let reconnectTimer = null;
     let heartbeatTimer = null;
     let autoReconnect = options.autoReconnect ?? true;
-    const maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
+    // Capped-infinite by default: unlimited attempts, delay capped at 30s. A
+    // client that gives up permanently (the old 5-attempt default) turns any
+    // blip longer than ~1 minute into a dead app.
+    const maxReconnectAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
+    // Normalize to a positive finite base: a negative/NaN/Infinity override
+    // would degenerate into a tight reconnect loop or no reconnect at all.
+    const reconnectBaseDelay = Number.isFinite(options.reconnectBaseDelayMs) && options.reconnectBaseDelayMs > 0
+        ? options.reconnectBaseDelayMs
+        : RECONNECT_BASE_DELAY;
+    const connectionTimeout = Number.isFinite(options.connectionTimeoutMs) && options.connectionTimeoutMs > 0 ? options.connectionTimeoutMs : CONNECTION_TIMEOUT;
+    // Close code of the connection loss the next successful reopen recovers
+    // from; null when no resync is owed (first connect, clean disconnect).
+    let pendingResyncCode = null;
     // Handler storage: channel -> set of handlers (supports multiple subscribers per channel)
     const handlers = new Map();
     const getStatus = () => {
         if (!ws)
-            return "disconnected";
+            return reconnectTimer ? "reconnecting" : "disconnected";
         switch (ws.readyState) {
             case WebSocket.CONNECTING:
                 return "connecting";
             case WebSocket.OPEN:
                 return "connected";
             default:
-                return "disconnected";
+                // CLOSING/CLOSED with a retry armed is mid-outage, not terminal:
+                // the timeout path arms the retry before the close event lands.
+                return reconnectTimer ? "reconnecting" : "disconnected";
         }
     };
     const getUrl = () => baseUrl;
@@ -169,17 +184,35 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         }
     };
     const scheduleReconnect = () => {
+        // Single scheduling authority: a failed attempt can report through both
+        // the connect() rejection and the socket's own close event — an armed
+        // timer means the retry is already owned.
+        if (reconnectTimer)
+            return;
         if (!autoReconnect || reconnectAttempts >= maxReconnectAttempts) {
             console.error("WebSocket: Max reconnect attempts reached");
             return;
         }
+        // Full-jitter exponential backoff: uniform in [0, min(base * 2^n, cap)],
+        // n starting at 0 so the first retry's ceiling is the base itself.
+        // Jitter desynchronizes the reconnect storm after a server deploy or a
+        // mass 1013 shed — synchronized clients would otherwise reconnect in
+        // lockstep waves.
+        const ceiling = Math.min(reconnectBaseDelay * 2 ** reconnectAttempts, MAX_RECONNECT_DELAY);
         reconnectAttempts++;
-        const delay = Math.min(1000 * 2 ** reconnectAttempts, MAX_RECONNECT_DELAY);
+        const delay = Math.random() * ceiling;
         reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            // Re-check: a callback already dequeued when disconnect() ran is not
+            // stopped by clearTimeout and must not reopen a socket.
+            if (!autoReconnect)
+                return;
             connect().catch((err) => {
                 console.warn("WebSocket: Failed to reconnect:", err);
+                scheduleReconnect();
             });
         }, delay);
+        options.onStatusChange?.("reconnecting");
     };
     const send = (data) => {
         if (ws?.readyState === WebSocket.OPEN) {
@@ -223,7 +256,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
                         socket.close(1000, "Connection timeout");
                         reject(new Error("WebSocket connection timeout"));
                     }
-                }, CONNECTION_TIMEOUT);
+                }, connectionTimeout);
                 socket.onopen = () => {
                     clearTimeout(timeout);
                     if (ws !== socket) {
@@ -231,12 +264,26 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
                         return;
                     }
                     reconnectAttempts = 0;
+                    // A retry armed before this open (e.g. a manual connect() during
+                    // backoff) is moot now — left running it would suppress the
+                    // terminal disconnected emit and reopen a socket after a clean
+                    // close.
+                    stopReconnect();
                     startHeartbeat();
                     // Authenticate before resubscribing so user-specific channels
                     // (orders, balances, …) are authorized when the Subscribe arrives.
                     sendAuthenticate();
                     resubscribeAll();
                     options.onStatusChange?.("connected");
+                    // Resync-join order: resume the live stream first (auth +
+                    // subscribe above), then tell the app to refetch snapshots and
+                    // reconcile by (id, updatedAt) — events racing the snapshot are
+                    // newer than the rows they duplicate.
+                    if (pendingResyncCode !== null) {
+                        const code = pendingResyncCode;
+                        pendingResyncCode = null;
+                        options.onResync?.({ code, slowClient: code === 1013 });
+                    }
                     resolve();
                 };
                 socket.onmessage = (event) => {
@@ -247,6 +294,12 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
                         // Handle pong silently
                         if (msg.type === "Pong")
                             return;
+                        // Answer a server-initiated application ping: the server owns
+                        // liveness through proxy idle timeouts, the client just echoes.
+                        if (msg.type === "Ping") {
+                            send({ type: "Pong" });
+                            return;
+                        }
                         routeMessage(msg);
                     }
                     catch (err) {
@@ -261,11 +314,22 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
                     }
                     ws = null;
                     stopHeartbeat();
-                    options.onStatusChange?.("disconnected");
-                    // Reconnect on abnormal close
+                    // Reconnect on abnormal close. 1013 is the server's slow-client
+                    // shed: the stream has a gap, so the reopen owes the app a resync.
+                    // Keep the first owed code (upgrading to 1013 if it arrives later):
+                    // failures of the reconnect attempts themselves must not launder
+                    // the slow-client signal into a generic 1006.
                     if (autoReconnect && event.code !== 1000) {
+                        if (pendingResyncCode === null || event.code === 1013) {
+                            pendingResyncCode = event.code;
+                        }
                         scheduleReconnect();
                     }
+                    // "disconnected" is terminal: suppressed while a retry is armed
+                    // (scheduleReconnect emitted "reconnecting" instead).
+                    if (!reconnectTimer) {
+                        options.onStatusChange?.("disconnected");
+                    }
                 };
                 socket.onerror = () => clearTimeout(timeout);
             }
@@ -279,6 +343,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         autoReconnect = false;
         stopReconnect();
         stopHeartbeat();
+        pendingResyncCode = null;
         handlers.clear();
         ws?.close(1000, "Client disconnect");
         ws = null;

package/dist/networks/networks.js

@@ -22,7 +22,10 @@ const DEFAULT_API_URLS = {
  */
 const DEFAULT_WS_URLS = {
     local: "ws://localhost:8085/ws",
-    development: "wss://develop.apimonaco.xyz/ws",
+    // Dedicated WebSocket ingress (NLB behind Cloudflare). The previous
+    // ALB path (wss://develop.apimonaco.xyz/ws) keeps working during the
+    // migration window.
+    development: "wss://ws-develop.apimonaco.xyz/ws",
     staging: "wss://staging.apimonaco.xyz/ws",
     mainnet: "wss://api.monaco.xyz/ws",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/core",
-	"version": "1.0.25-develop.1fab96c",
+	"version": "1.0.26",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -23,8 +23,8 @@
 		"viem": "^2.45.2"
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "1.0.25-develop.1fab96c",
-		"@0xmonaco/types": "1.0.25-develop.1fab96c",
+		"@0xmonaco/contracts": "1.0.26",
+		"@0xmonaco/types": "1.0.26",
 		"@noble/curves": "^1.9.1",
 		"@noble/hashes": "^1.8.0",
 		"http-status-codes": "^2.3.0"