@aglyn/tenant-data-admin 1.0.0-beta.222 → 1.0.0-beta.224

package/src/lib/server/render-monitor.d.ts

@@ -0,0 +1,233 @@
+/**
+ * @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 type { OperatorHealthStateDoc } from './operator-health';
+/** Every render monitor document id starts with this. */
+export declare const RENDER_MONITOR_CHECK_PREFIX = "render-monitor--";
+/** The beat id `/api/health/crons` reads for the scheduled run. */
+export declare const RENDER_MONITOR_JOB_ID = "render-monitor";
+/**
+ * How long one page fetch may take. Well under the 60 s a platform function
+ * may run, so a hung render is graded here as a timeout rather than waiting
+ * for the platform's 504, and well under the route's own `maxDuration`.
+ */
+export declare const RENDER_MONITOR_TIMEOUT_MS = 25000;
+/** Failing runs in a row before the alert goes out. */
+export declare const RENDER_MONITOR_DEFAULT_THRESHOLD = 2;
+/**
+ * The prefix of the never-requested path the `isr` probe asks for. A
+ * lowercase slug on purpose: it must reach the catch-all page like any
+ * screen slug would, not a reserved or rewritten route.
+ */
+export declare const RENDER_PROBE_ISR_PREFIX = "/aglyn-render-probe-";
+export type RenderProbeKind = 'dynamic' | 'isr' | 'page';
+export interface RenderProbeSpec {
+    kind: RenderProbeKind;
+    /** The path to request, given a fresh nonce. */
+    path: (nonce: string) => string;
+    /** The status a healthy render answers with. */
+    expectStatus: number;
+}
+export declare const RENDER_PROBES: readonly RenderProbeSpec[];
+/** One fetched response, reduced to what grading reads. */
+export interface RenderProbeResponse {
+    status: number;
+    contentType?: string | null;
+    body?: string;
+    location?: string | null;
+    /** `x-vercel-cache` on Vercel, `x-nextjs-cache` on a plain `next start`. */
+    cacheState?: string | null;
+}
+export interface RenderProbeVerdict {
+    ok: boolean;
+    /** Bot protection answered instead of the site. */
+    challenged: boolean;
+    /** A stable code; `ok` on a pass. */
+    code: string;
+    detail: string;
+}
+/**
+ * Grade one probe response. Pure.
+ *
+ * The page markers are the front doors' (`tools/scripts/lib/front-door.mjs`)
+ * and for their reason: structural, never site copy. `</html>` proves the
+ * document finished streaming, `/_next/static/` that our build produced it.
+ */
+export declare function gradeRenderProbe(response: RenderProbeResponse, expectStatus: number): RenderProbeVerdict;
+/**
+ * The pages Aglyn's own console renders fresh when `RENDER_MONITOR_PAGES` is
+ * unset: the canary's real client pages (`tools/scripts/lib/prod-canary.mjs`
+ * `DEFAULT_TENANT_HOSTS`), images, reusable components, repeats and a form
+ * between them. Applied ONLY on that console deployment (`VERCEL_PROJECT_ID`),
+ * so no other install ever requests them.
+ */
+export declare const PLATFORM_RENDER_PAGES: string;
+/** Aglyn's console project on Vercel, the one deployment the list above is for. */
+export declare const PLATFORM_CONSOLE_VERCEL_PROJECT_ID = "prj_gEzxEXc0Lhs81rmaXIg2a1GbsDfl";
+/**
+ * The tenant's production project domain on Vercel: follows every promote and
+ * rollback, honors `?tenantHost=`, and is reachable only with the bypass.
+ */
+export declare const PLATFORM_RENDER_ORIGIN = "https://aglyn-tenant-aglyn.vercel.app";
+/**
+ * Spelling number `n` of one site: a `?tenantHost=` value that resolves to
+ * that site and is a `[host]` route segment no other number produces, so the
+ * page it asks for has no cache entry to come from.
+ *
+ *  - `{sub}.{apex}` → the full name, letters upper-cased by the bits of `n`,
+ *    then one trailing dot per exhausted round of cases.
+ *  - any other name → `cname--{name}`, recased the same way and cycling after
+ *    `2 ** letters` (that form keeps trailing dots), with the prefix left
+ *    lower-case because the canonical-domain redirect tests the raw segment.
+ *
+ * MUST stay identical to `freshHostSpelling` in
+ * `tools/scripts/lib/prod-canary.mjs`; `apps/tenant/specs/probe-host-spelling.spec.ts`
+ * pins both against `normalizeHostAlias`.
+ */
+export declare function freshHostSpelling(host: string, n: number, apex?: string): string;
+/**
+ * The spelling number for a run at `nowMs`: minutes since 2026-10-01, so it
+ * never repeats on one deployment — a `{sub}.aglyn.app` name of 18 letters
+ * gains its first trailing dot after half a year.
+ */
+export declare function renderSpellingNumber(nowMs: number): number;
+/** One watched site's real pages. */
+export interface RenderMonitorPages {
+    /** The site's public origin, which keys its state document. */
+    origin: string;
+    host: string;
+    paths: string[];
+}
+/**
+ * `"a.example.app b.example.app/services, https://b.example.app/contact"` →
+ * one entry per host, paths merged, `/` when an entry names none. Entries that
+ * are not a hostname are dropped, as `RENDER_MONITOR_ORIGINS` drops them.
+ */
+export declare function parseRenderMonitorPages(text: string | undefined | null): RenderMonitorPages[];
+/**
+ * Which real pages the monitor renders, and through which origin.
+ *
+ * `RENDER_MONITOR_PAGES` (same grammar as the canary's `CANARY_TENANT_HOSTS`)
+ * and `RENDER_MONITOR_RENDER_ORIGIN`, else — on Aglyn's own console only —
+ * `PLATFORM_RENDER_PAGES` through `PLATFORM_RENDER_ORIGIN`. `off` (here or in
+ * `RENDER_MONITOR_ORIGINS`) renders none. No render origin, no pages.
+ */
+export declare function resolveRenderMonitorPages(env: Readonly<Record<string, string | undefined>>): {
+    renderOrigin: string;
+    pages: RenderMonitorPages[];
+};
+/** A configured value as an origin, or '' when it is not one. */
+export declare function originOf(value: string | undefined | null): string;
+/**
+ * Which sites the monitor renders, from the console's environment.
+ *
+ * 1. The install's demonstration site: `OPERATOR_HEALTH_TENANT_ORIGIN` when
+ *    set (the one published site the operator alerts tick already watches),
+ *    else `https://<AGLYN_TENANT_DEMO or demo>.<tenant apex>`.
+ * 2. Plus every origin in `RENDER_MONITOR_ORIGINS`, comma separated.
+ *
+ * `RENDER_MONITOR_ORIGINS=off` watches nothing, for an install with no
+ * published site to watch. Values that are not origins are dropped.
+ */
+export declare function resolveRenderMonitorTargets(env: Readonly<Record<string, string | undefined>>): string[];
+/** The state document id for one origin. */
+export declare function renderMonitorCheckId(origin: string): string;
+/** One render monitor state document. */
+export interface RenderMonitorStateDoc extends OperatorHealthStateDoc {
+    origin: string;
+    /** Failing runs in a row, reset by any passing run. */
+    consecutiveFailures: number;
+    /** When the current run of failures began; null while passing. */
+    failingSinceMs: number | null;
+    lastOkAtMs: number | null;
+}
+export type RenderMonitorTransition = 'failing' | 'recovered' | null;
+/**
+ * The next state for one site, given what this run saw. Pure.
+ *
+ * The status turns `degraded` only once `threshold` runs in a row have
+ * failed, so one slow cold start or one dropped connection says nothing. It
+ * turns back on the first passing run, because a render that works is
+ * proof, and a recovery held back is a recovery nobody hears about.
+ */
+export declare function nextRenderMonitorState(prior: Partial<RenderMonitorStateDoc> | null, observation: {
+    ok: boolean;
+    detail: string;
+}, context: {
+    origin: string;
+    label: string;
+    threshold: number;
+    now: number;
+}): {
+    next: RenderMonitorStateDoc;
+    transition: RenderMonitorTransition;
+};
+/** One probe as the report shows it. */
+export interface RenderProbeRow extends RenderProbeVerdict {
+    kind: RenderProbeKind;
+    url: string;
+    ms: number;
+    httpStatus: number | null;
+}
+/** One site's result for a run. */
+export interface RenderMonitorSiteResult {
+    origin: string;
+    ok: boolean;
+    probes: RenderProbeRow[];
+    /** The state written; absent on a dry run or a failed write. */
+    status?: 'ok' | 'degraded';
+    consecutiveFailures?: number;
+    transition?: RenderMonitorTransition;
+    error?: string;
+}
+export interface RenderMonitorReport {
+    dryRun: boolean;
+    threshold: number;
+    sites: RenderMonitorSiteResult[];
+}
+/** The read-modify-write of one site's state, as one transaction. */
+export type RenderMonitorStore = <T>(checkId: string, work: (prior: Partial<RenderMonitorStateDoc> | null) => {
+    next: RenderMonitorStateDoc;
+    result: T;
+}) => Promise<T>;
+type RaiseAlert = (type: string, options: {
+    dedupeKey?: string;
+    context?: Record<string, string | number>;
+}) => Promise<unknown>;
+/**
+ * The `page` probe's URL for one run: this run's page of the site's list
+ * (rotating every five-minute slot), under this run's spelling of the site.
+ */
+export declare function pageProbeUrl(renderOrigin: string, site: RenderMonitorPages, slot: number, spelling: number): string;
+/**
+ * One run: render every target, record each site's state, raise the edge.
+ *
+ * A dry run fetches and grades and writes nothing, so a person can ask
+ * "what would the monitor see right now" without moving its state.
+ */
+export declare function runRenderMonitor(options?: {
+    dryRun?: boolean;
+    env?: Readonly<Record<string, string | undefined>>;
+    fetcher?: typeof fetch;
+    /** Our own edge's bypass headers, from the caller's environment. */
+    headers?: Record<string, string>;
+    now?: () => number;
+    nonce?: () => string;
+    timeoutMs?: number;
+    store?: RenderMonitorStore;
+    raise?: RaiseAlert;
+}): Promise<RenderMonitorReport>;
+export {};