@logbrew/sdk 0.1.32 → 0.1.33

package/README.md

@@ -506,7 +506,7 @@ When either queue limit is full, LogBrew drops the incoming event and keeps earl
 
 A fatal crash report (an issue with `fatal` or `critical` level) is the exception. When it does not fit, LogBrew removes the oldest queued events that are not fatal until it fits, and counts each removed event as `evicted_for_fatal`. It never removes events in a batch that is being sent or retried, and it removes nothing if the fatal still cannot fit. So a full queue drops a fatal only when everything else in it is fatal or in a batch that is being sent; that fatal is counted as `queue_overflow` or `queue_bytes_overflow`. A fatal larger than one request body is still dropped as `event_too_large`. Drop callbacks are advisory and must not interrupt application logging. The default queue remains memory-only; automatic delivery reduces normal flush work, while the app still calls `shutdown()` at its owned graceful-lifecycle boundary.
 
-LogBrew sees these drops too. The next request body carries the per-reason counts since the last accepted report, such as `"client_report":{"dropped_events":{"queue_overflow":3}}`. The client clears exactly those counts after a `2xx` response for that request; drops recorded while it is in flight, and counts in a failed or retried request, wait for the next one. A report never sends a request of its own, is left out when nothing was dropped, lists at most 16 reasons, caps each count at 1,000,000,000, and fits inside `maxBatchBytes`. Counts live in memory only, so drops not yet reported are lost when the process restarts.
+LogBrew sees these drops too. The next request body carries the per-reason counts since the last accepted report, such as `"client_report":{"report_id":"5f0c6a1e9b2d4c7a8e3f1b6d0a9c2e4f","dropped_events":{"queue_overflow":3}}`. The counts keep one `report_id` until a `2xx` response acknowledges a request that carried them, and LogBrew counts every resend of one report ID once, even when the resend carries different events. Drops recorded while a request is in flight wait for the next report. A report never sends a request of its own, is left out when nothing was dropped, lists at most 16 reasons, caps each count at 1,000,000,000, and fits inside `maxBatchBytes`. Without an `eventStore`, counts live in memory and drops not yet reported are lost when the process restarts. A store that also provides synchronous `loadClientReport()` and `saveClientReport(state)` keeps them: the client saves at once for a new report or reason and at most once a second during a drop burst, and after a restart resends a pending report under its original `report_id`. The Node and React Native persistent queues and browser `persistOffline` do this for you.
 
 Server runtimes can supply an explicit synchronous `eventStore` when they need restart recovery. The core loads and revalidates compact records during client creation, persists each accepted event before adding it to memory, persists an accepted prefix before removing it from memory, and closes the store only after successful shutdown. `purgePendingEvents()` clears both layers only while no flush or shutdown is queued or active. Implementations must provide synchronous `load`, `append`, `acknowledge`, `purge`, and `close` methods; use the encrypted `persistentQueue` adapter in `@logbrew/node` instead of writing a filesystem adapter from scratch. A store can also provide a synchronous `remove(indexes)` that deletes the records at those ascending `load()` positions. Fatal eviction needs it: a full queue on a store without `remove` drops the fatal as before.
 

package/core.cjs

@@ -96,6 +96,11 @@ const MAX_CLIENT_REPORT_REASONS = 16;
 const MAX_CLIENT_REPORT_COUNT = 1_000_000_000;
 const DELIVERY_HEALTH_SCHEMA_VERSION = 1;
 const EVENT_QUEUE_FACTORY = Symbol.for("@logbrew/sdk.eventQueueFactory");
+// Runtimes without an event store (browser storage) persist unreported drop counts through this seam.
+const CLIENT_REPORT_STORE = Symbol.for("@logbrew/sdk.clientReportStore");
+const CLIENT_REPORT_SAVE_INTERVAL_MS = 1_000;
+const CLIENT_REPORT_ID_PATTERN = /^[A-Za-z0-9_-]{16,64}$/u;
+const CLIENT_REPORT_REASON_PATTERN = /^[a-z][a-z0-9_]{0,63}$/u;
 const CONTEXT_PROVIDER = Symbol.for("@logbrew/sdk.contextProvider");
 // Runtime packages supply request-scoped breadcrumbs through this seam; core merges them into issues.
 const BREADCRUMB_PROVIDER = Symbol.for("@logbrew/sdk.breadcrumbProvider");
@@ -228,6 +233,7 @@ class LogBrewClient {
     onEventDropped,
     eventStore,
     [EVENT_QUEUE_FACTORY]: eventQueueFactory,
+    [CLIENT_REPORT_STORE]: clientReportStore,
     transport,
     automaticDelivery = transport !== undefined,
     deliveryIntervalMs = DEFAULT_DELIVERY_INTERVAL_MS,
@@ -261,6 +267,9 @@ class LogBrewClient {
     if (eventStore !== undefined && eventQueueFactory !== undefined) {
       throw new SdkError("validation_error", "eventStore and event queue factory are mutually exclusive");
     }
+    if (clientReportStore !== undefined && !isClientReportStore(clientReportStore)) {
+      throw new SdkError("validation_error", "client report store must provide loadClientReport and saveClientReport");
+    }
     validateTransport(transport);
     if (typeof automaticDelivery !== "boolean") {
       throw new SdkError("validation_error", "automaticDelivery must be a boolean");
@@ -284,6 +293,7 @@ class LogBrewClient {
       deliveryQueueThreshold,
       eventStore,
       eventQueueFactory,
+      clientReportStore,
       eventFilter,
       maxBatchBytes,
       maxBatchEvents,
@@ -318,6 +328,7 @@ class LogBrewClient {
     breadcrumbProvider,
     eventStore,
     eventQueueFactory,
+    clientReportStore,
     transport,
     automaticDelivery,
     deliveryIntervalMs,
@@ -382,8 +393,14 @@ class LogBrewClient {
       queue_bytes_overflow: 0,
       queue_overflow: 0
     };
-    // In memory only: counts not yet acknowledged by a 2xx are lost on restart.
-    this.unreportedDropsByReason = {};
+    // A persistent store keeps counts not yet acknowledged by a 2xx across restarts.
+    this.clientReportStore = clientReportStore
+      ?? (isClientReportStore(resolvedEventStore) ? resolvedEventStore : undefined);
+    this.clientReportSavedAtMs = 0;
+    const restoredReport = loadClientReport(this.clientReportStore);
+    this.unreportedDropsByReason = restoredReport.unreported;
+    // Drop counts frozen under one report ID until a 2xx acknowledges a body that carried them.
+    this.pendingClientReport = restoredReport.pending;
     this.lastDropReason = "none";
     this.storage = resolvedEventStore ? "persistent" : "memory";
     this.hydratedEventCount = recovered.events.length;
@@ -618,6 +635,7 @@ class LogBrewClient {
       if (controlsAutomaticDelivery) {
         this.#recordAutomaticSuccess();
       }
+      this.#saveClientReport(true);
       if (this.eventStore) {
         try {
           requireSynchronousStoreResult("close", this.eventStore.close());
@@ -784,7 +802,9 @@ class LogBrewClient {
   #recordDroppedEvent(event, reason) {
     this.droppedEventCount = incrementBounded(this.droppedEventCount);
     this.droppedEventsByReason[reason] = incrementBounded(this.droppedEventsByReason[reason]);
+    const firstOfReason = this.unreportedDropsByReason[reason] === undefined;
     this.unreportedDropsByReason[reason] = Math.min(MAX_CLIENT_REPORT_COUNT, (this.unreportedDropsByReason[reason] ?? 0) + 1);
+    this.#saveClientReport(firstOfReason);
     this.lastDropReason = reason;
     this.lastDroppedAtUnixMs = nextBoundedTimestamp(this.lastDroppedAtUnixMs);
     if (!this.onEventDropped) {
@@ -949,9 +969,10 @@ class LogBrewClient {
       const batch = this.unacknowledgedBatch;
       const response = await this.#sendBatch(transport, batch.body);
       this.unacknowledgedBatch = undefined;
-      // Clear only what this body carried; drops recorded while it was in flight stay pending.
-      for (const [reason, count] of Object.entries(batch.droppedEvents ?? {})) {
-        this.unreportedDropsByReason[reason] -= count;
+      // Drops recorded while this body was in flight stay pending under a new report ID.
+      if (batch.carriesClientReport) {
+        this.pendingClientReport = undefined;
+        this.#saveClientReport(true);
       }
       this.#acknowledge(batch.eventsCount);
       this.acceptedBatchCount = incrementBounded(this.acceptedBatchCount);
@@ -979,11 +1000,8 @@ class LogBrewClient {
   }
 
   #nextBatch(maxEvents) {
-    const reported = Object.entries(this.unreportedDropsByReason).filter(([, count]) => count > 0);
-    const droppedEvents = reported.length > 0
-      ? Object.fromEntries(reported.slice(0, MAX_CLIENT_REPORT_REASONS))
-      : undefined;
-    const reportSuffix = droppedEvents && `],"client_report":${JSON.stringify({ dropped_events: droppedEvents })}}`;
+    const report = this.#pendingClientReport();
+    const reportSuffix = report && `],"client_report":${JSON.stringify(report)}}`;
     const reportedEvents = reportSuffix ? this.#batchEventCount(maxEvents, utf8ByteLength(reportSuffix)) : 0;
     const eventsCount = reportedEvents || this.#batchEventCount(maxEvents, this.batchSuffixBytes);
     if (eventsCount === 0) {
@@ -991,11 +1009,45 @@ class LogBrewClient {
     }
     return {
       body: `${this.batchPrefix}${this.serializedEvents.slice(0, eventsCount).join(",")}${reportedEvents ? reportSuffix : this.batchSuffix}`,
-      droppedEvents: reportedEvents ? droppedEvents : undefined,
+      carriesClientReport: reportedEvents > 0,
       eventsCount
     };
   }
 
+  // Freezes unreported drops under one stable ID, so every resend of them is counted once.
+  #pendingClientReport() {
+    if (this.pendingClientReport === undefined) {
+      const reported = Object.entries(this.unreportedDropsByReason).filter(([, count]) => count > 0);
+      if (reported.length === 0) {
+        return undefined;
+      }
+      const droppedEvents = Object.fromEntries(reported.slice(0, MAX_CLIENT_REPORT_REASONS));
+      for (const reason of Object.keys(droppedEvents)) {
+        delete this.unreportedDropsByReason[reason];
+      }
+      this.pendingClientReport = Object.freeze({ report_id: randomHex(16), dropped_events: droppedEvents });
+      this.#saveClientReport(true);
+    }
+    return this.pendingClientReport;
+  }
+
+  // Saves at once for a new report or reason, and at most once a second during a drop burst.
+  #saveClientReport(immediately) {
+    const now = Date.now();
+    if (!this.clientReportStore || (!immediately && now - this.clientReportSavedAtMs < CLIENT_REPORT_SAVE_INTERVAL_MS)) {
+      return;
+    }
+    this.clientReportSavedAtMs = now;
+    try {
+      requireSynchronousStoreResult("saveClientReport", this.clientReportStore.saveClientReport({
+        pending: this.pendingClientReport ?? null,
+        unreported: { ...this.unreportedDropsByReason }
+      }));
+    } catch {
+      // Drop counts are advisory: a failed save keeps them in memory and never blocks capture.
+    }
+  }
+
   #batchEventCount(maxEvents, suffixBytes) {
     let bodyBytes = this.batchPrefixBytes + suffixBytes;
     let eventsCount = 0;
@@ -1193,6 +1245,50 @@ function isFatalEvent(event) {
   return event.type === "issue" && event.attributes.level === "critical";
 }
 
+// Report IDs only need uniqueness, so runtimes without Web Crypto fall back to Math.random.
+function randomHex(byteLength) {
+  const bytes = new Uint8Array(byteLength);
+  if (typeof globalThis.crypto?.getRandomValues === "function") {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function isClientReportStore(store) {
+  return typeof store?.loadClientReport === "function" && typeof store.saveClientReport === "function";
+}
+
+// Restores saved drop counts; anything unreadable or out of bounds is ignored, never fatal.
+function loadClientReport(store) {
+  let state;
+  try {
+    state = store ? requireSynchronousStoreResult("loadClientReport", store.loadClientReport()) : undefined;
+  } catch {
+    state = undefined;
+  }
+  const pending = state?.pending;
+  const pendingCounts = validClientReportCounts(pending?.dropped_events);
+  return {
+    pending: CLIENT_REPORT_ID_PATTERN.test(pending?.report_id ?? "") && Object.keys(pendingCounts).length > 0
+      ? Object.freeze({ report_id: pending.report_id, dropped_events: pendingCounts })
+      : undefined,
+    unreported: validClientReportCounts(state?.unreported)
+  };
+}
+
+function validClientReportCounts(counts) {
+  if (!counts || typeof counts !== "object" || Array.isArray(counts)) {
+    return {};
+  }
+  return Object.fromEntries(Object.entries(counts).filter(([reason, count]) => (
+    CLIENT_REPORT_REASON_PATTERN.test(reason) && Number.isSafeInteger(count) && count >= 1 && count <= MAX_CLIENT_REPORT_COUNT
+  )).slice(0, MAX_CLIENT_REPORT_REASONS));
+}
+
 function incrementBounded(value) {
   return value >= Number.MAX_SAFE_INTEGER ? Number.MAX_SAFE_INTEGER : value + 1;
 }
@@ -1226,7 +1322,7 @@ function createEventStoreFromQueueFactory(eventQueueFactory, config) {
     restoreEvent: restoreStoredEvent
   });
   validateEventQueue(queue);
-  return {
+  const eventStore = {
     load() {
       const events = queue.events();
       const count = queue.length();
@@ -1256,6 +1352,14 @@ function createEventStoreFromQueueFactory(eventQueueFactory, config) {
       return queue.close();
     }
   };
+  if (typeof queue.remove === "function") {
+    eventStore.remove = (indexes) => queue.remove(indexes);
+  }
+  if (isClientReportStore(queue)) {
+    eventStore.loadClientReport = () => queue.loadClientReport();
+    eventStore.saveClientReport = (state) => queue.saveClientReport(state);
+  }
+  return eventStore;
 }
 
 function validateEventQueue(queue) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/sdk",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Public LogBrew JavaScript SDK for building, validating, and flushing event batches.",
   "type": "module",
   "main": "./index.cjs",