@forumone/throughline-core 0.9.0 → 0.10.0

package/dist/observability/report.d.ts

@@ -0,0 +1,175 @@
+import type { Logger } from '@forumone/throughline-plugin-contract';
+/** Request headers copied into a report unless the caller names its own list. */
+export declare const DEFAULT_REPORTED_HEADERS: readonly string[];
+/**
+ * Headers that are never copied, even when a caller lists them. Each one is,
+ * or routinely carries, a credential. `x-forwarded-for` is here too: the whole
+ * address is personal data, and a report carries only its prefix.
+ */
+export declare const NEVER_REPORTED_HEADERS: readonly string[];
+/** The environment variable the default reporter reads. */
+export declare const ERROR_WEBHOOK_URL_ENV = "ERROR_WEBHOOK_URL";
+/** Which deployment produced a report, so it is attributable after a rollback. */
+export interface ReportDeployment {
+    environment?: string;
+    commit?: string;
+}
+/** An unhandled error in a request, as `instrumentation.ts` sees one. */
+export interface RequestErrorReport {
+    kind: 'request';
+    /** ISO 8601, so a report is orderable without trusting the receiver's clock. */
+    at: string;
+    message: string;
+    name?: string;
+    stack?: string;
+    /** React's error digest — the only handle on a minified Server Component error. */
+    digest?: string;
+    request: {
+        path: string;
+        method: string;
+        /** The allowlisted headers that were present, lower-cased. */
+        headers: Record<string, string>;
+        /** The client address reduced to a /16 (IPv4) or /64 (IPv6). */
+        clientPrefix?: string;
+    };
+    context: {
+        routePath?: string;
+        routeType?: string;
+        renderSource?: string;
+        revalidateReason?: string;
+    };
+    deployment: ReportDeployment;
+}
+/** A background job that ran out of retries. */
+export interface JobFailureReport {
+    kind: 'job';
+    at: string;
+    /** The function that failed, e.g. an Inngest function id. `'unknown'` if nothing named it. */
+    functionId: string;
+    /** The run's id — the handle for finding it in the job runner's dashboard. */
+    runId?: string;
+    /** The event that triggered the run, so a failure is traceable to a cause. */
+    triggerEvent?: string;
+    message: string;
+    name?: string;
+    stack?: string;
+    deployment: ReportDeployment;
+}
+/** A healthcheck run in which at least one check failed. */
+export interface HealthcheckFailureReport {
+    kind: 'healthcheck';
+    at: string;
+    functionId: string;
+    failed: Array<{
+        name: string;
+        details?: string;
+    }>;
+    deployment: ReportDeployment;
+}
+export type ErrorReport = RequestErrorReport | JobFailureReport | HealthcheckFailureReport;
+/** Request headers as Next hands them over, or a Fetch `Headers`. */
+export type ReportableHeaders = Record<string, string | string[] | undefined> | {
+    get(name: string): string | null;
+};
+export interface BuildRequestErrorReportOptions {
+    /** Headers to copy. Default: {@link DEFAULT_REPORTED_HEADERS}. {@link NEVER_REPORTED_HEADERS} are dropped regardless. */
+    headers?: readonly string[];
+    /** Default: read from the environment — see {@link currentDeployment}. */
+    deployment?: ReportDeployment;
+    now?: Date;
+}
+/**
+ * The deployment a report came from, read from the environment.
+ *
+ * `VERCEL_ENV` before `NODE_ENV`, because on Vercel a preview deployment is
+ * `NODE_ENV=production` too, and "production or somebody's branch" is the
+ * first question about an alert. Off Vercel, `NODE_ENV` is what there is.
+ */
+export declare function currentDeployment(env?: NodeJS.ProcessEnv): ReportDeployment;
+/**
+ * An IPv4 or IPv6 address reduced to a prefix: enough to tell one host's burst
+ * from many readers hitting the same fault, and not enough to identify anyone.
+ * `x-forwarded-for` may carry a list; only the first entry is the client.
+ */
+export declare function clientPrefix(forwardedFor: string | undefined): string | undefined;
+/**
+ * Build a report for an error captured during a request. Pure, so the
+ * redaction is testable without a server.
+ *
+ * `error` is `unknown` because Next types it that way and means it: the value
+ * reaching `onRequestError` may have been processed by React rather than being
+ * the instance that was thrown, which is why `digest` is read separately.
+ */
+export declare function buildRequestErrorReport(error: unknown, request: {
+    path: string;
+    method: string;
+    headers: ReportableHeaders;
+}, context?: object, options?: BuildRequestErrorReportOptions): RequestErrorReport;
+export interface BuildJobFailureReportInput {
+    /** The failing function. Omitted or empty is reported as `'unknown'` rather than dropped. */
+    functionId?: string | undefined;
+    runId?: string | undefined;
+    triggerEvent?: string | undefined;
+    error: unknown;
+}
+/**
+ * Build a report for a job that ran out of retries.
+ *
+ * The stack is included: this goes to a webhook the team owns, where a stack
+ * is the most useful field in it. The job-failures collection, which admins
+ * read through the CMS, stores the message and not the stack.
+ */
+export declare function buildJobFailureReport(input: BuildJobFailureReportInput, options?: {
+    deployment?: ReportDeployment;
+    now?: Date;
+}): JobFailureReport;
+/** Build a report for a healthcheck run with failing checks. */
+export declare function buildHealthcheckFailureReport(failures: ReadonlyArray<{
+    name: string;
+    details?: string | undefined;
+}>, options?: {
+    functionId?: string;
+    deployment?: ReportDeployment;
+    now?: Date;
+}): HealthcheckFailureReport;
+/**
+ * One line describing a report, for a receiver that renders rather than
+ * indexes. Reads the report structurally, so a site's own report shapes get a
+ * sensible line too.
+ */
+export declare function summariseReport(report: unknown): string;
+/**
+ * Whether reports go anywhere, as a sentence for a boot-time log line. A
+ * sentence rather than a boolean because "off because this is a laptop" and
+ * "off because somebody forgot in production" look identical otherwise.
+ */
+export declare function describeErrorReporting(url?: string | undefined): string;
+export interface ErrorReporterOptions {
+    /**
+     * Where to POST. Default: `process.env.ERROR_WEBHOOK_URL`, read on every
+     * call so a reporter built before the environment loads still finds it.
+     * Unset or empty means reports are not delivered.
+     */
+    url?: string | undefined;
+    /** Extra headers sent *to the webhook*, e.g. an `authorization` the receiver expects. */
+    webhookHeaders?: Record<string, string>;
+    /** Abort the POST after this long. Default: 3000ms — shorter than any function timeout. */
+    timeoutMs?: number;
+    /** Where a failed delivery is logged. Default: the console logger. */
+    logger?: Logger;
+    /** Injected for tests. Default: the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** Posts a report. Never throws, never rejects. */
+export type ErrorReporter = (report: unknown) => Promise<void>;
+/**
+ * A reporter that POSTs each report as JSON, with a `text` summary added.
+ *
+ * A delivery that fails — a refused connection, a timeout, a non-2xx — is
+ * logged as a warning and otherwise swallowed. It is never rethrown: see the
+ * note at the top of this file.
+ */
+export declare function createErrorReporter(options?: ErrorReporterOptions): ErrorReporter;
+/** The default reporter: `ERROR_WEBHOOK_URL`, a 3s timeout, the console logger. */
+export declare const reportError: ErrorReporter;
+//# sourceMappingURL=report.d.ts.map

package/dist/observability/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/observability/report.ts"],"names":[],"mappings":"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"}

package/dist/observability/report.js

@@ -0,0 +1,274 @@
+import { defaultLogger } from '../logger/index.js';
+/*
+What an error looks like when it leaves the application, and how it leaves.
+
+Provider-agnostic on purpose. Which error tracker a site pays for is the site's
+decision, so this defines the *shape* of a report and posts it to whatever URL
+it is given — a log drain, an alerting endpoint, a Slack incoming webhook, a
+small proxy in front of Sentry. Swapping in an SDK later replaces the reporter
+and nothing that builds reports.
+
+Three rules hold everywhere in this file:
+
+- **Nothing here throws.** A reporter runs because something already went
+  wrong. One that throws turns a handled error into an unhandled one, and in an
+  Inngest `onFailure` handler it puts the run back in the retry queue for a
+  reason that has nothing to do with the original fault.
+- **Request headers are an allowlist.** Next's `onRequestError` hands over the
+  request's headers entire, and those include `cookie` — on an admin's request,
+  a live Payload session. A report that copied headers wholesale would post a
+  credential to a third party. A handful of headers that are never secret are
+  copied, and a short list that always is a credential can never be copied,
+  whatever a caller passes.
+- **Every report has a `text`.** Slack's incoming webhooks refuse a body
+  without one, and a delivery failure is swallowed here by design — so a Slack
+  URL without it would read as configured and deliver nothing. Other receivers
+  ignore the extra key.
+*/
+/** Request headers copied into a report unless the caller names its own list. */
+export const DEFAULT_REPORTED_HEADERS = [
+    'x-request-id',
+    'x-vercel-id',
+    'user-agent',
+    'referer',
+];
+/**
+ * Headers that are never copied, even when a caller lists them. Each one is,
+ * or routinely carries, a credential. `x-forwarded-for` is here too: the whole
+ * address is personal data, and a report carries only its prefix.
+ */
+export const NEVER_REPORTED_HEADERS = [
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
+    'x-api-key',
+    'x-forwarded-for',
+];
+/** The environment variable the default reporter reads. */
+export const ERROR_WEBHOOK_URL_ENV = 'ERROR_WEBHOOK_URL';
+const DEFAULT_TIMEOUT_MS = 3_000;
+/**
+ * The deployment a report came from, read from the environment.
+ *
+ * `VERCEL_ENV` before `NODE_ENV`, because on Vercel a preview deployment is
+ * `NODE_ENV=production` too, and "production or somebody's branch" is the
+ * first question about an alert. Off Vercel, `NODE_ENV` is what there is.
+ */
+export function currentDeployment(env = process.env) {
+    const environment = nonEmpty(env['VERCEL_ENV']) ?? nonEmpty(env['NODE_ENV']);
+    const commit = nonEmpty(env['VERCEL_GIT_COMMIT_SHA']);
+    return {
+        ...(environment ? { environment } : {}),
+        ...(commit ? { commit: commit.slice(0, 12) } : {}),
+    };
+}
+/**
+ * An IPv4 or IPv6 address reduced to a prefix: enough to tell one host's burst
+ * from many readers hitting the same fault, and not enough to identify anyone.
+ * `x-forwarded-for` may carry a list; only the first entry is the client.
+ */
+export function clientPrefix(forwardedFor) {
+    if (!forwardedFor)
+        return undefined;
+    const first = forwardedFor.split(',')[0]?.trim();
+    if (!first)
+        return undefined;
+    if (first.includes(':')) {
+        const groups = first.split(':').filter(Boolean).slice(0, 4);
+        return groups.length > 0 ? `${groups.join(':')}::/64` : undefined;
+    }
+    const octets = first.split('.');
+    return octets.length === 4 ? `${octets[0]}.${octets[1]}.0.0/16` : undefined;
+}
+/**
+ * Build a report for an error captured during a request. Pure, so the
+ * redaction is testable without a server.
+ *
+ * `error` is `unknown` because Next types it that way and means it: the value
+ * reaching `onRequestError` may have been processed by React rather than being
+ * the instance that was thrown, which is why `digest` is read separately.
+ */
+export function buildRequestErrorReport(error, request, context = {}, options = {}) {
+    const prefix = clientPrefix(headerValue(request.headers, 'x-forwarded-for'));
+    const headers = {};
+    for (const name of allowedHeaders(options.headers)) {
+        const value = headerValue(request.headers, name);
+        if (value)
+            headers[name] = value;
+    }
+    const routeContext = {};
+    for (const key of ['routePath', 'routeType', 'renderSource', 'revalidateReason']) {
+        const value = context[key];
+        if (typeof value === 'string')
+            routeContext[key] = value;
+    }
+    const digest = typeof error === 'object' && error !== null && 'digest' in error
+        ? String(error.digest)
+        : undefined;
+    return {
+        kind: 'request',
+        at: (options.now ?? new Date()).toISOString(),
+        ...describeError(error),
+        ...(digest ? { digest } : {}),
+        request: {
+            path: request.path,
+            method: request.method,
+            headers,
+            ...(prefix ? { clientPrefix: prefix } : {}),
+        },
+        context: routeContext,
+        deployment: options.deployment ?? currentDeployment(),
+    };
+}
+/**
+ * Build a report for a job that ran out of retries.
+ *
+ * The stack is included: this goes to a webhook the team owns, where a stack
+ * is the most useful field in it. The job-failures collection, which admins
+ * read through the CMS, stores the message and not the stack.
+ */
+export function buildJobFailureReport(input, options = {}) {
+    return {
+        kind: 'job',
+        at: (options.now ?? new Date()).toISOString(),
+        functionId: nonEmpty(input.functionId) ?? 'unknown',
+        ...(nonEmpty(input.runId) ? { runId: input.runId } : {}),
+        ...(nonEmpty(input.triggerEvent) ? { triggerEvent: input.triggerEvent } : {}),
+        ...describeError(input.error),
+        deployment: options.deployment ?? currentDeployment(),
+    };
+}
+/** Build a report for a healthcheck run with failing checks. */
+export function buildHealthcheckFailureReport(failures, options = {}) {
+    return {
+        kind: 'healthcheck',
+        at: (options.now ?? new Date()).toISOString(),
+        functionId: options.functionId ?? 'healthcheck',
+        failed: failures.map((failure) => ({
+            name: failure.name,
+            ...(failure.details ? { details: failure.details } : {}),
+        })),
+        deployment: options.deployment ?? currentDeployment(),
+    };
+}
+/**
+ * One line describing a report, for a receiver that renders rather than
+ * indexes. Reads the report structurally, so a site's own report shapes get a
+ * sensible line too.
+ */
+export function summariseReport(report) {
+    const row = (typeof report === 'object' && report !== null ? report : {});
+    const deployment = (row['deployment'] ?? {});
+    const environment = nonEmpty(deployment['environment']) ?? 'unknown environment';
+    const kind = nonEmpty(row['kind']) ?? 'error';
+    const failed = Array.isArray(row['failed'])
+        ? row['failed'].map((f) => String(f.name)).join(', ')
+        : undefined;
+    const headline = nonEmpty(row['message']) ?? (failed ? `failing: ${failed}` : undefined) ?? 'no message';
+    const request = (row['request'] ?? {});
+    const path = nonEmpty(request['path']);
+    const where = nonEmpty(row['functionId']) ??
+        (path ? `${nonEmpty(request['method']) ?? 'GET'} ${path}` : undefined);
+    return `[${environment}] ${kind}: ${headline}${where ? ` — ${where}` : ''}`;
+}
+/**
+ * Whether reports go anywhere, as a sentence for a boot-time log line. A
+ * sentence rather than a boolean because "off because this is a laptop" and
+ * "off because somebody forgot in production" look identical otherwise.
+ */
+export function describeErrorReporting(url = readWebhookUrl()) {
+    if (!url || url.trim() === '') {
+        return `error reporting: OFF (${ERROR_WEBHOOK_URL_ENV} unset) — errors reach the log only`;
+    }
+    try {
+        return `error reporting: on, to ${new URL(url).host}`;
+    }
+    catch {
+        return `error reporting: MISCONFIGURED (${ERROR_WEBHOOK_URL_ENV} is not a URL) — errors reach the log only`;
+    }
+}
+/**
+ * A reporter that POSTs each report as JSON, with a `text` summary added.
+ *
+ * A delivery that fails — a refused connection, a timeout, a non-2xx — is
+ * logged as a warning and otherwise swallowed. It is never rethrown: see the
+ * note at the top of this file.
+ */
+export function createErrorReporter(options = {}) {
+    const logger = options.logger ?? defaultLogger;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return async function deliver(report) {
+        try {
+            const url = (options.url ?? readWebhookUrl())?.trim();
+            if (!url)
+                return;
+            const text = summariseReport(report);
+            // A non-object report is still delivered, wrapped, rather than dropped.
+            const body = typeof report === 'object' && report !== null
+                ? { text, ...report }
+                : { text, report };
+            const doFetch = options.fetch ?? fetch;
+            const response = await doFetch(url, {
+                method: 'POST',
+                headers: { ...options.webhookHeaders, 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                // A serverless function may be frozen once its response is sent; a
+                // report that has not left by then never does.
+                keepalive: true,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!response.ok) {
+                logger.warn('Error report was not accepted', { status: response.status, summary: text });
+            }
+        }
+        catch (deliveryError) {
+            try {
+                logger.warn('Error report delivery failed', { error: String(deliveryError) });
+            }
+            catch {
+                // A logger that throws is the last thing that can go wrong here.
+            }
+        }
+    };
+}
+/** The default reporter: `ERROR_WEBHOOK_URL`, a 3s timeout, the console logger. */
+export const reportError = createErrorReporter();
+function readWebhookUrl() {
+    return typeof process === 'undefined' ? undefined : process.env[ERROR_WEBHOOK_URL_ENV];
+}
+function allowedHeaders(requested) {
+    const never = new Set(NEVER_REPORTED_HEADERS);
+    return (requested ?? DEFAULT_REPORTED_HEADERS)
+        .map((name) => name.toLowerCase())
+        .filter((name) => !never.has(name));
+}
+function headerValue(headers, name) {
+    let raw;
+    if (typeof headers.get === 'function') {
+        raw = headers.get(name);
+    }
+    else {
+        const record = headers;
+        raw = record[name] ?? Object.entries(record).find(([key]) => key.toLowerCase() === name)?.[1];
+    }
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return nonEmpty(value);
+}
+function describeError(error) {
+    if (error instanceof Error) {
+        return {
+            message: error.message || String(error),
+            ...(error.name ? { name: error.name } : {}),
+            ...(error.stack ? { stack: error.stack } : {}),
+        };
+    }
+    if (typeof error === 'object' && error !== null && 'message' in error) {
+        return { message: String(error.message) };
+    }
+    return { message: String(error) };
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+//# sourceMappingURL=report.js.map

package/dist/observability/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/observability/report.ts"],"names":[],"mappings":"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"}

package/dist/observability/writer.d.ts

@@ -0,0 +1,24 @@
+import type { Payload } from 'payload';
+import type { Logger } from '@forumone/throughline-plugin-contract';
+import { type HealthcheckFailureReport, type JobFailureReport } from './report.js';
+export interface JobFailureWriterOptions {
+    payload: Payload;
+    collectionSlug?: string | undefined;
+    logger?: Logger | undefined;
+}
+/** Records one failure. Never throws, never rejects. */
+export type JobFailureWriter = (report: JobFailureReport | HealthcheckFailureReport) => Promise<void>;
+/**
+ * Returns a writer that turns a failure report into a `job-failures` row.
+ *
+ * It never throws: it runs inside a failure handler, and a throw there is
+ * retried by the job runner — a retry storm about the recorder while the
+ * original failure goes unrecorded. A write that fails is logged at `error`
+ * **with the failure's own summary and message**, so the one thing this
+ * writer exists to keep is never lost silently, only demoted to the log.
+ *
+ * The stack is not stored. Rows are readable through the admin, and a stack
+ * names file paths; the webhook report carries it instead.
+ */
+export declare function createJobFailureWriter(options: JobFailureWriterOptions): JobFailureWriter;
+//# sourceMappingURL=writer.d.ts.map

package/dist/observability/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/observability/writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uCAAuC,CAAA;AAGnE,OAAO,EAAmB,KAAK,wBAAwB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnG,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAED,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG,CAC7B,MAAM,EAAE,gBAAgB,GAAG,wBAAwB,KAChD,OAAO,CAAC,IAAI,CAAC,CAAA;AAElB;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAsBzF"}

package/dist/observability/writer.js

@@ -0,0 +1,72 @@
+import { defaultLogger } from '../logger/index.js';
+import { DEFAULT_JOB_FAILURES_SLUG } from './collection.js';
+import { summariseReport } from './report.js';
+/**
+ * Returns a writer that turns a failure report into a `job-failures` row.
+ *
+ * It never throws: it runs inside a failure handler, and a throw there is
+ * retried by the job runner — a retry storm about the recorder while the
+ * original failure goes unrecorded. A write that fails is logged at `error`
+ * **with the failure's own summary and message**, so the one thing this
+ * writer exists to keep is never lost silently, only demoted to the log.
+ *
+ * The stack is not stored. Rows are readable through the admin, and a stack
+ * names file paths; the webhook report carries it instead.
+ */
+export function createJobFailureWriter(options) {
+    const { payload, collectionSlug = DEFAULT_JOB_FAILURES_SLUG } = options;
+    const logger = options.logger ?? defaultLogger;
+    return async function recordJobFailure(report) {
+        let data;
+        try {
+            data = toRow(report);
+            await payload.create({ collection: collectionSlug, data });
+        }
+        catch (writeError) {
+            try {
+                logger.error('Job failure write failed', {
+                    error: String(writeError),
+                    collection: collectionSlug,
+                    summary: data?.['summary'] ?? safeSummary(report),
+                    message: data?.['message'],
+                });
+            }
+            catch {
+                // Nothing left to tell.
+            }
+        }
+    };
+}
+function toRow(report) {
+    const base = {
+        createdAt: report.at,
+        kind: report.kind,
+        source: report.functionId,
+        summary: summariseReport(report).slice(0, 500),
+        ...(report.deployment.environment ? { environment: report.deployment.environment } : {}),
+        ...(report.deployment.commit ? { commit: report.deployment.commit } : {}),
+    };
+    if (report.kind === 'healthcheck') {
+        return {
+            ...base,
+            message: `${report.failed.length} check(s) failed: ${report.failed.map((f) => f.name).join(', ')}`,
+            details: report.failed,
+        };
+    }
+    return {
+        ...base,
+        message: report.message,
+        ...(report.name ? { errorName: report.name } : {}),
+        ...(report.runId ? { runId: report.runId } : {}),
+        ...(report.triggerEvent ? { triggerEvent: report.triggerEvent } : {}),
+    };
+}
+function safeSummary(report) {
+    try {
+        return summariseReport(report);
+    }
+    catch {
+        return '(unsummarisable failure report)';
+    }
+}
+//# sourceMappingURL=writer.js.map

package/dist/observability/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/observability/writer.ts"],"names":[],"mappings":"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"}