cross-tab-worker-databus 0.6.0 → 0.8.0

package/dist/cjs/centrifuge.cjs

@@ -537,6 +537,7 @@ var WorkerClusterRuntime = class {
       projectedLoads.set(owner.workerId, (projectedLoads.get(owner.workerId) ?? owner.load) + 1);
       const generation = (previous?.generation ?? 0) + 1;
       this.writeRoute(topicKey, owner, previous?.workerId, generation);
+      this.handlers.onDiagnostic?.({ operation: "route_migration", topic });
       this.flushStorage();
       this.handlers.onControl("UNSUBSCRIBE", topic);
       this.sendRouteReleased(owner.workerId, topic, topicKey, generation);
@@ -548,20 +549,20 @@ var WorkerClusterRuntime = class {
    * posted to a remote owner, so the caller can surface the failure instead of
    * silently dropping the publication.
    */
-  publish(topic, data) {
+  publish(topic, data, messageId) {
     const topicKey = this.rememberTopic(topic);
     if (this.assignedTopics.has(topicKey)) {
-      return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data);
+      return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, messageId);
     }
     for (const pattern of this.assignedTopics.values()) {
       if (pattern !== topic && topicMatchesPattern(pattern, topic)) {
-        return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data);
+        return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, messageId);
       }
     }
     const workers = this.readWorkers();
     const route = this.readRoute(topicKey);
     const target = this.routeOwnerIsLive(route, workers) ? route?.workerId ?? this.workerId : this.workerId;
-    return this.sendControl(target, "PUBLISH", topic, topicKey, data);
+    return this.sendControl(target, "PUBLISH", topic, topicKey, data, messageId);
   }
   /** True when `route` exists and its owner worker is among `workers`.
    * Shared by subscribe (skip re-assignment) and publish (route to owner).
@@ -683,7 +684,11 @@ var WorkerClusterRuntime = class {
       default:
         break;
     }
-    this.handlers.onControl(message.action, message.topic, message.data);
+    if (message.messageId === void 0) {
+      this.handlers.onControl(message.action, message.topic, message.data);
+    } else {
+      this.handlers.onControl(message.action, message.topic, message.data, message.messageId);
+    }
     if (message.action !== "PUBLISH") this.updateLoad();
   }
   /**
@@ -800,7 +805,7 @@ var WorkerClusterRuntime = class {
    * Local execution updates the assignment map and route synchronously, bypassing
    * the BroadcastChannel latency.
    */
-  sendControl(targetWorkerId, action, topic, topicKey, data) {
+  sendControl(targetWorkerId, action, topic, topicKey, data, messageId) {
     if (targetWorkerId === this.workerId) {
       switch (action) {
         case "SUBSCRIBE":
@@ -814,7 +819,8 @@ var WorkerClusterRuntime = class {
         default:
           break;
       }
-      this.handlers.onControl(action, topic, data);
+      if (messageId === void 0) this.handlers.onControl(action, topic, data);
+      else this.handlers.onControl(action, topic, data, messageId);
       if (action !== "PUBLISH") this.updateLoad();
       return true;
     }
@@ -825,7 +831,8 @@ var WorkerClusterRuntime = class {
       action,
       topic,
       topicKey,
-      ...data === void 0 ? {} : { data }
+      ...data === void 0 ? {} : { data },
+      ...messageId === void 0 ? {} : { messageId }
     });
   }
   /** Post a message on the BroadcastChannel. Returns false on postMessage failure. */
@@ -921,6 +928,8 @@ var WorkerClusterRuntime = class {
       ...route,
       confirmedAt: this.environment.now()
     });
+    const topic = this.knownTopics.get(topicKey);
+    if (topic) this.handlers.onDiagnostic?.({ operation: "route_ack", topic });
   }
   /** Remove routes whose topic has no subscribers and whose TTL has expired. */
   cleanupOrphanedRoutes(workers) {
@@ -1214,6 +1223,10 @@ var CrossTabDataBus = class _CrossTabDataBus {
   initialConfig;
   hasInitialConfig;
   trace;
+  dedupMaxEntries;
+  dedupTtlMs;
+  dedupEnabled;
+  seenMessageIds = /* @__PURE__ */ new Map();
   activeConfig;
   status = "disconnected";
   started = false;
@@ -1252,17 +1265,26 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.replayBuffers = replay ? /* @__PURE__ */ new Map() : null;
     this.replayPersistence = replay?.persistence ?? null;
     this.replayHydration = this.hydrateReplay();
-    const { autoStart, initialConfig, trace, transport, ...clusterOptions } = options;
+    const { autoStart, initialConfig, trace, transport, dedup, ...clusterOptions } = options;
     this.transport = transport;
     this.initialConfig = initialConfig;
     this.hasInitialConfig = "initialConfig" in options;
     this.trace = new DataBusTraceReporter(trace);
+    this.dedupMaxEntries = dedup?.maxEntries ?? 1e3;
+    this.dedupTtlMs = dedup?.ttlMs ?? 6e4;
+    this.dedupEnabled = dedup !== void 0;
+    if (!Number.isSafeInteger(this.dedupMaxEntries) || this.dedupMaxEntries <= 0) {
+      throw new TypeError("dedup.maxEntries must be a positive safe integer.");
+    }
+    if (!Number.isFinite(this.dedupTtlMs) || this.dedupTtlMs <= 0) {
+      throw new TypeError("dedup.ttlMs must be a positive finite number.");
+    }
     this.cluster = new WorkerClusterRuntime({
       ...clusterOptions,
       handlers: {
         // The cluster calls `onControl` when it receives a SUBSCRIBE/UNSUBSCRIBE/PUBLISH
         // control message — meaning the owning Worker has delegated the action to us.
-        onControl: (action, topic, data) => {
+        onControl: (action, topic, data, messageId) => {
           switch (action) {
             case "SUBSCRIBE":
               if (this.subscribeTransport(topic)) this.traceSubscription("subscribe", topic);
@@ -1271,7 +1293,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
               if (this.unsubscribeTransport(topic)) this.traceSubscription("unsubscribe", topic);
               break;
             case "PUBLISH":
-              this.runTransport(() => this.transport.publish(topic, data));
+              this.runTransport(() => this.transport.publish(topic, data, messageId ? { messageId } : void 0));
               break;
             default:
               break;
@@ -1296,6 +1318,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
           this.trace.event({ type: "lifecycle", action: "resume" });
           this.trace.start();
           this.resumeTransport();
+        },
+        onDiagnostic: (event) => {
+          this.trace.event({ type: "reliability", ...event });
         }
       }
     });
@@ -1442,12 +1467,27 @@ var CrossTabDataBus = class _CrossTabDataBus {
     if (handlers.size > 0) return;
     this.topicHandlers.delete(topic);
     this.replayBuffers?.delete(topic);
+    if (this.replayPersistence?.clearTopic) {
+      void this.replayPersistence.clearTopic(topic).catch((error) => this.reportError(error));
+    }
     this.cluster.unsubscribe(topic);
   }
+  /** Clear all in-memory replay buffers and, when supported, durable history. */
+  async clearReplay() {
+    this.replayBuffers?.clear();
+    if (this.replayPersistence?.clear) {
+      try {
+        await this.replayPersistence.clear();
+      } catch (error) {
+        this.reportError(error);
+        throw error;
+      }
+    }
+  }
   /** Publish a message to `topic`. The owning Worker delivers it to the transport. */
-  publish(topic, data) {
+  publish(topic, data, options) {
     this.ensureStarted();
-    if (!this.cluster.publish(topic, data)) {
+    if (!this.cluster.publish(topic, data, options?.messageId)) {
       this.reportError(
         new Error("Failed to send the publish control message to the owning worker.")
       );
@@ -1497,6 +1537,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
       else await this.transport.stop();
     } finally {
       this.transportSubscribedTopics.clear();
+      this.seenMessageIds.clear();
       this.started = false;
       this.stopping = false;
       this.suspended = false;
@@ -1514,6 +1555,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
    * and dispatches locally.
    */
   handleTransportMessage(message) {
+    if (this.isDuplicate(message)) return;
     this.trace.recordReceived(message.topic);
     if (!this.cluster.isAssigned(message.topic)) {
       this.trace.recordDiscarded(message.topic);
@@ -1526,6 +1568,24 @@ var CrossTabDataBus = class _CrossTabDataBus {
     }
     this.trace.recordDiscarded(message.topic);
   }
+  isDuplicate(message) {
+    if (!this.dedupEnabled || !message.messageId) return false;
+    const now = Date.now();
+    for (const [id, timestamp] of this.seenMessageIds) {
+      if (now - timestamp > this.dedupTtlMs) this.seenMessageIds.delete(id);
+    }
+    if (this.seenMessageIds.has(message.messageId)) {
+      this.trace.event({ type: "reliability", operation: "dedup_suppressed", topic: message.topic });
+      return true;
+    }
+    this.seenMessageIds.set(message.messageId, now);
+    while (this.seenMessageIds.size > this.dedupMaxEntries) {
+      const oldest = this.seenMessageIds.keys().next().value;
+      if (oldest === void 0) break;
+      this.seenMessageIds.delete(oldest);
+    }
+    return false;
+  }
   /** Deliver a message to every local handler registered for its topic,
    * plus every handler registered with a wildcard subscription that matches
    * (e.g. a handler subscribed to "chat.*" receives "chat.room.1"). */
@@ -1610,6 +1670,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
       const now = Date.now();
       if (now - this.lastRecoveryAt >= _CrossTabDataBus.RECOVERY_COOLDOWN_MS) {
         this.lastRecoveryAt = now;
+        this.trace.event({ type: "reliability", operation: "transport_recovery", attempt: 1 });
         setTimeout(() => {
           if (this.stopping || !this.started || this.suspended) return;
           if (this.status !== "error") return;
@@ -1790,7 +1851,7 @@ var CentrifugeSession = class {
         return;
       case "PUBLISH":
       case "PUBLISH_BIN":
-        this.publish(message.topic, message.data);
+        this.publish(message.topic, message.data, message.messageId);
         return;
       case "STOP":
         this.stop();
@@ -1855,9 +1916,10 @@ var CentrifugeSession = class {
     subscription.unsubscribe();
   }
   /** Publish a message to the Centrifuge channel. */
-  publish(topic, data) {
+  publish(topic, data, messageId) {
     if (!this.client) return this.postError(new Error("Centrifuge client is not initialized."));
-    void this.client.publish(topic, data).catch((error) => this.postError(error));
+    const payload = messageId ? { data, messageId } : data;
+    void this.client.publish(topic, payload).catch((error) => this.postError(error));
   }
   /** Forward a publication to the transport. Binary payloads take the
    * zero-copy `MESSAGE_BIN` path when `transferable` is enabled; everything
@@ -1869,7 +1931,9 @@ var CentrifugeSession = class {
       this.post({ type: "MESSAGE_BIN", topic, data }, [data]);
       return;
     }
-    this.post({ type: "MESSAGE", topic, data });
+    const messageId = data && typeof data === "object" && typeof data.messageId === "string" ? data.messageId : void 0;
+    const payload = messageId && Object.prototype.hasOwnProperty.call(data, "data") ? data.data : data;
+    this.post({ type: "MESSAGE", topic, data: payload, ...messageId ? { messageId } : {} });
   }
   /** Disconnect the client and clear all subscriptions. */
   stop() {
@@ -1999,12 +2063,12 @@ var CentrifugeWorkerTransport = class {
    * Publish data to `topic`. Binary data (ArrayBuffer) is sent via Transferable
    * when `transferable` is enabled, avoiding a structured-clone cycle.
    */
-  publish(topic, data) {
+  publish(topic, data, options) {
     if (this.transferable && data instanceof ArrayBuffer) {
-      this.post({ type: "PUBLISH_BIN", topic, data }, [data]);
+      this.post({ type: "PUBLISH_BIN", topic, data, ...options?.messageId ? { messageId: options.messageId } : {} }, [data]);
       return;
     }
-    this.post({ type: "PUBLISH", topic, data });
+    this.post({ type: "PUBLISH", topic, data, ...options?.messageId ? { messageId: options.messageId } : {} });
   }
   /**
    * Gracefully stop the transport: send STOP, clean up event listeners, and
@@ -2075,8 +2139,8 @@ var CentrifugeWorkerTransport = class {
    * and the local-session sink — all three feed into this single dispatcher. */
   handleOutput(message) {
     if (message.type === "STATUS") this.handlers?.onStatus(message.status);
-    if (message.type === "MESSAGE") this.handlers?.onMessage({ topic: message.topic, data: message.data });
-    if (message.type === "MESSAGE_BIN") this.handlers?.onMessage({ topic: message.topic, data: message.data });
+    if (message.type === "MESSAGE") this.handlers?.onMessage({ topic: message.topic, data: message.data, ...message.messageId ? { messageId: message.messageId } : {} });
+    if (message.type === "MESSAGE_BIN") this.handlers?.onMessage({ topic: message.topic, data: message.data, ...message.messageId ? { messageId: message.messageId } : {} });
     if (message.type === "ERROR") this.handlers?.onError(deserializeWorkerError(message.error));
   }
   /** Handle a Worker-level failure (crash, message decode error). Discards the