@smthrs/notifications 0.0.0-stage → 1.0.0-rc.4

package/dist/cjs/layerWebhook.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/layerWebhook.ts"],
+  "sourcesContent": ["/**\n * The webhook alert sink: one POST per alert, keyed so the receiver can\n * dedupe on it.\n *\n * The transport rules live here rather than beside the policy, because which\n * endpoint is paged, over which scheme, carrying which credential is a\n * deployment's decision and the delays are not.\n *\n * @since 1.0.0\n */\n\nimport { Duration, Effect, Layer, Option } from \"effect\"\nimport * as FetchHttpClient from \"effect/unstable/http/FetchHttpClient\"\nimport * as HttpClient from \"effect/unstable/http/HttpClient\"\nimport * as HttpClientRequest from \"effect/unstable/http/HttpClientRequest\"\nimport { alertId } from \"./AlertPolicy.ts\"\nimport { AlertError, Sink } from \"./AlertSink.ts\"\n\n/**\n * How long the webhook sink waits for an answer before it calls the page\n * refused.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const defaultWebhookTimeout: Duration.Duration = Duration.seconds(10)\n\n/**\n * The one check the webhook endpoint gets before an alert is ever built on\n * it.\n *\n * The url is operator config rather than runtime input, so there is no SSRF\n * vector to close here; the scheme bound is what keeps a credential the\n * deployment set in `headers` from being handed to a scheme that is not HTTP\n * at all. A `file:` or `javascript:` url is a config bug, and it fails the\n * composition the way an impossible policy rule does. The error names no\n * url: the value can carry basic-auth credentials, and an error is logged.\n */\nconst webhookUrl = (raw: string): Effect.Effect<string, AlertError> =>\n  Effect.suspend(() => {\n    const misconfigured = new AlertError({\n      code: \"sink_misconfigured\",\n      message: \"Alert webhook url must be an absolute http: or https: URL\"\n    })\n    let parsed: URL\n    try {\n      parsed = new URL(raw)\n    } catch {\n      return Effect.fail(misconfigured)\n    }\n    return parsed.protocol === \"http:\" || parsed.protocol === \"https:\"\n      ? Effect.succeed(raw)\n      : Effect.fail(misconfigured)\n  })\n\n/**\n * Runs a webhook request with redirect following switched off at the fetch\n * transport.\n *\n * The request carries whatever credential the deployment put in `headers`,\n * and a transport that follows a 3xx re-sends those headers to an origin the\n * deployment never named. Every other fetch default the composition set is\n * kept; only the redirect mode is forced. A 3xx therefore surfaces to the\n * status rule, which calls it `sink_rejected`: a redirecting pager endpoint\n * is a misconfiguration to fix, not an address to forward credentials to.\n */\nconst followingNoRedirects = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n  Effect.flatMap(\n    Effect.serviceOption(FetchHttpClient.RequestInit),\n    (init) =>\n      Effect.provideService(effect, FetchHttpClient.RequestInit, {\n        ...(Option.isSome(init) ? init.value : {}),\n        redirect: \"manual\"\n      })\n  )\n\n/**\n * A sink that POSTs each alert to one webhook.\n *\n * The body is the alert plus its {@link alertId}, and the same id is sent as\n * an `Idempotency-Key` header, because the package requires the receiver to\n * dedupe on it and a body without it cannot. The header is set after the\n * caller's headers, so it is the one this sink sends.\n *\n * The endpoint must be an absolute `http:` or `https:` URL, checked when the\n * layer is built, and the request is made with redirect following disabled:\n * the caller's headers can carry a credential, and a followed redirect would\n * re-send them to an origin the deployment never named. A 3xx answer is a\n * refusal like any other non-2xx, not a forwarding instruction. The sink owns\n * its Fetch transport; an externally supplied `HttpClient` is not used.\n * Each delivery has its own scope, which aborts the request and releases any\n * unread response body on completion, failure, timeout, or interruption.\n *\n * A non-2xx response is a failure, not a delivery, and an endpoint that never\n * answers is a failure after `timeout`. Paging is exactly the case where a\n * silently dropped request is worse than a retry, and a hung request is worse\n * than either: it is indistinguishable from silence, so it must not be\n * possible to wait on one forever.\n *\n * @param options the endpoint, any headers it needs, and how long to wait\n * @category layers\n * @since 0.1.0\n */\nexport const layerWebhook = (\n  options: {\n    readonly url: string\n    readonly headers?: Readonly<Record<string, string>> | undefined\n    readonly timeout?: Duration.Duration | undefined\n  }\n): Layer.Layer<Sink> =>\n  Layer.effect(\n    Sink,\n    Effect.gen(function*() {\n      const url = yield* Effect.orDie(webhookUrl(options.url))\n      const client = HttpClient.withScope(yield* HttpClient.HttpClient)\n      const timeout = options.timeout ?? defaultWebhookTimeout\n      return {\n        deliver: (alert) =>\n          client.execute(\n            HttpClientRequest.post(url).pipe(\n              (request) =>\n                options.headers === undefined ? request : HttpClientRequest.setHeaders(request, options.headers),\n              HttpClientRequest.setHeader(\"Idempotency-Key\", alertId(alert)),\n              HttpClientRequest.bodyJsonUnsafe({ ...alert, alertId: alertId(alert) })\n            )\n          ).pipe(\n            followingNoRedirects,\n            Effect.flatMap((response) =>\n              response.status >= 200 && response.status < 300\n                ? Effect.void\n                : Effect.fail(\n                  new AlertError({\n                    code: \"sink_rejected\",\n                    status: response.status,\n                    message: `Alert webhook answered ${response.status}`\n                  })\n                )\n            ),\n            Effect.timeout(timeout),\n            Effect.scoped,\n            Effect.catchTag(\"TimeoutError\", () =>\n              Effect.fail(\n                new AlertError({\n                  code: \"sink_timeout\",\n                  message: `Alert webhook did not answer within ${Duration.toMillis(timeout)} ms`\n                })\n              )),\n            // The transport error holds the request, and the request holds the\n            // caller's headers. Only its reason tag crosses into the failure.\n            Effect.catchTag(\"HttpClientError\", (cause) =>\n              Effect.fail(\n                new AlertError({\n                  code: \"sink_unreachable\",\n                  reason: cause.reason._tag,\n                  message: \"Alert webhook could not be reached\"\n                })\n              ))\n          )\n      }\n    })\n  ).pipe(Layer.provide(FetchHttpClient.layer))\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,oBAAgD;AAChD,sBAAiC;AACjC,iBAA4B;AAC5B,wBAAmC;AACnC,yBAAwB;AACxB,uBAAiC;AAS1B,MAAM,wBAA2C,uBAAS,QAAQ,EAAE;AAa3E,MAAM,aAAa,CAAC,QAClB,qBAAO,QAAQ,MAAM;AACnB,QAAM,gBAAgB,IAAI,4BAAW;AAAA,IACnC,MAAM;AAAA,IACN,SAAS;AAAA,EACX,CAAC;AACD,MAAI;AACJ,MAAI;AACF,aAAS,IAAI,IAAI,GAAG;AAAA,EACtB,QAAQ;AACN,WAAO,qBAAO,KAAK,aAAa;AAAA,EAClC;AACA,SAAO,OAAO,aAAa,WAAW,OAAO,aAAa,WACtD,qBAAO,QAAQ,GAAG,IAClB,qBAAO,KAAK,aAAa;AAC/B,CAAC;AAaH,MAAM,uBAAuB,CAAU,WACrC,qBAAO;AAAA,EACL,qBAAO,cAAc,gBAAgB,WAAW;AAAA,EAChD,CAAC,SACC,qBAAO,eAAe,QAAQ,gBAAgB,aAAa;AAAA,IACzD,GAAI,qBAAO,OAAO,IAAI,IAAI,KAAK,QAAQ,CAAC;AAAA,IACxC,UAAU;AAAA,EACZ,CAAC;AACL;AA6BK,MAAM,eAAe,CAC1B,YAMA,oBAAM;AAAA,EACJ;AAAA,EACA,qBAAO,IAAI,aAAY;AACrB,UAAM,MAAM,OAAO,qBAAO,MAAM,WAAW,QAAQ,GAAG,CAAC;AACvD,UAAM,SAAS,WAAW,UAAU,OAAO,WAAW,UAAU;AAChE,UAAM,UAAU,QAAQ,WAAW;AACnC,WAAO;AAAA,MACL,SAAS,CAAC,UACR,OAAO;AAAA,QACL,kBAAkB,KAAK,GAAG,EAAE;AAAA,UAC1B,CAAC,YACC,QAAQ,YAAY,SAAY,UAAU,kBAAkB,WAAW,SAAS,QAAQ,OAAO;AAAA,UACjG,kBAAkB,UAAU,uBAAmB,4BAAQ,KAAK,CAAC;AAAA,UAC7D,kBAAkB,eAAe,EAAE,GAAG,OAAO,aAAS,4BAAQ,KAAK,EAAE,CAAC;AAAA,QACxE;AAAA,MACF,EAAE;AAAA,QACA;AAAA,QACA,qBAAO;AAAA,UAAQ,CAAC,aACd,SAAS,UAAU,OAAO,SAAS,SAAS,MACxC,qBAAO,OACP,qBAAO;AAAA,YACP,IAAI,4BAAW;AAAA,cACb,MAAM;AAAA,cACN,QAAQ,SAAS;AAAA,cACjB,SAAS,0BAA0B,SAAS,MAAM;AAAA,YACpD,CAAC;AAAA,UACH;AAAA,QACJ;AAAA,QACA,qBAAO,QAAQ,OAAO;AAAA,QACtB,qBAAO;AAAA,QACP,qBAAO,SAAS,gBAAgB,MAC9B,qBAAO;AAAA,UACL,IAAI,4BAAW;AAAA,YACb,MAAM;AAAA,YACN,SAAS,uCAAuC,uBAAS,SAAS,OAAO,CAAC;AAAA,UAC5E,CAAC;AAAA,QACH,CAAC;AAAA;AAAA;AAAA,QAGH,qBAAO,SAAS,mBAAmB,CAAC,UAClC,qBAAO;AAAA,UACL,IAAI,4BAAW;AAAA,YACb,MAAM;AAAA,YACN,QAAQ,MAAM,OAAO;AAAA,YACrB,SAAS;AAAA,UACX,CAAC;AAAA,QACH,CAAC;AAAA,MACL;AAAA,IACJ;AAAA,EACF,CAAC;AACH,EAAE,KAAK,oBAAM,QAAQ,gBAAgB,KAAK,CAAC;",
+  "names": []
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/AlertPolicy.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Alert policy: what a condition is, when a journal leaves one open, and
+ * which open conditions have outlived their delay.
+ *
+ * Everything here is pure and a function of journal time, so the same entries
+ * decide the same alerts in any process at any instant past the delay. The
+ * transport that pages about them is `./layerWebhook.ts` and the journal-backed
+ * tick that drives them is `./AlertRuntime.ts`; `./Alerts.ts` is the module a
+ * consumer imports.
+ *
+ * @since 1.0.0
+ */
+import type { JournalEvent } from "@smthrs/journal";
+import { Schema } from "effect";
+/**
+ * The journal event type one delivered alert is recorded under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const deliveredEventType = "flows.alerts.delivered";
+/**
+ * The journal event type one failed delivery attempt is recorded under.
+ *
+ * One entry is written per alert per failure code, never one per tick: a
+ * webhook that stays down for an hour leaves one record, not a hundred and
+ * twenty that every later tick has to read past.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const failedEventType = "flows.alerts.failed";
+/**
+ * How loud an alert is.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Severity: Schema.Literals<readonly ["info", "warning", "critical"]>;
+/**
+ * How loud an alert is.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Severity = typeof Severity.Type;
+/**
+ * How a condition is recognized in the journal.
+ *
+ * `field` names a payload key, `value` the value that means the condition
+ * holds, and `eventTypes` narrows which entries are consulted at all. An
+ * `eventTypes` item ending in `.*` names a family: `control.*` consults
+ * `control.run.parked` and `control.monitor.beat` alike. An entry that carries
+ * the field with a different value CLOSES the condition, which is what makes a
+ * resume clear an approval alert without a second vocabulary for "cleared".
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Detector: Schema.Struct<{
+    readonly field: Schema.NonEmptyString;
+    readonly value: Schema.NonEmptyString;
+    readonly eventTypes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+}>;
+/**
+ * How a condition is recognized in the journal.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Detector = typeof Detector.Type;
+/**
+ * What to do about one condition, and after how long.
+ *
+ * `afterMs` is a whole, non-negative number of milliseconds. The bound is the
+ * schema's job because the delay is also arithmetic on journal time: a `NaN`
+ * delay fires on the first tick and stamps a `firedAt` that JSON writes as
+ * `null`, and a negative one fires with a `firedAt` earlier than the condition
+ * it describes.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Rule: Schema.Struct<{
+    readonly afterMs: Schema.Int;
+    readonly severity: Schema.optional<Schema.Literals<readonly ["info", "warning", "critical"]>>;
+    readonly owner: Schema.optional<Schema.String>;
+    readonly runbook: Schema.optional<Schema.String>;
+}>;
+/**
+ * What to do about one condition, and after how long.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Rule = typeof Rule.Type;
+/**
+ * The conditions a policy alerts on and the delays it alerts after.
+ *
+ * `defaults` fills in what a rule leaves out, so a policy states the delay per
+ * condition and the ownership once.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Policy: Schema.Struct<{
+    readonly defaults: Schema.optional<Schema.Struct<{
+        readonly severity: Schema.optional<Schema.Literals<readonly ["info", "warning", "critical"]>>;
+        readonly owner: Schema.optional<Schema.String>;
+        readonly runbook: Schema.optional<Schema.String>;
+    }>>;
+    readonly rules: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly afterMs: Schema.Int;
+        readonly severity: Schema.optional<Schema.Literals<readonly ["info", "warning", "critical"]>>;
+        readonly owner: Schema.optional<Schema.String>;
+        readonly runbook: Schema.optional<Schema.String>;
+    }>>;
+    /** Detectors for conditions this deployment names itself. */
+    readonly detectors: Schema.optional<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly field: Schema.NonEmptyString;
+        readonly value: Schema.NonEmptyString;
+        readonly eventTypes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>>>;
+}>;
+/**
+ * The conditions a policy alerts on and the delays it alerts after.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Policy = typeof Policy.Type;
+/**
+ * The four conditions a control plane journals out of the box.
+ *
+ * `status` rides on every `control.run.*` entry, and `health` on every
+ * `control.monitor.beat`. A deployment whose supervisor journals a park reason
+ * gets `quota-parked` from the same field the run summary reports it under.
+ *
+ * Each consults the `control.*` family only. A run's journal is shared with
+ * flow steps, agent traces, and anything else that writes to the run, and a
+ * `status` or `health` field on one of those entries would otherwise open or
+ * close a condition the control plane never reported.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultDetectors: Readonly<Record<string, Detector>>;
+/**
+ * A condition that is open on a run, and when it opened.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Open {
+    readonly runId: string;
+    readonly condition: string;
+    /** The journal time of the entry that opened the condition. */
+    readonly since: number;
+}
+/**
+ * One alert a policy decided to raise.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Alert {
+    readonly runId: string;
+    readonly condition: string;
+    readonly since: number;
+    /**
+     * The journal instant the condition outlived its delay: `since` plus the
+     * rule's `afterMs`, never the wall clock of whichever tick noticed.
+     */
+    readonly firedAt: number;
+    readonly severity: Severity;
+    readonly coalescingKey: string;
+    readonly owner?: string | undefined;
+    readonly runbook?: string | undefined;
+}
+/**
+ * The journal source the alerter writes one outcome of one alert under.
+ *
+ * A delivery record counts as evidence that an alert went out only under this
+ * source, so another producer's `flows.alerts.delivered` record with a
+ * matching `alertId` does not suppress a page. This scopes records; it does
+ * not authenticate the writer, because the journal does not bind a source to
+ * a writer.
+ *
+ * @param id the alert's {@link alertId}
+ * @param outcome `delivered`, `refused`, or `failed/<code>`
+ * @private
+ * @since 1.0.0
+ */
+export declare const recordSourceId: (id: string, outcome: string) => string;
+/**
+ * The key an alert coalesces on: one open condition on one run.
+ *
+ * Each component is percent-encoded before it is joined, so a run id or a
+ * condition name containing the separator cannot forge another pair's key and
+ * suppress a page that belongs to somebody else. Both components are values a
+ * deployment chooses, which is why the encoding is not optional.
+ *
+ * @param runId the run the condition is open on
+ * @param condition the condition name the policy uses
+ * @category getters
+ * @since 1.0.0
+ */
+export declare const coalescingKey: (runId: string, condition: string) => string;
+/**
+ * The identity a delivery is recorded under.
+ *
+ * The opening time is part of it on purpose. A condition that clears and
+ * re-opens is a NEW alert, because the second approval wait is not the first
+ * one, and a key without the time would suppress it forever.
+ *
+ * @param alert the alert
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const alertId: (alert: Pick<Alert, "coalescingKey" | "since">) => string;
+/**
+ * The detectors one policy decides with: the four this package ships, with
+ * the deployment's own overriding them by name.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const detectorsOf: (policy: Policy) => Readonly<Record<string, Detector>>;
+/**
+ * One entry's payload when it is a record a detector can read a field off,
+ * and `undefined` for the arrays and primitives that carry no fields at all.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const payloadRecord: (payload: unknown) => Readonly<Record<string, unknown>> | undefined;
+/**
+ * Folds one entry into the open-condition map. Shared by {@link conditions}
+ * and the runtime's incremental read, so both decide a condition the same
+ * way.
+ *
+ * The alerter's own records are never evidence about a condition. They are
+ * written into the same journal they are read from, and they carry the alert's
+ * own vocabulary: a refusal reports the answering HTTP `status`, which a
+ * detector watching the run's `status` would read as the condition clearing.
+ * A page would then close the condition it paged about and the next tick would
+ * re-open it, so a webhook that answered 503 once would alert forever.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const observe: (policy: Policy, detectors: Readonly<Record<string, Detector>>, entry: JournalEvent.Entry, payload: Readonly<Record<string, unknown>>, open: Map<string, number>) => void;
+/**
+ * Every condition a run's journal leaves open, with the time each opened.
+ *
+ * An entry that carries a detector's field opens the condition when the value
+ * matches and closes it when it does not. Entries the detector does not name
+ * are ignored entirely, so a monitor beat cannot close an approval wait and an
+ * approval cannot close a stall.
+ *
+ * @param policy the policy whose detectors decide what counts
+ * @param runId the run the entries belong to
+ * @param entries the run's journal, oldest first
+ * @category projections
+ * @since 0.1.0
+ */
+export declare const conditions: (policy: Policy, runId: string, entries: ReadonlyArray<JournalEvent.Entry>) => ReadonlyArray<Open>;
+/**
+ * The alerts a policy raises for the conditions open at `now`.
+ *
+ * Pure, and a function of journal time: the same journal raises the same
+ * alerts in any process, at any instant past the delay. `now` decides WHETHER
+ * an alert is raised; it never appears in one. A condition that has been open
+ * for less than its rule's delay raises nothing, which is the whole point of
+ * the delay, because most stalls clear themselves.
+ *
+ * @param policy the policy
+ * @param open the conditions the journal left open
+ * @param now the instant to judge them at
+ * @category projections
+ * @since 0.1.0
+ */
+export declare const decide: (policy: Policy, open: ReadonlyArray<Open>, now: number) => ReadonlyArray<Alert>;
+//# sourceMappingURL=AlertPolicy.d.ts.map

package/dist/esm/AlertPolicy.d.ts.map

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

package/dist/esm/AlertPolicy.js

@@ -0,0 +1,284 @@
+/**
+ * Alert policy: what a condition is, when a journal leaves one open, and
+ * which open conditions have outlived their delay.
+ *
+ * Everything here is pure and a function of journal time, so the same entries
+ * decide the same alerts in any process at any instant past the delay. The
+ * transport that pages about them is `./layerWebhook.ts` and the journal-backed
+ * tick that drives them is `./AlertRuntime.ts`; `./Alerts.ts` is the module a
+ * consumer imports.
+ *
+ * @since 1.0.0
+ */
+import { Schema } from "effect";
+/**
+ * The journal event type one delivered alert is recorded under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const deliveredEventType = "flows.alerts.delivered";
+/**
+ * The journal event type one failed delivery attempt is recorded under.
+ *
+ * One entry is written per alert per failure code, never one per tick: a
+ * webhook that stays down for an hour leaves one record, not a hundred and
+ * twenty that every later tick has to read past.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const failedEventType = "flows.alerts.failed";
+/**
+ * How loud an alert is.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Severity = Schema.Literals(["info", "warning", "critical"]);
+/**
+ * How a condition is recognized in the journal.
+ *
+ * `field` names a payload key, `value` the value that means the condition
+ * holds, and `eventTypes` narrows which entries are consulted at all. An
+ * `eventTypes` item ending in `.*` names a family: `control.*` consults
+ * `control.run.parked` and `control.monitor.beat` alike. An entry that carries
+ * the field with a different value CLOSES the condition, which is what makes a
+ * resume clear an approval alert without a second vocabulary for "cleared".
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Detector = Schema.Struct({
+    field: Schema.NonEmptyString,
+    value: Schema.NonEmptyString,
+    eventTypes: Schema.optional(Schema.Array(Schema.NonEmptyString))
+});
+/**
+ * What to do about one condition, and after how long.
+ *
+ * `afterMs` is a whole, non-negative number of milliseconds. The bound is the
+ * schema's job because the delay is also arithmetic on journal time: a `NaN`
+ * delay fires on the first tick and stamps a `firedAt` that JSON writes as
+ * `null`, and a negative one fires with a `firedAt` earlier than the condition
+ * it describes.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Rule = Schema.Struct({
+    afterMs: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+    severity: Schema.optional(Severity),
+    owner: Schema.optional(Schema.String),
+    runbook: Schema.optional(Schema.String)
+});
+/**
+ * The conditions a policy alerts on and the delays it alerts after.
+ *
+ * `defaults` fills in what a rule leaves out, so a policy states the delay per
+ * condition and the ownership once.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Policy = Schema.Struct({
+    defaults: Schema.optional(Schema.Struct({
+        severity: Schema.optional(Severity),
+        owner: Schema.optional(Schema.String),
+        runbook: Schema.optional(Schema.String)
+    })),
+    rules: Schema.Record(Schema.String, Rule),
+    /** Detectors for conditions this deployment names itself. */
+    detectors: Schema.optional(Schema.Record(Schema.String, Detector))
+});
+/**
+ * The four conditions a control plane journals out of the box.
+ *
+ * `status` rides on every `control.run.*` entry, and `health` on every
+ * `control.monitor.beat`. A deployment whose supervisor journals a park reason
+ * gets `quota-parked` from the same field the run summary reports it under.
+ *
+ * Each consults the `control.*` family only. A run's journal is shared with
+ * flow steps, agent traces, and anything else that writes to the run, and a
+ * `status` or `health` field on one of those entries would otherwise open or
+ * close a condition the control plane never reported.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const defaultDetectors = {
+    "waiting-approval": { field: "status", value: "waiting-approval", eventTypes: ["control.*"] },
+    failed: { field: "status", value: "failed", eventTypes: ["control.*"] },
+    stalled: { field: "health", value: "stalled", eventTypes: ["control.*"] },
+    "quota-parked": { field: "waitingReason", value: "quota", eventTypes: ["control.*"] }
+};
+/**
+ * Whether a detector's `eventTypes` names an entry's event type, exactly or
+ * through a `.*` family.
+ */
+const names = (eventTypes, eventType) => eventTypes.some((named) => named.endsWith(".*") ? eventType.startsWith(named.slice(0, -1)) : named === eventType);
+/**
+ * The journal source the alerter writes one outcome of one alert under.
+ *
+ * A delivery record counts as evidence that an alert went out only under this
+ * source, so another producer's `flows.alerts.delivered` record with a
+ * matching `alertId` does not suppress a page. This scopes records; it does
+ * not authenticate the writer, because the journal does not bind a source to
+ * a writer.
+ *
+ * @param id the alert's {@link alertId}
+ * @param outcome `delivered`, `refused`, or `failed/<code>`
+ * @private
+ * @since 1.0.0
+ */
+export const recordSourceId = (id, outcome) => `/notifications/alerts/${id}/${outcome}`;
+/**
+ * The key an alert coalesces on: one open condition on one run.
+ *
+ * Each component is percent-encoded before it is joined, so a run id or a
+ * condition name containing the separator cannot forge another pair's key and
+ * suppress a page that belongs to somebody else. Both components are values a
+ * deployment chooses, which is why the encoding is not optional.
+ *
+ * @param runId the run the condition is open on
+ * @param condition the condition name the policy uses
+ * @category getters
+ * @since 1.0.0
+ */
+export const coalescingKey = (runId, condition) => `${encodeURIComponent(runId)}:${encodeURIComponent(condition)}`;
+/**
+ * The identity a delivery is recorded under.
+ *
+ * The opening time is part of it on purpose. A condition that clears and
+ * re-opens is a NEW alert, because the second approval wait is not the first
+ * one, and a key without the time would suppress it forever.
+ *
+ * @param alert the alert
+ * @category getters
+ * @since 0.1.0
+ */
+export const alertId = (alert) => `alert:${alert.coalescingKey}:${alert.since}`;
+/**
+ * The detectors one policy decides with: the four this package ships, with
+ * the deployment's own overriding them by name.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const detectorsOf = (policy) => ({
+    ...defaultDetectors,
+    ...policy.detectors
+});
+/**
+ * One entry's payload when it is a record a detector can read a field off,
+ * and `undefined` for the arrays and primitives that carry no fields at all.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const payloadRecord = (payload) => typeof payload === "object" && payload !== null && !Array.isArray(payload)
+    ? payload
+    : undefined;
+/**
+ * Folds one entry into the open-condition map. Shared by {@link conditions}
+ * and the runtime's incremental read, so both decide a condition the same
+ * way.
+ *
+ * The alerter's own records are never evidence about a condition. They are
+ * written into the same journal they are read from, and they carry the alert's
+ * own vocabulary: a refusal reports the answering HTTP `status`, which a
+ * detector watching the run's `status` would read as the condition clearing.
+ * A page would then close the condition it paged about and the next tick would
+ * re-open it, so a webhook that answered 503 once would alert forever.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const observe = (policy, detectors, entry, payload, open) => {
+    if (entry.eventType === deliveredEventType || entry.eventType === failedEventType)
+        return;
+    for (const condition of Object.keys(policy.rules)) {
+        const detector = detectors[condition];
+        if (detector === undefined)
+            continue;
+        if (detector.eventTypes !== undefined && !names(detector.eventTypes, entry.eventType))
+            continue;
+        // Own properties only. `in` walks `Object.prototype`, so a detector named
+        // `toString` or `constructor` would read every record-shaped entry in the
+        // run as evidence and close the condition on all of them.
+        if (!Object.hasOwn(payload, detector.field))
+            continue;
+        if (payload[detector.field] === detector.value) {
+            if (!open.has(condition))
+                open.set(condition, entry.emittedAtMs);
+        }
+        else {
+            open.delete(condition);
+        }
+    }
+};
+/**
+ * Every condition a run's journal leaves open, with the time each opened.
+ *
+ * An entry that carries a detector's field opens the condition when the value
+ * matches and closes it when it does not. Entries the detector does not name
+ * are ignored entirely, so a monitor beat cannot close an approval wait and an
+ * approval cannot close a stall.
+ *
+ * @param policy the policy whose detectors decide what counts
+ * @param runId the run the entries belong to
+ * @param entries the run's journal, oldest first
+ * @category projections
+ * @since 0.1.0
+ */
+export const conditions = (policy, runId, entries) => {
+    const detectors = detectorsOf(policy);
+    const open = new Map();
+    for (const entry of entries) {
+        const payload = payloadRecord(entry.payload);
+        if (payload === undefined)
+            continue;
+        observe(policy, detectors, entry, payload, open);
+    }
+    return Array.from(open, ([condition, since]) => ({ runId, condition, since }));
+};
+/**
+ * The alerts a policy raises for the conditions open at `now`.
+ *
+ * Pure, and a function of journal time: the same journal raises the same
+ * alerts in any process, at any instant past the delay. `now` decides WHETHER
+ * an alert is raised; it never appears in one. A condition that has been open
+ * for less than its rule's delay raises nothing, which is the whole point of
+ * the delay, because most stalls clear themselves.
+ *
+ * @param policy the policy
+ * @param open the conditions the journal left open
+ * @param now the instant to judge them at
+ * @category projections
+ * @since 0.1.0
+ */
+export const decide = (policy, open, now) => open.flatMap((condition) => {
+    const rule = policy.rules[condition.condition];
+    if (rule === undefined)
+        return [];
+    if (now - condition.since < rule.afterMs)
+        return [];
+    const severity = rule.severity ?? policy.defaults?.severity ?? "warning";
+    const owner = rule.owner ?? policy.defaults?.owner;
+    const runbook = rule.runbook ?? policy.defaults?.runbook;
+    return [{
+            runId: condition.runId,
+            condition: condition.condition,
+            since: condition.since,
+            // Derived from the journal, not read off the clock. The alert id is
+            // stable across ticks, and the queue refuses a reused id whose content
+            // changed, so an alert stamped with the reading time would become
+            // permanently undeliverable the moment a tick refused and time moved on.
+            firedAt: condition.since + rule.afterMs,
+            severity,
+            coalescingKey: coalescingKey(condition.runId, condition.condition),
+            ...(owner === undefined ? {} : { owner }),
+            ...(runbook === undefined ? {} : { runbook })
+        }];
+});
+//# sourceMappingURL=AlertPolicy.js.map

package/dist/esm/AlertPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlertPolicy.js","sourceRoot":"","sources":["../../src/AlertPolicy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Alert policy: what a condition is, when a journal leaves one open, and\n * which open conditions have outlived their delay.\n *\n * Everything here is pure and a function of journal time, so the same entries\n * decide the same alerts in any process at any instant past the delay. The\n * transport that pages about them is `./layerWebhook.ts` and the journal-backed\n * tick that drives them is `./AlertRuntime.ts`; `./Alerts.ts` is the module a\n * consumer imports.\n *\n * @since 1.0.0\n */\n\nimport type { JournalEvent } from \"@smthrs/journal\"\nimport { Schema } from \"effect\"\n\n/**\n * The journal event type one delivered alert is recorded under.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const deliveredEventType = \"flows.alerts.delivered\"\n\n/**\n * The journal event type one failed delivery attempt is recorded under.\n *\n * One entry is written per alert per failure code, never one per tick: a\n * webhook that stays down for an hour leaves one record, not a hundred and\n * twenty that every later tick has to read past.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const failedEventType = \"flows.alerts.failed\"\n\n/**\n * How loud an alert is.\n *\n * @category models\n * @since 0.1.0\n */\nexport const Severity = Schema.Literals([\"info\", \"warning\", \"critical\"])\n\n/**\n * How loud an alert is.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Severity = typeof Severity.Type\n\n/**\n * How a condition is recognized in the journal.\n *\n * `field` names a payload key, `value` the value that means the condition\n * holds, and `eventTypes` narrows which entries are consulted at all. An\n * `eventTypes` item ending in `.*` names a family: `control.*` consults\n * `control.run.parked` and `control.monitor.beat` alike. An entry that carries\n * the field with a different value CLOSES the condition, which is what makes a\n * resume clear an approval alert without a second vocabulary for \"cleared\".\n *\n * @category models\n * @since 0.1.0\n */\nexport const Detector = Schema.Struct({\n  field: Schema.NonEmptyString,\n  value: Schema.NonEmptyString,\n  eventTypes: Schema.optional(Schema.Array(Schema.NonEmptyString))\n})\n\n/**\n * How a condition is recognized in the journal.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Detector = typeof Detector.Type\n\n/**\n * What to do about one condition, and after how long.\n *\n * `afterMs` is a whole, non-negative number of milliseconds. The bound is the\n * schema's job because the delay is also arithmetic on journal time: a `NaN`\n * delay fires on the first tick and stamps a `firedAt` that JSON writes as\n * `null`, and a negative one fires with a `firedAt` earlier than the condition\n * it describes.\n *\n * @category models\n * @since 0.1.0\n */\nexport const Rule = Schema.Struct({\n  afterMs: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),\n  severity: Schema.optional(Severity),\n  owner: Schema.optional(Schema.String),\n  runbook: Schema.optional(Schema.String)\n})\n\n/**\n * What to do about one condition, and after how long.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Rule = typeof Rule.Type\n\n/**\n * The conditions a policy alerts on and the delays it alerts after.\n *\n * `defaults` fills in what a rule leaves out, so a policy states the delay per\n * condition and the ownership once.\n *\n * @category models\n * @since 0.1.0\n */\nexport const Policy = Schema.Struct({\n  defaults: Schema.optional(Schema.Struct({\n    severity: Schema.optional(Severity),\n    owner: Schema.optional(Schema.String),\n    runbook: Schema.optional(Schema.String)\n  })),\n  rules: Schema.Record(Schema.String, Rule),\n  /** Detectors for conditions this deployment names itself. */\n  detectors: Schema.optional(Schema.Record(Schema.String, Detector))\n})\n\n/**\n * The conditions a policy alerts on and the delays it alerts after.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Policy = typeof Policy.Type\n\n/**\n * The four conditions a control plane journals out of the box.\n *\n * `status` rides on every `control.run.*` entry, and `health` on every\n * `control.monitor.beat`. A deployment whose supervisor journals a park reason\n * gets `quota-parked` from the same field the run summary reports it under.\n *\n * Each consults the `control.*` family only. A run's journal is shared with\n * flow steps, agent traces, and anything else that writes to the run, and a\n * `status` or `health` field on one of those entries would otherwise open or\n * close a condition the control plane never reported.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const defaultDetectors: Readonly<Record<string, Detector>> = {\n  \"waiting-approval\": { field: \"status\", value: \"waiting-approval\", eventTypes: [\"control.*\"] },\n  failed: { field: \"status\", value: \"failed\", eventTypes: [\"control.*\"] },\n  stalled: { field: \"health\", value: \"stalled\", eventTypes: [\"control.*\"] },\n  \"quota-parked\": { field: \"waitingReason\", value: \"quota\", eventTypes: [\"control.*\"] }\n}\n\n/**\n * Whether a detector's `eventTypes` names an entry's event type, exactly or\n * through a `.*` family.\n */\nconst names = (eventTypes: ReadonlyArray<string>, eventType: string): boolean =>\n  eventTypes.some((named) => named.endsWith(\".*\") ? eventType.startsWith(named.slice(0, -1)) : named === eventType)\n\n/**\n * A condition that is open on a run, and when it opened.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Open {\n  readonly runId: string\n  readonly condition: string\n  /** The journal time of the entry that opened the condition. */\n  readonly since: number\n}\n\n/**\n * One alert a policy decided to raise.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Alert {\n  readonly runId: string\n  readonly condition: string\n  readonly since: number\n  /**\n   * The journal instant the condition outlived its delay: `since` plus the\n   * rule's `afterMs`, never the wall clock of whichever tick noticed.\n   */\n  readonly firedAt: number\n  readonly severity: Severity\n  readonly coalescingKey: string\n  readonly owner?: string | undefined\n  readonly runbook?: string | undefined\n}\n\n/**\n * The journal source the alerter writes one outcome of one alert under.\n *\n * A delivery record counts as evidence that an alert went out only under this\n * source, so another producer's `flows.alerts.delivered` record with a\n * matching `alertId` does not suppress a page. This scopes records; it does\n * not authenticate the writer, because the journal does not bind a source to\n * a writer.\n *\n * @param id the alert's {@link alertId}\n * @param outcome `delivered`, `refused`, or `failed/<code>`\n * @private\n * @since 1.0.0\n */\nexport const recordSourceId = (id: string, outcome: string): string => `/notifications/alerts/${id}/${outcome}`\n\n/**\n * The key an alert coalesces on: one open condition on one run.\n *\n * Each component is percent-encoded before it is joined, so a run id or a\n * condition name containing the separator cannot forge another pair's key and\n * suppress a page that belongs to somebody else. Both components are values a\n * deployment chooses, which is why the encoding is not optional.\n *\n * @param runId the run the condition is open on\n * @param condition the condition name the policy uses\n * @category getters\n * @since 1.0.0\n */\nexport const coalescingKey = (runId: string, condition: string): string =>\n  `${encodeURIComponent(runId)}:${encodeURIComponent(condition)}`\n\n/**\n * The identity a delivery is recorded under.\n *\n * The opening time is part of it on purpose. A condition that clears and\n * re-opens is a NEW alert, because the second approval wait is not the first\n * one, and a key without the time would suppress it forever.\n *\n * @param alert the alert\n * @category getters\n * @since 0.1.0\n */\nexport const alertId = (alert: Pick<Alert, \"coalescingKey\" | \"since\">): string =>\n  `alert:${alert.coalescingKey}:${alert.since}`\n\n/**\n * The detectors one policy decides with: the four this package ships, with\n * the deployment's own overriding them by name.\n *\n * @private\n * @since 1.0.0\n */\nexport const detectorsOf = (policy: Policy): Readonly<Record<string, Detector>> => ({\n  ...defaultDetectors,\n  ...policy.detectors\n})\n\n/**\n * One entry's payload when it is a record a detector can read a field off,\n * and `undefined` for the arrays and primitives that carry no fields at all.\n *\n * @private\n * @since 1.0.0\n */\nexport const payloadRecord = (payload: unknown): Readonly<Record<string, unknown>> | undefined =>\n  typeof payload === \"object\" && payload !== null && !Array.isArray(payload)\n    ? payload as Readonly<Record<string, unknown>>\n    : undefined\n\n/**\n * Folds one entry into the open-condition map. Shared by {@link conditions}\n * and the runtime's incremental read, so both decide a condition the same\n * way.\n *\n * The alerter's own records are never evidence about a condition. They are\n * written into the same journal they are read from, and they carry the alert's\n * own vocabulary: a refusal reports the answering HTTP `status`, which a\n * detector watching the run's `status` would read as the condition clearing.\n * A page would then close the condition it paged about and the next tick would\n * re-open it, so a webhook that answered 503 once would alert forever.\n *\n * @private\n * @since 1.0.0\n */\nexport const observe = (\n  policy: Policy,\n  detectors: Readonly<Record<string, Detector>>,\n  entry: JournalEvent.Entry,\n  payload: Readonly<Record<string, unknown>>,\n  open: Map<string, number>\n): void => {\n  if (entry.eventType === deliveredEventType || entry.eventType === failedEventType) return\n  for (const condition of Object.keys(policy.rules)) {\n    const detector = detectors[condition]\n    if (detector === undefined) continue\n    if (detector.eventTypes !== undefined && !names(detector.eventTypes, entry.eventType)) continue\n    // Own properties only. `in` walks `Object.prototype`, so a detector named\n    // `toString` or `constructor` would read every record-shaped entry in the\n    // run as evidence and close the condition on all of them.\n    if (!Object.hasOwn(payload, detector.field)) continue\n    if (payload[detector.field] === detector.value) {\n      if (!open.has(condition)) open.set(condition, entry.emittedAtMs)\n    } else {\n      open.delete(condition)\n    }\n  }\n}\n\n/**\n * Every condition a run's journal leaves open, with the time each opened.\n *\n * An entry that carries a detector's field opens the condition when the value\n * matches and closes it when it does not. Entries the detector does not name\n * are ignored entirely, so a monitor beat cannot close an approval wait and an\n * approval cannot close a stall.\n *\n * @param policy the policy whose detectors decide what counts\n * @param runId the run the entries belong to\n * @param entries the run's journal, oldest first\n * @category projections\n * @since 0.1.0\n */\nexport const conditions = (\n  policy: Policy,\n  runId: string,\n  entries: ReadonlyArray<JournalEvent.Entry>\n): ReadonlyArray<Open> => {\n  const detectors = detectorsOf(policy)\n  const open = new Map<string, number>()\n  for (const entry of entries) {\n    const payload = payloadRecord(entry.payload)\n    if (payload === undefined) continue\n    observe(policy, detectors, entry, payload, open)\n  }\n  return Array.from(open, ([condition, since]) => ({ runId, condition, since }))\n}\n\n/**\n * The alerts a policy raises for the conditions open at `now`.\n *\n * Pure, and a function of journal time: the same journal raises the same\n * alerts in any process, at any instant past the delay. `now` decides WHETHER\n * an alert is raised; it never appears in one. A condition that has been open\n * for less than its rule's delay raises nothing, which is the whole point of\n * the delay, because most stalls clear themselves.\n *\n * @param policy the policy\n * @param open the conditions the journal left open\n * @param now the instant to judge them at\n * @category projections\n * @since 0.1.0\n */\nexport const decide = (\n  policy: Policy,\n  open: ReadonlyArray<Open>,\n  now: number\n): ReadonlyArray<Alert> =>\n  open.flatMap((condition) => {\n    const rule = policy.rules[condition.condition]\n    if (rule === undefined) return []\n    if (now - condition.since < rule.afterMs) return []\n    const severity = rule.severity ?? policy.defaults?.severity ?? \"warning\"\n    const owner = rule.owner ?? policy.defaults?.owner\n    const runbook = rule.runbook ?? policy.defaults?.runbook\n    return [{\n      runId: condition.runId,\n      condition: condition.condition,\n      since: condition.since,\n      // Derived from the journal, not read off the clock. The alert id is\n      // stable across ticks, and the queue refuses a reused id whose content\n      // changed, so an alert stamped with the reading time would become\n      // permanently undeliverable the moment a tick refused and time moved on.\n      firedAt: condition.since + rule.afterMs,\n      severity,\n      coalescingKey: coalescingKey(condition.runId, condition.condition),\n      ...(owner === undefined ? {} : { owner }),\n      ...(runbook === undefined ? {} : { runbook })\n    }]\n  })\n"]}