@weatherboard/errors 0.1.0 → 0.2.0

package/README.md

@@ -8,8 +8,10 @@ Entry points:
 - `./next/client`: deferred browser initialization and `onRouterTransitionStart`. Buffers early errors and rejections, loading immediately on the first error; otherwise waits for load and idle. Breadcrumbs before SDK initialization are unavailable.
 - `./next/global-error`: `GlobalError` reports render failures and renders its required `children`; the product supplies the fallback document and design.
 - `./client`: `reportHandled(error, { where, extra })` for catches that show a banner or toast. Fingerprints use `where` and message. Never throws; before the deferred browser SDK loads, queues the error and its context and requests the SDK immediately. With no configured loader or a disabled SDK, it is a no-op. The `where` tag identifies the catch site.
+- `./http`: `refuse(status, message, { kind, where, context?, body?, headers? })` returns `{ error: message, ...body }`. Expected refusals add a breadcrumb; invariant refusals capture a grouped warning. `fail(message, cause, { where, status = 500, context?, body?, headers? })` captures the original exception and returns only the supplied public message/body. Both tolerate reporting failures and skip telemetry before SDK initialization. Context redacts sensitive keys, bearer strings, known token formats and email addresses.
 - `./noise`: shared patterns with their justifying issue ids.
-- `./verify`: `verifyErrors(appDirectory)` registers the product wiring test.
+- `./worker`: `withWorkerErrors`, `withDurableObjectErrors` and Worker `reportHandled`.
+- `./verify`: `verifyErrors(appDirectory)` or `verifyWorkerWiring(workerDirectory)` registers the product wiring test.
 
 The five configuration variables are `SENTRY_DSN` (server), `PUBLIC_SENTRY_DSN` (browser), `SENTRY_ORG`, `SENTRY_PROJECT`, and `SENTRY_AUTH_TOKEN` (secret, build only). The wrapper inlines only the public DSN. Reporting requires a DSN and `VERCEL_ENV=production` or `preview`; development and unset environments do not initialize. Release comes from `VERCEL_GIT_COMMIT_SHA`, never `NODE_ENV`. Tracing is off and default PII is disabled.
 
@@ -20,4 +22,39 @@ Wire a Next app in four files:
 3. In `instrumentation-client.ts`: export `{ onRouterTransitionStart }` from `@weatherboard/errors/next/client`.
 4. In the app's global error boundary, mark it `"use client"`, import `{ GlobalError }` from `@weatherboard/errors/next/global-error`, and render `<GlobalError error={error}><html><body>your fallback</body></html></GlobalError>`.
 
-Add a node:test file calling `verifyErrors` with the app directory. HTTP helpers are reserved for a future `./http` entry; Workers and React Native are outside this version.
+Add a node:test file calling `verifyErrors` with the app directory. React Native is outside this version. Never pass a private cause message as the public HTTP message. Extra body fields retain their existing wire shape; they are not telemetry context.
+
+## Cloudflare Workers
+
+Import from `@weatherboard/errors/worker`. Wrap the default handler with
+`withWorkerErrors(handler)`. Export each Durable Object as
+`const MyObject = withDurableObjectErrors(MyObjectImplementation)` and an instance
+type alias when bindings reference that type. Built-in handlers, alarms, WebSocket
+handlers and prototype RPC methods are instrumented by `@sentry/cloudflare`.
+`verifyWorkerWiring(dir)` checks the defaults, DO classes and direct SDK imports.
+
+Optional environment fields (extend `WorkerErrorEnv` in the Worker's typed Env):
+
+| Field | Purpose |
+| --- | --- |
+| `SENTRY_DSN` | Worker secret; absent means the original invocation/construction path runs without Sentry |
+| `SENTRY_ENVIRONMENT` | Explicit reporting environment |
+| `ENVIRONMENT` | Existing per-environment Worker var, used when the explicit field is absent |
+| `SENTRY_RELEASE` | Git SHA recorded by the deploy; takes precedence over version metadata |
+| `CF_VERSION_METADATA` | Cloudflare `version_metadata` binding; when `SENTRY_RELEASE` is absent, release uses `tag`, then `id` if untagged (a platform version ID, not a git SHA) |
+
+A Worker deployed per environment reads its own environment var. A Worker shared
+by every environment must take the decision from its caller through a trusted
+mapping, or treat absence as non-production; never infer production from the
+shared Worker's deployment. Unset environment becomes `development`. Reporting is
+enabled by a DSN; development is not promoted to production or silently discarded.
+No DSN leaves the handler's arguments, receiver, result and thrown errors unchanged.
+The wrapper selects the original handler at invocation time because Worker secrets
+are unavailable at module evaluation. DO construction similarly bypasses the SDK.
+
+Tracing is disabled (`tracesSampleRate: 0`), default PII is disabled
+(`sendDefaultPii: false`), and the SDK flushes via `waitUntil`; responses do not wait
+for reporting. In catches that recover, keep the existing log and call
+`reportHandled(error, { where, extra })` inside the instrumented invocation. It
+fingerprints by `where` and message and never throws. Only send scrubbed errors and
+safe extras: default PII settings do not scrub application-supplied exception text.

package/http.d.ts

@@ -0,0 +1,15 @@
+type Options = {
+    where: string;
+    context?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+    headers?: HeadersInit;
+};
+/** A valid refusal is a breadcrumb; an impossible refusal is a grouped warning. */
+export declare function refuse(status: number, message: string, options: Options & {
+    kind: "expected" | "invariant";
+}): Response;
+/** Report the original cause; only the public message and body are sent to the caller. */
+export declare function fail(message: string, cause: unknown, options: Options & {
+    status?: number;
+}): Response;
+export {};

package/http.js

@@ -0,0 +1,60 @@
+import * as SentryModule from "@sentry/nextjs";
+const Sentry = SentryModule.default ?? SentryModule;
+function scrub(value, seen = /* @__PURE__ */ new WeakSet(), depth = 0) {
+  if (typeof value === "string") return value.replace(/\bBearer\s+\S+/gi, "[redacted]").replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "[redacted]").replace(/\b(?:gh[pousr]_[\w]+|github_pat_[\w]+|sk-[\w-]+|eyJ[\w-]+\.[\w-]+\.[\w-]+)\b/g, "[redacted]");
+  if (value === null || typeof value !== "object") return value;
+  if (depth >= 8 || seen.has(value)) return "[redacted]";
+  seen.add(value);
+  if (Array.isArray(value)) return value.map((item) => scrub(item, seen, depth + 1));
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    /token|secret|password|authorization|cookie|email|api.?key|credential/i.test(key) ? "[redacted]" : scrub(item, seen, depth + 1)
+  ]));
+}
+function template(message) {
+  return String(scrub(message)).replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi, "<id>").replace(/\b[a-z]+_[a-z0-9-]+\b/gi, "<id>").replace(/\b[0-9a-f]{8,}\b/gi, "<id>").replace(/\d+/g, "<n>");
+}
+function response(message, status, options) {
+  try {
+    return Response.json({ error: message, ...options.body }, { status, headers: options.headers });
+  } catch {
+    return Response.json({ error: message }, { status: status >= 200 && status <= 599 && ![204, 205, 304].includes(status) ? status : 500 });
+  }
+}
+function refuse(status, message, options) {
+  try {
+    if (Sentry.isInitialized() && Sentry.isEnabled()) {
+      const extra = scrub(options.context);
+      const safeMessage = String(scrub(message));
+      if (options.kind === "expected") Sentry.addBreadcrumb({
+        category: "refuse",
+        level: "info",
+        message: safeMessage,
+        data: { ...extra, where: options.where, status }
+      });
+      else Sentry.captureMessage(safeMessage, {
+        level: "warning",
+        tags: { where: options.where },
+        extra,
+        fingerprint: ["refuse", options.where, template(message)]
+      });
+    }
+  } catch {
+  }
+  return response(message, status, options);
+}
+function fail(message, cause, options) {
+  try {
+    if (Sentry.isInitialized() && Sentry.isEnabled()) Sentry.captureException(cause, {
+      level: "error",
+      tags: { where: options.where },
+      extra: scrub(options.context)
+    });
+  } catch {
+  }
+  return response(message, options.status ?? 500, options);
+}
+export {
+  fail,
+  refuse
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@weatherboard/errors",
-  "version": "0.1.0",
-  "description": "Shared Next.js and browser error reporting for Weatherboard products.",
+  "version": "0.2.0",
+  "description": "Shared Next.js, browser, HTTP and Cloudflare Worker error reporting for Weatherboard products.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -10,7 +10,9 @@
   },
   "type": "module",
   "dependencies": {
-    "@sentry/nextjs": "10.75.0"
+    "@sentry/cloudflare": "10.75.0",
+    "@sentry/nextjs": "10.75.0",
+    "typescript": "~5.7.2"
   },
   "peerDependencies": {
     "next": "^16.0.0",
@@ -41,6 +43,10 @@
       "types": "./client.d.ts",
       "import": "./client.js"
     },
+    "./http": {
+      "types": "./http.d.ts",
+      "import": "./http.js"
+    },
     "./noise": {
       "types": "./noise.d.ts",
       "import": "./noise.js"
@@ -48,6 +54,10 @@
     "./verify": {
       "types": "./verify.d.ts",
       "import": "./verify.js"
+    },
+    "./worker": {
+      "types": "./worker.d.ts",
+      "import": "./worker.js"
     }
   },
   "files": [

package/verify.d.ts

@@ -2,3 +2,4 @@
 export declare function assertErrorWiring(appDirectory: string): void;
 /** Call from a product's node:test file with the absolute app directory. */
 export declare function verifyErrors(appDirectory: string): void;
+export { assertWorkerWiring, verifyWorkerWiring } from "./worker-verify.js";

package/verify.js

@@ -27,7 +27,10 @@ function assertErrorWiring(appDirectory) {
 function verifyErrors(appDirectory) {
   test("shared error reporting wiring", () => assertErrorWiring(appDirectory));
 }
+import { assertWorkerWiring, verifyWorkerWiring } from "./worker-verify.js";
 export {
   assertErrorWiring,
-  verifyErrors
+  assertWorkerWiring,
+  verifyErrors,
+  verifyWorkerWiring
 };

package/worker-verify.d.ts

@@ -0,0 +1,4 @@
+/** Inspect actual syntax so a commented-out wrapper cannot satisfy the guard. */
+export declare function assertWorkerWiring(dir: string): void;
+/** Call from each converted Worker's node:test suite. */
+export declare function verifyWorkerWiring(dir: string): void;

package/worker-verify.js

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { test } from "node:test";
+import ts from "typescript";
+function sources(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (["node_modules", ".git", "dist", "test-fixtures"].includes(entry.name)) return [];
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return sources(path);
+    return /\.[cm]?[jt]s$/.test(entry.name) && !/\.(test|spec)\./.test(entry.name) && !entry.name.endsWith(".d.ts") ? [path] : [];
+  });
+}
+function assertWorkerWiring(dir) {
+  let defaults = 0;
+  const classes = [];
+  const wrapped = /* @__PURE__ */ new Set();
+  for (const file of sources(dir)) {
+    const name = relative(dir, file);
+    const source = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+    const imports = /* @__PURE__ */ new Map();
+    const visit = (node) => {
+      if (ts.isStringLiteral(node) && node.text.startsWith("@sentry/")) {
+        const parent = node.parent;
+        if (ts.isImportDeclaration(parent) || ts.isExportDeclaration(parent) || ts.isCallExpression(parent)) {
+          assert.fail(`${name}: products never import @sentry/* directly`);
+        }
+      }
+      if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "@weatherboard/errors/worker") {
+        const bindings = node.importClause?.namedBindings;
+        if (bindings && ts.isNamedImports(bindings)) {
+          for (const binding of bindings.elements) imports.set(binding.name.text, binding.propertyName?.text ?? binding.name.text);
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(source);
+    const isWrapper = (expression, kind) => ts.isCallExpression(expression) && ts.isIdentifier(expression.expression) && imports.get(expression.expression.text) === kind;
+    for (const statement of source.statements) {
+      if (name.startsWith("src/") && ts.isExportAssignment(statement) && !statement.isExportEquals) {
+        defaults++;
+        assert.ok(isWrapper(statement.expression, "withWorkerErrors"), `${name}: default export must be wrapped with withWorkerErrors`);
+      }
+      if (ts.isClassDeclaration(statement) && statement.name) {
+        const base = statement.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword)?.types[0]?.expression;
+        if (base && ts.isIdentifier(base)) classes.push({ name: statement.name.text, base: base.text, file: name });
+      }
+      if (ts.isVariableStatement(statement) && statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+        for (const declaration of statement.declarationList.declarations) {
+          if (declaration.initializer && isWrapper(declaration.initializer, "withDurableObjectErrors")) {
+            const arg = declaration.initializer.arguments[0];
+            if (arg && ts.isIdentifier(arg)) wrapped.add(`${name}:${arg.text}`);
+          }
+        }
+      }
+    }
+  }
+  assert.ok(defaults > 0, "Worker must have a wrapped default export");
+  const durable = /* @__PURE__ */ new Set(["DurableObject", "Sandbox"]);
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const item of classes) if (durable.has(item.base) && !durable.has(item.name)) {
+      durable.add(item.name);
+      changed = true;
+    }
+  }
+  for (const item of classes) if (durable.has(item.base)) {
+    assert.ok(wrapped.has(`${item.file}:${item.name}`), `${item.file}: Durable Object ${item.name} must be instrumented with withDurableObjectErrors`);
+  }
+}
+function verifyWorkerWiring(dir) {
+  test("shared Worker error reporting wiring", () => assertWorkerWiring(dir));
+}
+export {
+  assertWorkerWiring,
+  verifyWorkerWiring
+};

package/worker.d.ts

@@ -0,0 +1,22 @@
+import { type CloudflareOptions } from "@sentry/cloudflare";
+import type { HandledContext } from "./client.js";
+/** Shared Workers must supply caller-derived environment explicitly; unset is development. */
+export interface WorkerErrorEnv {
+    SENTRY_DSN?: string;
+    SENTRY_ENVIRONMENT?: string;
+    ENVIRONMENT?: string;
+    SENTRY_RELEASE?: string;
+    CF_VERSION_METADATA?: {
+        id: string;
+        tag?: string;
+    };
+}
+type Options<E> = (env: E) => CloudflareOptions;
+export declare function workerErrorOptions(env: WorkerErrorEnv): CloudflareOptions;
+/** Select instrumentation per invocation, without modifying the original handler. */
+export declare function withWorkerErrors<H extends object>(handler: H, options?: Options<WorkerErrorEnv>): H;
+/** Preserve the original construction path when a DSN is absent. */
+export declare function withDurableObjectErrors<C extends new (...args: never[]) => object>(object: C, options?: Options<WorkerErrorEnv>): C;
+/** Report inside an instrumented invocation's catch; logging stays at the call site. */
+export declare function reportHandled(error: unknown, context: HandledContext): void;
+export {};

package/worker.js

@@ -0,0 +1,70 @@
+import {
+  captureException,
+  getClient,
+  instrumentDurableObjectWithSentry,
+  withSentry,
+  wrapRequestHandler
+} from "@sentry/cloudflare";
+function workerErrorOptions(env) {
+  return {
+    dsn: env.SENTRY_DSN,
+    environment: env.SENTRY_ENVIRONMENT || env.ENVIRONMENT || "development",
+    release: env.SENTRY_RELEASE || env.CF_VERSION_METADATA?.tag || env.CF_VERSION_METADATA?.id,
+    tracesSampleRate: 0,
+    sendDefaultPii: false,
+    // On SDK 10.75, enableRpcTracePropagation alone captures only calls carrying
+    // SDK metadata. Manager-side callers do not carry it; instrument all methods.
+    instrumentPrototypeMethods: true
+  };
+}
+function withWorkerErrors(handler, options = workerErrorOptions) {
+  let instrumented;
+  const methods = /* @__PURE__ */ new Map();
+  const wrapped = new Proxy(handler, {
+    get(target, key, receiver) {
+      const original = Reflect.get(target, key, receiver);
+      if (typeof original !== "function") return original;
+      if (!methods.has(key)) methods.set(key, new Proxy(original, {
+        apply(method, thisArg, args) {
+          const receiver2 = thisArg === wrapped ? handler : thisArg;
+          const env = args[1];
+          if (!env?.SENTRY_DSN) return Reflect.apply(method, receiver2, args);
+          if (key === "fetch" && args[0] instanceof Request && ["HEAD", "OPTIONS"].includes(args[0].method)) {
+            return wrapRequestHandler({ options: options(env), request: args[0], context: args[2] }, () => Reflect.apply(method, receiver2, args));
+          }
+          instrumented ??= withSentry(options, { ...handler });
+          const captured = Reflect.get(instrumented, key);
+          return Reflect.apply(typeof captured === "function" ? captured : method, receiver2, args);
+        }
+      }));
+      return methods.get(key);
+    }
+  });
+  return wrapped;
+}
+function withDurableObjectErrors(object, options = workerErrorOptions) {
+  let instrumented;
+  return new Proxy(object, {
+    construct(target, args, newTarget) {
+      const env = args[1];
+      if (!env?.SENTRY_DSN) return Reflect.construct(target, args, newTarget);
+      instrumented ??= instrumentDurableObjectWithSentry(options, object);
+      return Reflect.construct(instrumented, args, newTarget);
+    }
+  });
+}
+function reportHandled(error, context) {
+  try {
+    const client = getClient();
+    if (!client?.getOptions().dsn || client.getOptions().enabled === false) return;
+    const message = error instanceof Error ? error.message : String(error);
+    captureException(error, { fingerprint: [context.where, message], extra: context.extra });
+  } catch {
+  }
+}
+export {
+  reportHandled,
+  withDurableObjectErrors,
+  withWorkerErrors,
+  workerErrorOptions
+};