@abraca/dabra 2.8.0 → 2.9.0

package/dist/index.d.ts

@@ -2212,7 +2212,19 @@ declare class AbracadabraWS extends EventEmitter {
     resolve: (value?: any) => void;
     reject: (reason?: any) => void;
   } | null;
+  private onlineListener;
+  private offlineListener;
   constructor(configuration: AbracadabraWSConfiguration);
+  /**
+   * Whether the device currently believes it has network connectivity.
+   *
+   * Treats "unknown" as online: in Node and other non-browser environments
+   * `navigator` (or `navigator.onLine`) is absent, and we must not gate
+   * reconnection there — only the browser exposes a trustworthy signal.
+   */
+  get isOnline(): boolean;
+  handleOnline(): void;
+  handleOffline(): void;
   receivedOnOpenPayload?: Event | undefined;
   onOpen(event: Event): Promise<void>;
   attach(provider: AbracadabraBaseProvider): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -41,7 +41,7 @@
     "yjs": "^13.6.8"
   },
   "devDependencies": {
-    "@abraca/schema": "2.8.0"
+    "@abraca/schema": "2.9.0"
   },
   "scripts": {
     "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"

package/src/AbracadabraWS.ts

@@ -182,6 +182,12 @@ export class AbracadabraWS extends EventEmitter {
     reject: (reason?: any) => void;
   } | null = null;
 
+  // Bound `online`/`offline` listeners, retained so we can detach them in
+  // destroy(). Only registered in browser-like environments (see constructor).
+  private onlineListener: (() => void) | null = null;
+
+  private offlineListener: (() => void) | null = null;
+
   constructor(configuration: AbracadabraWSConfiguration) {
     super();
     this.setConfiguration(configuration);
@@ -210,11 +216,57 @@ export class AbracadabraWS extends EventEmitter {
       this.configuration.messageReconnectTimeout / 10,
     );
 
+    // Offline-first reconnect gating. When the device reports it is offline we
+    // stop hammering the socket (failed attempts just flip status
+    // disconnected↔connecting and light up every connection indicator) and
+    // wait for the `online` event to resume immediately — no backoff wait.
+    if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+      this.onlineListener = this.handleOnline.bind(this);
+      this.offlineListener = this.handleOffline.bind(this);
+      window.addEventListener("online", this.onlineListener);
+      window.addEventListener("offline", this.offlineListener);
+    }
+
     if (this.shouldConnect) {
       this.connect();
     }
   }
 
+  /**
+   * Whether the device currently believes it has network connectivity.
+   *
+   * Treats "unknown" as online: in Node and other non-browser environments
+   * `navigator` (or `navigator.onLine`) is absent, and we must not gate
+   * reconnection there — only the browser exposes a trustworthy signal.
+   */
+  get isOnline(): boolean {
+    return typeof navigator === "undefined" || navigator.onLine !== false;
+  }
+
+  handleOnline() {
+    // Network came back — resume immediately if we still want a connection
+    // and aren't already connected. Bypasses the backoff that a pending
+    // retryer would otherwise wait out.
+    if (this.shouldConnect && this.status !== WebSocketStatus.Connected) {
+      this.connect();
+    }
+  }
+
+  handleOffline() {
+    // Stop attempting while offline, but preserve `shouldConnect` so intent
+    // survives — `handleOnline`/attach will resume once connectivity returns.
+    if (this.cancelWebsocketRetry) {
+      this.cancelWebsocketRetry();
+      this.cancelWebsocketRetry = undefined;
+    }
+    try {
+      this.webSocket?.close();
+      this.messageQueue = [];
+    } catch (e) {
+      console.error(e);
+    }
+  }
+
   receivedOnOpenPayload?: Event | undefined = undefined;
 
   async onOpen(event: Event) {
@@ -271,6 +323,14 @@ export class AbracadabraWS extends EventEmitter {
       return;
     }
 
+    // Don't attempt while the device is offline — record the intent and let
+    // the `online` event drive the resume. Avoids the reconnect storm of
+    // instantly-failing socket attempts against a known-dead network.
+    if (!this.isOnline) {
+      this.shouldConnect = true;
+      return;
+    }
+
     // Always cancel any previously initiated connection retryer instances
     if (this.cancelWebsocketRetry) {
       this.cancelWebsocketRetry();
@@ -548,8 +608,11 @@ export class AbracadabraWS extends EventEmitter {
       this.emit("rateLimited");
     }
 
-    // trigger connect if no retry is running and we want to have a connection
-    if (!this.cancelWebsocketRetry && this.shouldConnect) {
+    // trigger connect if no retry is running and we want to have a connection.
+    // Skip scheduling entirely while offline — `handleOnline` resumes the
+    // moment connectivity returns, so there's no point burning a timer (and a
+    // failed attempt) against a dead network.
+    if (!this.cancelWebsocketRetry && this.shouldConnect && this.isOnline) {
       // Apply a much longer delay for rate-limited closes to let the server window reset.
       const delay = isRateLimited ? 60_000 : this.configuration.delay;
       setTimeout(() => {
@@ -565,6 +628,13 @@ export class AbracadabraWS extends EventEmitter {
 
     this.emit("destroy");
 
+    if (typeof window !== "undefined" && typeof window.removeEventListener === "function") {
+      if (this.onlineListener) window.removeEventListener("online", this.onlineListener);
+      if (this.offlineListener) window.removeEventListener("offline", this.offlineListener);
+    }
+    this.onlineListener = null;
+    this.offlineListener = null;
+
     clearInterval(this.intervals.connectionChecker);
 
     // If there is still a connection attempt outstanding then we should stop