cross-tab-worker-databus 0.10.0 → 0.20.6

package/dist/cjs/centrifuge.cjs

@@ -1066,7 +1066,9 @@ var DataBusTraceReporter = class {
   // Bucketed histogram: bucket index = floor(delayMs / 50), capped at 19.
   latencyBuckets = new Array(LATENCY_BUCKET_COUNT).fill(0);
   latencySumMs = 0;
-  constructor(options, now = Date.now) {
+  dedupAccepted = 0;
+  dedupSuppressed = 0;
+  constructor(options, now = options?.now ?? Date.now) {
     this.enabled = options?.enabled ?? false;
     this.mode = options?.mode ?? "all";
     this.metricsIntervalMs = normalizeInterval(options?.metricsIntervalMs);
@@ -1141,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. */
@@ -1154,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",
@@ -1168,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();
@@ -1182,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 {
@@ -1217,6 +1230,12 @@ function roundMs(value) {
 // src/core/data-bus.ts
 var PUBLICATION_EVENT = "DATABUS_PUBLICATION";
 var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
+var PersistenceRetryCancelledError = class extends Error {
+  constructor() {
+    super("Persistence retry cancelled by lifecycle transition.");
+    this.name = "PersistenceRetryCancelledError";
+  }
+};
 var CrossTabDataBus = class _CrossTabDataBus {
   transport;
   cluster;
@@ -1232,13 +1251,26 @@ var CrossTabDataBus = class _CrossTabDataBus {
   replayBuffers;
   replayMaxPerTopic;
   replayPersistence;
+  replayRetentionMs;
+  replayRetentionSweepMs;
+  persistenceRetryMaxAttempts;
+  persistenceRetryBackoffMs;
+  persistenceRetryGeneration = 0;
   replayHydration;
+  // Retention cleanup is coalesced so a burst of publications does not issue
+  // one IndexedDB read/write transaction per message. The newest cutoff wins.
+  replayRetentionCleanup = null;
+  replayRetentionCutoff = null;
+  replayRetentionTimer = null;
   initialConfig;
   hasInitialConfig;
   trace;
   dedupMaxEntries;
   dedupTtlMs;
+  dedupSweepMs;
+  dedupSweepTimer = null;
   dedupEnabled;
+  now;
   seenMessageIds = /* @__PURE__ */ new Map();
   dedupSuppressed = 0;
   dedupAccepted = 0;
@@ -1279,14 +1311,32 @@ 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.replayHydration = this.hydrateReplay();
+    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.replayRetentionSweepMs = replay?.retentionSweepMs;
+    if (this.replayRetentionSweepMs !== void 0 && (!Number.isFinite(this.replayRetentionSweepMs) || this.replayRetentionSweepMs <= 0)) {
+      throw new TypeError("replay.retentionSweepMs must be a positive finite number.");
+    }
+    this.persistenceRetryMaxAttempts = replay?.persistenceRetry?.maxAttempts ?? 1;
+    this.persistenceRetryBackoffMs = replay?.persistenceRetry?.backoffMs ?? 50;
+    if (!Number.isSafeInteger(this.persistenceRetryMaxAttempts) || this.persistenceRetryMaxAttempts <= 0) {
+      throw new TypeError("replay.persistenceRetry.maxAttempts must be a positive safe integer.");
+    }
+    if (!Number.isFinite(this.persistenceRetryBackoffMs) || this.persistenceRetryBackoffMs < 0) {
+      throw new TypeError("replay.persistenceRetry.backoffMs must be a non-negative finite number.");
+    }
     const { autoStart, initialConfig, trace, transport, dedup, ...clusterOptions } = options;
+    this.now = dedup?.now ?? Date.now;
+    this.replayHydration = this.hydrateReplay();
     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.dedupSweepMs = dedup?.sweepMs;
     this.dedupEnabled = dedup !== void 0;
     if (!Number.isSafeInteger(this.dedupMaxEntries) || this.dedupMaxEntries <= 0) {
       throw new TypeError("dedup.maxEntries must be a positive safe integer.");
@@ -1294,6 +1344,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
     if (!Number.isFinite(this.dedupTtlMs) || this.dedupTtlMs <= 0) {
       throw new TypeError("dedup.ttlMs must be a positive finite number.");
     }
+    if (this.dedupSweepMs !== void 0 && (!Number.isFinite(this.dedupSweepMs) || this.dedupSweepMs <= 0)) {
+      throw new TypeError("dedup.sweepMs must be a positive finite number.");
+    }
     this.cluster = new WorkerClusterRuntime({
       ...clusterOptions,
       handlers: {
@@ -1334,11 +1387,16 @@ var CrossTabDataBus = class _CrossTabDataBus {
         onSuspend: () => {
           if (!this.stopping) this.trace.event({ type: "lifecycle", action: "suspend" });
           this.trace.pause();
+          this.persistenceRetryGeneration += 1;
+          this.stopDedupSweep();
+          this.stopReplayRetentionSweep();
           this.suspendTransport();
         },
         onResume: () => {
           this.trace.event({ type: "lifecycle", action: "resume" });
           this.trace.start();
+          this.startDedupSweep();
+          this.startReplayRetentionSweep();
           this.resumeTransport();
         },
         onDiagnostic: (event) => {
@@ -1366,6 +1424,8 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.lastError = null;
     this.trace.event({ type: "lifecycle", action: "start" });
     this.trace.start();
+    this.startDedupSweep();
+    this.startReplayRetentionSweep();
     this.updateStatus("connecting");
     this.cluster.start();
     const opening = this.openTransport(config, this.pendingStop ?? Promise.resolve(), true);
@@ -1490,7 +1550,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.topicHandlers.delete(topic);
     this.replayBuffers?.delete(topic);
     if (this.replayPersistence?.clearTopic) {
-      void this.replayPersistence.clearTopic(topic).catch((error) => this.reportError(error));
+      void this.withPersistenceRetry("clearTopic", () => this.replayPersistence.clearTopic(topic)).catch((error) => this.reportPersistenceError(error));
     }
     this.cluster.unsubscribe(topic);
   }
@@ -1499,9 +1559,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.replayBuffers?.clear();
     if (this.replayPersistence?.clear) {
       try {
-        await this.replayPersistence.clear();
+        await this.withPersistenceRetry("clear", () => this.replayPersistence.clear());
       } catch (error) {
-        this.reportError(error);
+        this.reportPersistenceError(error);
         throw error;
       }
     }
@@ -1511,9 +1571,9 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.replayBuffers?.delete(topic);
     if (this.replayPersistence?.clearTopic) {
       try {
-        await this.replayPersistence.clearTopic(topic);
+        await this.withPersistenceRetry("clearTopic", () => this.replayPersistence.clearTopic(topic));
       } catch (error) {
-        this.reportError(error);
+        this.reportPersistenceError(error);
         throw error;
       }
     }
@@ -1523,12 +1583,19 @@ var CrossTabDataBus = class _CrossTabDataBus {
     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);
+        const kept = messages.filter((message) => message.timestamp === void 0 || message.timestamp >= timestamp);
         if (kept.length) this.replayBuffers.set(topic, kept);
         else this.replayBuffers.delete(topic);
       }
     }
-    if (this.replayPersistence?.clearBefore) await this.replayPersistence.clearBefore(timestamp);
+    if (this.replayPersistence?.clearBefore) {
+      try {
+        await this.withPersistenceRetry("clearBefore", () => this.replayPersistence.clearBefore(timestamp));
+      } catch (error) {
+        this.reportPersistenceError(error);
+        throw error;
+      }
+    }
   }
   /** Return bounded deduplication counters for diagnostics and health checks. */
   getDedupStats() {
@@ -1586,8 +1653,11 @@ var CrossTabDataBus = class _CrossTabDataBus {
   async stop() {
     if (!this.started) return;
     this.stopping = true;
+    this.persistenceRetryGeneration += 1;
     this.trace.event({ type: "lifecycle", action: "stop" });
     this.trace.stop();
+    this.stopDedupSweep();
+    this.stopReplayRetentionSweep();
     this.topicHandlers.clear();
     this.replayBuffers?.clear();
     this.cluster.stop();
@@ -1598,7 +1668,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
       else await this.transport.stop();
     } finally {
       this.transportSubscribedTopics.clear();
-      this.seenMessageIds.clear();
+      this.resetDedup();
       this.started = false;
       this.stopping = false;
       this.suspended = false;
@@ -1631,17 +1701,19 @@ var CrossTabDataBus = class _CrossTabDataBus {
   }
   isDuplicate(message) {
     if (!this.dedupEnabled || !message.messageId) return false;
-    const now = Date.now();
+    const now = this.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 });
       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;
@@ -1649,6 +1721,20 @@ var CrossTabDataBus = class _CrossTabDataBus {
     }
     return false;
   }
+  startDedupSweep() {
+    if (this.dedupSweepTimer || !this.dedupEnabled || !this.dedupSweepMs) return;
+    this.dedupSweepTimer = setInterval(() => this.pruneExpiredDedup(), this.dedupSweepMs);
+  }
+  stopDedupSweep() {
+    if (this.dedupSweepTimer) clearInterval(this.dedupSweepTimer);
+    this.dedupSweepTimer = null;
+  }
+  pruneExpiredDedup() {
+    const cutoff = this.now() - this.dedupTtlMs;
+    for (const [id, timestamp] of this.seenMessageIds) {
+      if (timestamp < cutoff) this.seenMessageIds.delete(id);
+    }
+  }
   /** 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"). */
@@ -1675,7 +1761,10 @@ var CrossTabDataBus = class _CrossTabDataBus {
     buffer.push(storedMessage);
     if (buffer.length > this.replayMaxPerTopic) buffer.shift();
     if (this.replayPersistence) {
-      void this.replayPersistence.append(storedMessage).catch((error) => this.reportError(error));
+      void this.withPersistenceRetry("append", () => this.replayPersistence.append(storedMessage)).catch((error) => this.reportPersistenceError(error));
+      if (this.replayRetentionMs !== void 0 && this.replayPersistence.clearBefore) {
+        this.scheduleReplayRetentionCleanup(this.now() - this.replayRetentionMs);
+      }
     }
   }
   async hydrateReplay() {
@@ -1683,7 +1772,10 @@ var CrossTabDataBus = class _CrossTabDataBus {
       return;
     }
     try {
-      for (const message of await this.replayPersistence.load()) {
+      if (this.replayRetentionMs !== void 0 && this.replayPersistence.clearBefore) {
+        await this.withPersistenceRetry("clearBefore", () => this.replayPersistence.clearBefore(this.now() - this.replayRetentionMs));
+      }
+      for (const message of await this.withPersistenceRetry("load", () => this.replayPersistence.load())) {
         let buffer = this.replayBuffers.get(message.topic);
         if (!buffer) {
           buffer = [];
@@ -1693,7 +1785,66 @@ var CrossTabDataBus = class _CrossTabDataBus {
         if (buffer.length > this.replayMaxPerTopic) buffer.shift();
       }
     } catch (error) {
-      this.reportError(error);
+      this.reportPersistenceError(error);
+    }
+  }
+  scheduleReplayRetentionCleanup(cutoff) {
+    if (!this.replayPersistence?.clearBefore) return;
+    if (this.replayRetentionCutoff === null || cutoff > this.replayRetentionCutoff) {
+      this.replayRetentionCutoff = cutoff;
+    }
+    if (this.replayRetentionCleanup) return;
+    this.replayRetentionCleanup = (async () => {
+      while (this.replayRetentionCutoff !== null) {
+        const nextCutoff = this.replayRetentionCutoff;
+        this.replayRetentionCutoff = null;
+        try {
+          await this.replayPersistence.clearBefore(nextCutoff);
+        } catch (error) {
+          this.reportPersistenceError(error);
+        }
+      }
+    })().finally(() => {
+      this.replayRetentionCleanup = null;
+      if (this.replayRetentionCutoff !== null) {
+        this.scheduleReplayRetentionCleanup(this.replayRetentionCutoff);
+      }
+    });
+  }
+  startReplayRetentionSweep() {
+    if (this.replayRetentionTimer || !this.replayRetentionMs || !this.replayRetentionSweepMs || !this.replayPersistence?.clearBefore) return;
+    this.replayRetentionTimer = setInterval(() => {
+      this.scheduleReplayRetentionCleanup(this.now() - this.replayRetentionMs);
+    }, this.replayRetentionSweepMs);
+  }
+  stopReplayRetentionSweep() {
+    if (this.replayRetentionTimer) clearInterval(this.replayRetentionTimer);
+    this.replayRetentionTimer = null;
+  }
+  async withPersistenceRetry(persistenceOperation, operation) {
+    const generation = this.persistenceRetryGeneration;
+    let attempt = 0;
+    let delay = this.persistenceRetryBackoffMs;
+    while (true) {
+      attempt += 1;
+      try {
+        if (generation !== this.persistenceRetryGeneration) throw new PersistenceRetryCancelledError();
+        return await operation();
+      } catch (error) {
+        if (error instanceof PersistenceRetryCancelledError || generation !== this.persistenceRetryGeneration) {
+          throw new PersistenceRetryCancelledError();
+        }
+        if (attempt >= this.persistenceRetryMaxAttempts) throw error;
+        this.trace.event({
+          type: "reliability",
+          operation: "persistence_retry",
+          persistenceOperation,
+          attempt
+        });
+        if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay));
+        if (generation !== this.persistenceRetryGeneration) throw new PersistenceRetryCancelledError();
+        delay = Math.min(delay * 2, 1600);
+      }
     }
   }
   /** Deliver buffered history to a newly-registered handler. For an exact
@@ -1731,7 +1882,7 @@ var CrossTabDataBus = class _CrossTabDataBus {
       for (const topic of this.cluster.getSnapshot().assignedTopics) this.subscribeTransport(topic);
     }
     if (status === "error" && this.started && !this.stopping) {
-      const now = Date.now();
+      const now = this.now();
       if (now - this.lastRecoveryAt >= _CrossTabDataBus.RECOVERY_COOLDOWN_MS) {
         this.lastRecoveryAt = now;
         this.trace.event({ type: "reliability", operation: "transport_recovery", attempt: 1 });
@@ -1748,6 +1899,11 @@ var CrossTabDataBus = class _CrossTabDataBus {
     this.trace.event({ type: "error", source: "transport" });
     this.invokeHandlers(this.errorHandlers, (handler) => handler(error), "error handler");
   }
+  reportPersistenceError(error) {
+    if (error instanceof PersistenceRetryCancelledError) return;
+    this.trace.event({ type: "reliability", operation: "persistence_cleanup" });
+    this.reportError(error);
+  }
   traceSubscription(action, topic) {
     this.trace.event({
       type: "subscription",
@@ -1905,11 +2061,13 @@ function parseDataBusPublication(value, 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;
+  const messageId = typeof publication.messageId === "string" && publication.messageId.length > 0 ? publication.messageId : void 0;
+  const timestamp = typeof publication.timestamp === "number" && Number.isFinite(publication.timestamp) ? publication.timestamp : void 0;
   return {
     topic,
     data,
-    ...typeof publication.messageId === "string" ? { messageId: publication.messageId } : {},
-    ...typeof publication.timestamp === "number" ? { timestamp: publication.timestamp } : {}
+    ...messageId === void 0 ? {} : { messageId },
+    ...timestamp === void 0 ? {} : { timestamp }
   };
 }