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

package/dist/esm/layerWebhook.js

@@ -0,0 +1,118 @@
+/**
+ * The webhook alert sink: one POST per alert, keyed so the receiver can
+ * dedupe on it.
+ *
+ * The transport rules live here rather than beside the policy, because which
+ * endpoint is paged, over which scheme, carrying which credential is a
+ * deployment's decision and the delays are not.
+ *
+ * @since 1.0.0
+ */
+import { Duration, Effect, Layer, Option } from "effect";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import { alertId } from "./AlertPolicy.js";
+import { AlertError, Sink } from "./AlertSink.js";
+/**
+ * How long the webhook sink waits for an answer before it calls the page
+ * refused.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const defaultWebhookTimeout = Duration.seconds(10);
+/**
+ * The one check the webhook endpoint gets before an alert is ever built on
+ * it.
+ *
+ * The url is operator config rather than runtime input, so there is no SSRF
+ * vector to close here; the scheme bound is what keeps a credential the
+ * deployment set in `headers` from being handed to a scheme that is not HTTP
+ * at all. A `file:` or `javascript:` url is a config bug, and it fails the
+ * composition the way an impossible policy rule does. The error names no
+ * url: the value can carry basic-auth credentials, and an error is logged.
+ */
+const webhookUrl = (raw) => Effect.suspend(() => {
+    const misconfigured = new AlertError({
+        code: "sink_misconfigured",
+        message: "Alert webhook url must be an absolute http: or https: URL"
+    });
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return Effect.fail(misconfigured);
+    }
+    return parsed.protocol === "http:" || parsed.protocol === "https:"
+        ? Effect.succeed(raw)
+        : Effect.fail(misconfigured);
+});
+/**
+ * Runs a webhook request with redirect following switched off at the fetch
+ * transport.
+ *
+ * The request carries whatever credential the deployment put in `headers`,
+ * and a transport that follows a 3xx re-sends those headers to an origin the
+ * deployment never named. Every other fetch default the composition set is
+ * kept; only the redirect mode is forced. A 3xx therefore surfaces to the
+ * status rule, which calls it `sink_rejected`: a redirecting pager endpoint
+ * is a misconfiguration to fix, not an address to forward credentials to.
+ */
+const followingNoRedirects = (effect) => Effect.flatMap(Effect.serviceOption(FetchHttpClient.RequestInit), (init) => Effect.provideService(effect, FetchHttpClient.RequestInit, {
+    ...(Option.isSome(init) ? init.value : {}),
+    redirect: "manual"
+}));
+/**
+ * A sink that POSTs each alert to one webhook.
+ *
+ * The body is the alert plus its {@link alertId}, and the same id is sent as
+ * an `Idempotency-Key` header, because the package requires the receiver to
+ * dedupe on it and a body without it cannot. The header is set after the
+ * caller's headers, so it is the one this sink sends.
+ *
+ * The endpoint must be an absolute `http:` or `https:` URL, checked when the
+ * layer is built, and the request is made with redirect following disabled:
+ * the caller's headers can carry a credential, and a followed redirect would
+ * re-send them to an origin the deployment never named. A 3xx answer is a
+ * refusal like any other non-2xx, not a forwarding instruction. The sink owns
+ * its Fetch transport; an externally supplied `HttpClient` is not used.
+ * Each delivery has its own scope, which aborts the request and releases any
+ * unread response body on completion, failure, timeout, or interruption.
+ *
+ * A non-2xx response is a failure, not a delivery, and an endpoint that never
+ * answers is a failure after `timeout`. Paging is exactly the case where a
+ * silently dropped request is worse than a retry, and a hung request is worse
+ * than either: it is indistinguishable from silence, so it must not be
+ * possible to wait on one forever.
+ *
+ * @param options the endpoint, any headers it needs, and how long to wait
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerWebhook = (options) => Layer.effect(Sink, Effect.gen(function* () {
+    const url = yield* Effect.orDie(webhookUrl(options.url));
+    const client = HttpClient.withScope(yield* HttpClient.HttpClient);
+    const timeout = options.timeout ?? defaultWebhookTimeout;
+    return {
+        deliver: (alert) => client.execute(HttpClientRequest.post(url).pipe((request) => options.headers === undefined ? request : HttpClientRequest.setHeaders(request, options.headers), HttpClientRequest.setHeader("Idempotency-Key", alertId(alert)), HttpClientRequest.bodyJsonUnsafe({ ...alert, alertId: alertId(alert) }))).pipe(followingNoRedirects, Effect.flatMap((response) => response.status >= 200 && response.status < 300
+            ? Effect.void
+            : Effect.fail(new AlertError({
+                code: "sink_rejected",
+                status: response.status,
+                message: `Alert webhook answered ${response.status}`
+            }))), Effect.timeout(timeout), Effect.scoped, Effect.catchTag("TimeoutError", () => Effect.fail(new AlertError({
+            code: "sink_timeout",
+            message: `Alert webhook did not answer within ${Duration.toMillis(timeout)} ms`
+        }))), 
+        // The transport error holds the request, and the request holds the
+        // caller's headers. Only its reason tag crosses into the failure.
+        Effect.catchTag("HttpClientError", (cause) => Effect.fail(new AlertError({
+            code: "sink_unreachable",
+            reason: cause.reason._tag,
+            message: "Alert webhook could not be reached"
+        }))))
+    };
+})).pipe(Layer.provide(FetchHttpClient.layer));
+//# sourceMappingURL=layerWebhook.js.map

package/dist/esm/layerWebhook.js.map

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

package/docs/README.md

@@ -0,0 +1,144 @@
+---
+title: "@smthrs/notifications"
+description: "A durable queue for telling a running agent something: admit a message from any process, and deliver it only at a point in the run where reading it is safe."
+---
+
+`@smthrs/notifications` is a durable queue for telling a running agent
+something. Any process admits a message at any time, and the run collects what
+it may deliver at a boundary of its own choosing, so an instruction never lands
+in the middle of a turn.
+
+## The problem it solves
+
+An agent that has been working for twenty minutes is not something you can call
+a function on. An operator wants to redirect it, a supervisor wants to raise an
+alarm, a parent run wants to pass down a result. Writing any of those straight
+into the model's context changes what the model is reading while it is reading
+it, and holding them in memory loses them when the process restarts.
+
+This package pulls the two halves apart and puts a journal between them:
+
+- **Admission** is the writer's moment. Any process admits a notification at any
+  time. The queue records it durably and answers with a receipt.
+- **Promotion** is the reader's moment. The run asks, at a point where reading a
+  new instruction is safe, what this boundary may deliver.
+
+Nothing happens in between, and both halves survive a restart. The queue keeps
+no state of its own: it folds each run's state back out of the two journal
+records it writes, so a second process over the same database answers for a run
+the first one admitted to.
+
+Reach for it when you need durable, attributed delivery into a long-running
+process, and when losing a message or delivering it twice would both be wrong:
+operator steering, an idle-time follow-up queue, coalesced system events, or
+alerts about a run that has been stuck too long.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+Node.js 26.4.0 or later. `@smthrs/journal` is where the durable records go, and
+the example below imports it directly. See [Installation](./installation.md) for
+the SQLite composition a deployment uses.
+
+## Admit a message, deliver it at a turn boundary
+
+The journal here is the production SQLite one over an in-memory database, so
+nothing is stubbed and nothing needs configuring:
+
+```ts
+import * as TestJournal from "@smthrs/journal/test/TestJournal"
+import { NotificationQueue } from "@smthrs/notifications"
+import type { Notification } from "@smthrs/notifications/Notification"
+import * as Effect from "effect/Effect"
+
+const steer: Notification = {
+  _tag: "human-steer",
+  id: "message-1",
+  delivery: "steer",
+  targetLineageId: "run-1/root",
+  provenance: {
+    sourceRunId: "operator",
+    sourceLineageId: "operator",
+    sourceTurn: 0,
+    sourceActor: "human:will"
+  },
+  payload: { kind: "Message", body: "look at the failing test first" }
+}
+
+const program = Effect.gen(function*() {
+  const queue = yield* NotificationQueue.NotificationQueue
+
+  // Whoever is steering, whenever they say it.
+  yield* queue.admit("run-1", steer)
+
+  // The run, at a point where reading a new instruction is safe.
+  const receipt = yield* queue.drain({
+    runId: "run-1",
+    targetLineageId: "run-1/root",
+    boundary: "turn-1",
+    wouldIdle: true
+  })
+  return receipt.notifications.map((notification) => notification.id)
+})
+
+console.log(
+  await Effect.runPromise(
+    program.pipe(
+      Effect.provide(NotificationQueue.layer),
+      Effect.provide(TestJournal.layer()),
+      Effect.scoped,
+      Effect.orDie
+    )
+  )
+)
+```
+
+```text
+[ 'message-1' ]
+```
+
+`id` is your idempotency key: admitting it twice with the same content is one
+notification. `boundary` is the delivery's identity: draining `turn-1` again
+reads the committed record back and reports the same notifications with
+`duplicate: true`, rather than deciding a second time and disagreeing.
+`targetLineageId` is the address of the reader, which the queue only compares for
+equality: pass the run id when a run has one reader, and the branch's id when it
+has several. See
+[Admission and promotion](./concepts/admission-and-promotion.md).
+
+## How it relates to the smithers CLI
+
+This package is one of the pieces behind [`@smthrs/cli`](/api/cli), the `smthrs`
+command line that plans, runs, and inspects durable flows. Running
+`smthrs runs steer <run-id> --message "..."` admits a `human-steer` notification to
+this queue under a stable message id, and the run reads it when its next turn
+closes. `smthrs runs list` fills in each run's pending steer count from the same fold
+`drain` uses, which is why a listing never reports a delivered message as still
+waiting.
+
+Neither package needs the other. Install `@smthrs/cli` for the operator-facing
+command line and everything under it. Install this package when you are building
+the host on the other side: the code that decides where a turn boundary is and
+asks the queue what it may deliver there. [`@smthrs/harness`](/api/harness)
+is the one Smithers ships, and it drains this queue at every boundary.
+
+## Where to go next
+
+- [Installation](./installation.md): the journal, the HTTP client the webhook
+  sink needs, and the import forms.
+- [Quickstart](./quickstart.md): admit a steer and a follow-up, drain both, and
+  read what each step decided.
+- [Admission and promotion](./concepts/admission-and-promotion.md): delivery
+  classes, coalescing, the capacity bound, the turn cutoff, and the drain
+  identity.
+- [The journal records](./concepts/journal-records.md): the two durable events,
+  why replay never re-decides, and what a projection may assume.
+- [How alerting decides](./concepts/alerting.md): why an alert is a function of
+  journal time, and why delivery is at-least-once.
+- [Steer a run](./guides/steer-a-run.md) and
+  [Drain at a turn boundary](./guides/drain-at-a-turn-boundary.md): the writing
+  half and the reading half.
+- [API reference](./api.md): every export, with its signature.
+- [Troubleshooting](./troubleshooting.md): what each symptom means and what to
+  change.