@richardmcquiston01/error-log-adapter 0.5.0 → 0.7.0

package/README.md

@@ -70,24 +70,26 @@ Constructor options are checked when the adapter is created and throw a descript
 
 Every adapter takes an optional `prefix` (default `[error-log-adapter]`) that is printed before its failure messages.
 
-| Adapter                             | Sink                                                      | Runs in       | Main options                                     |
-| ----------------------------------- | --------------------------------------------------------- | ------------- | ------------------------------------------------ |
-| `ConsoleErrorAdapter`               | `console.error`                                           | Anywhere      |                                                  |
-| `WebhookErrorAdapter(url)`          | HTTP `POST` of the entry as JSON                          | Anywhere      | `headers`, `timeoutMs`, `allowInsecure`          |
-| `MongoDbErrorAdapter(collection)`   | Anything with `insertOne`, such as a MongoDB `Collection` | Node          | `timeoutMs`                                      |
-| `PostgresErrorAdapter(client)`      | A Postgres table, through `pg`                            | Node          | `tableName`, `createTable`, `timeoutMs`          |
-| `MySqlErrorAdapter(client)`         | A MySQL / MariaDB table, through `mysql2/promise`         | Node          | `tableName`, `createTable`, `timeoutMs`          |
-| `SqliteErrorAdapter(client)`        | A SQLite table, through any driver                        | Node, Bun     | `tableName`, `createTable`, `timeoutMs`          |
-| `SupabaseErrorAdapter(client)`      | A Supabase table, through `supabase-js`                   | Anywhere      | `tableName`, `timeoutMs`                         |
-| `RedisErrorAdapter(client)`         | A Redis list or stream                                    | Node          | `mode`, `key`, `maxEntries`, `side`, `timeoutMs` |
-| `S3ErrorAdapter(client, bucket)`    | S3, DigitalOcean Spaces, R2, MinIO objects                | Node          | `keyPrefix`, `batch`, `contentType`, `timeoutMs` |
-| `FirestoreErrorAdapter(collection)` | A Firestore collection                                    | Node, browser | `timeoutMs`                                      |
-| `RealtimeDatabaseErrorAdapter(ref)` | A Realtime Database reference                             | Node, browser | `timeoutMs`                                      |
-| `FlatFileErrorAdapter(path)`        | One text line per entry                                   | Node, Bun     | `formatLine`, `maxBytes`, `maxFiles`             |
-| `JsonFileErrorAdapter(path)`        | NDJSON lines or one JSON array                            | Node, Bun     | `mode`, `maxEntries`, `indent`                   |
-| `IndexedDbErrorAdapter(database)`   | An IndexedDB object store                                 | Browser       | `storeName`, `timeoutMs`                         |
-| `WebStorageErrorAdapter(storage)`   | `sessionStorage` or `localStorage`, as one capped array   | Browser       | `key`, `maxEntries`, `locks`                     |
-| `CompositeErrorAdapter([...])`      | Several adapters at once; succeeds only if all succeed    | Anywhere      | `timeoutMs`                                      |
+| Adapter                             | Sink                                                      | Runs in       | Main options                                                        |
+| ----------------------------------- | --------------------------------------------------------- | ------------- | ------------------------------------------------------------------- |
+| `ConsoleErrorAdapter`               | `console.error`                                           | Anywhere      |                                                                     |
+| `WebhookErrorAdapter(url)`          | HTTP `POST` of the entry as JSON                          | Anywhere      | `headers`, `timeoutMs`, `retries`, `signingSecret`, `allowInsecure` |
+| `MongoDbErrorAdapter(collection)`   | Anything with `insertOne`, such as a MongoDB `Collection` | Node          | `timeoutMs`                                                         |
+| `PostgresErrorAdapter(client)`      | A Postgres table, through `pg`                            | Node          | `tableName`, `createTable`, `timeoutMs`                             |
+| `MySqlErrorAdapter(client)`         | A MySQL / MariaDB table, through `mysql2/promise`         | Node          | `tableName`, `createTable`, `timeoutMs`                             |
+| `SqliteErrorAdapter(client)`        | A SQLite table, through any driver                        | Node, Bun     | `tableName`, `createTable`, `timeoutMs`                             |
+| `SupabaseErrorAdapter(client)`      | A Supabase table, through `supabase-js`                   | Anywhere      | `tableName`, `timeoutMs`                                            |
+| `RedisErrorAdapter(client)`         | A Redis list or stream                                    | Node          | `mode`, `key`, `maxEntries`, `side`, `timeoutMs`                    |
+| `S3ErrorAdapter(client, bucket)`    | S3, DigitalOcean Spaces, R2, MinIO objects                | Node          | `keyPrefix`, `batch`, `contentType`, `timeoutMs`                    |
+| `FirestoreErrorAdapter(collection)` | A Firestore collection                                    | Node, browser | `timeoutMs`                                                         |
+| `RealtimeDatabaseErrorAdapter(ref)` | A Realtime Database reference                             | Node, browser | `timeoutMs`                                                         |
+| `FlatFileErrorAdapter(path)`        | One text line per entry                                   | Node, Bun     | `formatLine`, `maxBytes`, `maxFiles`                                |
+| `JsonFileErrorAdapter(path)`        | NDJSON lines or one JSON array                            | Node, Bun     | `mode`, `maxEntries`, `indent`                                      |
+| `IndexedDbErrorAdapter(database)`   | An IndexedDB object store                                 | Browser       | `storeName`, `timeoutMs`                                            |
+| `WebStorageErrorAdapter(storage)`   | `sessionStorage` or `localStorage`, as one capped array   | Browser       | `key`, `maxEntries`, `locks`                                        |
+| `EventEmitterErrorAdapter(emitter)` | An event on an emitter you own (in-process hooks)         | Anywhere      | `eventName`, `requireListener`                                      |
+| `WebSocketErrorAdapter(socket)`     | One JSON message over a socket you own                    | Anywhere      | (none)                                                              |
+| `CompositeErrorAdapter([...])`      | Several adapters at once; succeeds only if all succeed    | Anywhere      | `timeoutMs`                                                         |
 
 Every stored record has the same shape: a UUID `id`, `code`, `message`, `timestamp` (ISO 8601), and optional `source` and `cause`. An `Error` cause is stored as `{ name, message, stack }`. `serializeEntry` and `serializeCause` are exported if you build your own sink.
 
@@ -99,7 +101,9 @@ What changes durability or size, by adapter:
 - **Files** (`maxBytes` / `maxFiles`, `maxEntries`): the flat file adapter rotates by size; the JSON file adapter's `array` mode keeps the newest `maxEntries`.
 - **Redis and Web Storage** (`maxEntries`): the oldest entries are dropped past the cap.
 - **Browser storage**: `sessionStorage` belongs to one tab. `localStorage` is shared by every tab and has no atomic update, so two tabs logging at the same instant can overwrite each other's entry. `WebStorageErrorAdapter` takes a `navigator.locks` lock around each write, which reduces the loss but cannot remove it, since tabs in separate processes can still read a stale copy. Use `IndexedDbErrorAdapter` when every entry matters. Create its object store from your `onupgradeneeded` handler with `createErrorLogStore`. A stored value the adapter cannot read is copied to `<key>.corrupt` before it is replaced.
-- **Webhook**: the URL must be `https://` (or `http://localhost`, `127.0.0.1`, `[::1]`) unless you pass `allowInsecure: true`, because entries carry messages and stack traces. Redirects are not followed, since a redirect would turn the `POST` into a body-less `GET` or re-send the entry and your headers to another host; a redirect is reported as `ok: false`. Failure messages contain only the origin, never the path or query, because webhook URLs often hold a secret.
+- **Event emitter**: each entry is emitted as an `error-log` event whose payload is the stored record, for in-process hooks such as a toast, a metrics counter or a test assertion. Listeners run synchronously, so one that throws makes `log()` return `ok: false` with its message. Node's `EventEmitter` and mitt work as they are; a browser `EventTarget` needs a one-line wrapper (shown in the example below). Don't name the event `error` on a Node `EventEmitter`: it throws when nobody listens. Node's `emit` returns `false` when there are no listeners; pass `requireListener: true` to report that as a failure instead of letting the entry vanish.
+- **WebSocket**: each entry is sent as one JSON text message (the serialized entry plus its UUID `id`) over a socket you own; the adapter never connects, reconnects or buffers. If the socket's `readyState` is not open (connecting, closing or closed), `log()` returns `ok: false` and says which. `ok: true` means the socket accepted the message, not that the server got it, since a WebSocket has no acknowledgement. Browsers, Node's global `WebSocket`, Deno, Bun and `ws` all fit. Pair it with a durable adapter in a `CompositeErrorAdapter` if entries must survive the socket being down.
+- **Webhook**: the URL must be `https://` (or `http://localhost`, `127.0.0.1`, `[::1]`) unless you pass `allowInsecure: true`, because entries carry messages and stack traces. Redirects are not followed, since a redirect would turn the `POST` into a body-less `GET` or re-send the entry and your headers to another host; a redirect is reported as `ok: false`. Failure messages contain only the origin, never the path or query, because webhook URLs often hold a secret. Set `retries` to try again after a network error, a timeout, HTTP 408, 425, 429 or 5xx (exponential backoff with jitter from `retryDelayMs`, capped by `maxRetryDelayMs`, honoring `Retry-After`; other 4xx answers are never retried). With `retries` set, every attempt sends the same body including an `id`, so the receiver can drop a repeat. Set `signingSecret` to add `X-Signature-Timestamp` and `X-Signature-256` (`sha256=` + hex HMAC-SHA256 of `<timestamp>.<body>`); the receiver recomputes it and rejects old timestamps.
 
 ### When a sink is slow or down
 
@@ -209,6 +213,50 @@ const errorLog = new S3ErrorAdapter(s3, 'my-space', {
 process.on('beforeExit', () => void errorLog.flush());
 ```
 
+Show a toast, count errors, and keep a file copy, all from one `log` call:
+
+```ts
+import { EventEmitter } from 'node:events';
+import {
+  CompositeErrorAdapter,
+  EventEmitterErrorAdapter,
+  FlatFileErrorAdapter,
+} from '@richardmcquiston01/error-log-adapter';
+
+const bus = new EventEmitter();
+bus.on('error-log', (record) => showToast(record.message));
+bus.on('error-log', (record) => metrics.increment(`errors.${record.code}`));
+
+const errorLog = new CompositeErrorAdapter([
+  new EventEmitterErrorAdapter(bus),
+  new FlatFileErrorAdapter('logs/errors.log'),
+]);
+```
+
+In a browser, wrap an `EventTarget`:
+
+```ts
+const target = new EventTarget();
+const emitter = {
+  emit: (name: string, payload: unknown) =>
+    target.dispatchEvent(new CustomEvent(name, { detail: payload })),
+};
+target.addEventListener('error-log', (event) =>
+  console.log((event as CustomEvent).detail)
+);
+const errorLog = new EventEmitterErrorAdapter(emitter);
+```
+
+Send errors over a socket you manage, with a file as the fallback while it is down:
+
+```ts
+const socket = new WebSocket('wss://logs.example.com/errors');
+const errorLog = new CompositeErrorAdapter([
+  new WebSocketErrorAdapter(socket),
+  new FlatFileErrorAdapter('./errors.log'),
+]);
+```
+
 Write your own adapter by implementing the interface. Catch failures and return them rather than throwing:
 
 ```ts

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   CompositeErrorAdapter: () => CompositeErrorAdapter,
   ConsoleErrorAdapter: () => ConsoleErrorAdapter,
+  EventEmitterErrorAdapter: () => EventEmitterErrorAdapter,
   FirestoreErrorAdapter: () => FirestoreErrorAdapter,
   FlatFileErrorAdapter: () => FlatFileErrorAdapter,
   IndexedDbErrorAdapter: () => IndexedDbErrorAdapter,
@@ -34,6 +35,7 @@ __export(index_exports, {
   S3ErrorAdapter: () => S3ErrorAdapter,
   SqliteErrorAdapter: () => SqliteErrorAdapter,
   SupabaseErrorAdapter: () => SupabaseErrorAdapter,
+  WebSocketErrorAdapter: () => WebSocketErrorAdapter,
   WebStorageErrorAdapter: () => WebStorageErrorAdapter,
   WebhookErrorAdapter: () => WebhookErrorAdapter,
   buildCreateErrorLogTableSql: () => buildCreateErrorLogTableSql,
@@ -278,6 +280,78 @@ function withTimeout(start, timeoutMs, message) {
 }
 
 // src/adapters/webhook-error-adapter.ts
+var DEFAULT_RETRY_DELAY_MS = 500;
+var DEFAULT_MAX_RETRY_DELAY_MS = 3e4;
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 425, 429]);
+var SigningUnavailableError = class extends Error {
+};
+async function hmacSha256Hex(secret, message) {
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle === void 0) {
+    throw new SigningUnavailableError(
+      "signingSecret needs Web Crypto (crypto.subtle), which this runtime does not provide, so the entry was not sent unsigned"
+    );
+  }
+  const encoder = new TextEncoder();
+  const key = await subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(message)
+  );
+  return Array.from(
+    new Uint8Array(signature),
+    (byte) => byte.toString(16).padStart(2, "0")
+  ).join("");
+}
+function parseRetryAfterMs(value) {
+  if (value === null || value === void 0 || value.trim() === "") {
+    return void 0;
+  }
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1e3;
+  }
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+}
+function validateRetryOptions(options) {
+  const retries = options.retries ?? 0;
+  if (!Number.isInteger(retries) || retries < 0) {
+    throw new RangeError(
+      `WebhookErrorAdapter: retries must be a whole number of 0 or more, received ${String(options.retries)}.`
+    );
+  }
+  const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+  if (!Number.isFinite(retryDelayMs) || retryDelayMs <= 0) {
+    throw new RangeError(
+      `WebhookErrorAdapter: retryDelayMs must be a positive number, received ${String(options.retryDelayMs)}.`
+    );
+  }
+  const maxRetryDelayMs = options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS;
+  if (!Number.isFinite(maxRetryDelayMs) || maxRetryDelayMs < retryDelayMs) {
+    throw new RangeError(
+      `WebhookErrorAdapter: maxRetryDelayMs must be a number no smaller than retryDelayMs (${retryDelayMs}), received ${String(options.maxRetryDelayMs)}.`
+    );
+  }
+  if (options.signingSecret === "") {
+    throw new RangeError(
+      "WebhookErrorAdapter: signingSecret must not be empty; leave it out to send unsigned."
+    );
+  }
+  return { retries, retryDelayMs, maxRetryDelayMs };
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
 var LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
   "localhost",
   "127.0.0.1",
@@ -303,15 +377,57 @@ function parseWebhookUrl(url, allowInsecure) {
   );
 }
 var WebhookErrorAdapter = class {
-  /** @throws {RangeError} if `url` is not a valid `https://` URL (see `allowInsecure`) or `timeoutMs` is invalid. */
+  /** @throws {RangeError} if `url` is not a valid `https://` URL (see `allowInsecure`) or a timeout, retry or signing option is invalid. */
   constructor(url, options = {}) {
     this.url = url;
     this.options = options;
     this.prefix = options.prefix ?? DEFAULT_PREFIX;
     this.timeoutMs = resolveTimeoutMs(options.timeoutMs, "WebhookErrorAdapter");
+    ({
+      retries: this.retries,
+      retryDelayMs: this.retryDelayMs,
+      maxRetryDelayMs: this.maxRetryDelayMs
+    } = validateRetryOptions(options));
     this.target = parseWebhookUrl(url, options.allowInsecure ?? false).origin;
   }
   async log(entry) {
+    let body;
+    try {
+      body = JSON.stringify(
+        hasCallerId(entry) || this.retries > 0 ? { id: resolveEntryId(entry), ...serializeEntry(entry) } : serializeEntry(entry)
+      );
+    } catch (error) {
+      console.error(`${this.prefix} WebhookErrorAdapter:`, error);
+      return this.fail(
+        `could not prepare the entry: ${this.redact(describeError(error))}`
+      );
+    }
+    let attempt = await this.send(body);
+    let attempts = 1;
+    while (!attempt.ok && attempt.retryable && attempts <= this.retries) {
+      await sleep(this.retryWaitMs(attempts, attempt.retryAfterMs));
+      attempt = await this.send(body);
+      attempts += 1;
+    }
+    if (attempt.ok) {
+      return { ok: true };
+    }
+    return this.fail(
+      attempts > 1 ? `${attempt.reason} (after ${attempts} attempts)` : attempt.reason
+    );
+  }
+  /** Milliseconds to wait before retry number `retryNumber` (1 for the first). */
+  retryWaitMs(retryNumber, retryAfterMs) {
+    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;
+  }
+  async send(body) {
     const controller = new AbortController();
     let timedOut = false;
     const timer = this.timeoutMs === Infinity ? void 0 : setTimeout(() => {
@@ -323,43 +439,70 @@ var WebhookErrorAdapter = class {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          ...this.options.headers
+          ...this.options.headers,
+          ...await this.signatureHeaders(body)
         },
-        // A caller-supplied id goes along so the receiver can drop a repeat.
-        body: JSON.stringify(
-          hasCallerId(entry) ? { id: resolveEntryId(entry), ...serializeEntry(entry) } : serializeEntry(entry)
-        ),
+        body,
         // A redirect would turn the POST into a GET without a body (302, 303)
         // or re-send the entry and headers to another host (307, 308).
         redirect: "manual",
         signal: controller.signal
       });
       if (response.type === "opaqueredirect") {
-        return this.fail(this.redirectMessage("a redirect"));
+        return this.rejected(this.redirectMessage("a redirect"));
       }
       if (!response.ok) {
         if (response.status >= 300 && response.status < 400) {
-          return this.fail(this.redirectMessage(`HTTP ${response.status}`));
+          return this.rejected(this.redirectMessage(`HTTP ${response.status}`));
         }
-        return this.fail(
-          `webhook ${this.target} responded with HTTP ${response.status}`
-        );
+        return {
+          ok: false,
+          reason: `webhook ${this.target} responded with HTTP ${response.status}`,
+          retryable: response.status >= 500 || RETRYABLE_STATUSES.has(response.status),
+          retryAfterMs: parseRetryAfterMs(response.headers?.get("retry-after"))
+        };
       }
       return { ok: true };
     } catch (error) {
       console.error(`${this.prefix} WebhookErrorAdapter:`, error);
+      if (error instanceof SigningUnavailableError) {
+        return this.rejected(error.message);
+      }
       if (timedOut) {
-        return this.fail(
-          timeoutMessage(`webhook ${this.target}`, this.timeoutMs)
-        );
+        return {
+          ok: false,
+          reason: timeoutMessage(`webhook ${this.target}`, this.timeoutMs),
+          retryable: true
+        };
       }
-      return this.fail(
-        `could not reach webhook ${this.target}: ${this.redact(describeError(error))}`
-      );
+      return {
+        ok: false,
+        reason: `could not reach webhook ${this.target}: ${this.redact(describeError(error))}`,
+        retryable: true
+      };
     } finally {
       clearTimeout(timer);
     }
   }
+  /** Timestamp and signature headers, or none when no `signingSecret` is set. */
+  async signatureHeaders(body) {
+    const secret = this.options.signingSecret;
+    if (secret === void 0) {
+      return {};
+    }
+    const timestamp = String(Math.floor(Date.now() / 1e3));
+    const signature = await hmacSha256Hex(
+      secret,
+      `${timestamp}.${body}`
+    );
+    return {
+      "X-Signature-Timestamp": timestamp,
+      "X-Signature-256": `sha256=${signature}`
+    };
+  }
+  rejected(reason) {
+    return { ok: false, reason, retryable: false };
+  }
   redirectMessage(what) {
     return `webhook ${this.target} responded with ${what}, which is not followed because the entry would not arrive intact; use the final URL instead`;
   }
@@ -1639,10 +1782,86 @@ var SupabaseErrorAdapter = class {
     });
   }
 };
+
+// src/adapters/event-emitter-error-adapter.ts
+var DEFAULT_EVENT_NAME = "error-log";
+var EventEmitterErrorAdapter = class {
+  /** @throws {RangeError} if `options.eventName` is empty. */
+  constructor(emitter, options = {}) {
+    this.emitter = emitter;
+    this.eventName = options.eventName ?? DEFAULT_EVENT_NAME;
+    if (this.eventName === "") {
+      throw new RangeError(
+        "EventEmitterErrorAdapter: eventName must not be empty."
+      );
+    }
+    this.requireListener = options.requireListener ?? false;
+    this.prefix = options.prefix ?? DEFAULT_PREFIX;
+  }
+  async log(entry) {
+    try {
+      const record = {
+        id: resolveEntryId(entry),
+        ...serializeEntry(entry)
+      };
+      const delivered = this.emitter.emit(this.eventName, record);
+      if (this.requireListener && delivered === false) {
+        throw new Error(
+          `no listener is attached to "${this.eventName}", so nothing received the entry`
+        );
+      }
+      return { ok: true };
+    } catch (error) {
+      return reportFailure({
+        adapterName: "EventEmitterErrorAdapter",
+        prefix: this.prefix,
+        action: `to emit "${this.eventName}"`,
+        error
+      });
+    }
+  }
+};
+
+// src/adapters/websocket-error-adapter.ts
+var OPEN = 1;
+var STATE_NAMES = {
+  0: "still connecting",
+  1: "open",
+  2: "closing",
+  3: "closed"
+};
+var WebSocketErrorAdapter = class {
+  constructor(socket, options = {}) {
+    this.socket = socket;
+    this.prefix = options.prefix ?? DEFAULT_PREFIX;
+  }
+  async log(entry) {
+    try {
+      const state = this.socket.readyState;
+      if (state !== OPEN) {
+        throw new Error(
+          `the socket is ${STATE_NAMES[state] ?? `in unknown state ${String(state)}`} (readyState ${String(state)}), so the entry was not sent; connect or reconnect it first`
+        );
+      }
+      this.socket.send(
+        JSON.stringify({ id: resolveEntryId(entry), ...serializeEntry(entry) })
+      );
+      return { ok: true };
+    } catch (error) {
+      return reportFailure({
+        adapterName: "WebSocketErrorAdapter",
+        prefix: this.prefix,
+        action: "to send over the socket",
+        error
+      });
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CompositeErrorAdapter,
   ConsoleErrorAdapter,
+  EventEmitterErrorAdapter,
   FirestoreErrorAdapter,
   FlatFileErrorAdapter,
   IndexedDbErrorAdapter,
@@ -1655,6 +1874,7 @@ var SupabaseErrorAdapter = class {
   S3ErrorAdapter,
   SqliteErrorAdapter,
   SupabaseErrorAdapter,
+  WebSocketErrorAdapter,
   WebStorageErrorAdapter,
   WebhookErrorAdapter,
   buildCreateErrorLogTableSql,