@uptimizr/collector-server 2.1.0 → 2.2.0

package/dist/subscriptions/cli.js

@@ -0,0 +1,143 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { subscriptionSchema } from "@uptimizr/schema";
+import { getMetric } from "@uptimizr/metrics";
+import { createStore } from "../serve.js";
+import { evaluateSubscription } from "./evaluate.js";
+/**
+ * `uptimizr subscriptions …` — the operator's offline half of the subscriptions
+ * API (#311, ADR 0051 §6).
+ *
+ * The offline sibling of `/api/v1/subscriptions`, and an **operator** command in
+ * the same sense as `new-key` and `regions set`: it takes no API key and opens
+ * the store directly, because store access is already strictly more than any
+ * capability grants. It is the path a self-hoster uses to put a subscription
+ * under version control — `sub.json` in a repo, applied by a deploy step —
+ * rather than clicking one together.
+ *
+ * `test` deliberately **never delivers**. A dry run from a shell should not be
+ * able to page anyone; proving a webhook receiver works is
+ * `POST /api/v1/subscriptions/:id/test?deliver=true`, which needs an `annotate`
+ * key and is auditable.
+ *
+ * Human progress goes to stderr, machine-readable JSON to stdout — the same
+ * split the rest of `cli.ts` uses, so `uptimizr subscriptions list | jq` works.
+ */
+/** Read and validate a declaration file (a bare object or a `{ subscription }` envelope). */
+export function readSubscriptionFile(file) {
+    const raw = readFileSync(resolve(file), "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${file} is not valid JSON: ${err instanceof Error ? err.message : err}`, {
+            cause: err,
+        });
+    }
+    const candidate = parsed != null && typeof parsed === "object" && "subscription" in parsed
+        ? parsed.subscription
+        : parsed;
+    const result = subscriptionSchema.safeParse(candidate);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`)
+            .join("\n");
+        throw new Error(`${file} is not a valid subscription:\n${issues}`);
+    }
+    return result.data;
+}
+/** One line per subscription, for `list`'s stderr summary. */
+function summarize(sub) {
+    const state = sub.enabled ? "enabled" : "disabled";
+    const last = sub.lastFiredAt ? sub.lastFiredAt.toISOString() : "never";
+    const error = sub.lastError ? ` · last error: ${sub.lastError}` : "";
+    return `${sub.id}  ${sub.name}  [${sub.predicate.kind} on ${sub.metric}] ${state} · last fired ${last}${error}`;
+}
+async function withStore(fn) {
+    const store = await createStore();
+    try {
+        return await fn(store);
+    }
+    finally {
+        await store.close();
+    }
+}
+/** `uptimizr subscriptions list` — every subscription of `projectId`. */
+export async function cmdSubscriptionsList(projectId) {
+    const rows = await withStore((store) => store.listSubscriptions(projectId));
+    for (const sub of rows)
+        console.error(summarize(sub));
+    if (rows.length === 0)
+        console.error(`No subscriptions on project ${projectId}.`);
+    process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+}
+/** `uptimizr subscriptions add --file sub.json` — store a new declaration. */
+export async function cmdSubscriptionsAdd(projectId, file) {
+    const declaration = readSubscriptionFile(file);
+    // The registry check the route does, done here too: an operator must not be
+    // able to create offline a subscription the scheduler will only reject later.
+    if (getMetric(declaration.metric) == null) {
+        throw new Error(`Unknown metric ${JSON.stringify(declaration.metric)}.`);
+    }
+    const created = await withStore((store) => store.createSubscription(projectId, declaration));
+    console.error(`✓ subscription ${created.id} created on project ${projectId}`);
+    if (created.delivery.some((d) => d.kind === "webhook")) {
+        console.error("  A webhook is configured. The collector only POSTs to hosts named in " +
+            "COLLECTOR_WEBHOOK_ALLOWED_HOSTS; until one is set, firings are recorded and " +
+            "fanned out over SSE but nothing leaves the process.");
+    }
+    process.stdout.write(`${JSON.stringify(created, null, 2)}\n`);
+}
+/** `uptimizr subscriptions remove <id>` — delete a subscription and its firings. */
+export async function cmdSubscriptionsRemove(projectId, id) {
+    const deleted = await withStore((store) => store.deleteSubscription(projectId, id));
+    if (!deleted)
+        throw new Error(`No subscription ${JSON.stringify(id)} on project ${projectId}.`);
+    console.error(`✓ subscription ${id} removed`);
+}
+/**
+ * `uptimizr subscriptions test <id>` — evaluate once, now, delivering nothing.
+ *
+ * Answers with the evaluation, including why it did not fire, which is what
+ * makes a subscription tunable rather than mysterious.
+ */
+export async function cmdSubscriptionsTest(projectId, id) {
+    const result = await withStore(async (store) => {
+        const sub = await store.getSubscription(projectId, id);
+        if (sub == null) {
+            throw new Error(`No subscription ${JSON.stringify(id)} on project ${projectId}.`);
+        }
+        const metric = getMetric(sub.metric);
+        if (metric == null) {
+            throw new Error(`Subscription ${id} names unknown metric ${JSON.stringify(sub.metric)}.`);
+        }
+        const evaluation = await evaluateSubscription({
+            readBuckets: (opts) => store.metricBuckets(projectId, opts),
+            // No live bus in a one-shot CLI process, so a `presence` predicate here
+            // reads zero live sessions. Said plainly rather than left to be guessed.
+            activeSessions: () => 0,
+        }, sub, metric);
+        return { sub, evaluation };
+    });
+    console.error(result.evaluation.fired
+        ? `✓ would fire: ${result.evaluation.reason}`
+        : `· would not fire: ${result.evaluation.reason}`);
+    if (result.sub.predicate.kind === "presence") {
+        console.error("  Note: `presence` is evaluated from the running collector's live bus; a CLI process " +
+            "has none, so this reports zero live sessions.");
+    }
+    process.stdout.write(`${JSON.stringify({
+        subscriptionId: result.sub.id,
+        fired: result.evaluation.fired,
+        reason: result.evaluation.reason,
+        window: result.evaluation.window,
+        value: result.evaluation.value,
+        expected: result.evaluation.expected,
+        sampleSize: result.evaluation.sampleSize,
+        dimensionValue: result.evaluation.dimensionValue,
+        bucket: result.evaluation.bucket,
+        delivered: false,
+    }, null, 2)}\n`);
+}
+//# sourceMappingURL=cli.js.map

package/dist/subscriptions/cli.js.map

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

package/dist/subscriptions/delivery.d.ts

@@ -0,0 +1,101 @@
+import type { SubscriptionDelivery, SubscriptionFiring } from "@uptimizr/schema";
+import { type SubscriptionRecord } from "@uptimizr/db";
+/**
+ * **Delivering a subscription firing** (#311, ADR 0051 §6 / sketch §F.3).
+ *
+ * Two targets, and they are deliberately asymmetric:
+ *
+ * - **SSE** is a fan-out to whoever is already connected. It costs nothing, it
+ *   leaves the process only over a connection the operator's own key opened, and
+ *   it is the default.
+ * - **A webhook is egress.** Nothing here makes an outbound request unless a
+ *   subscription carries a `webhook` delivery with a URL — ADR 0051 §6, "no
+ *   outbound egress happens unless a self-hoster configures a webhook URL", is
+ *   enforced by {@link deliver} having nothing to do in that case.
+ *
+ * ## The SSRF boundary
+ *
+ * `parseWebhookUrl` (shared with `uptimizr agent report`) rejects anything that
+ * is not `http(s)`, and its own doc is explicit that a surface which accepts a
+ * URL *over HTTP* must add an allow-list on top — which is exactly this surface,
+ * because a subscription is created through the API by an `annotate` key rather
+ * than typed into the operator's shell. {@link checkWebhookUrl} is that
+ * allow-list: `COLLECTOR_WEBHOOK_ALLOWED_HOSTS`, empty by default, which means
+ * **no webhook delivery leaves the process at all until an operator names the
+ * hosts it may reach**. A key holder can therefore not turn the collector into a
+ * probe for the network it sits in.
+ *
+ * ## Retries
+ *
+ * Three attempts, exponential backoff, only for failures that can plausibly
+ * succeed on a retry (a network error, a 408/429, any 5xx). A 4xx other than
+ * those is the receiver saying "not like that", and repeating it just triples
+ * the noise. Every attempt carries the same {@link WEBHOOK_DELIVERY_HEADER} id,
+ * so a receiver can dedupe.
+ */
+/** Attempts per firing, including the first. */
+export declare const WEBHOOK_MAX_ATTEMPTS = 3;
+/** Backoff before the 2nd attempt; doubled for each further one. */
+export declare const WEBHOOK_BASE_BACKOFF_MS = 500;
+/** Per-attempt timeout. A webhook receiver that is slow is a webhook that fails. */
+export declare const WEBHOOK_TIMEOUT_MS = 10000;
+/** The body a webhook receives. */
+export interface WebhookPayload {
+    /** Schema marker, so a receiver can branch on shape without guessing. */
+    type: "subscription.firing";
+    firing: SubscriptionFiring;
+    /** Bounded `format=summary` of the metric over the window that fired. */
+    summary: Record<string, unknown> | null;
+}
+/** Outcome of delivering one firing. */
+export interface DeliveryOutcome {
+    /** Whether every configured target accepted it (SSE always does). */
+    ok: boolean;
+    /** Bounded, redacted failure text when a webhook failed, else `null`. */
+    error: string | null;
+    /** How many webhook attempts were made (0 when no webhook is configured). */
+    attempts: number;
+    /** True when a webhook request actually left the process. */
+    egress: boolean;
+}
+/** What {@link deliver} needs from its host. */
+export interface DeliveryDeps {
+    /** Push the firing to connected SSE listeners. */
+    broadcast: (firing: SubscriptionFiring, summary: Record<string, unknown> | null) => void;
+    /** The subscription's webhook secret, or `null`. */
+    secret: string | null;
+    /** Hosts a webhook may target; empty forbids all webhook egress. */
+    allowedHosts: readonly string[];
+    /** Injected for tests. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests. Defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Validate a webhook URL against the operator's allow-list.
+ *
+ * Returns the parsed URL, or a refusal string naming why. Matching is on the
+ * **hostname** (case-insensitive, port-independent), because a port is not a
+ * trust boundary: an operator who allows `hooks.slack.com` means the host, and
+ * an operator who allows `localhost` means their own box. `*` allows every host
+ * and is an explicit, documented opt-out for a collector on a closed network.
+ */
+export declare function checkWebhookUrl(raw: string, allowedHosts: readonly string[]): {
+    url: URL;
+} | {
+    refused: string;
+};
+/** The one webhook target of a subscription, or `null`. */
+export declare function webhookTargetOf(sub: SubscriptionRecord): Extract<SubscriptionDelivery, {
+    kind: "webhook";
+}> | null;
+/** Whether a subscription asks for SSE fan-out. */
+export declare function wantsSse(sub: SubscriptionRecord): boolean;
+/**
+ * Deliver one firing to every target the subscription declares.
+ *
+ * SSE first and unconditionally — it is in-process, so a broken webhook must
+ * never cost a connected agent its event.
+ */
+export declare function deliver(sub: SubscriptionRecord, firing: SubscriptionFiring, summary: Record<string, unknown> | null, deps: DeliveryDeps): Promise<DeliveryOutcome>;
+//# sourceMappingURL=delivery.d.ts.map

package/dist/subscriptions/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../src/subscriptions/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAA0B,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAS/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,gDAAgD;AAChD,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,oFAAoF;AACpF,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,EAAE,EAAE,OAAO,CAAC;IACZ,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,SAAS,EAAE,CAAC,MAAM,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IACzF,oDAAoD;IACpD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oEAAoE;IACpE,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,oDAAoD;IACpD,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAQD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B;IAAE,GAAG,EAAE,GAAG,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAsBpC;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,CAC7B,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,oBAAoB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,GAAG,IAAI,CAG3D;AAED,mDAAmD;AACnD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAEzD;AA0DD;;;;;GAKG;AACH,wBAAsB,OAAO,CAC3B,GAAG,EAAE,kBAAkB,EACvB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,eAAe,CAAC,CAuB1B"}

package/dist/subscriptions/delivery.js

@@ -0,0 +1,165 @@
+import { clampSubscriptionError } from "@uptimizr/db";
+import { WEBHOOK_DELIVERY_HEADER, WEBHOOK_SIGNATURE_HEADER, newDeliveryId, parseWebhookUrl, signWebhookBody, } from "../webhookSignature.js";
+/**
+ * **Delivering a subscription firing** (#311, ADR 0051 §6 / sketch §F.3).
+ *
+ * Two targets, and they are deliberately asymmetric:
+ *
+ * - **SSE** is a fan-out to whoever is already connected. It costs nothing, it
+ *   leaves the process only over a connection the operator's own key opened, and
+ *   it is the default.
+ * - **A webhook is egress.** Nothing here makes an outbound request unless a
+ *   subscription carries a `webhook` delivery with a URL — ADR 0051 §6, "no
+ *   outbound egress happens unless a self-hoster configures a webhook URL", is
+ *   enforced by {@link deliver} having nothing to do in that case.
+ *
+ * ## The SSRF boundary
+ *
+ * `parseWebhookUrl` (shared with `uptimizr agent report`) rejects anything that
+ * is not `http(s)`, and its own doc is explicit that a surface which accepts a
+ * URL *over HTTP* must add an allow-list on top — which is exactly this surface,
+ * because a subscription is created through the API by an `annotate` key rather
+ * than typed into the operator's shell. {@link checkWebhookUrl} is that
+ * allow-list: `COLLECTOR_WEBHOOK_ALLOWED_HOSTS`, empty by default, which means
+ * **no webhook delivery leaves the process at all until an operator names the
+ * hosts it may reach**. A key holder can therefore not turn the collector into a
+ * probe for the network it sits in.
+ *
+ * ## Retries
+ *
+ * Three attempts, exponential backoff, only for failures that can plausibly
+ * succeed on a retry (a network error, a 408/429, any 5xx). A 4xx other than
+ * those is the receiver saying "not like that", and repeating it just triples
+ * the noise. Every attempt carries the same {@link WEBHOOK_DELIVERY_HEADER} id,
+ * so a receiver can dedupe.
+ */
+/** Attempts per firing, including the first. */
+export const WEBHOOK_MAX_ATTEMPTS = 3;
+/** Backoff before the 2nd attempt; doubled for each further one. */
+export const WEBHOOK_BASE_BACKOFF_MS = 500;
+/** Per-attempt timeout. A webhook receiver that is slow is a webhook that fails. */
+export const WEBHOOK_TIMEOUT_MS = 10_000;
+const defaultSleep = (ms) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+});
+/**
+ * Validate a webhook URL against the operator's allow-list.
+ *
+ * Returns the parsed URL, or a refusal string naming why. Matching is on the
+ * **hostname** (case-insensitive, port-independent), because a port is not a
+ * trust boundary: an operator who allows `hooks.slack.com` means the host, and
+ * an operator who allows `localhost` means their own box. `*` allows every host
+ * and is an explicit, documented opt-out for a collector on a closed network.
+ */
+export function checkWebhookUrl(raw, allowedHosts) {
+    let url;
+    try {
+        url = parseWebhookUrl(raw);
+    }
+    catch (err) {
+        return { refused: err instanceof Error ? err.message : "invalid webhook url" };
+    }
+    if (allowedHosts.length === 0) {
+        return {
+            refused: "webhook delivery is disabled: set COLLECTOR_WEBHOOK_ALLOWED_HOSTS to the hosts this " +
+                "collector may POST to",
+        };
+    }
+    const host = url.hostname.toLowerCase();
+    const allowed = allowedHosts.some((entry) => {
+        const candidate = entry.trim().toLowerCase();
+        return candidate === "*" || candidate === host;
+    });
+    return allowed
+        ? { url }
+        : { refused: `webhook host ${JSON.stringify(host)} is not allow-listed` };
+}
+/** The one webhook target of a subscription, or `null`. */
+export function webhookTargetOf(sub) {
+    for (const target of sub.delivery)
+        if (target.kind === "webhook")
+            return target;
+    return null;
+}
+/** Whether a subscription asks for SSE fan-out. */
+export function wantsSse(sub) {
+    return sub.delivery.some((target) => target.kind === "sse");
+}
+/** Whether a response/error is worth another attempt. */
+function retryable(status) {
+    if (status == null)
+        return true; // network-level failure
+    return status === 408 || status === 429 || status >= 500;
+}
+/**
+ * POST one firing to `url`, signed, with bounded retries.
+ *
+ * The body is serialised **once** and the signature is taken over those exact
+ * bytes, because re-serialising between signing and sending is the classic way
+ * to ship a signature the receiver cannot reproduce.
+ */
+async function postWebhook(url, payload, secret, deps) {
+    const doFetch = deps.fetchImpl ?? fetch;
+    const sleep = deps.sleep ?? defaultSleep;
+    const body = JSON.stringify(payload);
+    const deliveryId = newDeliveryId();
+    const headers = {
+        "content-type": "application/json",
+        "user-agent": "uptimizr-collector",
+        [WEBHOOK_DELIVERY_HEADER]: deliveryId,
+    };
+    if (secret != null)
+        headers[WEBHOOK_SIGNATURE_HEADER] = signWebhookBody(secret, body);
+    let lastError = "webhook delivery failed";
+    for (let attempt = 1; attempt <= WEBHOOK_MAX_ATTEMPTS; attempt += 1) {
+        let status = null;
+        try {
+            const res = await doFetch(url, {
+                method: "POST",
+                headers,
+                body,
+                signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
+                redirect: "error",
+            });
+            status = res.status;
+            if (res.ok)
+                return { ok: true, error: null, attempts: attempt };
+            lastError = `webhook responded ${res.status}`;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err.message : String(err);
+        }
+        if (!retryable(status) || attempt === WEBHOOK_MAX_ATTEMPTS) {
+            return { ok: false, error: clampSubscriptionError(lastError), attempts: attempt };
+        }
+        await sleep(WEBHOOK_BASE_BACKOFF_MS * 2 ** (attempt - 1));
+    }
+    /* c8 ignore next */
+    return { ok: false, error: clampSubscriptionError(lastError), attempts: WEBHOOK_MAX_ATTEMPTS };
+}
+/**
+ * Deliver one firing to every target the subscription declares.
+ *
+ * SSE first and unconditionally — it is in-process, so a broken webhook must
+ * never cost a connected agent its event.
+ */
+export async function deliver(sub, firing, summary, deps) {
+    if (wantsSse(sub))
+        deps.broadcast(firing, summary);
+    const target = webhookTargetOf(sub);
+    if (target == null)
+        return { ok: true, error: null, attempts: 0, egress: false };
+    const checked = checkWebhookUrl(target.url, deps.allowedHosts);
+    if ("refused" in checked) {
+        return {
+            ok: false,
+            error: clampSubscriptionError(checked.refused),
+            attempts: 0,
+            egress: false,
+        };
+    }
+    const result = await postWebhook(checked.url, { type: "subscription.firing", firing, summary }, deps.secret, deps);
+    return { ...result, egress: true };
+}
+//# sourceMappingURL=delivery.js.map

package/dist/subscriptions/delivery.js.map

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

package/dist/subscriptions/evaluate.d.ts

@@ -0,0 +1,119 @@
+import { type BucketGrain, type MetricBucketOptions, type MetricBucketRow, type SubscriptionRecord } from "@uptimizr/db";
+import { type ComparisonOp, type SubscriptionFiring } from "@uptimizr/schema";
+import type { MetricDefinition } from "@uptimizr/metrics";
+/**
+ * **Subscription predicate evaluation** (#311, ADR 0051 §6 / sketch §F.2).
+ *
+ * Everything that decides whether a standing question is answered "yes" right
+ * now lives here, and it is a pure function of *rows* — the only I/O is the one
+ * injected {@link BucketReader}, which is the same
+ * `store.metricBuckets(projectId, …)` the insight routes call. That keeps the
+ * whole predicate vocabulary unit-testable without a database, a timer or a
+ * server, and keeps the four stores interchangeable: the series a predicate sees
+ * is the parity-tested portable bucket series, not per-dialect SQL of its own.
+ *
+ * ## Why the window is not snapped the way the insight routes snap theirs
+ *
+ * `baseline`, `movers` and `anomalies` floor `until` to the last **complete**
+ * bucket, because they compare periods and a partial period reads as a collapse
+ * every morning. A subscription is the opposite question — *is something wrong
+ * right now* — so its window ends at the instant of evaluation and its final
+ * bucket is deliberately partial. `since` is still floored, so the series the
+ * store returns is bucket-aligned and every row is attributed exactly once.
+ *
+ * ## Why `threshold.column` must be the metric's headline column
+ *
+ * The portable series reproduces exactly one column per metric — the registry's
+ * `comparable.primary` (`perf_summary` → `p50_fps`). Comparing any other column
+ * would mean running the metric's own endpoint handler, which is per-metric code
+ * the scheduler would have to re-enter, and would drag five dialects' quantile
+ * semantics into an alert threshold. Asking for another column is a `400` that
+ * *names* the right one — see {@link thresholdColumnFor}.
+ */
+/** The one store read a predicate may issue, injected so tests need no store. */
+export type BucketReader = (opts: MetricBucketOptions) => Promise<MetricBucketRow[]>;
+/** Live presence, injected the same way (the `presence` predicate's only input). */
+export type PresenceReader = () => number;
+/** What an evaluation needs besides the subscription itself. */
+export interface EvaluateDeps {
+    readBuckets: BucketReader;
+    /** Concurrent live sessions; only read by the `presence` predicate. */
+    activeSessions?: PresenceReader;
+    /** Injected clock. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** The half-open window an evaluation measured. */
+export interface EvaluationWindow {
+    since: number;
+    until: number;
+}
+/**
+ * The outcome of one evaluation.
+ *
+ * A non-firing evaluation still carries its numbers and a `reason`: that is what
+ * `POST /api/v1/subscriptions/:id/test` answers with, and "it did not fire
+ * because the window held 12 samples and `minSample` is 20" is the difference
+ * between a subscription an operator can tune and one they delete.
+ */
+export interface EvaluationResult {
+    fired: boolean;
+    /** Human-readable account of the outcome, firing or not. */
+    reason: string;
+    window: EvaluationWindow;
+    /** The observed value the predicate judged, when there is a single one. */
+    value: number | null;
+    /** What it was judged against — a level, an expectation, a previous window. */
+    expected: number | null;
+    /** The window's denominator: events, or distinct sessions. */
+    sampleSize: number;
+    /** The dimension value behind the outcome (`new_value`, attributed anomaly). */
+    dimensionValue: string | null;
+    /** The bucket series the evaluation read, for the delivery summary. */
+    series: readonly MetricBucketRow[];
+    /** Grain the series was read at. */
+    bucket: BucketGrain;
+}
+/** Resolve the series grain: the declared one, else hourly for short windows. */
+export declare function bucketFor(sub: SubscriptionRecord): BucketGrain;
+/**
+ * The window one evaluation measures: `[floor(now − window), now)`.
+ *
+ * `since` is floored so the series is bucket-aligned; `until` is not, so the
+ * partial bucket containing *this minute* is included. See the module note.
+ */
+export declare function resolveWindow(windowMs: number, bucket: BucketGrain, now: number): EvaluationWindow;
+/** Compare two numbers with a subscription's operator. */
+export declare function compare(left: number, op: ComparisonOp, right: number): boolean;
+/**
+ * The column a `threshold` predicate on `metric` may name — its registry
+ * `comparable.primary`, or `null` when the metric declares none.
+ */
+export declare function thresholdColumnFor(metric: MetricDefinition): string | null;
+/** Whether a metric can back a store-evaluated subscription at all. */
+export declare function isSubscribableMetric(metricId: string): boolean;
+/**
+ * Evaluate one subscription now.
+ *
+ * Every predicate kind but `presence` issues **one** bucket read; `movers` and
+ * `new_value` cover both their windows with a single spanning scan, the same
+ * trick `movers` itself uses, so both windows are guaranteed to have seen one
+ * snapshot of the data.
+ */
+export declare function evaluateSubscription(deps: EvaluateDeps, sub: SubscriptionRecord, metric: MetricDefinition): Promise<EvaluationResult>;
+/** Shape an evaluation into the firing record stored and delivered. */
+export declare function toFiring(sub: SubscriptionRecord, result: EvaluationResult, at: number): SubscriptionFiring;
+/**
+ * The bounded `format=summary` block a webhook carries alongside the firing
+ * (sketch §F.3: "so the receiver can act without a second call").
+ *
+ * It is the registry's own summary of `insight_baseline` over exactly the window
+ * that fired — a real registry metric with real declared units and caveats,
+ * rather than a hand-rolled bag of numbers. That is deliberate: the receiver
+ * reads the same envelope it would get from `GET /api/v1/insights/baseline`, so
+ * anything that can already render one can render this.
+ *
+ * `null` when the predicate read no series (`presence`) or the summariser
+ * declines the rows.
+ */
+export declare function summaryFor(sub: SubscriptionRecord, result: EvaluationResult): Record<string, unknown> | null;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/subscriptions/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/subscriptions/evaluate.ts"],"names":[],"mappings":"AAAA,OAAO,EAaL,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAmB,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,mBAAmB,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;AAErF,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC;AAE1C,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,YAAY,CAAC;IAC1B,uEAAuE;IACvE,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,gBAAgB,CAAC;IACzB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,uEAAuE;IACvE,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IACnC,oCAAoC;IACpC,MAAM,EAAE,WAAW,CAAC;CACrB;AAKD,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,GAAG,EAAE,kBAAkB,GAAG,WAAW,CAI9D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,MAAM,GACV,gBAAgB,CAIlB;AAED,0DAA0D;AAC1D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAe9E;AAmBD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAE1E;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE9D;AAgCD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,kBAAkB,EACvB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAkN3B;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CACtB,GAAG,EAAE,kBAAkB,EACvB,MAAM,EAAE,gBAAgB,EACxB,EAAE,EAAE,MAAM,GACT,kBAAkB,CAepB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,kBAAkB,EACvB,MAAM,EAAE,gBAAgB,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAiBhC"}