@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/client-error-report.d.ts

@@ -0,0 +1,301 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import '@aglyn/shared-util-fbserver';
+import { type BeaconCheck } from '@aglyn/aglyn/server';
+export interface ClientErrorEvent {
+    kind: string;
+    message: string;
+    stack?: string;
+    source?: string;
+    line?: number;
+    url?: string;
+}
+/**
+ * The events in a posted payload, clamped and capped. Anything malformed is
+ * simply dropped — this endpoint never argues with a browser — and so is an
+ * error none of our code threw (see {@link isForeignOnlyStack}).
+ */
+export declare function parseClientErrorEvents(payload: unknown): ClientErrorEvent[];
+/** The log the beacon writes; the alert policy and any triage query key on it. */
+export declare const CLIENT_ERROR_LOG_ID = "client-errors";
+/**
+ * The admin credential and project the beacon writes under.
+ *
+ * Extracted (AGL-1923) so the heartbeat below mints its token through the
+ * SAME path the reporter does. That sharing is the whole value of the
+ * heartbeat: the failures it exists to catch — an expired service-account
+ * key, a revoked `logging.logEntries.create`, an exhausted Logging quota —
+ * are environmental, and a heartbeat that acquired its credential some other
+ * way could report healthy while every real report was being dropped.
+ *
+ * Returns null when either half is missing; the caller decides what that
+ * means (the reporter drops the batch, the heartbeat reports degraded).
+ *
+ * EXPORTED for the Vercel log-drain receiver (AGL-1921, third arm), which
+ * writes to `vercel-runtime` through this same credential for the same
+ * reason the heartbeat does: the failures that would silence the drain are
+ * the environmental ones AGL-1923's heartbeat already probes, and it probes
+ * them through exactly this path. A receiver that minted its own token would
+ * need its own dead-man's switch.
+ */
+export declare function beaconLoggingTarget(): Promise<{
+    token: string;
+    projectId: string;
+} | null>;
+/** The credential, plus WHY there isn't one when there isn't. */
+export interface BeaconTargetResolution {
+    target: {
+        token: string;
+        projectId: string;
+    } | null;
+    /** Set only when `target` is null. */
+    code?: 'no-credential' | 'credential-unavailable';
+}
+/**
+ * The same resolution, saying which of two very different things went wrong
+ * (AGL-2713).
+ *
+ * `no-credential` used to cover both, and the collapse is what made
+ * `/api/health/error-beacon` cry wolf: one of the two is permanent and one is
+ * a cold lambda's first outbound connection.
+ *
+ * - **`no-credential`** — there is no admin app, or it has no project, or it
+ *   has no credential object. `initializeApp` runs at module load and is
+ *   guarded on `FIREBASE_PRIVATE_KEY` + `FIREBASE_CLIENT_EMAIL` +
+ *   `NEXT_PUBLIC_FIREBASE_PROJECT_ID`, so this is a STATIC fact about the
+ *   deployment's environment: it cannot heal on the next request, and every
+ *   browser error is being dropped for as long as it holds. Red immediately —
+ *   which is exactly what the remedy text on the staff board already says
+ *   (`no-credential` is the deployment `FIREBASE_*` env).
+ * - **`credential-unavailable`** — the app and the certificate are both there
+ *   and `getAccessToken()` did not produce a token on THIS attempt. That is a
+ *   JWT-bearer exchange against `oauth2.googleapis.com`, and on a cold
+ *   instance it is the first outbound TLS handshake the sandbox has ever made.
+ *   Nothing was decided, so nothing about the beacon has been established.
+ */
+export declare function resolveBeaconLoggingTarget(): Promise<BeaconTargetResolution>;
+/**
+ * Forwards events under the admin service account — via Cloud LOGGING, not
+ * the Error Reporting `events:report` API, and the transport is the point:
+ * a log entry whose payload carries the `ReportedErrorEvent` `@type` is
+ * ingested by Error Reporting automatically (grouping, the Error Reporting
+ * console, version tracking), while ALSO being a real log entry that a
+ * Cloud Monitoring log-match alert policy can page on — `events:report`
+ * produces no log entry and nothing standard to alert from. One batched
+ * write per request instead of one call per event is the bonus.
+ *
+ * Returns how many events were written; failures are logged (one line) and
+ * swallowed.
+ */
+export declare function reportClientErrors(events: readonly ClientErrorEvent[], options: {
+    service: string;
+}): Promise<number>;
+/**
+ * The log the SERVER half writes to (AGL-1921).
+ *
+ * DELIBERATELY NOT `client-errors`. The `Client error beacon` policy is a
+ * log-match on that log id, and a server 5xx is a different incident with a
+ * different first move — a browser error is one visitor's broken render, a
+ * 500 rate is every visitor's. Merging the streams would make the existing
+ * policy fire for both and force triage to start by asking which it was.
+ * A sibling log id also lets the counter this whole issue is about key on
+ * server errors ALONE.
+ */
+export declare const SERVER_ERROR_LOG_ID = "server-errors";
+/**
+ * One server-side error, as `onRequestError` sees it.
+ *
+ * `route` is the route PATTERN (`/[host]/[scheme]/[[...slug]]`), never the resolved
+ * path: the resolved path carries org slugs, document ids and whatever a
+ * visitor typed into a URL, and this payload leaves our origin for a Google
+ * log. The pattern is what you group and alert on anyway.
+ */
+export interface ServerErrorEvent {
+    message: string;
+    stack?: string;
+    route?: string;
+    method?: string;
+    routeType?: string;
+    digest?: string;
+}
+/** What happened to one `reportServerError` call, for tests and callers. */
+export type ServerErrorOutcome = 'written' | 'suppressed' | 'dropped';
+/**
+ * Forwards ONE server-side error to Cloud Logging under the admin credential.
+ *
+ * This is AGL-1921's fallback arm, and it is a fallback on purpose: it cannot
+ * see an error that kills the process before the handler runs, nor a
+ * platform-level 5xx that never reaches our code at all. A Vercel log drain
+ * would see both. What this does buy is the case that matters most and is
+ * most likely — our own route handlers and renders throwing — reported
+ * through a transport that already works, on an account we already pay for.
+ * `docs/UPTIME_AND_SLA.md` carries the blind spots in writing, because
+ * partial visibility whose gaps are documented beats none.
+ *
+ * It shares `beaconLoggingTarget` with the client reporter deliberately: that
+ * makes AGL-1923's heartbeat a dead-man's switch for THIS path too. The
+ * failures that would silence server-error reporting — expired key, revoked
+ * `logging.logEntries.create`, exhausted quota — are the same environmental
+ * ones the heartbeat already probes, and it probes them through this exact
+ * credential.
+ *
+ * Fail-soft and never throws: this runs inside `onRequestError`, so throwing
+ * here would turn an observed error into a second one during an incident.
+ */
+export declare function reportServerError(event: ServerErrorEvent, options: {
+    service: string;
+}): Promise<ServerErrorOutcome>;
+/**
+ * The log the beacon's heartbeat is written to (AGL-1923).
+ *
+ * DELIBERATELY NOT `client-errors`. The `Client error beacon` alert policy is
+ * a log-match on `logName="…/client-errors" AND severity>=ERROR`, so a
+ * heartbeat written there would page the on-call owner on every probe — building the
+ * alert-fatigue mechanism the heartbeat exists to protect against. A separate
+ * log id at INFO keeps the two streams from ever being confused, and keeps
+ * the payload out of Error Reporting (which ingests on the
+ * `ReportedErrorEvent` `@type`, absent here on purpose).
+ */
+export declare const BEACON_HEARTBEAT_LOG_ID = "client-error-beacon-heartbeat";
+/** What a heartbeat attempt proved, for the health verdict to reduce. */
+export interface BeaconHeartbeatResult {
+    /** Did the entry actually reach Cloud Logging? */
+    ok: boolean;
+    /** A stable code on failure — never a raw error message. */
+    code?: string;
+}
+/**
+ * Write one heartbeat entry through the beacon's own transport (AGL-1923).
+ *
+ * ## Why this exists
+ *
+ * `reportClientErrors` is fail-soft by design and must stay that way — it may
+ * never turn an observed error into a served one. But every one of its
+ * failure paths ends in a `console.warn` to the Vercel runtime log, which
+ * retains about an hour and drains nowhere (AGL-1799). So the beacon can fail
+ * completely and the only readings anyone has are "Error Reporting shows zero
+ * errors" and "the log-match policy is silent" — which are exactly the
+ * readings a clean launch produces. **A dead beacon is indistinguishable from
+ * zero errors.**
+ *
+ * A log-match policy can only ever report presence. The fix is a signal whose
+ * ABSENCE is detectable, and the cheapest one that needs no new vendor is a
+ * write that a health endpoint can grade synchronously: this returns whether
+ * the write landed, `/api/health/error-beacon` turns that into the 200/503
+ * contract the sibling health checks already speak, and the existing uptime
+ * check + alert + email path becomes the listener. The uptime probe is what
+ * winds the dead-man's switch, so there is no cron to forget.
+ *
+ * ## What it can and cannot prove
+ *
+ * It proves the credential mints, the IAM grant still covers
+ * `logging.logEntries.create`, the Logging API answers, and the quota is not
+ * exhausted — the whole environmental failure class AGL-1923 names. It does
+ * NOT prove a browser can reach `/api/errors`, and it does not prove the
+ * payload shape Error Reporting ingests on, because it deliberately does not
+ * write that shape.
+ *
+ * ## Clearing
+ *
+ * The condition it raises is an EVENT, not a state: the next successful write
+ * clears it, within one probe TTL. Nothing here can latch (AGL-1843).
+ *
+ * Never throws. A heartbeat that could 500 a health endpoint would be a
+ * monitoring probe that causes the outage it reports.
+ */
+export declare function writeBeaconHeartbeat(options: {
+    service: string;
+}): Promise<BeaconHeartbeatResult>;
+/**
+ * How long the probe waits before its second attempt (AGL-2713).
+ *
+ * Long enough for a JWT-bearer exchange that lost its first connection to get
+ * another one, short enough that it is invisible next to a probe already
+ * budgeted at 4s for the Logging write. It is a delay, not a backoff schedule:
+ * a second attempt either establishes something or it does not, and a third
+ * would only spend a public endpoint's time proving the same point.
+ */
+export declare const BEACON_HEARTBEAT_RETRY_DELAY_MS = 250;
+/**
+ * How long a missed heartbeat is forgiven after the last one that landed.
+ *
+ * One monitor interval. The uptime workflow reads this door every 15 minutes,
+ * so a grace of exactly that means the FIRST probe after a miss can be
+ * forgiven and the second cannot — "tolerate a single miss, red on a
+ * sustained one", stated in the only unit the reader actually samples in.
+ *
+ * The bound this puts on a real outage: the marker is refreshed by every
+ * successful probe, and this endpoint is polled every 5 minutes, so the last
+ * landing is at most one probe TTL old when a sustained failure starts. Worst
+ * case the door reds 20 minutes later than it does today, and the 15-minute
+ * workflow sees it on its next run.
+ */
+export declare const BEACON_HEARTBEAT_GRACE_MS: number;
+/** Injectable clock, sleep, writer and store, so a spec can drive every branch. */
+export interface BeaconHeartbeatProbeOptions {
+    service: string;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    firestore?: any;
+    graceMs?: number;
+    retryDelayMs?: number;
+    /**
+     * The heartbeat writer. Defaults to the real one, and exists as a seam
+     * because the belt below catches a contract `writeBeaconHeartbeat` is
+     * documented never to break — a branch that is otherwise unreachable, and
+     * therefore one nobody has ever watched work.
+     */
+    write?: (options: {
+        service: string;
+    }) => Promise<BeaconHeartbeatResult>;
+}
+/**
+ * One heartbeat probe, graded — the whole of what both doors do (AGL-2713).
+ *
+ * ## Why this is one function and not two copies
+ *
+ * `apps/console` and `apps/tenant` each own a copy of
+ * `/api/health/error-beacon`, and they must: the deployments carry different
+ * admin credentials, so a console heartbeat proves nothing about the tenant
+ * one. What they do NOT need is two copies of the policy. Before this the two
+ * route files were byte-identical apart from a service name, which is the
+ * arrangement that guarantees a fix reaches one door and not the other. The
+ * per-deployment part (which credential, which service name, which memo) stays
+ * in the routes; the grading lives here, once.
+ *
+ * ## The sequence, and why each step is where it is
+ *
+ * 1. Write. If it lands, record the durable marker and report green — the
+ *    marker being the evidence a LATER miss will be forgiven with.
+ * 2. If it did not land and the code is a refusal — `http-401`/`http-403`
+ *    (a lost `logging.logEntries.create` grant), `http-429` (quota),
+ *    `no-credential` (the deployment env) — report red NOW, with no retry and
+ *    no grace. Those are permanent until a person acts, and re-asking a
+ *    credential that has been revoked only delays the page.
+ * 3. Otherwise nothing was decided, so ask once more after a short delay. On a
+ *    cold lambda this is the step that actually fixes the measured incident:
+ *    the memo is per-instance, so a fresh instance has no history to be
+ *    forgiving WITH, and the only tolerance available inside the request is
+ *    another attempt.
+ * 4. If the second attempt misses too, forgive only against the durable
+ *    marker — see {@link beaconHealth}, which will not forgive without proof.
+ *
+ * `attempts` and `ms` ride in the body on every outcome, including green ones,
+ * because a retry that is quietly always needed is a credential on its way out
+ * and a door that hid it would be back where it started.
+ */
+export declare function beaconHeartbeatProbe(options: BeaconHeartbeatProbeOptions): Promise<BeaconCheck>;