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

package/src/AlertSink.ts

@@ -0,0 +1,105 @@
+/**
+ * The alert sink port: where a raised alert is sent, and why a send failed.
+ *
+ * The port is a tag and an error so a deployment supplies the transport and
+ * the policy needs none. `./layerWebhook.ts` is the transport this package
+ * ships, and {@link layerNoop} is the one a test composes.
+ *
+ * @since 1.0.0
+ */
+
+import { Context, Effect, Layer, Schema } from "effect"
+import type { Alert } from "./AlertPolicy.ts"
+
+/**
+ * Why a sink did not take an alert.
+ *
+ * `sink_rejected` is an answer that refused the page, `sink_unreachable` a
+ * request that never got one, and `sink_timeout` one that got no answer inside
+ * the sink's bound. `sink_misconfigured` is an endpoint the sink may not POST
+ * to at all; it is raised when the layer is built, before any alert exists,
+ * so it never reaches a journal.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const FailureCode = Schema.Literals(["sink_rejected", "sink_unreachable", "sink_timeout", "sink_misconfigured"])
+
+/**
+ * Why a sink did not take an alert.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type FailureCode = typeof FailureCode.Type
+
+/**
+ * A sink refused or could not take an alert.
+ *
+ * The error carries a code, the answering status when there was one, and a
+ * short reason. It deliberately holds no request: a webhook request carries
+ * the credential the deployment handed {@link layerWebhook}, and an error is
+ * logged, encoded, and journaled in places a credential must never reach.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class AlertError extends Schema.TaggedError<AlertError>()(
+  "/notifications/AlertError",
+  {
+    code: FailureCode.pipe(Schema.withConstructorDefault(Effect.succeed("sink_rejected" as const))),
+    message: Schema.String,
+    /** The HTTP status that refused the page, when the sink speaks HTTP. */
+    status: Schema.optional(Schema.Int),
+    /** A short, credential-free description of the transport failure. */
+    reason: Schema.optional(Schema.String)
+  }
+) {}
+
+/**
+ * Where a raised alert is sent.
+ *
+ * Injected rather than fixed, because who gets paged is a deployment's
+ * decision and the policy is not: the same rules feed a webhook in production
+ * and nothing at all in a test.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface SinkService {
+  /**
+   * Sends one alert, and does so idempotently on {@link alertId}.
+   *
+   * Delivery is at-least-once: the `flows.alerts.delivered` record is written
+   * after this effect succeeds, so a process that dies in between pages again
+   * on the next tick. Every field of the alert, {@link Alert.firedAt}
+   * included, is derived from the journal, so the same alert is byte-identical
+   * on every attempt and `alertId(alert)` is the deduplication key a receiving
+   * system should key on. A sink that cannot dedupe is a sink that will
+   * occasionally page twice about one condition.
+   *
+   * A failure means the page did not go out. Succeeding on a page that was
+   * dropped is the one thing this port must never do.
+   */
+  readonly deliver: (alert: Alert) => Effect.Effect<void, AlertError>
+}
+
+/**
+ * The {@link SinkService} tag.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class Sink extends Context.Service<Sink, SinkService>()("/notifications/AlertSink") {}
+
+/**
+ * A sink that accepts every alert and sends it nowhere.
+ *
+ * The admission and the delivery record still happen, so a composition without
+ * an outbound channel still has the durable evidence of what it would have
+ * paged about.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop: Layer.Layer<Sink> = Layer.succeed(Sink)({ deliver: () => Effect.void })

package/src/Alerts.ts

@@ -0,0 +1,71 @@
+/**
+ * Alert policy: run conditions that have lasted too long, turned into durable,
+ * coalesced, delivered-once notifications.
+ *
+ * A notification queue answers "tell this run something". An alert answers the
+ * question nobody is around to ask: a run has been waiting for an approval for
+ * an hour, and the person who could grant it does not know. The two are the
+ * same machinery, since an alert is admitted as a coalesced system event, and
+ * they differ only in who decides to write one.
+ *
+ * ## Journal time, not wall time
+ *
+ * A condition's clock starts at the journal entry that opened it, which makes
+ * the decision replayable: the same journal produces the same alerts, whatever
+ * process reads it and whenever. A restart re-derives every open condition
+ * from the entries rather than from a timer it lost.
+ *
+ * ## Delivered at least once
+ *
+ * The admission is idempotent on the notification id, so re-admitting the same
+ * alert writes nothing new, and `flows.alerts.delivered` is journaled AFTER
+ * the sink accepted the page and is checked before the sink is called again.
+ * That ordering is deliberate and it is the reason the guarantee is
+ * at-least-once rather than exactly-once: a process that dies between the
+ * accepted send and the delivery record has paged, left no evidence of it, and
+ * will page again on the next tick. Recording the delivery first turns the
+ * same crash into a page nobody ever receives, which for an alert is the worse
+ * failure.
+ *
+ * So the sink owns the last mile: {@link SinkService.deliver} MUST be
+ * idempotent on {@link alertId}, which is stable for the life of one condition
+ * and reaches the sink on every alert it is handed. A sink that fails journals
+ * `flows.alerts.failed` once per failure code and the alert is retried on the
+ * next tick, because a refused page is not a delivered page.
+ *
+ * ## What a refusal costs
+ *
+ * The queue can refuse the admission when a run already holds its capacity of
+ * pending notifications. A tick that is refused pages nobody: the alert comes
+ * back in {@link Tick.refused}, the refusal is journaled, and the next tick
+ * tries again once a boundary has drained. Calling the sink anyway would page
+ * about an alert the run will never see.
+ *
+ * ## Conditions are data
+ *
+ * A condition is a payload field with a value: `status` is `waiting-approval`,
+ * `health` is `stalled`. Those are the fields control-plane entries and monitor
+ * beats already carry, so a deployment that journals a different vocabulary
+ * supplies its own detectors instead of a fork of this module.
+ *
+ * @since 0.1.0
+ */
+
+export {
+  type Alert,
+  alertId,
+  coalescingKey,
+  conditions,
+  decide,
+  defaultDetectors,
+  deliveredEventType,
+  Detector,
+  failedEventType,
+  type Open,
+  Policy,
+  Rule,
+  Severity
+} from "./AlertPolicy.ts"
+export { AlertRuntime, layer, type RuntimeService, type Tick } from "./AlertRuntime.ts"
+export { AlertError, FailureCode, layerNoop, Sink, type SinkService } from "./AlertSink.ts"
+export { defaultWebhookTimeout, layerWebhook } from "./layerWebhook.ts"

package/src/Notification.ts

@@ -0,0 +1,171 @@
+/**
+ * Durable notification payloads and their admission classification.
+ *
+ * @since 0.1.0
+ */
+
+import { Schema } from "effect"
+
+/**
+ * Producer-supplied attribution carried as data alongside the authenticated
+ * source actor. These labels never authorize a notification or a model action.
+ * They pass through the journal's ordinary redaction policy.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const Attribution = Schema.Record(Schema.String, Schema.String)
+
+/**
+ * Durable origin of a notification: who said it, from where, and at which
+ * turn.
+ *
+ * Provenance travels with the notification because the run that receives one
+ * is not the run that wrote it. An operator steer, a parent run's event, and a
+ * webhook all arrive on the same queue, and only these fields say which is
+ * which after the fact.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Provenance = Schema.Struct({
+  sourceRunId: Schema.String,
+  sourceLineageId: Schema.String,
+  sourceTurn: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+  sourceActor: Schema.String,
+  attribution: Schema.optional(Attribution)
+})
+
+/**
+ * The decoded form of {@link Provenance}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Provenance = typeof Provenance.Type
+
+const common = {
+  id: Schema.NonEmptyString,
+  targetLineageId: Schema.NonEmptyString,
+  provenance: Provenance,
+  payload: Schema.Json
+}
+
+/**
+ * A human message that must reach the model before the current turn closes.
+ *
+ * `id` is the caller's idempotency key: admitting it twice with the same
+ * content is one notification, and admitting it with different content is a
+ * producer bug the queue refuses. New admissions fingerprint the validated
+ * content before journal redaction, so redaction does not change retry identity.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const HumanSteer = Schema.TaggedStruct("human-steer", {
+  ...common,
+  delivery: Schema.Literal("steer")
+})
+
+/**
+ * The decoded form of {@link HumanSteer}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type HumanSteer = typeof HumanSteer.Type
+
+/**
+ * A human message that waits for the run to become idle.
+ *
+ * The delivery class is the whole difference from {@link HumanSteer}: a
+ * follow-up is not urgent enough to interrupt the turn in flight, so it is
+ * promoted one at a time when the run would otherwise have nothing to do.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const HumanFollowup = Schema.TaggedStruct("human-followup", {
+  ...common,
+  delivery: Schema.Literal("queue")
+})
+
+/**
+ * The decoded form of {@link HumanFollowup}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type HumanFollowup = typeof HumanFollowup.Type
+
+/**
+ * A machine-originated event. Events sharing a coalescing key and a target
+ * lineage collapse to the most recent one while pending.
+ *
+ * Coalescing is what keeps a chatty producer from filling the queue: ten
+ * updates about one condition are one pending notification carrying the latest
+ * of them. The key is scoped to `targetLineageId`, so two branches reporting
+ * one condition under the same ordinary key each keep their own event. An
+ * event with no key never coalesces.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const SystemEvent = Schema.TaggedStruct("system-event", {
+  ...common,
+  delivery: Schema.Literal("queue"),
+  coalescingKey: Schema.optional(Schema.String)
+})
+
+/**
+ * The decoded form of {@link SystemEvent}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SystemEvent = typeof SystemEvent.Type
+
+/**
+ * Any durable notification retained by the pending queue.
+ *
+ * `NotificationQueue.admit` decodes its argument against this union before it
+ * journals anything, so a value that does not match it is refused rather than
+ * acknowledged and then skipped by every replay. Journal-backed queues deeply
+ * freeze decoded notifications, including payloads, before returning them from
+ * `pending` or `drain`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Notification = Schema.Union([HumanSteer, HumanFollowup, SystemEvent])
+
+/**
+ * Any durable notification retained by the pending queue.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Notification = typeof Notification.Type
+
+/**
+ * How a notification is allowed to reach the model.
+ *
+ * `steer` notifications are promoted in a batch at turn close; `queue`
+ * notifications are promoted one at a time when the run would otherwise idle.
+ *
+ * @param notification the notification to classify
+ * @category getters
+ * @since 0.1.0
+ */
+export const admissionClass = (notification: Notification): "steer" | "queue" => notification.delivery
+
+/**
+ * The key a pending notification coalesces on, or `null` when it must never
+ * be coalesced. Only system events coalesce, and only when they declare a key.
+ *
+ * @param notification the notification to key
+ * @category getters
+ * @since 0.1.0
+ */
+export const coalesceKey = (notification: Notification): string | null =>
+  notification._tag === "system-event" ? notification.coalescingKey ?? null : null

package/src/NotificationEvent.ts

@@ -0,0 +1,213 @@
+/**
+ * Journal event types owned by the notification queue.
+ *
+ * @since 0.1.0
+ */
+
+import { JournalEvent } from "@smthrs/journal"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import * as Notification from "./Notification.ts"
+
+/**
+ * The journal `eventType` recorded for one admission decision.
+ *
+ * The spelling is slashes and a PascalCase leaf, where every other event type
+ * in this repository is dot-separated and lowercase (`control.run.parked`,
+ * `flows.alerts.delivered`). The value is already durable in every engine
+ * database, and a rename would silently stop matching the projections that
+ * consumers key on, so it stays as written. A foreign projection must match
+ * this literal rather than the repository convention, which is why the two
+ * spellings are frozen by `test/WireFormat.test.ts`.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const AdmittedEventType = "flows/notifications/Admitted"
+
+/**
+ * The journal `eventType` recorded when pending notifications are promoted.
+ *
+ * Spelled like {@link AdmittedEventType}, and frozen for the same reason.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const PromotedEventType = "flows/notifications/Promoted"
+
+/**
+ * What a durable admission record says was decided.
+ *
+ * This is the one declaration of the admission vocabulary: it validates every
+ * journal entry through {@link fromEntry}, and `NotificationState` types its
+ * public signatures against it, so a fourth decision cannot be added to one
+ * half and forgotten in the other.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const AdmissionDecision = Schema.Literals(["admitted", "coalesced", "rejected-full"])
+
+/**
+ * The decoded form of {@link AdmissionDecision}.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type AdmissionDecision = typeof AdmissionDecision.Type
+
+/**
+ * A durable admission record: the notification a run was told about, and what
+ * the queue decided to do with it.
+ *
+ * A `rejected-full` decision is never written. The queue refuses a full queue
+ * in the receipt alone, so the notification id stays admissible once a
+ * boundary drains. The literal remains in {@link AdmissionDecision} because a
+ * reader must stay total over a record any writer could have produced.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Admitted = Schema.Struct({
+  notification: Notification.Notification,
+  decision: AdmissionDecision,
+  /** SHA-256 of canonical validated input, absent in legacy admission rows. */
+  fingerprint: Schema.optional(Schema.String),
+  version: Schema.optional(Schema.Number)
+})
+
+/**
+ * The decoded form of {@link Admitted}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Admitted = typeof Admitted.Type
+
+/**
+ * A durable promotion record: which notifications one boundary of one lineage
+ * delivered.
+ *
+ * The triple `(runId, targetLineageId, boundary)` is the unit of promotion, so
+ * a second lineage draining the same boundary name is a separate record rather
+ * than a repeat of the first.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Promoted = Schema.Struct({
+  boundary: Schema.String,
+  targetLineageId: Schema.String,
+  ids: Schema.Array(Schema.String)
+})
+
+/**
+ * The decoded form of {@link Promoted}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Promoted = typeof Promoted.Type
+
+/**
+ * Any journal event owned by this package.
+ *
+ * The two members are told apart with {@link isAdmitted} and
+ * {@link isPromoted} rather than a stored discriminant, because the discriminant
+ * would be a durable field this vocabulary does not have.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Event = Admitted | Promoted
+
+/**
+ * Whether an owned event is an admission record.
+ *
+ * @param event an owned event
+ * @category refinements
+ * @since 1.0.0
+ */
+export const isAdmitted = (event: Event): event is Admitted => "notification" in event
+
+/**
+ * Whether an owned event is a promotion record.
+ *
+ * @param event an owned event
+ * @category refinements
+ * @since 1.0.0
+ */
+export const isPromoted = (event: Event): event is Promoted => !isAdmitted(event)
+
+/**
+ * The journal source every admission of one notification is written under.
+ *
+ * @param notificationId the admitted notification's id
+ * @category constructors
+ * @since 1.0.0
+ */
+export const admissionSourceId = (notificationId: string): JournalEvent.SourceId =>
+  JournalEvent.SourceId.make(`${admissionSourcePrefix}${notificationId}`)
+
+/**
+ * The identity of one drain: the lineage and the boundary, each encoded so a
+ * value containing a slash cannot forge another pair's identity.
+ *
+ * @param targetLineageId the lineage the boundary closed on
+ * @param boundary the boundary name
+ * @category constructors
+ * @since 1.0.0
+ */
+export const drainKey = (targetLineageId: string, boundary: string): string =>
+  `${encodeURIComponent(targetLineageId)}/${encodeURIComponent(boundary)}`
+
+/**
+ * The journal source one drain's promotion record is written under.
+ *
+ * @param targetLineageId the lineage the boundary closed on
+ * @param boundary the boundary name
+ * @category constructors
+ * @since 1.0.0
+ */
+export const drainSourceId = (targetLineageId: string, boundary: string): JournalEvent.SourceId =>
+  JournalEvent.SourceId.make(`${drainSourcePrefix}${drainKey(targetLineageId, boundary)}`)
+
+const admissionSourcePrefix = "/notifications/admission/"
+const drainSourcePrefix = "/notifications/drain/"
+
+const decodeAdmitted = Schema.decodeUnknownOption(Admitted)
+const decodePromoted = Schema.decodeUnknownOption(Promoted)
+
+/**
+ * Decodes an owned notification event from a journal entry.
+ *
+ * Foreign entries and structurally invalid payloads decode to `None` so a
+ * projection over a shared journal stays total.
+ *
+ * The event type alone does not make an entry owned: any producer on a shared
+ * journal can choose one. An admission counts only under
+ * {@link admissionSourceId} for the notification it carries, and a promotion
+ * only under the `/notifications/drain/` source family the queue writes, so
+ * another producer's record with the same event type stays out of the
+ * projection. This scopes records; it does not authenticate the writer. The
+ * journal fences writes on run ownership, not on source, so a writer that
+ * sets this package's source id is read as this package. The drain check is
+ * a prefix because records written before the lineage joined the identity
+ * carry the boundary alone.
+ *
+ * @param entry one journal entry, owned or foreign
+ * @category constructors
+ * @since 0.1.0
+ */
+export const fromEntry = (entry: JournalEvent.Entry): Option.Option<Event> => {
+  if (entry.eventType === AdmittedEventType) {
+    return Option.filter(
+      decodeAdmitted(entry.payload),
+      (event) => entry.sourceId === admissionSourceId(event.notification.id)
+    )
+  }
+  if (entry.eventType === PromotedEventType && entry.sourceId.startsWith(drainSourcePrefix)) {
+    return decodePromoted(entry.payload)
+  }
+  return Option.none()
+}