@decohere/http 0.0.1-dev.125 → 0.0.1-dev.5

package/src/routing/services/route-argument-resolver.ts

@@ -0,0 +1,92 @@
+import type { Constructable, Type } from "@decohere/core/reflection";
+import { isPrimitiveOrDateType } from "@decohere/core/reflection";
+import type { IPrincipalProvider } from "../../auth/principal-provider.js";
+import type { FieldMeta, HttpRequest, RouteArg } from "../anvil.types.js";
+import type { Pipe, PipeContext } from "../pipes/pipes.js";
+
+export class RouteArgumentResolve {
+	public resolveArguments(
+		httpRequest: HttpRequest,
+		routeArgs: RouteArg[],
+		principalProvider?: IPrincipalProvider,
+	) {
+		const argsValues = [];
+		for (const [argIdx, routeArg] of routeArgs.entries()) {
+			const val = this.getValue(httpRequest, routeArg, principalProvider);
+			argsValues[argIdx] = val;
+		}
+		return argsValues;
+	}
+
+	private getValue(
+		httpRequest: HttpRequest,
+		routeArg: RouteArg,
+		principalProvider?: IPrincipalProvider,
+	) {
+		switch (routeArg.argumentLocation) {
+			case "principal":
+				return principalProvider?.currentPrincipal;
+			case "signal":
+				return httpRequest.signal;
+			case "lastEventId":
+				return httpRequest.headers["last-event-id"];
+		}
+		const value = isPrimitiveOrDateType(routeArg.argumentType)
+			? this.mapPrimitive(httpRequest, routeArg)
+			: this.mapObject(httpRequest, routeArg);
+		return value;
+	}
+
+	private mapPrimitive(httpRequest: HttpRequest, routeArg: RouteArg) {
+		const { argumentLocation, mappingKey, pipes } = routeArg;
+		const value = httpRequest[argumentLocation][mappingKey];
+		const tranformedValue = this.transform(value, pipes, routeArg.fieldMap);
+		return tranformedValue;
+	}
+
+	private mapObject(httpRequest: HttpRequest, routeArg: RouteArg) {
+		const { argumentType } = routeArg;
+		const inst = new argumentType();
+		const { fieldMap } = routeArg;
+
+		for (const [fieldKey, meta] of fieldMap.entries()) {
+			const { fieldLocation, mappingKey, pipes } = meta;
+			const value = httpRequest[fieldLocation][mappingKey];
+			const transformedValue = this.transform(value, pipes, fieldMap);
+			inst[fieldKey] = transformedValue;
+		}
+
+		return inst;
+	}
+
+	private transform(
+		value: unknown,
+		pipes: Constructable<Pipe>[] | undefined,
+		fieldMap?: Map<string, FieldMeta>,
+	) {
+		let transformed = value;
+		if (value == null) {
+			return value;
+		}
+
+		const context = this.pipeContext(fieldMap);
+		for (const pipeConstructor of pipes ?? []) {
+			const pipe = new pipeConstructor();
+			transformed = pipe.transform(transformed, context);
+		}
+		return transformed;
+	}
+
+	private pipeContext(fieldMap?: Map<string, FieldMeta>): PipeContext | undefined {
+		if (fieldMap == null || fieldMap.size === 0) {
+			return undefined;
+		}
+		const fieldTypes: Record<string, Type> = {};
+		for (const [key, meta] of fieldMap.entries()) {
+			if (meta.fieldType != null) {
+				fieldTypes[key] = meta.fieldType;
+			}
+		}
+		return Object.keys(fieldTypes).length > 0 ? { fieldTypes } : undefined;
+	}
+}

package/src/routing/services/route-registry.ts

@@ -0,0 +1,229 @@
+import { inject, injectable } from "@decohere/di/decorators";
+import type { Constructable, Field, FunctionType, Type } from "@decohere/core/reflection";
+import {
+	getArgumentMeta,
+	getFields,
+	getFunctionArgs,
+	getFunctions,
+	getMeta,
+	isConstructable,
+	isPrimitiveOrDateType,
+} from "@decohere/core/reflection";
+import { HttpOptionsToken, MetadataKeys } from "../../const.js";
+import type { HttpOptions } from "../../http/http.options.js";
+import type { SseOptions } from "../../sse/sse.types.js";
+import type {
+	ArgumentMeta,
+	ControllerMetadata,
+	FieldMeta,
+	MappedRoute,
+	RouteArg,
+	RouteMetadata,
+} from "../anvil.types.js";
+import { InjectedParts, RouteConfigurationError, type RequestPart } from "../anvil.types.js";
+import { applyGlobalPrefix, joinRoutePath, normalizePrefix } from "../path.util.js";
+import { BooleanPipe, DatePipe, JsonPipe, NumberPipe, type Pipe } from "../pipes/pipes.js";
+
+@injectable()
+export class RouteRegistry {
+	private readonly routeMap = new Map<string, MappedRoute>();
+	private readonly httpOptions?: HttpOptions;
+
+	public constructor(@inject(HttpOptionsToken) httpOptions?: HttpOptions) {
+		this.httpOptions = httpOptions;
+	}
+
+	public addController(controller: Constructable) {
+		const funcs = getFunctions(controller);
+		for (const func of funcs) {
+			this.addControllerRoute(controller, func);
+		}
+	}
+
+	public get routes(): MapIterator<MappedRoute> {
+		return this.routeMap.values();
+	}
+
+	public getRoute(key: string): MappedRoute {
+		return this.routeMap.get(key);
+	}
+
+	private addControllerRoute(controller: Constructable, prop: PropertyDescriptor) {
+		const func = prop.value;
+		const handler = func.name;
+		const route = getMeta<RouteMetadata>(MetadataKeys.route, func);
+		if (route == null) {
+			return;
+		}
+
+		const globalPrefix = this.takesGlobalPrefix(controller)
+			? normalizePrefix(this.httpOptions?.globalPrefix)
+			: "";
+		const controllerPrefix = this.getControllerPrefix(controller);
+		const path = applyGlobalPrefix(globalPrefix, joinRoutePath(controllerPrefix, route.path));
+		const { method } = route;
+		const key = `${method}|${path}`;
+		const existing = this.routeMap.get(key);
+		if (existing != null) {
+			// Last one used to win silently, leaving the other handler unreachable (#503).
+			throw new RouteConfigurationError(
+				`Duplicate route ${method.toUpperCase()} ${path}: ${existing.controller.name}.${existing.handler} and ${controller.name}.${handler}`,
+			);
+		}
+		const routeArgs = this.getRouteArguments(controller, func);
+		const httpCode = getMeta<number>(MetadataKeys.httpCode, func);
+		const headers = getMeta<Record<string, string>>(MetadataKeys.headers, func);
+		const sse = getMeta<SseOptions>(MetadataKeys.sse, func);
+
+		this.routeMap.set(key, {
+			key,
+			controller,
+			handler,
+			path,
+			method,
+			routeArgs,
+			httpCode,
+			headers,
+			sse,
+		});
+	}
+
+	/** `@Controller({ globalPrefix: false })` opts out, unless the app put it back under. */
+	private takesGlobalPrefix(controller: Constructable): boolean {
+		const meta = getMeta<ControllerMetadata>(MetadataKeys.controller, controller.prototype);
+		return (
+			meta?.globalPrefix !== false ||
+			this.httpOptions?.underGlobalPrefix.has(controller) === true
+		);
+	}
+
+	private getControllerPrefix(controller: Constructable): string {
+		const meta = getMeta<ControllerMetadata>(MetadataKeys.controller, controller.prototype);
+		if (meta?.prefix) {
+			return normalizePrefix(meta.prefix);
+		}
+		const controllerName = controller.name.toLowerCase().replace("controller", "");
+		return controllerName !== "" ? `/${controllerName}` : "";
+	}
+
+	private getRouteArguments(controller: Constructable, handler: FunctionType): RouteArg[] {
+		const types = getFunctionArgs(controller.prototype, handler) ?? [];
+		const args: RouteArg[] = [];
+		for (const [argumentIndex, argumentType] of types.entries()) {
+			const argMeta = getArgumentMeta<ArgumentMeta>(
+				MetadataKeys.parameter,
+				handler,
+				argumentIndex,
+			);
+			if (argMeta == null && !isConstructable(argumentType)) {
+				continue;
+			}
+			args.push(this.getRouteArgument(argumentType, argumentIndex, handler));
+		}
+		return args;
+	}
+
+	private getRouteArgument(
+		argumentType: Type,
+		argumentIndex: number,
+		handler: FunctionType,
+	): RouteArg {
+		const argMeta = getArgumentMeta<ArgumentMeta>(
+			MetadataKeys.parameter,
+			handler,
+			argumentIndex,
+		);
+
+		// @CurrentUser() / interface params are Object (or other non-DTO types) — no field map.
+		if (isInjectedPart(argMeta?.argumentLocation) || !isConstructable(argumentType)) {
+			return {
+				...argMeta,
+				pipes: [],
+				argumentIndex,
+				argumentType: (isConstructable(argumentType) ? argumentType : Object) as Constructable,
+				fieldMap: new Map(),
+			};
+		}
+
+		const pipes = argMeta != null ? this.getDefaultPipes(argumentType) : [];
+		const fieldMap = this.getFields(argumentType, argumentIndex, argMeta);
+		const routeArg: RouteArg = {
+			...argMeta,
+			pipes,
+			argumentIndex,
+			argumentType,
+			fieldMap,
+		};
+
+		return routeArg;
+	}
+
+	private getFields(
+		argumentType: Constructable,
+		argumentIndex: number,
+		argMeta: ArgumentMeta,
+	) {
+		const inst = new argumentType();
+		const fields = getFields(inst);
+		const fieldMap =
+			getMeta<Map<string, FieldMeta>>(MetadataKeys.fieldMap, argumentType.prototype) ??
+			new Map<string, FieldMeta>();
+
+		for (const field of fields) {
+			const fieldKey = field.key;
+			const fieldMeta = fieldMap.get(field.key);
+			if (fieldMeta && fieldMeta.fieldLocation == null && argMeta?.argumentLocation == null) {
+				throw new RouteConfigurationError(
+					`field ${fieldMeta.fieldKey} must specify a location because location was not specified for the route argument at idx ${argumentIndex}`,
+				);
+			}
+			const enriched = this.enrichField(field, fieldMeta, argMeta);
+			fieldMap.set(fieldKey, enriched);
+		}
+
+		return fieldMap;
+	}
+
+	private enrichField(field: Field, fieldMeta: FieldMeta, argMeta: ArgumentMeta): FieldMeta {
+		const fieldLocation = fieldMeta?.fieldLocation ?? argMeta.argumentLocation;
+		const pipes = this.getDefaultPipes(fieldMeta?.fieldType);
+		return {
+			fieldKey: field.key,
+			mappingKey: field.key,
+			...fieldMeta,
+			fieldLocation,
+			pipes,
+		};
+	}
+
+	private getDefaultPipes(argumentType: Type) {
+		if (argumentType == null) {
+			return [];
+		}
+
+		let pipe: Constructable<Pipe>;
+		if (!isPrimitiveOrDateType(argumentType)) {
+			pipe = JsonPipe;
+			return [pipe];
+		}
+		switch (argumentType.name) {
+			case "Number":
+				pipe = NumberPipe;
+				break;
+			case "Boolean":
+				pipe = BooleanPipe;
+				break;
+			case "Date":
+				pipe = DatePipe;
+				break;
+			default:
+				return [];
+		}
+
+		return [pipe];
+	}
+}
+
+function isInjectedPart(location: RequestPart | undefined): boolean {
+	return location != null && InjectedParts.includes(location);
+}

package/src/routing/services/router.ts

@@ -0,0 +1,166 @@
+import { type LifetimeScope, LifetimeScopeToken } from "@decohere/di";
+import { inject, injectable, optional } from "@decohere/di/decorators";
+import type { Constructable } from "@decohere/core/reflection";
+import { scribe } from "@decohere/scribe";
+import type { IAuthorizationService } from "../../auth/auth.types.js";
+import type { PrincipalProvider } from "../../auth/principal-provider.js";
+import {
+	AuthorizationServiceToken,
+	HttpOptionsToken,
+	IPrincipalProviderToken,
+	RouteRegistryToken,
+} from "../../const.js";
+import type { HttpOptions } from "../../http/http.options.js";
+import { validateRequest } from "../../openapi/request-validator.js";
+import { SseResponse } from "../../sse/sse.types.js";
+import type { HttpRequest } from "../anvil.types.js";
+import { RoutingError } from "../anvil.types.js";
+import { getAuthorizeOptions, isAllowAnonymous } from "../decorators/auth.decorator.js";
+import { composeMiddleware, type Middleware } from "../middleware/middleware.js";
+import { RouteArgumentResolve } from "./route-argument-resolver.js";
+import { RouteRegistry } from "./route-registry.js";
+
+@injectable()
+export class Router {
+	private readonly argResolver = new RouteArgumentResolve();
+	private readonly lifetimeScope: LifetimeScope;
+	private readonly routeRegistry: RouteRegistry;
+	private readonly authService?: IAuthorizationService;
+	private readonly httpOptions?: HttpOptions;
+	private readonly logger = scribe.logger(Router.name);
+
+	public constructor(
+		@inject(RouteRegistryToken) routeRegistry: RouteRegistry,
+		@inject(LifetimeScopeToken) lifetimeScope: LifetimeScope,
+		@inject(AuthorizationServiceToken) @optional() authService?: IAuthorizationService,
+		@inject(HttpOptionsToken) httpOptions?: HttpOptions,
+	) {
+		this.routeRegistry = routeRegistry;
+		this.lifetimeScope = lifetimeScope;
+		this.authService = authService;
+		this.httpOptions = httpOptions;
+		this.assertAuthConfiguredForProtectedRoutes();
+	}
+
+	/**
+	 * Without an authorization service nothing checks tokens, so a route marked @Authorize
+	 * would be served to anyone. Refuse to start instead of failing open (#500).
+	 */
+	private assertAuthConfiguredForProtectedRoutes(): void {
+		if (this.authService != null) {
+			return;
+		}
+		const protectedRoutes = [...this.routeRegistry.routes]
+			.filter(({ controller, handler }) =>
+				getAuthorizeOptions(controller.prototype, controller.prototype[handler]),
+			)
+			.map(({ controller, handler }) => `${controller.name}.${String(handler)}`);
+		if (protectedRoutes.length > 0) {
+			throw new RoutingError(
+				`Routes use @Authorize but auth is not configured, so they would be open to anyone: ${protectedRoutes.join(", ")}. Add .withAuth() to the builder, or remove @Authorize.`,
+			);
+		}
+	}
+
+	public async route(routeKey: string, httpRequest: HttpRequest) {
+		const routeConfig = this.routeRegistry.getRoute(routeKey);
+		if (!routeConfig) {
+			throw new RoutingError(`Route was not configured for key ${routeKey}`);
+		}
+
+		const { controller, handler, routeArgs } = routeConfig;
+		// Unnamed: the request id comes from the client, so it is not unique (#497).
+		// Disposed before we respond, so async cleanup (e.g. rolling back a DB transaction)
+		// finishes first. An SSE route is the exception: its scope lives as long as the stream.
+		const scope = this.lifetimeScope.beginScope();
+		let scopeHandedOff = false;
+
+		// Runs inside the middleware chain so rejections (401/403/400) reach middleware such as
+		// the access log. Auth comes first so anonymous callers learn nothing about the body (#501).
+		const handle = async () => {
+			const principal = await this.authorize(routeConfig, httpRequest);
+
+			if (this.httpOptions?.openapi?.validateRequests !== false && this.httpOptions?.openapi) {
+				validateRequest(routeConfig, httpRequest);
+			}
+
+			const provider = scope.resolve<PrincipalProvider>(IPrincipalProviderToken);
+			provider.setPrincipal(principal);
+
+			const controllerInstance = scope.resolve(controller);
+			const func = controllerInstance[handler];
+			const argValues = this.argResolver.resolveArguments(httpRequest, routeArgs, provider);
+			try {
+				const result = await func.apply(controllerInstance, argValues);
+				if (routeConfig.sse == null) {
+					return result;
+				}
+				if (typeof result?.[Symbol.asyncIterator] !== "function") {
+					throw new RoutingError(
+						`${controller.name}.${String(handler)} is marked @Sse() so it must return an AsyncIterable (an async generator method works)`,
+					);
+				}
+				scopeHandedOff = true;
+				return new SseResponse(result, () => scope[Symbol.asyncDispose]());
+			} catch (error) {
+				this.logger.error(error.message, error.stack);
+				throw error;
+			}
+		};
+
+		try {
+			const middlewares = this.resolveMiddlewares(scope);
+			if (middlewares.length === 0) {
+				return await handle();
+			}
+
+			return await composeMiddleware(middlewares, handle, {
+				request: httpRequest,
+				route: routeConfig,
+			});
+		} catch (error) {
+			// A middleware failed after the handler returned: nobody will consume the stream.
+			scopeHandedOff = false;
+			throw error;
+		} finally {
+			if (!scopeHandedOff) {
+				await scope[Symbol.asyncDispose]();
+			}
+		}
+	}
+
+	private resolveMiddlewares(scope: LifetimeScope): Middleware[] {
+		const types = this.httpOptions?.middlewareTypes ?? [];
+		return types.map((type) => scope.resolve(type as Constructable<Middleware>));
+	}
+
+	private async authorize(
+		routeConfig: ReturnType<RouteRegistry["getRoute"]>,
+		httpRequest: HttpRequest,
+	): Promise<import("../../auth/auth.types.js").Principal | undefined> {
+		// Optional DI may resolve as null when auth is not registered.
+		if (this.authService == null) {
+			return;
+		}
+
+		const { controller, handler } = routeConfig;
+		const handlerFn = controller.prototype[handler];
+
+		if (isAllowAnonymous(controller.prototype, handlerFn)) {
+			return;
+		}
+
+		const authOptions = getAuthorizeOptions(controller.prototype, handlerFn);
+		if (authOptions === undefined) {
+			// Auth is enabled but the route has no @Authorize — require a valid
+			// token (fail closed) without checking a specific ability.
+			return this.authService.authenticateRequest(httpRequest);
+		}
+
+		return this.authService.authorizeRequest(
+			httpRequest,
+			authOptions.action,
+			authOptions.subject,
+		);
+	}
+}

package/src/sse/sse.decorator.ts

@@ -0,0 +1,41 @@
+import type { FunctionType } from "@decohere/core/reflection";
+import { defineArgumentMeta, defineMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../const.js";
+import type { ArgumentMeta, RequestPart } from "../routing/anvil.types.js";
+import type { SseOptions } from "./sse.types.js";
+
+/**
+ * Mark a route as a server-sent event stream. The method returns an `AsyncIterable` of
+ * {@link SseMessage}s (an `async *` method is the usual shape) and the HTTP package writes it as
+ * `text/event-stream`. Auth, validation and middleware run first, exactly as on any route,
+ * so an unauthorised caller gets a normal 401/403 and no event is ever sent.
+ *
+ * Combine with `@Get()` (EventSource only issues GET).
+ */
+export function Sse(options: SseOptions = {}) {
+	return (_target: object, _methodName: string, descriptor: PropertyDescriptor) => {
+		defineMeta(MetadataKeys.sse, options, descriptor.value);
+	};
+}
+
+function injected(location: RequestPart) {
+	return () => (target: object, propertyKey: string, parameterIndex: number) => {
+		const fn = (target as Record<string, FunctionType>)[propertyKey];
+		const meta: ArgumentMeta = {
+			argumentIndex: parameterIndex,
+			argumentLocation: location,
+			mappingKey: undefined,
+			pipes: [],
+		};
+		defineArgumentMeta<ArgumentMeta>(MetadataKeys.parameter, meta, fn, parameterIndex);
+	};
+}
+
+/**
+ * Inject an `AbortSignal` that aborts when the client disconnects or the app stops. Pass it to
+ * whatever the producer waits on (timers, subscriptions, queries) so it stops promptly.
+ */
+export const Signal = injected("signal");
+
+/** Inject the `Last-Event-ID` header the browser sends when it reconnects, or `undefined`. */
+export const LastEventId = injected("lastEventId");

package/src/sse/sse.encoder.ts

@@ -0,0 +1,86 @@
+import { scribe } from "@decohere/scribe";
+import { sseWire } from "./sse.wire.js";
+
+export type SseEncodeOptions = {
+	/** Aborted when the client disconnects or the app stops. */
+	signal: AbortSignal;
+	heartbeatMs: number;
+	/**
+	 * Called once, as the stream ends, with a promise that settles when the producer has
+	 * actually stopped (its `finally` blocks have run).
+	 */
+	onProducerStopped: (stopped: Promise<void>) => void;
+};
+
+const logger = scribe.logger("SseEncoder");
+
+type Step =
+	| { kind: "item"; result: IteratorResult<unknown> }
+	| { kind: "heartbeat" }
+	| { kind: "abort" };
+
+/**
+ * Turn the handler's events into SSE text. Writes an opening comment so the browser sees the
+ * response headers at once, a heartbeat whenever the producer is quiet, and stops as soon as the
+ * signal aborts, without waiting for a producer that is stuck.
+ */
+export async function* encodeSse(
+	source: AsyncIterable<unknown>,
+	options: SseEncodeOptions,
+): AsyncGenerator<string> {
+	const { signal, heartbeatMs } = options;
+	const iterator = source[Symbol.asyncIterator]();
+	let onAbort: (() => void) | undefined;
+	const abortStep = new Promise<Step>((resolve) => {
+		onAbort = () => resolve({ kind: "abort" });
+		if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+	});
+	let pending: Promise<Step> | undefined;
+	try {
+		yield sseWire.formatComment("open");
+		while (!signal.aborted) {
+			pending ??= iterator.next().then((result): Step => ({ kind: "item", result }));
+			let timer: NodeJS.Timeout | undefined;
+			const steps: Promise<Step>[] = [pending, abortStep];
+			if (heartbeatMs > 0) {
+				steps.push(
+					new Promise<Step>((resolve) => {
+						timer = setTimeout(() => resolve({ kind: "heartbeat" }), heartbeatMs);
+					}),
+				);
+			}
+			let step: Step;
+			try {
+				step = await Promise.race(steps);
+			} finally {
+				clearTimeout(timer);
+			}
+			if (step.kind === "abort") return;
+			if (step.kind === "heartbeat") {
+				yield sseWire.formatComment("heartbeat");
+				continue;
+			}
+			pending = undefined;
+			if (step.result.done) return;
+			yield sseWire.formatMessage(step.result.value);
+		}
+	} catch (error) {
+		// Headers are already sent, so the only honest thing left is to log and end the stream.
+		if (!signal.aborted) logger.error("SSE producer failed", error);
+	} finally {
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+		// If the producer has not answered its last `next()`, `return()` waits behind it. That is
+		// why handlers must pass the signal to whatever they wait on.
+		options.onProducerStopped(
+			Promise.resolve()
+				.then(() => iterator.return?.())
+				.then(
+					() => undefined,
+					(error: unknown) => {
+						if (!signal.aborted) logger.error("SSE producer failed while stopping", error);
+					},
+				),
+		);
+	}
+}

package/src/sse/sse.types.ts

@@ -0,0 +1,47 @@
+/**
+ * One server-sent event. A bare `string` yielded by a handler is shorthand for `{ data }`.
+ *
+ * `data` is written as-is when it is a string and as JSON otherwise.
+ */
+export type SseMessage<T = unknown> = {
+	data: T;
+	/** Becomes the `event:` field; the browser dispatches it to `addEventListener(event, ...)`. */
+	event?: string;
+	/** Becomes the `id:` field; the browser sends the last one back as `Last-Event-ID` on reconnect. */
+	id?: string;
+	/** Tells the browser how many milliseconds to wait before reconnecting. */
+	retry?: number;
+};
+
+/** What a `@Sse()` handler returns: any async iterable of messages (an `async *` method is the usual shape). */
+export type SseStream<T = unknown> = AsyncIterable<SseMessage<T> | string>;
+
+export type SseOptions = {
+	/**
+	 * Milliseconds of silence before the HTTP package writes a `: heartbeat` comment, which keeps proxies
+	 * and load balancers from closing an idle connection. Default 15000. `0` turns heartbeats off.
+	 */
+	heartbeatMs?: number;
+};
+
+export const DEFAULT_SSE_HEARTBEAT_MS = 15_000;
+
+/**
+ * What the router hands the HTTP provider for an `@Sse()` route. The request-scoped services the
+ * handler uses must stay alive for as long as the stream runs, so the provider calls `release()`
+ * once the stream is over, instead of the router disposing them as soon as the handler returns.
+ */
+export class SseResponse {
+	private released: Promise<void> | undefined;
+
+	public constructor(
+		public readonly events: AsyncIterable<unknown>,
+		private readonly onRelease: () => Promise<void>,
+	) {}
+
+	/** Safe to call more than once. */
+	public release(): Promise<void> {
+		this.released ??= this.onRelease();
+		return this.released;
+	}
+}

package/src/sse/sse.wire.ts

@@ -0,0 +1,34 @@
+import type { SseMessage } from "./sse.types.js";
+
+/** Line breaks would end a field early, so a client-controlled `id` could inject extra fields. */
+function singleLine(value: string): string {
+	return value.replace(/[\r\n]+/g, " ");
+}
+
+function toMessage(item: unknown): SseMessage {
+	if (typeof item === "object" && item !== null && "data" in item) {
+		return item as SseMessage;
+	}
+	return { data: item };
+}
+
+/** Encode one event as the text a browser's `EventSource` parses. */
+function formatMessage(item: unknown): string {
+	const { data, event, id, retry } = toMessage(item);
+	let frame = "";
+	if (id != null) frame += `id: ${singleLine(String(id))}\n`;
+	if (event != null) frame += `event: ${singleLine(event)}\n`;
+	if (retry != null && Number.isFinite(retry)) frame += `retry: ${Math.trunc(retry)}\n`;
+	const text = typeof data === "string" ? data : (JSON.stringify(data) ?? "");
+	for (const line of text.split(/\r\n|\r|\n/)) {
+		frame += `data: ${line}\n`;
+	}
+	return `${frame}\n`;
+}
+
+/** A comment line: ignored by `EventSource`, but it is traffic on the wire. */
+function formatComment(text: string): string {
+	return `: ${singleLine(text)}\n\n`;
+}
+
+export const sseWire = { formatMessage, formatComment };