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

package/src/testing/boot-module.ts

@@ -0,0 +1,63 @@
+import type { ContainerBuilder } from "@decohere/di";
+import type { Constructable } from "@decohere/core/reflection";
+import type { App } from "../app/app.js";
+import { Builder } from "../builder/builder.js";
+import "../http/http.extensions.js";
+import { FastifyProvider } from "../providers/fastify.provider.js";
+import type { HttpProvider } from "../routing/anvil.types.js";
+import {
+	type EventStreamRead,
+	type ReadEventsOptions,
+	readEventStream,
+} from "./sse-reader.js";
+
+export type BootModuleOptions = {
+	controllers: Constructable[];
+	/** Register services the controllers need. */
+	services?: (containerBuilder: ContainerBuilder) => void;
+	/** Add anything else to the builder (`withAuth()`, `withOpenApi()`, ...) before the app is built. */
+	configure?: (builder: Builder) => unknown;
+	/** Defaults to the Fastify provider. */
+	provider?: Constructable<HttpProvider>;
+};
+
+export type BootedModule = AsyncDisposable & {
+	app: App;
+	/** Origin of the listening app, e.g. `http://127.0.0.1:41233`. */
+	baseUrl: string;
+	/** `GET path` as an `EventSource` would, and collect the first `count` events. */
+	readEvents(path: string, options?: ReadEventsOptions): Promise<EventStreamRead>;
+	/** Stop the app (closing any open streams). Same as `await using`. */
+	stop(): Promise<void>;
+};
+
+/**
+ * Boot the given controllers as a real app on a free loopback port, so a test can call it over
+ * HTTP. The app runs the full pipeline: routing, auth, middleware, and the real provider.
+ *
+ * @example
+ * await using api = await bootModule({ controllers: [PriceController] });
+ * const { events } = await api.readEvents("/prices/stream", { count: 3 });
+ */
+export async function bootModule(options: BootModuleOptions): Promise<BootedModule> {
+	let builder = Builder.create()
+		.withHttp(options.provider ?? FastifyProvider)
+		.withControllers(...options.controllers);
+	if (options.services) builder = builder.withServices(options.services);
+	options.configure?.(builder);
+	const app = await builder.build();
+	await app.start({ port: 0, host: "127.0.0.1", shutdownSignals: false });
+	const baseUrl = app.addresses[0];
+	if (baseUrl == null) {
+		await app.dispose();
+		throw new Error("app.start({ port: 0 }) advertised no IPv4 address");
+	}
+	const stop = () => app.dispose();
+	return {
+		app,
+		baseUrl,
+		readEvents: (path, readOptions) => readEventStream(`${baseUrl}${path}`, readOptions),
+		stop,
+		[Symbol.asyncDispose]: stop,
+	};
+}

package/src/testing/sse-reader.ts

@@ -0,0 +1,120 @@
+export type ReceivedEvent = {
+	/** The `data:` lines joined with `\n`, as `EventSource` would give them. */
+	data: string;
+	event?: string;
+	id?: string;
+	retry?: number;
+};
+
+export type EventStreamRead = {
+	status: number;
+	headers: Headers;
+	/** The events received, at most the requested count. */
+	events: ReceivedEvent[];
+	/** Comment lines (`: heartbeat` and the like) seen before the read ended. */
+	comments: string[];
+	/** True when the server ended the stream (as opposed to the reader stopping at the count). */
+	ended: boolean;
+};
+
+export type ReadEventsOptions = {
+	/** Stop and close the connection after this many events. Default 1. `Infinity` reads until the server ends the stream. */
+	count?: number;
+	headers?: Record<string, string>;
+	/** Give up (and fail) if the read has not finished after this many milliseconds. Default 5000. */
+	timeoutMs?: number;
+};
+
+/** Incremental parser for the `text/event-stream` format. */
+class SseParser {
+	private buffer = "";
+	private data: string[] = [];
+	private current: ReceivedEvent = { data: "" };
+	private hasFields = false;
+
+	public readonly events: ReceivedEvent[] = [];
+	public readonly comments: string[] = [];
+
+	public push(chunk: string): void {
+		this.buffer += chunk;
+		let newline: number;
+		while ((newline = this.buffer.search(/\r\n|\r|\n/)) !== -1) {
+			const line = this.buffer.slice(0, newline);
+			const eol = this.buffer.slice(newline).startsWith("\r\n") ? 2 : 1;
+			this.buffer = this.buffer.slice(newline + eol);
+			this.line(line);
+		}
+	}
+
+	private line(line: string): void {
+		if (line === "") {
+			if (this.hasFields) {
+				this.events.push({ ...this.current, data: this.data.join("\n") });
+			}
+			this.data = [];
+			this.current = { data: "" };
+			this.hasFields = false;
+			return;
+		}
+		if (line.startsWith(":")) {
+			this.comments.push(line.slice(1).trim());
+			return;
+		}
+		const colon = line.indexOf(":");
+		const field = colon === -1 ? line : line.slice(0, colon);
+		let value = colon === -1 ? "" : line.slice(colon + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+		this.hasFields = true;
+		if (field === "data") this.data.push(value);
+		else if (field === "event") this.current.event = value;
+		else if (field === "id") this.current.id = value;
+		else if (field === "retry") this.current.retry = Number(value);
+	}
+}
+
+/**
+ * GET `url` as an `EventSource` would and collect events until `count` have arrived or the
+ * server ends the stream. A non-200 answer (401, 403, ...) returns at once with no events.
+ */
+export async function readEventStream(
+	url: string,
+	options: ReadEventsOptions = {},
+): Promise<EventStreamRead> {
+	const count = options.count ?? 1;
+	const abort = new AbortController();
+	const timer = setTimeout(
+		() => abort.abort(new Error(`No ${count} events from ${url} in time`)),
+		options.timeoutMs ?? 5000,
+	);
+	try {
+		const response = await fetch(url, {
+			headers: { accept: "text/event-stream", ...options.headers },
+			signal: abort.signal,
+		});
+		const parser = new SseParser();
+		let ended = false;
+		if (response.status === 200 && response.body != null) {
+			const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+			while (parser.events.length < count) {
+				const { done, value } = await reader.read();
+				if (done) {
+					ended = true;
+					break;
+				}
+				parser.push(value);
+			}
+			await reader.cancel();
+		} else {
+			await response.body?.cancel();
+		}
+		return {
+			status: response.status,
+			headers: response.headers,
+			events: parser.events.slice(0, count),
+			comments: parser.comments,
+			ended,
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/tests/app.hosted-services.spec.ts

@@ -0,0 +1,292 @@
+import { inject, injectable } from "@decohere/di/decorators";
+import { afterEach, describe, expect, it } from "vitest";
+import type { App } from "../src/app/app.js";
+import { Builder } from "../src/builder/builder.js";
+import type { HostedService } from "../src/hosting/hosted-service.js";
+import "../src/health/health.extensions.js";
+import "../src/http/http.extensions.js";
+import { FastifyProvider } from "../src/providers/fastify.provider.js";
+
+/** What happened, in order, across every service and the app in one test. */
+let events: string[] = [];
+
+const DbToken = Symbol("Db");
+
+/** Stands in for a connection pool: closed when the app's container is disposed. */
+@injectable()
+class Db {
+	public async [Symbol.asyncDispose]() {
+		events.push("db closed");
+	}
+}
+
+/** Records its lifecycle. Subclassed, not built by a factory: the container keys a class by name. */
+abstract class Recording implements HostedService {
+	protected abstract readonly label: string;
+	public constructor(private readonly db: Db) {}
+	public start(signal: AbortSignal) {
+		signal.addEventListener("abort", () => events.push(`${this.label} signal aborted`));
+		events.push(`${this.label} started (db ${this.db == null ? "missing" : "ready"})`);
+	}
+	public stop() {
+		events.push(`${this.label} stopped`);
+	}
+}
+
+@injectable()
+class First extends Recording {
+	protected readonly label = "first";
+	public constructor(@inject(DbToken) db: Db) {
+		super(db);
+	}
+}
+
+@injectable()
+class Second extends Recording {
+	protected readonly label = "second";
+	public constructor(@inject(DbToken) db: Db) {
+		super(db);
+	}
+}
+
+/** A worker that ticks on a timer until its signal is aborted, like a feed refresh loop. */
+@injectable()
+class Ticker implements HostedService {
+	public ticks = 0;
+	public start(signal: AbortSignal) {
+		const timer = setInterval(() => {
+			this.ticks += 1;
+		}, 5);
+		signal.addEventListener("abort", () => clearInterval(timer));
+	}
+}
+
+function builder() {
+	return Builder.create().withServices((c) => c.registerSingleton(DbToken, Db));
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+describe("hosted services (#541)", () => {
+	let app: App | undefined;
+
+	afterEach(async () => {
+		await app?.dispose();
+		app = undefined;
+		events = [];
+	});
+
+	it("starts each service once, in registration order, before the app listens", async () => {
+		@injectable()
+		class SeesAddresses implements HostedService {
+			public constructor(@inject(DbToken) private readonly db: Db) {}
+			public start() {
+				events.push(`listening during start: ${String(appRef?.addresses.length ?? 0)}`);
+				void this.db;
+			}
+		}
+		let appRef: App | undefined;
+		app = await builder()
+			.withHttp(FastifyProvider)
+			.withHostedService(First, Second, SeesAddresses)
+			.build();
+		appRef = app;
+
+		await app.start({ port: 0, host: "127.0.0.1", shutdownSignals: false });
+
+		expect(events).toEqual([
+			"first started (db ready)",
+			"second started (db ready)",
+			"listening during start: 0",
+		]);
+		expect(app.addresses).toHaveLength(1);
+	});
+
+	it("stops in reverse order: signal first, then each stop(), then the container", async () => {
+		app = await builder().withHttp(FastifyProvider).withHostedService(First, Second).build();
+		await app.start({ port: 0, host: "127.0.0.1", shutdownSignals: false });
+		events = [];
+
+		await app.dispose();
+
+		expect(events).toEqual([
+			"first signal aborted",
+			"second signal aborted",
+			"second stopped",
+			"first stopped",
+			"db closed",
+		]);
+	});
+
+	it("runs in an app with no HTTP server", async () => {
+		app = await builder().withHostedService(First).build();
+
+		await app.start({ port: 0, shutdownSignals: false });
+		await app.dispose();
+
+		expect(events).toEqual([
+			"first started (db ready)",
+			"first signal aborted",
+			"first stopped",
+			"db closed",
+		]);
+	});
+
+	// Flux reboots an app by calling its default export's Symbol.asyncDispose.
+	it("leaves no timer running after a Flux reboot (Symbol.asyncDispose)", async () => {
+		app = await builder().withHostedService(Ticker).build();
+		await app.start({ port: 0, shutdownSignals: false });
+		await sleep(30);
+		const ticker = (
+			app as unknown as { container: { resolve(t: unknown): Ticker } }
+		).container.resolve(Ticker);
+		expect(ticker.ticks).toBeGreaterThan(0);
+
+		await app[Symbol.asyncDispose]();
+		const ticksAtStop = ticker.ticks;
+		await sleep(30);
+
+		expect(ticker.ticks).toBe(ticksAtStop);
+	});
+
+	it("is the same instance when injected by its class", async () => {
+		@injectable()
+		class ReadsTicker {
+			public constructor(@inject(Ticker) public readonly ticker: Ticker) {}
+		}
+		app = await builder()
+			.withHostedService(Ticker)
+			.withServices((c) => c.registerSingleton(ReadsTicker))
+			.build();
+		await app.start({ port: 0, shutdownSignals: false });
+		await sleep(20);
+
+		const container = (app as unknown as { container: { resolve<T>(t: unknown): T } })
+			.container;
+		const reader = container.resolve<ReadsTicker>(ReadsTicker);
+
+		expect(reader.ticker.ticks).toBeGreaterThan(0);
+	});
+
+	it("does not wait for background work started by start()", async () => {
+		@injectable()
+		class SlowWarmUp implements HostedService {
+			public warm = false;
+			public start(signal: AbortSignal) {
+				// The ledger position feed: minutes of loading, started in the background.
+				void sleep(10_000).then(() => {
+					if (!signal.aborted) this.warm = true;
+				});
+			}
+		}
+		app = await builder().withHttp(FastifyProvider).withHostedService(SlowWarmUp).build();
+
+		const started = Date.now();
+		await app.start({ port: 0, host: "127.0.0.1", shutdownSignals: false });
+
+		expect(Date.now() - started).toBeLessThan(2_000);
+		expect(app.addresses).toHaveLength(1);
+	});
+
+	it("aborts the signal of a start() still running when the app stops, then stops it", async () => {
+		let release: () => void = () => {};
+		@injectable()
+		class Starting implements HostedService {
+			public async start(signal: AbortSignal) {
+				events.push("start begun");
+				signal.addEventListener("abort", () => events.push("signal aborted"));
+				await new Promise<void>((resolve) => {
+					release = resolve;
+				});
+				events.push("start finished");
+			}
+			public stop() {
+				events.push("stopped");
+			}
+		}
+		app = await builder().withHostedService(Starting).build();
+
+		const starting = app.start({ port: 0, shutdownSignals: false });
+		await sleep(5);
+		const stopping = app.dispose();
+		await sleep(5);
+		release();
+		await Promise.allSettled([starting, stopping]);
+
+		expect(events).toEqual(["start begun", "signal aborted", "start finished", "stopped"]);
+	});
+
+	it("stops the services already started when a later start() fails, and fails app.start", async () => {
+		@injectable()
+		class Broken implements HostedService {
+			public start() {
+				events.push("broken started");
+				throw new Error("feed unreachable");
+			}
+			public stop() {
+				events.push("broken stopped");
+			}
+		}
+		app = await builder()
+			.withHttp(FastifyProvider)
+			.withHostedService(First, Broken, Second)
+			.build();
+
+		await expect(
+			app.start({ port: 0, host: "127.0.0.1", shutdownSignals: false }),
+		).rejects.toThrow("feed unreachable");
+
+		expect(events).toEqual([
+			"first started (db ready)",
+			"broken started",
+			"first signal aborted",
+			"first stopped",
+		]);
+		expect(app.addresses).toHaveLength(0);
+	});
+
+	it("keeps stopping the others when one stop() throws", async () => {
+		@injectable()
+		class FailsToStop implements HostedService {
+			public start() {}
+			public stop() {
+				throw new Error("stuck");
+			}
+		}
+		app = await builder().withHostedService(First, FailsToStop, Second).build();
+		await app.start({ port: 0, shutdownSignals: false });
+		events = [];
+
+		await expect(app.dispose()).rejects.toThrow("stuck");
+		app = undefined; // dispose() keeps returning that rejection
+
+		expect(events).toContain("second stopped");
+		expect(events).toContain("first stopped");
+		expect(events.at(-1)).toBe("db closed");
+	});
+
+	it("reports a warming service as not ready on /ready until its check() passes", async () => {
+		@injectable()
+		class Warming implements HostedService {
+			public warm = false;
+			public start() {}
+			public async check() {
+				if (!this.warm) throw new Error("still loading positions");
+			}
+		}
+		app = await builder()
+			.withHttp(FastifyProvider)
+			.withHealth()
+			.withHostedService(Warming)
+			.build();
+		await app.start({ port: 0, host: "127.0.0.1", shutdownSignals: false });
+		const url = `${app.addresses[0]}/ready`;
+
+		expect((await fetch(url)).status).toBe(503);
+		const container = (app as unknown as { container: { resolve<T>(t: unknown): T } })
+			.container;
+		container.resolve<Warming>(Warming).warm = true;
+		expect((await fetch(url)).status).toBe(200);
+		expect((await fetch(`${app.addresses[0]}/health`)).status).toBe(200);
+	});
+});

package/tests/app.shutdown.integration.spec.ts

@@ -0,0 +1,160 @@
+import { createConnection } from "node:net";
+import { inject, injectable } from "@decohere/di/decorators";
+import axios from "axios";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { App } from "../src/app/app.js";
+import { Builder } from "../src/builder/builder.js";
+import "../src/http/http.extensions.js";
+import { FastifyProvider } from "../src/providers/fastify.provider.js";
+import { Controller, Get } from "../src/routing/index.js";
+
+const DbToken = Symbol("Db");
+
+/** Stands in for a connection pool: closed when the app's container is disposed. */
+@injectable()
+class Db {
+	public closed = false;
+	public async [Symbol.asyncDispose]() {
+		this.closed = true;
+	}
+}
+
+@Controller({ prefix: "/slow" })
+class SlowController {
+	public constructor(@inject(DbToken) private readonly db: Db) {}
+
+	@Get("/wait")
+	public async slow() {
+		await new Promise((resolve) => setTimeout(resolve, 150));
+		return { dbClosedDuringRequest: this.db.closed };
+	}
+}
+
+/** Open (and close) a raw TCP connection — no HTTP agent that might reuse a kept-alive socket. */
+function connect(baseURL: string): Promise<void> {
+	const { hostname, port } = new URL(baseURL);
+	return new Promise((resolve, reject) => {
+		const socket = createConnection({ host: hostname, port: Number(port) });
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve();
+		});
+		socket.once("error", reject);
+	});
+}
+
+async function buildApp(): Promise<App> {
+	return Builder.create()
+		.withHttp(FastifyProvider)
+		.withServices((c) => c.registerSingleton(DbToken, Db))
+		.withControllers(SlowController)
+		.build();
+}
+
+/** The listener `app.start()` added for `signal` (invoked directly; emitting would hit the test runner too). */
+async function startCapturing(app: App, signal: NodeJS.Signals, options = {}) {
+	const before = new Set(process.listeners(signal));
+	await app.start({ port: 0, host: "127.0.0.1", ...options });
+	const added = process.listeners(signal).filter((listener) => !before.has(listener));
+	return {
+		baseURL: app.addresses[0] as string,
+		handler: added[0] as (s: NodeJS.Signals) => void,
+		added,
+	};
+}
+
+describe("graceful shutdown on SIGTERM / SIGINT (#473)", () => {
+	let app: App | undefined;
+	/** Cancels requests that never answer, so the server can close in afterEach. */
+	let hung: AbortController;
+
+	beforeEach(() => {
+		hung = new AbortController();
+	});
+
+	afterEach(async () => {
+		hung.abort();
+		await app?.dispose();
+		app = undefined;
+		vi.restoreAllMocks();
+	});
+
+	it("lets an in-flight request finish before closing dependencies, then stops listening", async () => {
+		app = await buildApp();
+		const { baseURL, handler } = await startCapturing(app, "SIGTERM");
+
+		const inFlight = axios.get(`${baseURL}/slow/wait`);
+		await new Promise((resolve) => setTimeout(resolve, 30));
+		handler("SIGTERM");
+
+		const res = await inFlight;
+		expect(res.status).toBe(200);
+		expect(res.data).toEqual({ dbClosedDuringRequest: false });
+
+		await app.dispose(); // same shutdown already under way
+		await expect(connect(baseURL)).rejects.toMatchObject({ code: "ECONNREFUSED" });
+	});
+
+	it("handles SIGINT too, and removes both listeners once stopped", async () => {
+		app = await buildApp();
+		const intBefore = process.listeners("SIGINT").length;
+		const term = await startCapturing(app, "SIGTERM");
+		expect(term.added).toHaveLength(1);
+		expect(process.listeners("SIGINT")).toHaveLength(intBefore + 1);
+
+		await app.dispose();
+		expect(process.listeners("SIGTERM")).not.toContain(term.handler);
+		expect(process.listeners("SIGINT")).toHaveLength(intBefore);
+	});
+
+	it("registers nothing when shutdownSignals is false", async () => {
+		app = await buildApp();
+		const { added } = await startCapturing(app, "SIGTERM", { shutdownSignals: false });
+		expect(added).toHaveLength(0);
+	});
+
+	it("exits with code 1 when stopping takes longer than shutdownTimeoutMs", async () => {
+		// Signalled once the request is in the handler: a fixed sleep before SIGTERM let a slow
+		// machine stop before the request arrived, so nothing was in flight and it exited 0.
+		let arrived = () => {};
+		const inHandler = new Promise<void>((resolve) => {
+			arrived = resolve;
+		});
+		@Controller({ prefix: "/hang" })
+		class HangController {
+			@Get("/wait")
+			public hang() {
+				arrived();
+				return new Promise(() => {});
+			}
+		}
+		app = await Builder.create()
+			.withHttp(FastifyProvider)
+			.withControllers(HangController)
+			.build();
+		const exit = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
+		const stderr = vi.spyOn(console, "error").mockImplementation(() => {});
+		const { baseURL, handler } = await startCapturing(app, "SIGTERM", {
+			shutdownTimeoutMs: 50,
+		});
+
+		axios.get(`${baseURL}/hang/wait`, { signal: hung.signal }).catch(() => {});
+		await inHandler;
+		handler("SIGTERM");
+
+		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1), { timeout: 1000 });
+		expect(stderr.mock.calls.flat().join(" ")).toContain("50ms");
+	});
+
+	it("stops listening for signals as soon as shutdown starts, so a second one exits the default way", async () => {
+		app = await buildApp();
+		const { handler } = await startCapturing(app, "SIGTERM");
+		const intBefore = process.listeners("SIGINT").length;
+
+		handler("SIGTERM");
+
+		expect(process.listeners("SIGTERM")).not.toContain(handler);
+		expect(process.listeners("SIGINT")).toHaveLength(intBefore - 1);
+		await app.dispose();
+	});
+});