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

package/tests/sse.integration.spec.ts

@@ -0,0 +1,421 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import type { ContainerBuilder } from "@decohere/di";
+import { inject, injectable } from "@decohere/di/decorators";
+import type { IConfigurationService } from "@decohere/core/configuration";
+import { ConfigurationServiceToken } from "@decohere/core/configuration";
+import type { Constructable } from "@decohere/core/reflection";
+import { describe, expect, it } from "vitest";
+import type { OpenApiDocument } from "../src/openapi/openapi.types.js";
+import { AuthConfig } from "../src/auth/auth.config.js";
+import "../src/auth/auth.extensions.js";
+import { TokenService } from "../src/auth/token-service.js";
+import {
+	AllowAnonymous,
+	Authorize,
+	Controller,
+	Get,
+	LastEventId,
+	Signal,
+	Sse,
+	type SseStream,
+} from "../src/index.js";
+import { bootModule } from "../src/testing/index.js";
+
+/** Records what the producers did, so tests can see that cleanup ran. */
+class Probe {
+	public started = 0;
+	public timersRunning = 0;
+	public signalAborted = false;
+	public lastEventId: string | undefined;
+	public scopeDisposed = false;
+}
+const probe = new Probe();
+
+/** Request-scoped: lives as long as the stream, disposed when it ends. */
+@injectable()
+class RequestResource {
+	public constructor() {
+		probe.scopeDisposed = false;
+	}
+	public async [Symbol.asyncDispose]() {
+		probe.scopeDisposed = true;
+	}
+}
+
+/** A producer that owns a timer, like a real subscription would. */
+async function* ticker(signal: AbortSignal, intervalMs: number): AsyncGenerator<string> {
+	probe.started += 1;
+	probe.timersRunning += 1;
+	let tick = 0;
+	try {
+		while (!signal.aborted) {
+			await new Promise<void>((resolve) => {
+				const timer = setTimeout(resolve, intervalMs);
+				signal.addEventListener(
+					"abort",
+					() => {
+						clearTimeout(timer);
+						resolve();
+					},
+					{ once: true },
+				);
+			});
+			if (!signal.aborted) yield `tick ${++tick}`;
+		}
+	} finally {
+		probe.timersRunning -= 1;
+		probe.signalAborted = signal.aborted;
+	}
+}
+
+@Controller({ prefix: "/feed" })
+class FeedController {
+	public constructor(@inject(RequestResource) private readonly resource: RequestResource) {}
+
+	@Sse()
+	@Get("/items")
+	public async *items(): SseStream {
+		probe.started += 1;
+		yield { id: "1", event: "item", data: { name: "first" } };
+		yield { id: "2", event: "item", data: { name: "second" } };
+		yield "plain text";
+		yield { data: "line one\nline two" };
+	}
+
+	@Sse()
+	@Get("/resume")
+	public async *resume(@LastEventId() lastEventId?: string): SseStream {
+		probe.lastEventId = lastEventId;
+		const from = lastEventId == null ? 1 : Number(lastEventId) + 1;
+		for (const id of [from, from + 1]) {
+			yield { id: String(id), data: `event ${id}` };
+		}
+	}
+
+	@Sse({ heartbeatMs: 20 })
+	@Get("/quiet")
+	public async *quiet(@Signal() signal: AbortSignal): SseStream {
+		yield "hello";
+		await sleep(100, undefined, { signal });
+		yield "world";
+	}
+
+	@Sse({ heartbeatMs: 0 })
+	@Get("/live")
+	public async *live(@Signal() signal: AbortSignal): SseStream {
+		void this.resource;
+		yield { id: "0", data: "connected" };
+		for await (const message of ticker(signal, 10)) yield message;
+	}
+
+	@Sse()
+	@Get("/broken")
+	public async *broken(): SseStream {
+		yield "before";
+		throw new Error("producer exploded");
+	}
+
+	@Sse()
+	@Get("/not-a-stream")
+	public notAStream() {
+		return { oops: true };
+	}
+
+	@Get("/plain")
+	public plain() {
+		return { ok: true };
+	}
+}
+
+describe("server-sent events from a controller route (#629)", () => {
+	it("writes the handler's events as text/event-stream", async () => {
+		await using api = await bootModule({
+			controllers: [FeedController],
+			services: services(),
+		});
+
+		const read = await api.readEvents("/feed/items", { count: 4 });
+
+		expect(read.status).toBe(200);
+		expect(read.headers.get("content-type")).toContain("text/event-stream");
+		expect(read.headers.get("cache-control")).toContain("no-cache");
+		expect(read.events).toEqual([
+			{ id: "1", event: "item", data: '{"name":"first"}' },
+			{ id: "2", event: "item", data: '{"name":"second"}' },
+			{ data: "plain text" },
+			{ data: "line one\nline two" },
+		]);
+	});
+
+	it("ends the response when the handler finishes", async () => {
+		await using api = await bootModule({
+			controllers: [FeedController],
+			services: services(),
+		});
+
+		const read = await api.readEvents("/feed/items", { count: Infinity });
+
+		expect(read.ended).toBe(true);
+		expect(read.events).toHaveLength(4);
+	});
+
+	it("gives the handler the Last-Event-ID the browser sends when it reconnects", async () => {
+		await using api = await bootModule({
+			controllers: [FeedController],
+			services: services(),
+		});
+
+		const first = await api.readEvents("/feed/resume", { count: 2 });
+		expect(first.events.map((e) => e.id)).toEqual(["1", "2"]);
+		expect(probe.lastEventId).toBeUndefined();
+
+		const resumed = await api.readEvents("/feed/resume", {
+			count: 2,
+			headers: { "Last-Event-ID": "2" },
+		});
+		expect(probe.lastEventId).toBe("2");
+		expect(resumed.events.map((e) => e.id)).toEqual(["3", "4"]);
+	});
+
+	it("writes a heartbeat comment while the producer is quiet", async () => {
+		await using api = await bootModule({
+			controllers: [FeedController],
+			services: services(),
+		});
+
+		const read = await api.readEvents("/feed/quiet", { count: 2 });
+
+		expect(read.events.map((e) => e.data)).toEqual(["hello", "world"]);
+		expect(read.comments.filter((c) => c === "heartbeat").length).toBeGreaterThanOrEqual(2);
+	});
+
+	it("ends the stream without sending a half-built event when the producer throws", async () => {
+		await using api = await bootModule({
+			controllers: [FeedController],
+			services: services(),
+		});
+
+		const read = await api.readEvents("/feed/broken", { count: Infinity });
+
+		expect(read.events).toEqual([{ data: "before" }]);
+		expect(read.ended).toBe(true);
+	});
+
+	it("answers 500 for an @Sse() method that does not return a stream", async () => {
+		await using api = await bootModule({
+			controllers: [FeedController],
+			services: services(),
+		});
+
+		const read = await api.readEvents("/feed/not-a-stream");
+
+		expect(read.status).toBe(500);
+		expect(read.events).toEqual([]);
+	});
+
+	it("leaves ordinary routes alone", async () => {
+		await using api = await bootModule({
+			controllers: [FeedController],
+			services: services(),
+		});
+
+		const response = await fetch(`${api.baseUrl}/feed/plain`);
+
+		expect(response.headers.get("content-type")).toContain("application/json");
+		expect(await response.json()).toEqual({ ok: true });
+	});
+});
+
+describe("SSE: client disconnect and app stop", () => {
+	it("stops the producer, its timer and the request scope when the client disconnects", async () => {
+		await using api = await bootModule({
+			controllers: [FeedController],
+			services: services(),
+		});
+		const timersBefore = probe.timersRunning;
+		probe.signalAborted = false;
+
+		const read = await api.readEvents("/feed/live", { count: 2 });
+
+		expect(read.events.length).toBe(2);
+		await waitFor(() => probe.timersRunning === timersBefore);
+		expect(probe.signalAborted).toBe(true);
+		await waitFor(() => probe.scopeDisposed);
+	});
+
+	it("keeps request-scoped services alive while the stream is running", async () => {
+		await using api = await bootModule({
+			controllers: [FeedController],
+			services: services(),
+		});
+
+		const reading = api.readEvents("/feed/live", { count: Infinity, timeoutMs: 4000 });
+		await sleep(80);
+
+		expect(probe.scopeDisposed).toBe(false);
+		await api.stop();
+		await reading;
+		expect(probe.scopeDisposed).toBe(true);
+	});
+
+	it("closes open streams when the app stops, so stopping does not hang", async () => {
+		const api = await bootModule({ controllers: [FeedController], services: services() });
+		const timersBefore = probe.timersRunning;
+
+		const reading = api.readEvents("/feed/live", { count: Infinity, timeoutMs: 4000 });
+		await waitFor(() => probe.timersRunning > timersBefore);
+
+		await api.stop();
+		const read = await reading;
+
+		expect(read.ended).toBe(true);
+		expect(probe.timersRunning).toBe(timersBefore);
+		expect(probe.signalAborted).toBe(true);
+	});
+
+	it("closes open streams on the dispose path Flux uses for a reboot", async () => {
+		const api = await bootModule({ controllers: [FeedController], services: services() });
+		const timersBefore = probe.timersRunning;
+		const reading = api.readEvents("/feed/live", { count: Infinity, timeoutMs: 4000 });
+		await waitFor(() => probe.timersRunning > timersBefore);
+
+		// Flux calls Symbol.asyncDispose on the entry's default export, which is the app.
+		await api.app[Symbol.asyncDispose]();
+
+		expect((await reading).ended).toBe(true);
+		expect(probe.timersRunning).toBe(timersBefore);
+	});
+});
+
+// Auth: a real shared-secret token service, no dev shortcuts.
+const secretConfig = {
+	secret: "super-secret-key-that-is-long-enough-for-hs256",
+	issuer: "test-issuer",
+	audience: "test-audience",
+};
+
+class SecretConfigService implements IConfigurationService {
+	public get dataSources() {
+		return [];
+	}
+	public async get<T extends object>(type: Constructable<T> | string): Promise<T> {
+		if (type === AuthConfig)
+			return Object.assign(new AuthConfig(), secretConfig) as unknown as T;
+		return {} as T;
+	}
+}
+
+@Controller({ prefix: "/secure" })
+class SecureFeedController {
+	@Authorize("read", "Article")
+	@Sse()
+	@Get("/articles")
+	public async *articles(): SseStream {
+		probe.started += 1;
+		yield { id: "1", data: "secret article" };
+	}
+
+	@AllowAnonymous()
+	@Sse()
+	@Get("/public")
+	public async *open(): SseStream {
+		yield "hello everyone";
+	}
+}
+
+describe("SSE: auth runs before any event is sent", () => {
+	const boot = () =>
+		bootModule({
+			controllers: [SecureFeedController],
+			services: (c) =>
+				c.registerSingleton(ConfigurationServiceToken, new SecretConfigService()),
+			configure: (builder) => builder.withAuth(),
+		});
+	const tokens = new TokenService(secretConfig);
+
+	it("answers 401 with no events when there is no token", async () => {
+		await using api = await boot();
+		probe.started = 0;
+
+		const read = await api.readEvents("/secure/articles");
+
+		expect(read.status).toBe(401);
+		expect(read.events).toEqual([]);
+		expect(read.headers.get("content-type")).not.toContain("text/event-stream");
+		expect(probe.started).toBe(0);
+	});
+
+	it("answers 403 with no events when the token lacks the permission", async () => {
+		await using api = await boot();
+		probe.started = 0;
+		const token = await tokens.sign({ sub: "alice", scope: "read:Comment" });
+
+		const read = await api.readEvents("/secure/articles", {
+			headers: { authorization: `Bearer ${token}` },
+		});
+
+		expect(read.status).toBe(403);
+		expect(read.events).toEqual([]);
+		expect(probe.started).toBe(0);
+	});
+
+	it("streams to a caller whose token allows it", async () => {
+		await using api = await boot();
+		const token = await tokens.sign({ sub: "alice", scope: "read:Article" });
+
+		const read = await api.readEvents("/secure/articles", {
+			headers: { authorization: `Bearer ${token}` },
+		});
+
+		expect(read.status).toBe(200);
+		expect(read.events).toEqual([{ id: "1", data: "secret article" }]);
+	});
+
+	it("honours @AllowAnonymous on a stream", async () => {
+		await using api = await boot();
+
+		const read = await api.readEvents("/secure/public");
+
+		expect(read.events).toEqual([{ data: "hello everyone" }]);
+	});
+});
+
+describe("SSE: OpenAPI", () => {
+	it("documents a stream route as text/event-stream, with the Last-Event-ID header", async () => {
+		await using api = await bootModule({
+			controllers: [FeedController],
+			services: services(),
+			configure: (builder) => builder.withOpenApi({ info: { title: "t", version: "1" } }),
+		});
+
+		const document = (await (
+			await fetch(`${api.baseUrl}/openapi.json`)
+		).json()) as OpenApiDocument;
+
+		const stream = document.paths["/feed/items"].get;
+		expect(stream.responses["200"].content).toEqual({
+			"text/event-stream": { schema: { type: "string" } },
+		});
+		const resume = document.paths["/feed/resume"].get;
+		expect(resume.parameters).toContainEqual({
+			name: "Last-Event-ID",
+			in: "header",
+			schema: { type: "string" },
+		});
+		expect(document.paths["/feed/plain"].get.responses["200"].content).toBeUndefined();
+	});
+});
+
+function services() {
+	return (c: ContainerBuilder) => {
+		c.registerRequestScoped(RequestResource);
+	};
+}
+
+async function waitFor(condition: () => boolean, timeoutMs = 2000) {
+	const deadline = Date.now() + timeoutMs;
+	while (!condition()) {
+		if (Date.now() > deadline) throw new Error("condition not met in time");
+		await sleep(5);
+	}
+}

package/tests/sse.wire.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { sseWire } from "../src/sse/sse.wire.js";
+
+// Edges the HTTP tests cannot see: what the bytes look like for hostile or odd input.
+describe("SSE wire format", () => {
+	it("cannot be made to inject a field through a line break in id or event", () => {
+		const frame = sseWire.formatMessage({
+			id: "1\ndata: injected",
+			event: "a\r\nretry: 1",
+			data: "x",
+		});
+
+		expect(frame).toBe("id: 1 data: injected\nevent: a retry: 1\ndata: x\n\n");
+	});
+
+	it("splits multi-line data into one data field per line, whatever the line ending", () => {
+		expect(sseWire.formatMessage("a\r\nb\rc\nd")).toBe(
+			"data: a\ndata: b\ndata: c\ndata: d\n\n",
+		);
+	});
+
+	it("writes non-string data as JSON and a bare string as-is", () => {
+		expect(sseWire.formatMessage({ data: { n: 1 } })).toBe('data: {"n":1}\n\n');
+		expect(sseWire.formatMessage("hi")).toBe("data: hi\n\n");
+		expect(sseWire.formatMessage(42)).toBe("data: 42\n\n");
+	});
+
+	it("writes retry as a whole number of milliseconds", () => {
+		expect(sseWire.formatMessage({ data: "x", retry: 1500.9 })).toBe(
+			"retry: 1500\ndata: x\n\n",
+		);
+	});
+});

package/LICENSE

@@ -1,15 +0,0 @@
-ISC License
-
-Copyright (c) 2025-2026 Typesmiths
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/commonjs/src/app/app.js

@@ -1,166 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get ApiConfiguration () {
-        return ApiConfiguration;
-    },
-    get App () {
-        return App;
-    }
-});
-const _crucible = require("@decohere/crucible");
-const _decorators = require("@decohere/crucible/decorators");
-const _configuration = require("@decohere/core/configuration");
-const _scribe = require("@decohere/scribe");
-const _const = require("../const.js");
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-function _ts_metadata(k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-function _ts_param(paramIndex, decorator) {
-    return function(target, key) {
-        decorator(target, key, paramIndex);
-    };
-}
-const DEFAULT_PORT = 3000;
-const DEFAULT_SHUTDOWN_SIGNALS = [
-    "SIGTERM",
-    "SIGINT"
-];
-const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
-class ApiConfiguration {
-    port;
-}
-class App {
-    container;
-    configurationService;
-    httpProvider;
-    hostedServices;
-    _addresses = Array.of();
-    logger = _scribe.scribe.logger(App.name);
-    disposing;
-    disposingContainer = false;
-    signalHandler;
-    shutdownSignals = [];
-    constructor(container, configurationService, httpProvider, hostedServices){
-        this.container = container;
-        this.configurationService = configurationService;
-        this.httpProvider = httpProvider;
-        this.hostedServices = hostedServices;
-    }
-    get addresses() {
-        return this._addresses;
-    }
-    async start(options) {
-        this.logger.info("Starting app");
-        // Before HTTP, so a request never reaches a service that has not started.
-        await this.hostedServices?.start(this.container);
-        // The app was stopped while a hosted service was still starting.
-        if (this.disposing != null) return;
-        const hasHostedServices = this.hostedServices != null && !this.hostedServices.isEmpty;
-        if (!this.httpProvider) {
-            if (hasHostedServices) this.stopOnSignals(options);
-            return;
-        }
-        const port = await this.getPort(options);
-        this.logger.info(`Starting http on port ${port}`);
-        const startResponse = await this.httpProvider?.start({
-            port,
-            ...options?.host != null ? {
-                host: options.host
-            } : {}
-        });
-        this._addresses = [
-            ...startResponse.addresses
-        ];
-        this.logger.info("Listening on:", this._addresses);
-        this.stopOnSignals(options);
-        return startResponse;
-    }
-    [Symbol.asyncDispose]() {
-        // The container holds this App too; when stop() disposes the container it lands
-        // here, and awaiting our own shutdown would deadlock.
-        if (this.disposingContainer) return Promise.resolve();
-        return this.dispose();
-    }
-    /** Stop the app. Calling it again (or from a signal) returns the same shutdown. */ dispose() {
-        this.disposing ??= this.stop();
-        return this.disposing;
-    }
-    async stop() {
-        // Removed first, so a second Ctrl+C / SIGTERM gets Node's default: exit now.
-        this.removeSignalHandlers();
-        this.logger.info("Stopping");
-        // Hosted services hear the signal at once, so background work winds down while HTTP drains.
-        this.hostedServices?.abort();
-        try {
-            // HTTP first: in-flight requests still need the services (DB pools etc.) that
-            // disposing the container would close.
-            await this.httpProvider?.stop();
-            // Hosted services next, while what they use is still open.
-            await this.hostedServices?.stop();
-        } finally{
-            this.disposingContainer = true;
-            await this.container[Symbol.asyncDispose]();
-            await _scribe.scribe.stop();
-        }
-    }
-    stopOnSignals(options) {
-        const signals = options?.shutdownSignals ?? DEFAULT_SHUTDOWN_SIGNALS;
-        const timeoutMs = options?.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
-        if (signals === false || signals.length === 0) return;
-        this.signalHandler = (signal)=>{
-            this.logger.info(`Received ${signal}; finishing in-flight requests`);
-            // console.error, not the logger: scribe may be the thing that's stuck.
-            const timer = setTimeout(()=>{
-                console.error(`Shutdown did not finish within ${timeoutMs}ms; exiting.`);
-                process.exit(1);
-            }, timeoutMs);
-            timer.unref();
-            this.dispose().then(()=>clearTimeout(timer), (error)=>{
-                clearTimeout(timer);
-                console.error("Shutdown failed:", error);
-                process.exit(1);
-            });
-        };
-        this.shutdownSignals = signals;
-        for (const signal of signals)process.on(signal, this.signalHandler);
-    }
-    removeSignalHandlers() {
-        if (!this.signalHandler) return;
-        for (const signal of this.shutdownSignals)process.off(signal, this.signalHandler);
-    }
-    async getPort(options) {
-        const port = options?.port ?? (await this.configurationService?.get(ApiConfiguration))?.port ?? DEFAULT_PORT;
-        return port;
-    }
-}
-App = _ts_decorate([
-    _ts_param(0, (0, _decorators.inject)(_crucible.LifetimeScopeToken)),
-    _ts_param(1, (0, _decorators.inject)(_configuration.ConfigurationServiceToken)),
-    _ts_param(1, (0, _decorators.optional)()),
-    _ts_param(2, (0, _decorators.inject)(_const.HttpProviderToken)),
-    _ts_param(2, (0, _decorators.optional)()),
-    _ts_param(3, (0, _decorators.inject)(_const.HostedServiceHostToken)),
-    _ts_param(3, (0, _decorators.optional)()),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof LifetimeScope === "undefined" ? Object : LifetimeScope,
-        typeof IConfigurationService === "undefined" ? Object : IConfigurationService,
-        typeof HttpProvider === "undefined" ? Object : HttpProvider,
-        typeof HostedServiceHost === "undefined" ? Object : HostedServiceHost
-    ])
-], App);

package/commonjs/src/app/index.js

@@ -1,19 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-_export_star(require("./app.js"), exports);
-_export_star(require("./module.js"), exports);
-function _export_star(from, to) {
-    Object.keys(from).forEach(function(k) {
-        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
-            Object.defineProperty(to, k, {
-                enumerable: true,
-                get: function() {
-                    return from[k];
-                }
-            });
-        }
-    });
-    return from;
-}

package/commonjs/src/app/module.js

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-Object.defineProperty(exports, "Module", {
-    enumerable: true,
-    get: function() {
-        return Module;
-    }
-});
-class Module {
-    constructor(data){
-        Object.assign(this, data);
-    }
-    entities;
-    repositories;
-}