@richardmcquiston01/error-log-adapter 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BatchingErrorAdapter: () => BatchingErrorAdapter,
+  CloudWatchLogsErrorAdapter: () => CloudWatchLogsErrorAdapter,
   CompositeErrorAdapter: () => CompositeErrorAdapter,
   ConsoleErrorAdapter: () => ConsoleErrorAdapter,
   EventEmitterErrorAdapter: () => EventEmitterErrorAdapter,
@@ -191,6 +193,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;
@@ -292,10 +300,10 @@ async function hmacSha256Hex(secret, message) {
       "signingSecret needs Web Crypto (crypto.subtle), which this runtime does not provide, so the entry was not sent unsigned"
     );
   }
-  const encoder = new TextEncoder();
+  const encoder2 = new TextEncoder();
   const key = await subtle.importKey(
     "raw",
-    encoder.encode(secret),
+    encoder2.encode(secret),
     { name: "HMAC", hash: "SHA-256" },
     false,
     ["sign"]
@@ -303,7 +311,7 @@ async function hmacSha256Hex(secret, message) {
   const signature = await subtle.sign(
     "HMAC",
     key,
-    encoder.encode(message)
+    encoder2.encode(message)
   );
   return Array.from(
     new Uint8Array(signature),
@@ -402,6 +410,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) {
@@ -421,11 +459,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();
@@ -1857,8 +1891,548 @@ var WebSocketErrorAdapter = class {
     }
   }
 };
+
+// src/adapters/cloudwatch-logs-error-adapter.ts
+var MAX_EVENT_BYTES = 262144;
+var EVENT_OVERHEAD_BYTES = 26;
+var MAX_BATCH_BYTES = 1048576;
+var MAX_BATCH_EVENTS = 1e4;
+var MAX_BATCH_SPAN_MS = 24 * 60 * 60 * 1e3;
+var BUFFER_LIMIT_MULTIPLIER2 = 10;
+var encoder = new TextEncoder();
+function eventBytes(message) {
+  return encoder.encode(message).length + EVENT_OVERHEAD_BYTES;
+}
+function errorName(error) {
+  return typeof error === "object" && error !== null ? error.name : void 0;
+}
+function splitIntoRequests(events) {
+  const requests = [];
+  let current = [];
+  let bytes = 0;
+  for (const event of events) {
+    const size = eventBytes(event.message);
+    const first = current[0];
+    if (first !== void 0 && (current.length >= MAX_BATCH_EVENTS || bytes + size > MAX_BATCH_BYTES || event.timestamp - first.timestamp > MAX_BATCH_SPAN_MS)) {
+      requests.push(current);
+      current = [];
+      bytes = 0;
+    }
+    current.push(event);
+    bytes += size;
+  }
+  if (current.length > 0) {
+    requests.push(current);
+  }
+  return requests;
+}
+var CloudWatchLogsErrorAdapter = class {
+  /** @throws {RangeError} if a name is empty, the batch or timeout options are invalid, or `createMissing` is on but the client cannot create streams. */
+  constructor(client, logGroupName, logStreamName, options = {}) {
+    this.client = client;
+    this.logGroupName = logGroupName;
+    this.logStreamName = logStreamName;
+    this.buffer = [];
+    this.timer = null;
+    this.flushQueue = new SerialQueue();
+    this.createMissing = options.createMissing ?? true;
+    this.batch = options.batch;
+    this.logPrefix = options.prefix ?? DEFAULT_PREFIX;
+    this.timeoutMs = resolveTimeoutMs(
+      options.timeoutMs,
+      "CloudWatchLogsErrorAdapter"
+    );
+    if (logGroupName === "") {
+      throw new RangeError(
+        "CloudWatchLogsErrorAdapter: logGroupName must not be empty."
+      );
+    }
+    if (logStreamName === "") {
+      throw new RangeError(
+        "CloudWatchLogsErrorAdapter: logStreamName must not be empty."
+      );
+    }
+    if (this.createMissing && typeof client.createLogStream !== "function") {
+      throw new RangeError(
+        "CloudWatchLogsErrorAdapter: createMissing is on, but the client has no createLogStream method. Pass createMissing: false, or use an AWS SDK CloudWatchLogs client."
+      );
+    }
+    if (this.batch !== void 0) {
+      if (!Number.isInteger(this.batch.batchSize) || this.batch.batchSize < 1) {
+        throw new RangeError(
+          `CloudWatchLogsErrorAdapter: batch.batchSize must be a positive integer, received ${String(this.batch.batchSize)}.`
+        );
+      }
+      if (this.batch.maxWaitMs !== void 0 && (!Number.isFinite(this.batch.maxWaitMs) || this.batch.maxWaitMs <= 0)) {
+        throw new RangeError(
+          `CloudWatchLogsErrorAdapter: batch.maxWaitMs must be a positive number, received ${String(this.batch.maxWaitMs)}.`
+        );
+      }
+    }
+  }
+  async log(entry) {
+    try {
+      const id = resolveEntryId(entry);
+      const record = { id, ...serializeEntry(entry) };
+      const timestamp = Date.parse(record.timestamp);
+      if (Number.isNaN(timestamp)) {
+        throw new RangeError(
+          `timestamp "${record.timestamp}" is not a valid ISO 8601 date`
+        );
+      }
+      const message = JSON.stringify(record);
+      const size = eventBytes(message);
+      if (size > MAX_EVENT_BYTES) {
+        throw new RangeError(
+          `the event is ${size} bytes, over the ${MAX_EVENT_BYTES} byte limit CloudWatch Logs puts on one event, so it was not sent; shorten the message or cause`
+        );
+      }
+      const event = { id, timestamp, message };
+      if (this.batch === void 0) {
+        const rejection = await this.send([event]);
+        if (rejection !== void 0) {
+          throw new Error(rejection);
+        }
+        return { ok: true };
+      }
+      return await this.addToBatch(event, this.batch);
+    } catch (error) {
+      return this.fail(error);
+    }
+  }
+  /**
+   * Sends any buffered events now. Resolves ok when nothing is buffered. Events
+   * from a failed send stay buffered and are retried by the next flush.
+   */
+  flush() {
+    return this.flushQueue.run(
+      () => this.sendBuffered()
+    );
+  }
+  async addToBatch(event, batch) {
+    this.buffer.push(event);
+    const limit = batch.batchSize * BUFFER_LIMIT_MULTIPLIER2;
+    if (this.buffer.length > limit) {
+      const dropped = this.buffer.length - limit;
+      this.buffer = this.buffer.slice(dropped);
+      console.error(
+        `${this.logPrefix} CloudWatchLogsErrorAdapter: dropped the ${dropped} oldest buffered events because sends to log stream "${this.logStreamName}" keep failing and the buffer is full (${limit} events).`
+      );
+    }
+    if (this.buffer.length >= batch.batchSize) {
+      return this.flush();
+    }
+    this.scheduleFlush(batch);
+    return { ok: true };
+  }
+  scheduleFlush(batch) {
+    if (batch.maxWaitMs === void 0 || this.timer !== null) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, batch.maxWaitMs);
+    timer.unref?.();
+    this.timer = timer;
+  }
+  async sendBuffered() {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    const pending = this.buffer.slice();
+    if (pending.length === 0) {
+      return { ok: true };
+    }
+    pending.sort(
+      (a, b) => a.timestamp - b.timestamp
+    );
+    let rejectedTotal = 0;
+    let lastRejection = "";
+    try {
+      for (const request of splitIntoRequests(pending)) {
+        const rejection = await this.send(request);
+        const sent = new Set(request);
+        this.buffer = this.buffer.filter(
+          (event) => !sent.has(event)
+        );
+        if (rejection !== void 0) {
+          rejectedTotal += request.length;
+          lastRejection = rejection;
+        }
+      }
+    } catch (error) {
+      if (this.batch !== void 0) {
+        this.scheduleFlush(this.batch);
+      }
+      return this.fail(error, this.buffer.length);
+    }
+    if (rejectedTotal > 0) {
+      return this.fail(new Error(lastRejection), rejectedTotal);
+    }
+    return { ok: true };
+  }
+  /**
+   * Sends one request, creating the stream first if CloudWatch says it is
+   * missing. Resolves to a description of any events CloudWatch refused, or
+   * undefined when it took them all.
+   */
+  async send(events) {
+    let output;
+    try {
+      output = await this.putLogEvents(events);
+    } catch (error) {
+      if (!this.createMissing || errorName(error) !== "ResourceNotFoundException") {
+        throw error;
+      }
+      await this.createStream();
+      output = await this.putLogEvents(events);
+    }
+    return describeRejection(output, events.length);
+  }
+  putLogEvents(events) {
+    return withTimeout(
+      () => this.client.putLogEvents({
+        logGroupName: this.logGroupName,
+        logStreamName: this.logStreamName,
+        logEvents: events.map(
+          ({ timestamp, message }) => ({
+            timestamp,
+            message
+          })
+        )
+      }),
+      this.timeoutMs,
+      timeoutMessage("CloudWatch Logs", this.timeoutMs)
+    );
+  }
+  async createStream() {
+    const createStream = () => withTimeout(
+      () => this.client.createLogStream({
+        logGroupName: this.logGroupName,
+        logStreamName: this.logStreamName
+      }),
+      this.timeoutMs,
+      timeoutMessage("CloudWatch Logs", this.timeoutMs, "create the stream")
+    );
+    try {
+      await createStream();
+    } catch (error) {
+      const name = errorName(error);
+      if (name === "ResourceAlreadyExistsException") {
+        return;
+      }
+      if (name !== "ResourceNotFoundException" || typeof this.client.createLogGroup !== "function") {
+        throw error;
+      }
+      const createGroup = this.client.createLogGroup.bind(this.client);
+      try {
+        await withTimeout(
+          () => createGroup({ logGroupName: this.logGroupName }),
+          this.timeoutMs,
+          timeoutMessage("CloudWatch Logs", this.timeoutMs, "create the group")
+        );
+      } catch (groupError) {
+        if (errorName(groupError) !== "ResourceAlreadyExistsException") {
+          throw groupError;
+        }
+      }
+      try {
+        await createStream();
+      } catch (retryError) {
+        if (errorName(retryError) !== "ResourceAlreadyExistsException") {
+          throw retryError;
+        }
+      }
+    }
+  }
+  fail(error, count) {
+    return reportFailure({
+      adapterName: "CloudWatchLogsErrorAdapter",
+      prefix: this.logPrefix,
+      action: `to send to log stream "${this.logStreamName}" in log group "${this.logGroupName}"${count === void 0 ? "" : ` (${count} event${count === 1 ? "" : "s"} affected)`}`,
+      error
+    });
+  }
+};
+function describeRejection(output, eventCount) {
+  const info = typeof output === "object" && output !== null ? output.rejectedLogEventsInfo : void 0;
+  if (info === void 0 || info === null) {
+    return void 0;
+  }
+  const reasons = [];
+  if (info.tooOldLogEventEndIndex !== void 0) {
+    reasons.push(
+      `${info.tooOldLogEventEndIndex} event(s) were older than the 14 days CloudWatch accepts`
+    );
+  }
+  if (info.expiredLogEventEndIndex !== void 0) {
+    reasons.push(
+      `${info.expiredLogEventEndIndex} event(s) were older than the log group's retention period`
+    );
+  }
+  if (info.tooNewLogEventStartIndex !== void 0) {
+    reasons.push(
+      `${Math.max(0, eventCount - info.tooNewLogEventStartIndex)} event(s) were more than 2 hours ahead of the current time`
+    );
+  }
+  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 {
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BatchingErrorAdapter,
+  CloudWatchLogsErrorAdapter,
   CompositeErrorAdapter,
   ConsoleErrorAdapter,
   EventEmitterErrorAdapter,