@droponair/sdk-js 0.22.1 → 0.23.1

package/CHANGELOG.md

@@ -6,6 +6,23 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.23.1], 2026-06-01
+
+### Fixed
+
+- **WebSocket reconnect storm / eviction loop.** Reconnect is now single-flight: each connect attempt claims a generation, and a superseded socket's `onOpen`/`onClose`/`onError` callbacks are ignored. A stale socket closing (notably the old socket the server evicts with close code `4000 REPLACED_BY_SAME_DEVICE` right after our own reconnect) no longer nulls the live transport or schedules another reconnect, which was causing rapid connect/disconnect flapping. The client also no longer reconnects on close code `4000` (another connection is authoritative), reconnect timers never stack, and backoff gained jitter.
+- **`Cannot read properties of null (reading 'send')` on send.** `sendMessage`'s open-check happens before a long async encryption phase during which the socket can close. Sends now go through a guarded `sendFrame` that re-checks the captured transport and throws a clean, retryable "not connected" error instead of dereferencing null.
+
+---
+
+## [0.23.0], 2026-06-01
+
+### Added
+
+- **Idempotent retries via `sendMessage(..., { clientMessageId })`.** Pass a stable id to reuse across retries of the same logical message. The relay now dedups by `(appId, fromUserId, messageId)`, so re-sending after a lost ack or a reconnect delivers the message at most once instead of creating duplicates. Omit it for new messages and a fresh id is generated (unchanged default behavior). Requires relay support shipped alongside this release; wire format and `PROTOCOL_VERSION` are unchanged (the `clientMessageId` field already existed).
+
+---
+
 ## [0.22.1], 2026-05-31
 
 ### Fixed

package/dist/core/messaging-client.d.ts

@@ -23,6 +23,7 @@ export declare class MessagingClient implements DropOnAirClient {
     private deviceId;
     private rateLimited;
     private reconnectAttempt;
+    private connectGeneration;
     private handlingJwtExpiry;
     private proactiveRefreshTimer;
     private visibilityChangeHandler;
@@ -41,6 +42,8 @@ export declare class MessagingClient implements DropOnAirClient {
     /** Pending joinRoom resolver (Feature 3.1), keyed by roomId. */
     private readonly pendingRoomJoins;
     private reconnectDelayMs;
+    /** Schedule a single reconnect, replacing any pending one (never stack timers). */
+    private scheduleReconnect;
     /**
      * Register a document visibilitychange listener so that when the iOS app
      * returns from background we can immediately assess the JWT state.
@@ -101,9 +104,18 @@ export declare class MessagingClient implements DropOnAirClient {
     disconnect(): void;
     sendMessage(toUserId: string, plaintextMessage: string, options?: {
         attachments?: AttachmentRef[];
+        clientMessageId?: string;
     }): Promise<{
         messageId: string;
     }>;
+    /**
+     * Send raw frame bytes with a fresh open-check on a captured transport ref.
+     * sendMessage's open-check happens before a long async encryption phase; the
+     * socket can close during it. Re-checking here (and letting the transport's own
+     * guard throw cleanly) avoids `Cannot read properties of null (reading 'send')`
+     * and instead throws a retryable "not connected" the app can handle.
+     */
+    private sendFrame;
     ack(messageId: string): Promise<void>;
     onMessage(callback: MessageCallback): () => void;
     onEvent(callback: EventCallback): () => void;

package/dist/core/messaging-client.js

@@ -12,10 +12,28 @@ const attachment_client_1 = require("../attachment/attachment-client");
 const STORAGE_DEVICE_ID = 'droponair.device.id.v1';
 class MessagingClient {
     reconnectDelayMs() {
-        // Exponential backoff: 2s, 4s, 8s, 16s, 32s, 60s (capped)
-        const delay = Math.min(2000 * Math.pow(2, this.reconnectAttempt), 60000);
+        // Exponential backoff with jitter: ~2s, 4s, 8s, 16s, 32s, 60s (capped), +/-20%.
+        // Jitter avoids many clients reconnecting in lockstep after a server blip.
+        const base = Math.min(2000 * Math.pow(2, this.reconnectAttempt), 60000);
         this.reconnectAttempt++;
-        return delay;
+        const jitter = base * 0.2 * (Math.random() * 2 - 1);
+        return Math.max(1000, Math.round(base + jitter));
+    }
+    /** Schedule a single reconnect, replacing any pending one (never stack timers). */
+    scheduleReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const delay = this.reconnectDelayMs();
+        this.log('ws_reconnect_scheduled', { attempt: this.reconnectAttempt, delayMs: delay });
+        this.emitEvent({ type: 'RECONNECTING' });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connectWebSocket().catch(() => {
+                this.emitEvent({ type: 'ERROR', reason: 'RECONNECT_FAILED' });
+            });
+        }, delay);
     }
     /**
      * Register a document visibilitychange listener so that when the iOS app
@@ -206,6 +224,13 @@ class MessagingClient {
         this.deviceId = null;
         this.rateLimited = false;
         this.reconnectAttempt = 0;
+        // Monotonic id for each connect attempt. Transport callbacks (onOpen/onError/
+        // onClose) check this against the live generation and ignore themselves if a
+        // newer attempt has superseded them. This makes connect single-flight and
+        // prevents a stale socket's close (e.g. the old socket evicted with code 4000
+        // after our own reconnect) from nulling the live transport and scheduling
+        // another reconnect, which was the eviction/flap loop.
+        this.connectGeneration = 0;
         this.handlingJwtExpiry = false;
         this.proactiveRefreshTimer = null;
         this.visibilityChangeHandler = null;
@@ -337,7 +362,10 @@ class MessagingClient {
             throw new Error('JWT_EXPIRED: Secure messaging session is reconnecting; please retry in a moment');
         }
         const myDeviceId = this.deviceId ?? await this.getOrCreateDeviceId();
-        const messageId = crypto.randomUUID();
+        // Reuse a caller-supplied id for idempotent retries: the relay dedups by
+        // (appId, fromUserId, messageId), so re-sending with the same id is a no-op
+        // delivery instead of a duplicate. Defaults to a fresh id for new messages.
+        const messageId = options?.clientMessageId ?? crypto.randomUUID();
         const timestamp = Date.now();
         const myIdentity = await this.cryptoService.getOrCreateIdentity();
         const myPublicKeyBytes = (0, bytes_1.fromBase64)(myIdentity.publicKey);
@@ -382,7 +410,7 @@ class MessagingClient {
             if (options?.attachments && options.attachments.length > 0) {
                 envelope.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
             }
-            this.transport.send(this.codec.encodeEnvelope(envelope));
+            this.sendFrame(this.codec.encodeEnvelope(envelope));
         }
         else {
             // Legacy fallback: peer has no device keys (old client)
@@ -405,10 +433,24 @@ class MessagingClient {
             if (options?.attachments && options.attachments.length > 0) {
                 envelope.attachments = options.attachments.map(a => this.attachmentClient.toWire(a));
             }
-            this.transport.send(this.codec.encodeEnvelope(envelope));
+            this.sendFrame(this.codec.encodeEnvelope(envelope));
         }
         return { messageId };
     }
+    /**
+     * Send raw frame bytes with a fresh open-check on a captured transport ref.
+     * sendMessage's open-check happens before a long async encryption phase; the
+     * socket can close during it. Re-checking here (and letting the transport's own
+     * guard throw cleanly) avoids `Cannot read properties of null (reading 'send')`
+     * and instead throws a retryable "not connected" the app can handle.
+     */
+    sendFrame(bytes) {
+        const t = this.transport;
+        if (!t || !t.isOpen()) {
+            throw new Error('DropOnAir websocket is not connected');
+        }
+        t.send(bytes);
+    }
     async ack(messageId) {
         if (!this.transport?.isOpen()) {
             return;
@@ -1650,7 +1692,20 @@ class MessagingClient {
             this.logError('ws_connect_jwt_expired', this.jwtSummary(this.dropOnAirJwt));
             throw new Error('DropOnAir JWT expired before websocket connect');
         }
+        // Single-flight: claim a generation for this attempt. Any socket/callbacks
+        // from an older attempt are now stale and must be ignored.
+        const myGen = ++this.connectGeneration;
         const transport = await this.resolveTransport(this.dropOnAirJwt);
+        // A newer connect attempt started while we were exchanging the token; abandon
+        // this one so we never run two live sockets for the same device.
+        if (myGen !== this.connectGeneration) {
+            this.log('ws_connect_superseded_pre_open', { myGen, current: this.connectGeneration });
+            try {
+                transport.close();
+            }
+            catch { /* ignore */ }
+            return;
+        }
         this.log('ws_connect_start', {
             transport: this.resolvedTransportName,
             wsUrl: this.wsUrl,
@@ -1660,9 +1715,19 @@ class MessagingClient {
         await new Promise((resolve, reject) => {
             let opened = false;
             transport.onOpen(() => {
+                // If superseded between resolve and open, drop this stale socket.
+                if (myGen !== this.connectGeneration) {
+                    try {
+                        transport.close();
+                    }
+                    catch { /* ignore */ }
+                    resolve();
+                    return;
+                }
                 this.transport = transport;
                 opened = true;
                 this.rateLimited = false;
+                this.reconnectAttempt = 0; // healthy connection resets backoff
                 this.log('ws_connected', { transport: this.resolvedTransportName, wsUrl: this.wsUrl });
                 this.emitEvent({ type: 'CONNECTED' });
                 if (this.dropOnAirJwt) {
@@ -1675,12 +1740,22 @@ class MessagingClient {
                 resolve();
             });
             transport.onError((err) => {
+                if (myGen !== this.connectGeneration) {
+                    return;
+                }
                 this.logError('ws_error', { wsUrl: this.wsUrl, error: err.message });
                 if (!opened) {
                     reject(new Error('Failed to connect DropOnAir websocket'));
                 }
             });
             transport.onClose((info) => {
+                // Stale close from a superseded socket (e.g. the old socket evicted with
+                // code 4000 after our own reconnect). Ignore it: do NOT null the live
+                // transport and do NOT schedule a reconnect, that was the flap loop.
+                if (myGen !== this.connectGeneration) {
+                    this.log('ws_stale_close_ignored', { code: info.code, myGen, current: this.connectGeneration });
+                    return;
+                }
                 this.transport = null;
                 this.handlingJwtExpiry = false;
                 if (this.proactiveRefreshTimer) {
@@ -1692,17 +1767,15 @@ class MessagingClient {
                     this.emitEvent({ type: 'ERROR', reason: 'JWT_EXPIRED' });
                 }
                 this.emitEvent({ type: 'DISCONNECTED' });
-                if (this.shouldReconnect) {
-                    const delay = this.reconnectDelayMs();
-                    this.log('ws_reconnect_scheduled', { attempt: this.reconnectAttempt, delayMs: delay });
-                    this.emitEvent({ type: 'RECONNECTING' });
-                    this.reconnectTimer = setTimeout(() => {
-                        this.connectWebSocket().then(() => {
-                            this.reconnectAttempt = 0;
-                        }).catch(() => {
-                            this.emitEvent({ type: 'ERROR', reason: 'RECONNECT_FAILED' });
-                        });
-                    }, delay);
+                // 4000 = the server superseded this session (REPLACED_BY_SAME_DEVICE /
+                // MAX_SESSIONS_EXCEEDED). Another connection is authoritative; do not
+                // reconnect or we would fight it in an eviction loop.
+                const supersededByOtherSession = info.code === 4000;
+                if (this.shouldReconnect && !supersededByOtherSession) {
+                    this.scheduleReconnect();
+                }
+                else if (supersededByOtherSession) {
+                    this.log('ws_superseded_no_reconnect', { code: info.code, reason: info.reason });
                 }
             });
             transport.onFrame(async (bytes) => {

package/dist/core/types.d.ts

@@ -304,9 +304,16 @@ export interface DropOnAirClient {
     /**
      * Send a 1:1 E2EE message. Optionally attach one or more attachments
      * prepared via {@link prepareAttachmentAndUpload} or {@link createUploadSession}.
+     *
+     * Pass `options.clientMessageId` to reuse a stable id across retries: the relay
+     * dedups by `(appId, fromUserId, messageId)`, so re-sending a message with the
+     * same id delivers it at most once instead of creating a duplicate. Omit it for
+     * new messages and a fresh id is generated. The chosen id is returned as
+     * `messageId`.
      */
     sendMessage(toUserId: string, plaintextMessage: string, options?: {
         attachments?: import('../attachment/attachment-types').AttachmentRef[];
+        clientMessageId?: string;
     }): Promise<{
         messageId: string;
     }>;

package/dist/version.d.ts

@@ -7,7 +7,7 @@
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-export declare const SDK_VERSION = "0.22.1";
+export declare const SDK_VERSION = "0.23.1";
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/dist/version.js

@@ -10,7 +10,7 @@ exports.PROTOCOL_VERSION = exports.PAYLOAD_FORMAT_VERSION = exports.SDK_VERSION
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-exports.SDK_VERSION = '0.22.1';
+exports.SDK_VERSION = '0.23.1';
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@droponair/sdk-js",
-  "version": "0.22.1",
+  "version": "0.23.1",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",