@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/webhook/subscriptions.mjs

@@ -0,0 +1,342 @@
+import { canonicalInput } from "../contract/canonical.mjs";
+import { reported } from "../contract/reported.mjs";
+import { encodeUntaggedOf } from "../contract/occurrence.mjs";
+import { CallbackFailed, NotSubscribed, SubscriptionError } from "../Event.mjs";
+import { sentError } from "../contract/codes.mjs";
+import { randomToken, subscriptionId } from "./signing.mjs";
+import { pushed, refusalIn } from "../contract/push.mjs";
+import { checkedHost } from "./address.mjs";
+import { attempt, challenged } from "./attempt.mjs";
+import { Cause, Clock, Context, DateTime, Deferred, Duration, Effect, Exit, Fiber, FiberMap, Match, Option, RcMap, Schedule, Schema, Scope, Semaphore, Stream, Struct } from "effect";
+import { HttpRouter, HttpServerRequest } from "effect/http";
+// src/webhook/subscriptions.ts
+const minTtl = Duration.minutes(1);
+const rotationGrace = Duration.minutes(5);
+const maxBody = 262144;
+const encoder = new TextEncoder();
+const lastAttempts = Schedule.exponential(Duration.seconds(1)).pipe(Schedule.upTo({ times: 3 }));
+const iso = (millis) => DateTime.formatIso(DateTime.makeUnsafe(millis));
+const active = (status) => status.active ? status : {
+	...Struct.omit(status, ["failedSince"]),
+	active: true
+};
+const grantOf = (ttlMs, policy) => Duration.clamp(ttlMs === null || ttlMs === void 0 ? policy.maxTtl : Duration.millis(ttlMs), {
+	minimum: minTtl,
+	maximum: policy.maxTtl
+});
+const trusted = (url, prefixes) => prefixes.some(({ origin, pathname }) => url.origin === origin && (url.pathname === pathname || url.pathname.startsWith(pathname.endsWith("/") ? pathname : `${pathname}/`)));
+const snapshotOf = Context.omit(Scope.Scope, HttpServerRequest.HttpServerRequest, HttpServerRequest.ParsedSearchParams, HttpRouter.RouteContext);
+const unencoded = Effect.die(/* @__PURE__ */ new Error("A webhook subscriber's identity did not encode by its authentication's schema (give Authentication.make a schema that encodes every identity its verifier provides)"));
+/**
+* The webhook subscriptions of one `Webhook.layer`: each a worker reading its feed as the
+* subscriber and POSTing what it reads to the callback, until it expires, is unsubscribed, or
+* is refused.
+*/
+const confirmedAt = (cursor) => Effect.tap(Deferred.make(), (confirmation) => Deferred.succeed(confirmation, {
+	cursor,
+	truncated: false
+}));
+const failedCallback = (feed, category) => SubscriptionError.of(feed.event.name, new CallbackFailed({ category }));
+const idOf = ({ feed, principal, input, delivery: { url } }) => Effect.flatMap(canonicalInput(feed.event.input, input), (encoded) => subscriptionId(`${principal}\u0000${url.href}\u0000${feed.event.name}\u0000${encoded}`));
+const named = (feeds) => feeds.map(({ event }) => `"${event.name}"`).join(", ");
+const makeWebhooks = (policy) => Effect.gen(function* () {
+	const built = yield* Effect.context();
+	const workers = yield* FiberMap.make();
+	const held = /* @__PURE__ */ new Map();
+	const served = /* @__PURE__ */ new Map();
+	const { storage } = policy;
+	const holds = (subscription) => held.get(subscription.id) === subscription;
+	const kept = (subscription) => Effect.sync(() => {
+		if (storage !== void 0 && holds(subscription)) storage.mark(subscription.id, {
+			...subscription.kept,
+			url: subscription.url,
+			event: subscription.feed.event.name,
+			secret: subscription.secret,
+			expiresAt: subscription.expiresAt,
+			watermark: subscription.watermark,
+			status: subscription.status
+		});
+	});
+	const dropped = (id) => Effect.sync(() => storage?.mark(id, void 0));
+	const verified = /* @__PURE__ */ new Map();
+	const locks = yield* RcMap.make({ lookup: (_id) => Semaphore.make(1) });
+	const retryForMillis = Duration.toMillis(policy.retryFor);
+	const failingFor = ({ status }) => Effect.map(Clock.currentTimeMillis, (now) => status.failedSince === void 0 ? 0 : now - Date.parse(status.failedSince));
+	const retrying = (subscription) => ({
+		schedule: Schedule.modifyDelay(Schedule.forever, () => Effect.map(failingFor(subscription), (failing) => Duration.clamp(Duration.millis(failing), {
+			minimum: Duration.seconds(1),
+			maximum: Duration.minutes(5)
+		}))),
+		while: (failure) => failure.final ? Effect.succeed(false) : Effect.map(failingFor(subscription), (failing) => failing < retryForMillis)
+	});
+	const locked = (id) => (effect) => Effect.scoped(Effect.flatMap(RcMap.get(locks, id), (lock) => lock.withPermits(1)(effect)));
+	const asSubscriber = (subscription, effect) => Effect.updateContext(effect, () => subscription.context);
+	const post = (subscription, webhookId, body) => Effect.flatMap(Clock.currentTimeMillis, (now) => Effect.provideContext(attempt({
+		url: subscription.url,
+		subscriptionId: subscription.id,
+		webhookId,
+		body,
+		keys: subscription.previous !== void 0 && now < subscription.previous.until ? [subscription.secret.key, subscription.previous.key] : [subscription.secret.key]
+	}, trusted(subscription.url, policy.allowedCallbacks) ? Effect.void : checkedHost(subscription.url, policy.dns)), built));
+	const recorded = (subscription, failure) => Effect.flatMap(Clock.currentTimeMillis, (now) => Effect.suspend(() => {
+		const { status } = subscription;
+		subscription.status = failure === void 0 ? {
+			active: true,
+			lastDeliveryAt: iso(now),
+			lastError: null
+		} : {
+			...status,
+			lastError: failure.category,
+			failedSince: status.failedSince ?? iso(now)
+		};
+		return failure !== void 0 && status.lastError === failure.category && status.failedSince !== void 0 ? Effect.void : kept(subscription);
+	}));
+	const suspended = (subscription) => Effect.andThen(Effect.andThen(Effect.sync(() => {
+		subscription.status = {
+			...subscription.status,
+			active: false
+		};
+	}), kept(subscription)), Effect.never);
+	const abandoned = (subscription) => Effect.andThen(Effect.sync(() => {
+		subscription.status = Struct.omit(subscription.status, ["failedSince"]);
+	}), kept(subscription));
+	const delivered = (subscription, webhookId, body) => post(subscription, webhookId, body).pipe(Effect.tapError((failure) => recorded(subscription, failure)), Effect.retry(retrying(subscription)), Effect.matchEffect({
+		onSuccess: () => Effect.as(recorded(subscription, void 0), true),
+		onFailure: (failure) => failure.final ? Effect.as(abandoned(subscription), false) : suspended(subscription)
+	}));
+	const gapped = (subscription, cursor) => Effect.flatMap(randomToken, (token) => delivered(subscription, `msg_gap_${token}`, JSON.stringify({
+		type: "gap",
+		cursor
+	})));
+	const deliverTo = (subscription, input, confirmation) => {
+		const encode = encodeUntaggedOf(subscription.feed.event);
+		const moved = (cursor) => cursor === null || cursor === subscription.watermark ? Effect.void : Effect.andThen(Effect.sync(() => {
+			subscription.watermark = cursor;
+		}), kept(subscription));
+		const confirmed = (cursor, truncated) => Effect.andThen(moved(cursor), Deferred.succeed(confirmation, {
+			cursor,
+			truncated
+		}));
+		const skipped = (cursor) => Effect.andThen(gapped(subscription, cursor), moved(cursor));
+		return (sent) => Match.valueTags(sent, {
+			Checked: ({ cursor }) => Deferred.isDoneUnsafe(confirmation) ? moved(cursor) : confirmed(cursor, false),
+			Gap: ({ cursor }) => Deferred.isDoneUnsafe(confirmation) ? skipped(cursor) : confirmed(cursor, true),
+			Occurrence: (occurrence) => Effect.gen(function* () {
+				const body = yield* asSubscriber(subscription, subscription.feed.admit(input)).pipe(Effect.andThen(Effect.map(encode(occurrence), JSON.stringify)));
+				if (encoder.encode(body).length > maxBody) {
+					yield* Effect.logWarning(`Webhook delivery of ${occurrence.eventId} abandoned: its body is over 256 KiB`);
+					return yield* skipped(occurrence.cursor);
+				}
+				if (yield* delivered(subscription, occurrence.eventId, body)) return yield* moved(occurrence.cursor);
+				return yield* skipped(occurrence.cursor);
+			}),
+			Failed: () => Effect.void
+		});
+	};
+	const expired = ({ expiresAt }) => Effect.flatMap(Clock.currentTimeMillis, (now) => Effect.sleep(Duration.millis(Math.max(expiresAt - now, 0))));
+	const terminated = (subscription, cause) => {
+		const refusal = refusalIn(cause);
+		if (refusal === void 0) return Cause.hasInterruptsOnly(cause) ? Effect.void : reported(cause);
+		return Effect.flatMap(randomToken, (token) => post(subscription, `msg_terminated_${token}`, JSON.stringify({
+			type: "terminated",
+			error: sentError(refusal)
+		})).pipe(Effect.retry({
+			schedule: lastAttempts,
+			while: (failure) => !failure.final
+		}), Effect.ignore));
+	};
+	const ended = (subscription) => Effect.sync(() => {
+		if (holds(subscription)) held.delete(subscription.id);
+	});
+	const finished = (subscription) => Effect.suspend(() => holds(subscription) ? Effect.andThen(ended(subscription), dropped(subscription.id)) : Effect.void);
+	const workerOf = (subscription, input, cursor, confirmation) => Effect.raceFirst(pushed((from) => Stream.unwrap(Effect.map(subscription.feed.stream(input), (read) => read(from))), cursor, deliverTo(subscription, input, confirmation), {
+		inOrder: true,
+		resumesUnconfirmed: Deferred.isDoneUnsafe(confirmation)
+	}), expired(subscription)).pipe(Effect.exit, Effect.tap(() => finished(subscription)), Effect.flatMap((exit) => {
+		if (Deferred.isDoneUnsafe(confirmation)) return Exit.isFailure(exit) ? terminated(subscription, exit.cause) : Effect.void;
+		return Exit.isFailure(exit) ? Deferred.failCause(confirmation, exit.cause) : Deferred.succeed(confirmation, {
+			cursor,
+			truncated: false
+		});
+	}), Effect.onInterrupt(() => Effect.andThen(ended(subscription), Deferred.interrupt(confirmation))), (worker) => asSubscriber(subscription, worker));
+	const remembered = ({ verifiedAs, expiresAt }, now) => Effect.sync(() => {
+		for (const [each, expiry] of verified) if (expiry <= now) verified.delete(each);
+		verified.set(verifiedAs, Math.max(expiresAt, verified.get(verifiedAs) ?? 0));
+	});
+	const verify = ({ verifiedAs, url, id, secret, feed }, now) => {
+		if ((verified.get(verifiedAs) ?? 0) > now || trusted(url, policy.allowedCallbacks)) return Effect.void;
+		return Effect.gen(function* () {
+			const challenge = yield* randomToken;
+			if ((yield* Effect.provideContext(challenged({
+				url,
+				subscriptionId: id,
+				webhookId: `msg_verification_${yield* randomToken}`,
+				body: JSON.stringify({
+					type: "verification",
+					challenge
+				}),
+				keys: [secret.key]
+			}, checkedHost(url, policy.dns)), built).pipe(Effect.mapError(({ category }) => failedCallback(feed, category)))) !== challenge) return yield* failedCallback(feed, "challenge_failed");
+		});
+	};
+	const handover = (id, next, worker) => Effect.uninterruptible(Effect.gen(function* () {
+		const previous = yield* FiberMap.get(workers, id);
+		if (next === void 0) held.delete(id);
+		else held.set(id, next);
+		yield* FiberMap.run(workers, id, Option.match(previous, {
+			onNone: () => worker,
+			onSome: (fiber) => Effect.andThen(Fiber.await(fiber), worker)
+		}));
+	}));
+	const refreshed = (subscription, granted, input, now) => Effect.gen(function* () {
+		const { status, watermark } = subscription;
+		const renewed = {
+			...subscription,
+			...granted,
+			...granted.secret.text === subscription.secret.text ? {} : { previous: {
+				key: subscription.secret.key,
+				until: now + Duration.toMillis(rotationGrace)
+			} },
+			status: active(status)
+		};
+		const confirmation = yield* confirmedAt(watermark);
+		yield* handover(renewed.id, renewed, workerOf(renewed, input, watermark, confirmation));
+		yield* remembered(renewed, now);
+		yield* kept(renewed);
+		return {
+			id: renewed.id,
+			refreshBefore: iso(renewed.expiresAt),
+			cursor: watermark,
+			truncated: false,
+			deliveryStatus: status
+		};
+	});
+	const heldOf = (fields) => ({
+		...fields,
+		verifiedAs: `${fields.principal}\u0000${fields.url.href}`,
+		previous: void 0
+	});
+	const keptOf = ({ feed, keyed, input }) => Effect.gen(function* () {
+		const { schema } = keyed;
+		if (storage === void 0 || schema === void 0) return {
+			input: null,
+			identity: null
+		};
+		const identity = yield* Effect.service(feed.event.caller);
+		return {
+			input: yield* Effect.orDie(Schema.encodeUnknownEffect(Schema.toCodecJson(feed.event.input))(input)),
+			identity: yield* Effect.catch(Schema.encodeUnknownEffect(Schema.toCodecJson(schema))(identity), () => unencoded)
+		};
+	});
+	const restoredFrom = (store, feeds, keyed, schema, id) => Effect.gen(function* () {
+		const record = Option.getOrUndefined(yield* store.get(id));
+		if (record === void 0) return yield* dropped(id);
+		const feed = feeds.find(({ event }) => event.name === record.event);
+		if (feed === void 0) return;
+		const { expiresAt, url, secret } = record;
+		if (expiresAt <= (yield* Clock.currentTimeMillis)) return yield* dropped(id);
+		const input = yield* Schema.decodeEffect(Schema.toCodecJson(feed.event.input))(record.input);
+		const identity = yield* Schema.decodeEffect(Schema.toCodecJson(schema))(record.identity);
+		const principal = keyed.principal(identity);
+		const current = yield* idOf({
+			feed,
+			principal,
+			input,
+			delivery: { url }
+		});
+		if (current !== id) yield* dropped(id);
+		if (held.has(current)) return;
+		const subscription = heldOf({
+			id: current,
+			url,
+			feed,
+			principal,
+			kept: {
+				input: record.input,
+				identity: record.identity
+			},
+			secret,
+			context: Context.add(built, feed.event.caller, identity),
+			expiresAt,
+			status: record.status,
+			watermark: record.watermark
+		});
+		const confirmation = yield* confirmedAt(record.watermark);
+		yield* handover(current, subscription, record.status.active ? workerOf(subscription, input, record.watermark, confirmation) : Effect.andThen(expired(subscription), finished(subscription)));
+		if (current !== id) yield* kept(subscription);
+	}).pipe(Effect.catchCause(reported));
+	const serve = (feeds, keyed) => Effect.gen(function* () {
+		const { schema } = keyed;
+		const namesake = feeds.filter(({ event }) => served.has(event.name) && served.get(event.name)?.event !== event);
+		if (namesake.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`Webhook.layer serves ${named(namesake)} for two event types of that name (give each event type a name of its own, or each surface its own Webhook.layer)`));
+		if (storage !== void 0 && feeds.length > 0 && schema === void 0) return yield* Effect.die(/* @__PURE__ */ new Error(`Webhook.layer persists webhook subscriptions, but the authentication of ${named(feeds)} has no schema to keep a subscriber's identity by (give its Authentication.make a schema)`));
+		const twice = feeds.filter(({ event }) => served.has(event.name) && served.get(event.name)?.schema !== schema);
+		if (storage !== void 0 && twice.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`Webhook.layer persists webhook subscriptions, but ${named(twice)} is served by two authentications with different schemas (serve each event with one authentication, or give them one schema)`));
+		for (const { event } of feeds) served.set(event.name, {
+			event,
+			schema
+		});
+		if (storage === void 0 || schema === void 0) return;
+		for (const id of storage.ids()) yield* locked(id)(Effect.suspend(() => held.has(id) ? Effect.void : restoredFrom(storage, feeds, keyed, schema, id)));
+	});
+	const refused = (id, cause) => Effect.gen(function* () {
+		const existing = held.get(id);
+		if (existing !== void 0 && refusalIn(cause) !== void 0 && (yield* Clock.currentTimeMillis) < existing.expiresAt) {
+			yield* handover(id, void 0, terminated(existing, cause));
+			yield* dropped(id);
+		}
+		return yield* Effect.failCause(cause);
+	});
+	const subscribe = (subscribing) => Effect.gen(function* () {
+		const { feed, principal, input, delivery: { url, secret }, cursor, ttlMs } = subscribing;
+		const id = yield* idOf(subscribing);
+		return yield* locked(id)(Effect.gen(function* () {
+			yield* Effect.catchCause(feed.admit(input), (cause) => refused(id, cause));
+			const now = yield* Clock.currentTimeMillis;
+			const granted = {
+				secret,
+				context: Context.merge(built, snapshotOf(yield* Effect.context())),
+				kept: yield* keptOf(subscribing),
+				expiresAt: now + Duration.toMillis(grantOf(ttlMs, policy))
+			};
+			const existing = held.get(id);
+			if (existing !== void 0 && now < existing.expiresAt) return yield* refreshed(existing, granted, input, now);
+			const subscription = heldOf({
+				...granted,
+				id,
+				url,
+				feed,
+				principal,
+				status: {
+					active: true,
+					lastDeliveryAt: null,
+					lastError: null
+				},
+				watermark: cursor
+			});
+			yield* verify(subscription, now);
+			yield* remembered(subscription, now);
+			const confirmation = yield* Deferred.make();
+			yield* handover(id, subscription, workerOf(subscription, input, cursor, confirmation));
+			const started = yield* Deferred.await(confirmation);
+			yield* kept(subscription);
+			return {
+				id,
+				refreshBefore: iso(subscription.expiresAt),
+				cursor: started.cursor,
+				truncated: started.truncated
+			};
+		}));
+	});
+	const unsubscribe = (subscription) => Effect.flatMap(idOf(subscription), (id) => locked(id)(Effect.gen(function* () {
+		if ((yield* Clock.currentTimeMillis) < (held.get(id)?.expiresAt ?? 0)) return yield* Effect.andThen(handover(id, void 0, Effect.void), dropped(id));
+		if (storage?.ids().includes(id) === true) return yield* dropped(id);
+		return yield* SubscriptionError.of(subscription.feed.event.name, new NotSubscribed());
+	})));
+	return {
+		serve,
+		subscribe,
+		unsubscribe
+	};
+});
+export { makeWebhooks };

package/docs/Action-failures.md

@@ -1,7 +1,6 @@
 # Action failure modes
 
-What you see when something is wrong, and the fix. Search for a fragment of the message.
-The tasks are in [Action.md](Action.md).
+What you see when something is wrong, and the fix. Search for a fragment of the message. The tasks are in [Action.md](Action.md).
 
 ## At `make`
 
@@ -30,6 +29,7 @@ The tasks are in [Action.md](Action.md).
 - `HttpRouter.Request<"Requires", X>` still owed, or `Type 'X' is not assignable to type 'never'` at `runMain`, although `X`, a store the authorizer reads, is provided at startup: what a plain authorizer yields is a request-time requirement, and this one yields `X` on every call. Make `authorize` an Effect that yields `X` once and returns the function ([Authorize calls](Action.md#authorize-calls)).
 - `unknown` among a surface's requirements, and a type error where it is served or run, such as `Argument of type 'Layer<never, unknown, unknown>' is not assignable` at `HttpRouter.toWebHandler` or `Type 'unknown' is not assignable to type 'never'`: the implementations are typed `Action.AnyImplementation`, as a helper's parameter or a list's annotation. Make the helper generic over them, `<const Apps extends Action.AnyImplementation | ReadonlyArray<Action.AnyImplementation>>(apps: Apps)`, or drop the annotation.
 - `Request<"Requires", unknown>` where an implementation is served, or `unknown` among the services a call or a run still requires: TypeScript inferred no requirements for one handler of a record, as a data-first call whose type takes a parameter from no argument causes, `Effect.catchTag(effect, tag, f)` for one. Write that handler's Effect `effect.pipe(Effect.catchTag(tag, f))`, or as a generator.
+- `Service not found: effect-actions/Action/Idempotency`, a defect where an action naming `idempotencyKey` is built: its actions were typed `Action.Any`, so no type required `Action.Idempotency`. Provide `Action.layerIdempotency` around the surfaces.
 
 ## At `client` and its calls
 

package/docs/Action-streams.md

@@ -0,0 +1,115 @@
+# Progress and streamed answers
+
+An action answers once, at the end. Two options let a caller see more while it runs: `progress`, values the handler reports along the way, which a caller may miss some of, and `Action.Stream`, an answer of many elements, each arriving as it is produced. Both are declared on the contract ([Action.md](Action.md#define-a-contract)) and carried by every surface its own way: the declaration's JSDoc says how.
+
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [Action-failures.md](Action-failures.md). For one symbol, `grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions/dist/`.
+
+## Report progress
+
+An action declaring `progress`, a schema or struct fields, gets a second argument in its handler, `{ progress }`, which reports a value to the caller without waiting for it; a client's call takes `{ onProgress }` after its input ([build-events/test/builds/progress.test.ts](../examples/build-events/test/builds/progress.test.ts)). The contract is `StartBuild` in [build-events/src/builds/Builds.ts](../examples/build-events/src/builds/Builds.ts).
+
+```ts example=build-events/src/builds/handlers.ts
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import {
+  BuildFinished,
+  FinishBuild,
+  PipelineStatus,
+  StartBuild,
+} from "./Builds.js";
+import type { Build } from "./Builds.js";
+import { BuildStore } from "./store.js";
+
+// DEMO ONLY: each step passes at once. A runner's steps take their time, which is why a caller
+// wants to see them.
+const steps = ["install", "build", "test"];
+
+export const builds = Action.implement(
+  [FinishBuild, StartBuild],
+  Effect.gen(function* () {
+    const store = yield* BuildStore;
+    const events = yield* Event.Events;
+
+    // `build.finished` is a check source over the store: write the build there first, then wake
+    // its subscribers, who read it now rather than at their next poll. `pipeline.status` is a
+    // current source: the notify moves its pipeline's revision, so its subscribers alone read it.
+    const finished = (build: Effect.Effect<Build>) =>
+      Effect.tap(build, ({ pipeline }) =>
+        Effect.andThen(
+          events.notify(BuildFinished),
+          events.notify(PipelineStatus, { key: pipeline })
+        )
+      );
+
+    return {
+      finishBuild: ({ pipeline, status }) =>
+        finished(store.finish(pipeline, status, [status])),
+      // `progress` never waits for the caller: the build runs at its own pace.
+      startBuild: ({ pipeline }, { progress }) =>
+        Effect.andThen(
+          Effect.forEach(
+            steps,
+            (step, done) => progress({ step, done, total: steps.length }),
+            {
+              discard: true,
+            }
+          ),
+          finished(
+            store.finish(pipeline, "passed", [
+              ...steps.map((step) => `${step}: passed`),
+              "passed",
+            ])
+          )
+        ),
+    };
+  }),
+  { authorize: Action.allowAll }
+);
+```
+
+The rules are on `Action.Options.progress`; how each surface carries the values, on `ActionHttp.layer`, `ActionRpc.make`, `ActionMcp.layerHttp`, `ActionToolkit.make` and `ActionCli.command`.
+
+- **Report a snapshot to show, never an event to count.** A caller falling behind loses the oldest values, never the answer: what a caller must receive each time is the answer, or an [event](Event.md).
+
+## Answer a stream
+
+An action whose `success` is `Action.Stream(element)` has a handler returning a `Stream` of elements, and every client's call returns one ([build-events/test/builds/log.test.ts](../examples/build-events/test/builds/log.test.ts)). The contract is `TailLog` in [Builds.ts](../examples/build-events/src/builds/Builds.ts).
+
+```ts example=build-events/src/builds/log.ts
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect, Stream } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { TailLog } from "./Builds.js";
+import { BuildStore } from "./store.js";
+
+export const logs = Action.implement(
+  TailLog,
+  Effect.gen(function* () {
+    const store = yield* BuildStore;
+
+    // The handler returns a `Stream`, run in a scope of its own that closes when the caller
+    // stops reading, so what it acquires is released then.
+    return ({ buildId }) =>
+      Stream.unwrap(
+        Effect.gen(function* () {
+          const member = yield* CurrentMember;
+          // A failure before the first line, `BuildNotFound` here, fails the call as an action
+          // answering one value fails, a 404 over HTTP; one after a line ends the stream, the
+          // lines before it already read.
+          const log = yield* store.logOf(member.pipelines, buildId);
+
+          return Stream.fromIterable(log.map((line) => ({ line })));
+        })
+      );
+  }),
+  // Which builds a member may read is the store's check, by pipeline.
+  { authorize: Action.allowAll }
+);
+```
+
+How each surface carries it is on `ActionHttp.layer`, `ActionRpc.make`, `ActionMcp.layerHttp`, `ActionToolkit.make` and `ActionCli.command`.
+
+- **A tool collects it whole.** A tool answers one result, so an MCP endpoint and a toolkit answer the elements as one array once the stream ends, and `ActionMcp.client`'s method streams that array again: a stream that never ends never answers a tool, and a long one fills a model's context, so [kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts) leaves `exportIssues` out of its tools.