cross-tab-worker-databus 0.8.0 → 0.11.0

package/dist/cjs/centrifuge.cjs

@@ -314,6 +314,13 @@ function writeJson(storage, key, value) {
   } catch {
   }
 }
+function publicationMetadata(messageId, timestamp) {
+  if (messageId === void 0 && timestamp === void 0) return void 0;
+  return {
+    ...messageId === void 0 ? {} : { messageId },
+    ...timestamp === void 0 ? {} : { timestamp }
+  };
+}
 function listKeys(storage, prefix) {
   try {
     return Array.from({ length: storage.length }, (_, index) => storage.key(index)).filter(
@@ -543,26 +550,21 @@ var WorkerClusterRuntime = class {
       this.sendRouteReleased(owner.workerId, topic, topicKey, generation);
     }
   }
-  /**
-   * Publish a message to `topic`, routing through the owning Worker (or self if
-   * no owner is found). Returns false when the control message could not be
-   * posted to a remote owner, so the caller can surface the failure instead of
-   * silently dropping the publication.
-   */
-  publish(topic, data, messageId) {
+  publish(topic, data, metadataOrMessageId) {
+    const metadata = typeof metadataOrMessageId === "string" ? { messageId: metadataOrMessageId } : metadataOrMessageId;
     const topicKey = this.rememberTopic(topic);
     if (this.assignedTopics.has(topicKey)) {
-      return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, messageId);
+      return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, metadata);
     }
     for (const pattern of this.assignedTopics.values()) {
       if (pattern !== topic && topicMatchesPattern(pattern, topic)) {
-        return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, messageId);
+        return this.sendControl(this.workerId, "PUBLISH", topic, topicKey, data, metadata);
       }
     }
     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, messageId);
+    return this.sendControl(target, "PUBLISH", topic, topicKey, data, metadata);
   }
   /** True when `route` exists and its owner worker is among `workers`.
    * Shared by subscribe (skip re-assignment) and publish (route to owner).
@@ -684,11 +686,15 @@ var WorkerClusterRuntime = class {
       default:
         break;
     }
-    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);
-    }
+    const metadata = publicationMetadata(message.messageId, message.timestamp);
+    if (metadata) this.handlers.onControl(
+      message.action,
+      message.topic,
+      message.data,
+      metadata.messageId,
+      metadata.timestamp
+    );
+    else this.handlers.onControl(message.action, message.topic, message.data);
     if (message.action !== "PUBLISH") this.updateLoad();
   }
   /**
@@ -805,7 +811,7 @@ var WorkerClusterRuntime = class {
    * Local execution updates the assignment map and route synchronously, bypassing
    * the BroadcastChannel latency.
    */
-  sendControl(targetWorkerId, action, topic, topicKey, data, messageId) {
+  sendControl(targetWorkerId, action, topic, topicKey, data, metadata) {
     if (targetWorkerId === this.workerId) {
       switch (action) {
         case "SUBSCRIBE":
@@ -819,8 +825,14 @@ var WorkerClusterRuntime = class {
         default:
           break;
       }
-      if (messageId === void 0) this.handlers.onControl(action, topic, data);
-      else this.handlers.onControl(action, topic, data, messageId);
+      if (metadata) this.handlers.onControl(
+        action,
+        topic,
+        data,
+        metadata.messageId,
+        metadata.timestamp
+      );
+      else this.handlers.onControl(action, topic, data);
       if (action !== "PUBLISH") this.updateLoad();
       return true;
     }
@@ -832,7 +844,8 @@ var WorkerClusterRuntime = class {
       topic,
       topicKey,
       ...data === void 0 ? {} : { data },
-      ...messageId === void 0 ? {} : { messageId }
+      ...metadata?.messageId === void 0 ? {} : { messageId: metadata.messageId },
+      ...metadata?.timestamp === void 0 ? {} : { timestamp: metadata.timestamp }
     });
   }
   /** Post a message on the BroadcastChannel. Returns false on postMessage failure. */
@@ -1053,6 +1066,8 @@ var DataBusTraceReporter = class {
   // Bucketed histogram: bucket index = floor(delayMs / 50), capped at 19.
   latencyBuckets = new Array(LATENCY_BUCKET_COUNT).fill(0);
   latencySumMs = 0;
+  dedupAccepted = 0;
+  dedupSuppressed = 0;
   constructor(options, now = Date.now) {
     this.enabled = options?.enabled ?? false;
     this.mode = options?.mode ?? "all";
@@ -1128,6 +1143,13 @@ var DataBusTraceReporter = class {
     this.latencyBuckets[bucketIndex] = (this.latencyBuckets[bucketIndex] ?? 0) + 1;
     this.latencySumMs += delayMs;
   }
+  /** Record deduplication outcomes for the next metrics window. */
+  recordDedupAccepted() {
+    if (this.metricsActive) this.dedupAccepted += 1;
+  }
+  recordDedupSuppressed() {
+    if (this.metricsActive) this.dedupSuppressed += 1;
+  }
   /** True when metrics recording is active: enabled and mode includes metrics.
    * Extracted so the four record / flush methods share one guard expression
    * instead of repeating `!this.enabled || this.mode === 'events'` at each. */
@@ -1141,7 +1163,7 @@ var DataBusTraceReporter = class {
   }
   flushNow() {
     const timestamp = this.now();
-    if (this.received > 0 || this.dispatched > 0) {
+    if (this.received > 0 || this.dispatched > 0 || this.dedupAccepted > 0 || this.dedupSuppressed > 0) {
       const samples = this.latencySamples;
       this.emit({
         type: "message_metrics",
@@ -1155,6 +1177,8 @@ var DataBusTraceReporter = class {
         dispatchP50Ms: roundMs(percentileMs(this.latencyBuckets, samples, 0.5)),
         dispatchP95Ms: roundMs(percentileMs(this.latencyBuckets, samples, 0.95)),
         dispatchMaxMs: roundMs(percentileMs(this.latencyBuckets, samples, 1)),
+        dedupAccepted: this.dedupAccepted,
+        dedupSuppressed: this.dedupSuppressed,
         timestamp
       });
       this.resetMetrics();
@@ -1169,6 +1193,8 @@ var DataBusTraceReporter = class {
     this.receivedAt.clear();
     this.latencyBuckets.fill(0);
     this.latencySumMs = 0;
+    this.dedupAccepted = 0;
+    this.dedupSuppressed = 0;
   }
   emit(event) {
     try {
@@ -1219,6 +1245,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
   replayBuffers;
   replayMaxPerTopic;
   replayPersistence;
+  replayRetentionMs;
   replayHydration;
   initialConfig;
   hasInitialConfig;
@@ -1227,6 +1254,8 @@ var CrossTabDataBus = class _CrossTabDataBus {
   dedupTtlMs;
   dedupEnabled;
   seenMessageIds = /* @__PURE__ */ new Map();
+  dedupSuppressed = 0;
+  dedupAccepted = 0;
   activeConfig;
   status = "disconnected";
   started = false;
@@ -1264,6 +1293,10 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.replayMaxPerTopic = replay?.maxPerTopic ?? DEFAULT_REPLAY_MAX_PER_TOPIC;
     this.replayBuffers = replay ? /* @__PURE__ */ new Map() : null;
     this.replayPersistence = replay?.persistence ?? null;
+    this.replayRetentionMs = replay?.retentionMs;
+    if (this.replayRetentionMs !== void 0 && (!Number.isFinite(this.replayRetentionMs) || this.replayRetentionMs <= 0)) {
+      throw new TypeError("replay.retentionMs must be a positive finite number.");
+    }
     this.replayHydration = this.hydrateReplay();
     const { autoStart, initialConfig, trace, transport, dedup, ...clusterOptions } = options;
     this.transport = transport;
@@ -1284,7 +1317,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
       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, messageId) => {
+        onControl: (action, topic, data, messageId, timestamp) => {
           switch (action) {
             case "SUBSCRIBE":
               if (this.subscribeTransport(topic)) this.traceSubscription("subscribe", topic);
@@ -1293,7 +1326,14 @@ var CrossTabDataBus = class _CrossTabDataBus {
               if (this.unsubscribeTransport(topic)) this.traceSubscription("unsubscribe", topic);
               break;
             case "PUBLISH":
-              this.runTransport(() => this.transport.publish(topic, data, messageId ? { messageId } : void 0));
+              this.runTransport(() => this.transport.publish(
+                topic,
+                data,
+                messageId === void 0 && timestamp === void 0 ? void 0 : {
+                  ...messageId === void 0 ? {} : { messageId },
+                  ...timestamp === void 0 ? {} : { timestamp }
+                }
+              ));
               break;
             default:
               break;
@@ -1484,10 +1524,49 @@ var CrossTabDataBus = class _CrossTabDataBus {
       }
     }
   }
+  /** Clear replay history for one exact topic, including durable storage. */
+  async clearReplayTopic(topic) {
+    this.replayBuffers?.delete(topic);
+    if (this.replayPersistence?.clearTopic) {
+      try {
+        await this.replayPersistence.clearTopic(topic);
+      } catch (error) {
+        this.reportError(error);
+        throw error;
+      }
+    }
+  }
+  /** Remove replay entries older than an epoch-millisecond cutoff. */
+  async clearReplayBefore(timestamp) {
+    if (!Number.isFinite(timestamp)) throw new TypeError("timestamp must be finite.");
+    if (this.replayBuffers) {
+      for (const [topic, messages] of this.replayBuffers) {
+        const kept = messages.filter((message) => (message.timestamp ?? 0) >= timestamp);
+        if (kept.length) this.replayBuffers.set(topic, kept);
+        else this.replayBuffers.delete(topic);
+      }
+    }
+    if (this.replayPersistence?.clearBefore) await this.replayPersistence.clearBefore(timestamp);
+  }
+  /** Return bounded deduplication counters for diagnostics and health checks. */
+  getDedupStats() {
+    return {
+      enabled: this.dedupEnabled,
+      tracked: this.seenMessageIds.size,
+      suppressed: this.dedupSuppressed,
+      accepted: this.dedupAccepted
+    };
+  }
+  /** Drop all remembered IDs and reset dedup counters. */
+  resetDedup() {
+    this.seenMessageIds.clear();
+    this.dedupSuppressed = 0;
+    this.dedupAccepted = 0;
+  }
   /** Publish a message to `topic`. The owning Worker delivers it to the transport. */
   publish(topic, data, options) {
     this.ensureStarted();
-    if (!this.cluster.publish(topic, data, options?.messageId)) {
+    if (!this.cluster.publish(topic, data, options)) {
       this.reportError(
         new Error("Failed to send the publish control message to the owning worker.")
       );
@@ -1576,9 +1655,13 @@ var CrossTabDataBus = class _CrossTabDataBus {
     }
     if (this.seenMessageIds.has(message.messageId)) {
       this.trace.event({ type: "reliability", operation: "dedup_suppressed", topic: message.topic });
+      this.dedupSuppressed += 1;
+      this.trace.recordDedupSuppressed();
       return true;
     }
     this.seenMessageIds.set(message.messageId, now);
+    this.dedupAccepted += 1;
+    this.trace.recordDedupAccepted();
     while (this.seenMessageIds.size > this.dedupMaxEntries) {
       const oldest = this.seenMessageIds.keys().next().value;
       if (oldest === void 0) break;
@@ -1608,10 +1691,14 @@ var CrossTabDataBus = class _CrossTabDataBus {
       buffer = [];
       this.replayBuffers.set(message.topic, buffer);
     }
-    buffer.push(message);
+    const storedMessage = message;
+    buffer.push(storedMessage);
     if (buffer.length > this.replayMaxPerTopic) buffer.shift();
     if (this.replayPersistence) {
-      void this.replayPersistence.append(message).catch((error) => this.reportError(error));
+      void this.replayPersistence.append(storedMessage).catch((error) => this.reportError(error));
+      if (this.replayRetentionMs !== void 0 && this.replayPersistence.clearBefore) {
+        void this.replayPersistence.clearBefore(Date.now() - this.replayRetentionMs).catch((error) => this.reportError(error));
+      }
     }
   }
   async hydrateReplay() {
@@ -1619,6 +1706,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
       return;
     }
     try {
+      if (this.replayRetentionMs !== void 0 && this.replayPersistence.clearBefore) {
+        await this.replayPersistence.clearBefore(Date.now() - this.replayRetentionMs);
+      }
       for (const message of await this.replayPersistence.load()) {
         let buffer = this.replayBuffers.get(message.topic);
         if (!buffer) {
@@ -1828,6 +1918,28 @@ function formatRouteTrace(route) {
 
 // src/centrifuge-session.ts
 var import_centrifuge = require("centrifuge");
+
+// src/core/publication.ts
+function parseDataBusPublication(value, fallbackTopic) {
+  if (!value || typeof value !== "object") {
+    return fallbackTopic ? { topic: fallbackTopic, data: value } : null;
+  }
+  const frame = value;
+  const nested = frame.publication && typeof frame.publication === "object" ? frame.publication : null;
+  const publication = nested ?? frame;
+  const topic = typeof publication.topic === "string" ? publication.topic : fallbackTopic;
+  if (!topic) return null;
+  const hasMetadataEnvelope = fallbackTopic !== void 0 && Object.prototype.hasOwnProperty.call(publication, "data") && (typeof publication.messageId === "string" || typeof publication.timestamp === "number");
+  const data = nested || fallbackTopic === void 0 || hasMetadataEnvelope ? publication.data : value;
+  return {
+    topic,
+    data,
+    ...typeof publication.messageId === "string" ? { messageId: publication.messageId } : {},
+    ...typeof publication.timestamp === "number" ? { timestamp: publication.timestamp } : {}
+  };
+}
+
+// src/centrifuge-session.ts
 var CentrifugeSession = class {
   constructor(sink) {
     this.sink = sink;
@@ -1851,7 +1963,7 @@ var CentrifugeSession = class {
         return;
       case "PUBLISH":
       case "PUBLISH_BIN":
-        this.publish(message.topic, message.data, message.messageId);
+        this.publish(message.topic, message.data, message.messageId, message.timestamp);
         return;
       case "STOP":
         this.stop();
@@ -1916,9 +2028,14 @@ var CentrifugeSession = class {
     subscription.unsubscribe();
   }
   /** Publish a message to the Centrifuge channel. */
-  publish(topic, data, messageId) {
+  publish(topic, data, messageId, timestamp) {
     if (!this.client) return this.postError(new Error("Centrifuge client is not initialized."));
-    const payload = messageId ? { data, messageId } : data;
+    const hasMetadata = messageId !== void 0 || timestamp !== void 0;
+    const payload = hasMetadata ? {
+      data,
+      ...messageId === void 0 ? {} : { messageId },
+      ...timestamp === void 0 ? {} : { timestamp }
+    } : data;
     void this.client.publish(topic, payload).catch((error) => this.postError(error));
   }
   /** Forward a publication to the transport. Binary payloads take the
@@ -1931,9 +2048,15 @@ var CentrifugeSession = class {
       this.post({ type: "MESSAGE_BIN", topic, data }, [data]);
       return;
     }
-    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 } : {} });
+    const publication = parseDataBusPublication(data, topic);
+    if (!publication) return;
+    this.post({
+      type: "MESSAGE",
+      topic: publication.topic,
+      data: publication.data,
+      ...publication.messageId === void 0 ? {} : { messageId: publication.messageId },
+      ...publication.timestamp === void 0 ? {} : { timestamp: publication.timestamp }
+    });
   }
   /** Disconnect the client and clear all subscriptions. */
   stop() {
@@ -2065,10 +2188,10 @@ var CentrifugeWorkerTransport = class {
    */
   publish(topic, data, options) {
     if (this.transferable && data instanceof ArrayBuffer) {
-      this.post({ type: "PUBLISH_BIN", topic, data, ...options?.messageId ? { messageId: options.messageId } : {} }, [data]);
+      this.post({ type: "PUBLISH_BIN", topic, data, ...publicationMetadata2(options) }, [data]);
       return;
     }
-    this.post({ type: "PUBLISH", topic, data, ...options?.messageId ? { messageId: options.messageId } : {} });
+    this.post({ type: "PUBLISH", topic, data, ...publicationMetadata2(options) });
   }
   /**
    * Gracefully stop the transport: send STOP, clean up event listeners, and
@@ -2139,8 +2262,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, ...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 === "MESSAGE") this.handlers?.onMessage({ topic: message.topic, data: message.data, ...publicationMetadata2(message) });
+    if (message.type === "MESSAGE_BIN") this.handlers?.onMessage({ topic: message.topic, data: message.data, ...publicationMetadata2(message) });
     if (message.type === "ERROR") this.handlers?.onError(deserializeWorkerError(message.error));
   }
   /** Handle a Worker-level failure (crash, message decode error). Discards the
@@ -2305,4 +2428,10 @@ function deserializeWorkerError(error) {
   if (error.context !== void 0) Object.assign(result, { context: error.context });
   return result;
 }
+function publicationMetadata2(metadata) {
+  return {
+    ...metadata?.messageId === void 0 ? {} : { messageId: metadata.messageId },
+    ...metadata?.timestamp === void 0 ? {} : { timestamp: metadata.timestamp }
+  };
+}
 //# sourceMappingURL=centrifuge.cjs.map