@richardmcquiston01/error-log-adapter 0.8.0 → 0.10.0

package/dist/index.mjs

@@ -140,6 +140,12 @@ var ConsoleErrorAdapter = class {
   }
 };
 
+// src/backoff.ts
+function backoffDelayMs(retryNumber, baseMs, maxMs) {
+  const ceiling = Math.min(maxMs, baseMs * 2 ** (retryNumber - 1));
+  return ceiling / 2 + Math.random() * ceiling / 2;
+}
+
 // src/uuid.ts
 function generateId() {
   const cryptoApi = globalThis.crypto;
@@ -351,6 +357,36 @@ var WebhookErrorAdapter = class {
         `could not prepare the entry: ${this.redact(describeError(error))}`
       );
     }
+    return this.deliver(body);
+  }
+  /**
+   * Sends several entries in one request, as a JSON array of the same records
+   * `log` sends one at a time (each with an `id`). `BatchingErrorAdapter` uses
+   * this when it wraps a webhook, so the receiver must accept an array. The
+   * whole request succeeds or fails together.
+   */
+  async logBatch(entries) {
+    if (entries.length === 0) {
+      return { ok: true };
+    }
+    let body;
+    try {
+      body = JSON.stringify(
+        entries.map((entry) => ({
+          id: resolveEntryId(entry),
+          ...serializeEntry(entry)
+        }))
+      );
+    } catch (error) {
+      console.error(`${this.prefix} WebhookErrorAdapter:`, error);
+      return this.fail(
+        `could not prepare the entries: ${this.redact(describeError(error))}`
+      );
+    }
+    return this.deliver(body);
+  }
+  /** Sends one prepared body, trying again as `retries` allows. */
+  async deliver(body) {
     let attempt = await this.send(body);
     let attempts = 1;
     while (!attempt.ok && attempt.retryable && attempts <= this.retries) {
@@ -370,11 +406,7 @@ var WebhookErrorAdapter = class {
     if (retryAfterMs !== void 0) {
       return Math.min(retryAfterMs, this.maxRetryDelayMs);
     }
-    const ceiling = Math.min(
-      this.maxRetryDelayMs,
-      this.retryDelayMs * 2 ** (retryNumber - 1)
-    );
-    return ceiling / 2 + Math.random() * ceiling / 2;
+    return backoffDelayMs(retryNumber, this.retryDelayMs, this.maxRetryDelayMs);
   }
   async send(body) {
     const controller = new AbortController();
@@ -1542,6 +1574,15 @@ var S3ErrorAdapter = class {
 };
 
 // src/adapters/firebase-error-adapter.ts
+var DEFAULT_EXPIRE_FIELD = "expire_at";
+var RESERVED_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "code",
+  "message",
+  "timestamp",
+  "source",
+  "cause"
+]);
 function waitForWrite(start, timeoutMs) {
   return withTimeout(
     start,
@@ -1566,7 +1607,7 @@ function buildRecord(entry) {
   return record;
 }
 var FirestoreErrorAdapter = class {
-  /** @throws {RangeError} if `options.timeoutMs` is not a positive number or `Infinity`. */
+  /** @throws {RangeError} if `options.timeoutMs` is not a positive number or `Infinity`, or the expiry options are invalid. */
   constructor(collection, options = {}) {
     this.collection = collection;
     this.prefix = options.prefix ?? DEFAULT_PREFIX;
@@ -1574,10 +1615,31 @@ var FirestoreErrorAdapter = class {
       options.timeoutMs,
       "FirestoreErrorAdapter"
     );
+    this.expireAfterMs = options.expireAfterMs;
+    this.expireField = options.expireField ?? DEFAULT_EXPIRE_FIELD;
+    if (this.expireAfterMs !== void 0 && (!Number.isFinite(this.expireAfterMs) || this.expireAfterMs <= 0)) {
+      throw new RangeError(
+        `FirestoreErrorAdapter: expireAfterMs must be a positive number of milliseconds, received ${String(options.expireAfterMs)}.`
+      );
+    }
+    if (this.expireField === "" || /[./]/.test(this.expireField) || RESERVED_FIELDS.has(this.expireField)) {
+      throw new RangeError(
+        `FirestoreErrorAdapter: expireField must be a name other than ${[...RESERVED_FIELDS].join(", ")}, without "." or "/", received ${JSON.stringify(this.expireField)}.`
+      );
+    }
   }
   async log(entry) {
     try {
-      const record = buildRecord(entry);
+      const record = { ...buildRecord(entry) };
+      if (this.expireAfterMs !== void 0) {
+        const occurredAt = Date.parse(record.timestamp);
+        if (Number.isNaN(occurredAt)) {
+          throw new RangeError(
+            `timestamp "${record.timestamp}" is not a valid ISO 8601 date, so the expiry time cannot be worked out`
+          );
+        }
+        record[this.expireField] = new Date(occurredAt + this.expireAfterMs);
+      }
       await waitForWrite(
         () => this.collection.doc(record.id).set(record),
         this.timeoutMs
@@ -2094,7 +2156,258 @@ function describeRejection(output, eventCount) {
   }
   return reasons.length === 0 ? void 0 : `CloudWatch Logs accepted the request but rejected events: ${reasons.join("; ")}`;
 }
+
+// src/adapters/batching-error-adapter.ts
+var DEFAULT_BATCH_SIZE = 20;
+var DEFAULT_MAX_WAIT_MS = 5e3;
+var DEFAULT_RETRIES = 3;
+var DEFAULT_RETRY_DELAY_MS2 = 500;
+var DEFAULT_MAX_RETRY_DELAY_MS2 = 3e4;
+var DEFAULT_MAX_BUFFERED = 1e3;
+function hasLogBatch(adapter) {
+  return typeof adapter.logBatch === "function";
+}
+var BatchingErrorAdapter = class {
+  /** @throws {RangeError} if an option is out of range. */
+  constructor(inner, options = {}) {
+    this.inner = inner;
+    this.queue = [];
+    this.waitTimer = null;
+    this.backoffTimer = null;
+    this.draining = null;
+    this.flushers = 0;
+    this.droppedSinceFlush = 0;
+    this.lastDropReason = "";
+    this.batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    this.maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    this.retries = options.retries ?? DEFAULT_RETRIES;
+    this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS2;
+    this.maxRetryDelayMs = options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS2;
+    this.maxBuffered = options.maxBuffered ?? DEFAULT_MAX_BUFFERED;
+    this.useBatchMethod = options.useBatchMethod ?? true;
+    this.onDrop = options.onDrop;
+    this.logPrefix = options.prefix ?? DEFAULT_PREFIX;
+    if (!Number.isInteger(this.batchSize) || this.batchSize < 1) {
+      throw new RangeError(
+        `BatchingErrorAdapter: batchSize must be a positive integer, received ${String(options.batchSize)}.`
+      );
+    }
+    if (Number.isNaN(this.maxWaitMs) || this.maxWaitMs <= 0) {
+      throw new RangeError(
+        `BatchingErrorAdapter: maxWaitMs must be a positive number or Infinity, received ${String(options.maxWaitMs)}.`
+      );
+    }
+    if (!Number.isInteger(this.retries) || this.retries < 0) {
+      throw new RangeError(
+        `BatchingErrorAdapter: retries must be a whole number of 0 or more, received ${String(options.retries)}.`
+      );
+    }
+    if (!Number.isFinite(this.retryDelayMs) || this.retryDelayMs <= 0) {
+      throw new RangeError(
+        `BatchingErrorAdapter: retryDelayMs must be a positive number, received ${String(options.retryDelayMs)}.`
+      );
+    }
+    if (!Number.isFinite(this.maxRetryDelayMs) || this.maxRetryDelayMs < this.retryDelayMs) {
+      throw new RangeError(
+        `BatchingErrorAdapter: maxRetryDelayMs must be a number no smaller than retryDelayMs (${this.retryDelayMs}), received ${String(options.maxRetryDelayMs)}.`
+      );
+    }
+    if (!Number.isInteger(this.maxBuffered) || this.maxBuffered < this.batchSize) {
+      throw new RangeError(
+        `BatchingErrorAdapter: maxBuffered must be a whole number no smaller than batchSize (${this.batchSize}), received ${String(options.maxBuffered)}.`
+      );
+    }
+  }
+  /** Queues the entry. Resolves ok straight away; delivery happens in the background. */
+  log(entry) {
+    this.queue.push({ entry, failures: 0 });
+    if (this.queue.length > this.maxBuffered) {
+      const overflow = this.queue.splice(
+        0,
+        this.queue.length - this.maxBuffered
+      );
+      this.drop(
+        overflow,
+        `the buffer of ${this.maxBuffered} entries was full because the wrapped adapter keeps failing`
+      );
+    }
+    if (this.queue.length >= this.batchSize) {
+      this.startDraining();
+    } else {
+      this.scheduleDrain();
+    }
+    return Promise.resolve({ ok: true });
+  }
+  /**
+   * Delivers everything queued, retrying as configured, and resolves once the
+   * queue is empty. Resolves `ok: false` if any entries were given up on since
+   * the last flush. With retries on and the sink down this can take a while
+   * (the waits add up to well over a minute with the defaults).
+   */
+  async flush() {
+    this.flushers += 1;
+    this.backoffTimer?.ref?.();
+    try {
+      this.startDraining();
+      while (this.draining !== null) {
+        await this.draining;
+      }
+    } finally {
+      this.flushers -= 1;
+    }
+    if (this.droppedSinceFlush > 0) {
+      const count = this.droppedSinceFlush;
+      const reason = this.lastDropReason;
+      this.droppedSinceFlush = 0;
+      this.lastDropReason = "";
+      return {
+        ok: false,
+        error: `BatchingErrorAdapter gave up on ${count} entr${count === 1 ? "y" : "ies"}: ${reason}`
+      };
+    }
+    return { ok: true };
+  }
+  scheduleDrain() {
+    if (this.waitTimer !== null || this.maxWaitMs === Infinity) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      this.waitTimer = null;
+      this.startDraining();
+    }, this.maxWaitMs);
+    timer.unref?.();
+    this.waitTimer = timer;
+  }
+  startDraining() {
+    if (this.waitTimer !== null) {
+      clearTimeout(this.waitTimer);
+      this.waitTimer = null;
+    }
+    if (this.draining !== null || this.queue.length === 0) {
+      return;
+    }
+    this.draining = this.drain().catch((error) => {
+      console.error(`${this.logPrefix} BatchingErrorAdapter:`, error);
+    }).finally(() => {
+      this.draining = null;
+      if (this.queue.length > 0) {
+        this.scheduleDrain();
+      }
+    });
+  }
+  /** Delivers batches until the queue is empty, waiting out a backoff after each failure. */
+  async drain() {
+    let failedRounds = 0;
+    while (this.queue.length > 0) {
+      const batch = this.queue.slice(0, this.batchSize);
+      const failure = await this.deliver(batch);
+      if (failure === void 0) {
+        failedRounds = 0;
+        continue;
+      }
+      failedRounds += 1;
+      const exhausted = this.queue.filter(
+        (item) => item.failures > this.retries
+      );
+      if (exhausted.length > 0) {
+        this.queue = this.queue.filter(
+          (item) => item.failures <= this.retries
+        );
+        this.drop(
+          exhausted,
+          `delivery failed ${this.retries + 1} time${this.retries === 0 ? "" : "s"}; last error: ${failure}`
+        );
+      }
+      if (this.queue.length > 0) {
+        await this.backoff(failedRounds);
+      }
+    }
+  }
+  /**
+   * Tries to deliver `batch` (the front of the queue). Delivered entries leave
+   * the queue; an entry that failed has its failure count raised and stays.
+   * Resolves to the failure message, or undefined when everything went through.
+   */
+  async deliver(batch) {
+    const remove = (delivered) => {
+      const gone = new Set(delivered);
+      this.queue = this.queue.filter(
+        (item) => !gone.has(item)
+      );
+    };
+    if (this.useBatchMethod && hasLogBatch(this.inner)) {
+      const result = await this.safely(
+        () => this.inner.logBatch(
+          batch.map(
+            (item) => item.entry
+          )
+        )
+      );
+      if (result.ok) {
+        remove(batch);
+        return void 0;
+      }
+      for (const item of batch) {
+        item.failures += 1;
+      }
+      return result.error ?? "the wrapped adapter reported a failure";
+    }
+    for (const item of batch) {
+      const result = await this.safely(
+        () => this.inner.log(item.entry)
+      );
+      if (result.ok) {
+        remove([item]);
+        continue;
+      }
+      item.failures += 1;
+      return result.error ?? "the wrapped adapter reported a failure";
+    }
+    return void 0;
+  }
+  /** The wrapped adapter should not throw, but a bug in one must not stop the queue. */
+  async safely(call) {
+    try {
+      return await call();
+    } catch (error) {
+      return { ok: false, error: describeError(error) };
+    }
+  }
+  backoff(failedRounds) {
+    return new Promise((resolve) => {
+      const timer = setTimeout(
+        () => {
+          this.backoffTimer = null;
+          resolve();
+        },
+        backoffDelayMs(failedRounds, this.retryDelayMs, this.maxRetryDelayMs)
+      );
+      if (this.flushers === 0) {
+        timer.unref?.();
+      }
+      this.backoffTimer = timer;
+    });
+  }
+  drop(items, reason) {
+    if (items.length === 0) {
+      return;
+    }
+    this.droppedSinceFlush += items.length;
+    this.lastDropReason = reason;
+    console.error(
+      `${this.logPrefix} BatchingErrorAdapter: gave up on ${items.length} entr${items.length === 1 ? "y" : "ies"}: ${reason}`
+    );
+    try {
+      this.onDrop?.(
+        items.map((item) => item.entry),
+        reason
+      );
+    } catch {
+    }
+  }
+};
 export {
+  BatchingErrorAdapter,
   CloudWatchLogsErrorAdapter,
   CompositeErrorAdapter,
   ConsoleErrorAdapter,