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

package/src/lib/server/vercel-log-drain.d.ts

@@ -0,0 +1,259 @@
+/**
+ * @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.
+ */
+/**
+ * The log id the drain writes to. Contains "vercel" on purpose: the alert
+ * policy `projects/aglyn-main/alertPolicies/14031689508473384486` matches
+ * `logName=~"vercel"`, so the name is load-bearing. Renaming this log without
+ * repointing that policy silences the platform-5xx arm.
+ */
+export declare const VERCEL_RUNTIME_LOG_ID = "vercel-runtime";
+/** The env var holding the drain's signature secret. Fails closed if unset. */
+export declare const DRAIN_SECRET_ENV = "VERCEL_LOG_DRAIN_SECRET";
+/**
+ * The receiver's own path — the FEEDBACK-LOOP GUARD (requirement 5).
+ *
+ * ⚠️ HISTORICAL, AND KEPT AS DEFENCE IN DEPTH (2026-08-26). The receiver USED
+ * to run on `aglyn-console`, whose logs the console drain collects, and the
+ * two cuts below were the answer to one receiver 500 draining back in.
+ *
+ * They were not enough, and the reason is worth stating plainly because the
+ * docstring that used to live here got it wrong: **both cuts are about the
+ * WRITE, and the cost was the DELIVERY.** Nothing inside a receiver can
+ * decline to be requested, and every delivery POST is itself a request that
+ * produces a log the same drain then delivers. Measured at 695K invocations
+ * in nine hours. Vercel's drain `sampling` rules are not a fix either — a
+ * single `{rate: 0}` rule with no path prefix moved delivery volume from 31
+ * to 32 per five minutes, i.e. the whole `schemas.log` filter block is stored
+ * and never applied.
+ *
+ * The receiver now lives OFF Vercel, at `cloud/log-drain` on Cloud Run, which
+ * no drain watches — so the loop is structurally impossible rather than
+ * filtered against. These cuts stay because they cost nothing and they are
+ * the backstop if anyone ever mounts this gate on a Vercel route again.
+ *
+ * Two structural cuts, not one:
+ *
+ * a. Every entry whose path is this route is dropped before the 5xx filter —
+ *    so even the receiver's OWN 500s can never be forwarded, by anything, at
+ *    any budget. It is not "we try not to error"; it is that its errors are
+ *    unforwardable.
+ * b. Every line this module logs about itself is `console.warn`, i.e. Vercel
+ *    `level: "warning"`, and the filter forwards only 5xx and `fatal`. A
+ *    suppression summary drained back in is therefore dropped a second time,
+ *    on a different property, by a different rule.
+ *
+ * Matched as a PREFIX so `/api/log-drain`, a future `/api/log-drain/test` and
+ * the query-bearing `proxy.path` form all fall on the same side of it.
+ */
+export declare const RECEIVER_ROUTE_PATH = "/api/log-drain";
+/**
+ * The lockdown notice route — a route whose 503 is the FEATURE, not a fault.
+ *
+ * `apps/tenant/app/api/locked/route.ts` answers every request with a real 503
+ * carrying `Retry-After`, and the middleware rewrites every path of a locked
+ * or bandwidth-capped host to it. That status is deliberate: a takedown
+ * notice answering 200 would tell crawlers and uptime checks the site is
+ * fine, which is the whole reason the notice is a route handler rather than a
+ * page.
+ *
+ * Forwarded, it is indistinguishable from an outage. One suspended host being
+ * crawled emits a 5xx per request, forever, into the arm whose only consumer
+ * is an alert policy — so the policy fires on a working feature and the next
+ * real incident arrives in a stream that is already red.
+ *
+ * Matched EXACTLY, not as a prefix: the notice is one path, and a future
+ * `/api/locked/*` would be a different route with no such guarantee about its
+ * status.
+ */
+export declare const LOCKDOWN_NOTICE_ROUTE_PATH = "/api/locked";
+/** Reset the budget counters. Test seam only — never called in production. */
+export declare function resetDrainBudgetForTests(): void;
+/**
+ * One log entry as a Vercel drain delivers it. Only the fields this receiver
+ * reads are named; the wire object carries many more (client IP, user agent,
+ * referer, the query-bearing `proxy.path`) which are deliberately NOT in this
+ * type, because a field that has no name here cannot be forwarded by accident.
+ */
+export interface VercelDrainEntry {
+    id?: string;
+    deploymentId?: string;
+    projectId?: string;
+    projectName?: string;
+    source?: string;
+    host?: string;
+    timestamp?: number;
+    level?: string;
+    type?: string;
+    message?: string;
+    path?: string;
+    entrypoint?: string;
+    requestId?: string;
+    statusCode?: number;
+    environment?: string;
+    executionRegion?: string;
+    proxy?: {
+        method?: string;
+        statusCode?: number;
+        path?: string;
+        pathType?: string;
+    };
+}
+/**
+ * The entries in one delivery, in either format Vercel will send.
+ *
+ * `json` delivers an array (and, per the reference's own example, sometimes a
+ * newline-separated sequence of objects); `ndjson` delivers one object per
+ * line. Parsing both means the drain's `deliveryFormat` can be changed in the
+ * dashboard without a deploy, and a malformed line is skipped rather than
+ * failing the whole delivery — Vercel disables a drain that errors too often,
+ * so a receiver that 500s on one bad line silences itself.
+ */
+export declare function parseDrainPayload(rawBody: string): VercelDrainEntry[];
+/** Does this entry describe the receiver's own route? See RECEIVER_ROUTE_PATH. */
+export declare function isReceiverEntry(entry: VercelDrainEntry): boolean;
+/**
+ * Is this the lockdown notice serving its deliberate 503? See
+ * {@link LOCKDOWN_NOTICE_ROUTE_PATH}.
+ *
+ * Narrow on purpose — the route being exempt must not make the route
+ * unwatchable. Only a clean 503 is excused: a 500 the handler threw, the
+ * `statusCode -1` of a crashed lambda, and a `fatal` line all still forward,
+ * because those say the notice itself is broken and a locked host is then
+ * serving nothing at all.
+ */
+export declare function isLockdownNoticeEntry(entry: VercelDrainEntry): boolean;
+/**
+ * The health contract's routes, whose 503 is a VERDICT and not a fault.
+ *
+ * Prefix, not an exact path: every endpoint under it speaks the same contract
+ * — `healthHttpStatus` answers 200 while a check reports ok and 503 the moment
+ * it reports degraded — so `/api/health`, `/api/health/crons` and
+ * `/api/health/render/site` are all the same case.
+ */
+export declare const HEALTH_ROUTE_PREFIX = "/api/health";
+/**
+ * Is this a health endpoint answering 503 because it is doing its job?
+ * (AGL-2709)
+ *
+ * ⚠️ THE STREAM WAS 91% THIS. Measured over the 48 hours to 2026-09-09, the
+ * drain forwarded 251 entries into `vercel-runtime`. **229 were `/api/health/*`
+ * answering 503** — `crons` 113, `funnel` 73, `server-errors` 18 — and 22 were
+ * the AGL-2708 outage, the only real server errors in the window. The policy
+ * on that log (`logName=~"vercel" AND severity>=ERROR`, one notification an
+ * hour) therefore mails about a working health check for as long as any
+ * subsystem is degraded: `/api/health/crons` was CORRECTLY reporting a broken
+ * job for six hours on 2026-09-07, which is six hours of "server errors" mail
+ * arriving in the same inbox that then had to notice 04:02 on 2026-09-09.
+ *
+ * Excusing it removes a DUPLICATE, not a signal, and the reason is structural
+ * rather than a judgement call: every `/api/health/*` route both apps ship has
+ * a monitor reading it, and `evaluateSubsystemReaders` fails the build if one
+ * ever does not. The 503 is already on the uptime probe's board, in an
+ * UptimeRobot monitor and on `docs.aglyn.com/status`, said in a body that
+ * names WHICH check failed — which the drain entry never could.
+ *
+ * Narrow in exactly the same three ways as {@link isLockdownNoticeEntry}, and
+ * each one is load-bearing:
+ *
+ *  - a clean 503 only. A 500 the handler threw means the health route itself
+ *    is broken, and a check that cannot answer must never look calm;
+ *  - never a `fatal` line, which is process death rather than a verdict;
+ *  - never `statusCode -1`, the crashed-lambda sentinel, which is not 503 and
+ *    so fails the status test above.
+ */
+export declare function isHealthContractEntry(entry: VercelDrainEntry): boolean;
+/**
+ * THE COST GATE (requirement 3). Everything false here is dropped unwritten.
+ *
+ * What counts as a server error:
+ *
+ * - `statusCode >= 500` or `proxy.statusCode >= 500` — the platform 5xx this
+ *   whole arm exists for, including the ones our code never saw.
+ * - `statusCode === -1` — documented as "no response returned and the lambda
+ *   crashed". The OOM/hard-crash case, and the single most important entry
+ *   shape the `onRequestError` hook is structurally unable to produce.
+ * - `level === 'fatal'` or `type === 'fatal'` — the edge-runtime and
+ *   process-death shape, which may carry no status at all.
+ *
+ * What deliberately does NOT count:
+ *
+ * - `level === 'error'`. That is any `console.error`, including the fail-soft
+ *   warn/error lines the beacons themselves write, and forwarding it would
+ *   mean paying per line for a stream the `onRequestError` hook already
+ *   covers properly. If an errored request matters, it has a status.
+ * - `proxy.statusCode === -1`. Same sentinel, opposite meaning: on the proxy
+ *   object it documents a BACKGROUND REVALIDATION, which is a healthy ISR
+ *   refresh. Reading it as a crash would forward a steady trickle of normal
+ *   traffic forever — the exact bill this gate exists to prevent.
+ */
+export declare function isServerErrorEntry(entry: VercelDrainEntry): boolean;
+/**
+ * Everything above, in the order the cost argument requires.
+ * Exported so the tests can assert the gate without a transport.
+ */
+export declare function selectForwardableEntries(entries: readonly VercelDrainEntry[]): VercelDrainEntry[];
+/** What one delivery did, for the response body, the tests and the caller. */
+export interface DrainIngestResult {
+    /** Entries in the delivery. */
+    received: number;
+    /** Entries that passed the receiver-path and 5xx gates. */
+    matched: number;
+    /** Entries actually written to Cloud Logging. */
+    forwarded: number;
+    /** Entries dropped by the per-window budget — REPORTED, never silent. */
+    suppressed: number;
+    /** Set when nothing could be written at all; a stable code, never a message. */
+    code?: 'no-credential' | 'transport' | `http-${number}`;
+}
+/**
+ * Where the write goes, and under whose credential.
+ *
+ * Injectable because the receiver has to be able to run somewhere that is NOT
+ * a Vercel project this drain watches — a delivery POST is a request to
+ * whatever hosts it, and a request produces a log the same drain then
+ * delivers, which is the AGL-1921 feedback loop. Vercel's drain `sampling`
+ * rules look like the answer and are NOT: measured 2026-08-26, a single
+ * `{rate: 0}` rule with no path prefix — literally "drop everything" — changed
+ * delivery volume from 31 to 32 per five minutes. The whole `schemas.log`
+ * filter block is accepted by the API, echoed back on `GET`, and never
+ * applied. Separation is the only control that works.
+ *
+ * The default keeps every existing caller on the Firebase admin credential.
+ * A receiver hosted off Vercel (Cloud Run in `aglyn-main`) passes its own
+ * resolver instead and never imports `firebase-admin` at all, which is what
+ * lets this module be bundled for it without dragging the SDK along.
+ */
+export interface DrainIngestOptions {
+    /**
+     * Resolve the Cloud Logging bearer token and project. Returning `null`
+     * means "no credential" and the delivery is dropped, reported, and answered
+     * 200 — never an error, because Vercel disables a drain whose endpoint
+     * fails often enough.
+     */
+    target?: () => Promise<{
+        token: string;
+        projectId: string;
+    } | null>;
+}
+/**
+ * Ingest ONE verified delivery: filter, budget, then a single batched write.
+ *
+ * Never throws. Vercel disables a drain whose endpoint fails often enough, so
+ * a receiver that propagated a Logging outage would end by turning itself off
+ * during the incident it exists to report.
+ */
+export declare function ingestDrainDelivery(entries: readonly VercelDrainEntry[], options?: DrainIngestOptions): Promise<DrainIngestResult>;