@o3co/create-auth-provider 0.17.0-rc.4 → 0.18.0-rc.1

package/templates/standalone/src/__tests__/shutdown.test.mts

@@ -1,622 +0,0 @@
-/*
- * Copyright 2026 1o1 Co. Ltd.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-/**
- * The contract of the template's graceful shutdown (README, "Shutdown
- * guarantees"): a force-close deadline on the drain, a bounded cleanup, and
- * every stage logged through the app's own logger. `server.close()` alone
- * waits for in-flight requests indefinitely, so one stuck request would keep
- * the process up until the orchestrator's SIGKILL took it down mid-flight.
- */
-
-import { createServer, type Server } from "node:http";
-import {
-	type BootstrapMap,
-	createApp,
-	createMemoryReplaySeenSet,
-	defineModule,
-	type Logger,
-} from "@o3co/auth-provider-core";
-import { makeValidCoreConfig } from "@o3co/auth-provider-core/testing";
-import { describe, expect, it, vi } from "vitest";
-import { deferExit, installGracefulShutdown } from "../shutdown.mjs";
-
-/** A `Server` double whose `close` callback fires only when we say so. */
-function makeServer() {
-	let closeCallback: ((err?: Error) => void) | undefined;
-	const server = {
-		close: vi.fn((cb?: (err?: Error) => void) => {
-			closeCallback = cb;
-			return server;
-		}),
-		closeIdleConnections: vi.fn(),
-		closeAllConnections: vi.fn(),
-	};
-	return {
-		server: server as unknown as Server,
-		spies: server,
-		/** Simulate the last in-flight request finishing. */
-		finishDraining: () => closeCallback?.(),
-		/** Simulate `close` reporting a failure through its callback. */
-		failClose: (err: Error) => closeCallback?.(err),
-		get drained() {
-			return closeCallback !== undefined;
-		},
-	};
-}
-
-/**
- * A `Logger`-shaped spy. Typed rather than cast: `as never` would hide a real
- * mismatch the day the port gains a method.
- */
-const makeLogger = () => {
-	const spy = {
-		trace: vi.fn(),
-		debug: vi.fn(),
-		info: vi.fn(),
-		warn: vi.fn(),
-		error: vi.fn(),
-		fatal: vi.fn(),
-		// `child` returns a Logger; returning this one keeps a child's calls
-		// visible on the same spies, which is what a test wants.
-		child: vi.fn(() => spy as unknown as Logger),
-	};
-	return spy satisfies Logger;
-};
-
-/**
- * A logger that serialises every own property of what it is handed, `cause`
- * and non-enumerable fields included — a deployment is free to install one.
- * `lines` is what it wrote; its levels are spies.
- */
-const serialiseEverythingLogger = () => {
-	const lines: string[] = [];
-	const walk = (value: unknown, seen = new WeakSet<object>()): unknown => {
-		if (typeof value !== "object" || value === null) return value;
-		if (seen.has(value)) return "[circular]";
-		seen.add(value);
-		const out: Record<string, unknown> = {};
-		for (const key of Object.getOwnPropertyNames(value)) {
-			out[key] = walk((value as Record<string, unknown>)[key], seen);
-		}
-		return out;
-	};
-	const record = (level: string) =>
-		vi.fn((...args: unknown[]): void => {
-			lines.push(JSON.stringify({ level, args: walk(args) }));
-		});
-	const logger = {
-		trace: record("trace"),
-		debug: record("debug"),
-		info: record("info"),
-		warn: record("warn"),
-		error: record("error"),
-		fatal: record("fatal"),
-		child: vi.fn(() => logger as unknown as Logger),
-	};
-	return { logger: logger satisfies Logger, lines };
-};
-
-/** A logged projection's `stack`: frames only, from the first. */
-const FRAMES = expect.stringMatching(/^ {4}at /);
-
-/** Drive one shutdown without touching the real `process` or exiting. */
-function install(
-	opts: {
-		cleanup?: () => void | Promise<void>;
-		drainTimeoutMs?: number;
-		cleanupTimeoutMs?: number;
-		cleanupAllowanceMs?: () => number | undefined;
-		logger?: ReturnType<typeof makeLogger>;
-	} = {},
-) {
-	const { server, spies, finishDraining, failClose } = makeServer();
-	const logger = opts.logger ?? makeLogger();
-	const exit = vi.fn();
-	const signals = new Map<string, () => void>();
-
-	installGracefulShutdown(server, {
-		logger,
-		cleanup: opts.cleanup ?? (() => {}),
-		...(opts.drainTimeoutMs === undefined ? {} : { drainTimeoutMs: opts.drainTimeoutMs }),
-		...(opts.cleanupTimeoutMs === undefined ? {} : { cleanupTimeoutMs: opts.cleanupTimeoutMs }),
-		...(opts.cleanupAllowanceMs === undefined
-			? {}
-			: { cleanupAllowanceMs: opts.cleanupAllowanceMs }),
-		exit,
-		onSignal: (name, handler) => signals.set(name, handler),
-		offSignal: (name) => signals.delete(name),
-	});
-
-	return { spies, logger, exit, signals, finishDraining, failClose };
-}
-
-describe("installGracefulShutdown", () => {
-	it("listens for both SIGTERM and SIGINT", async () => {
-		const { signals } = install();
-		expect([...signals.keys()].sort()).toEqual(["SIGINT", "SIGTERM"]);
-	});
-
-	it("stops accepting connections and releases idle keep-alive sockets", async () => {
-		const { spies, signals } = install();
-		signals.get("SIGTERM")?.();
-		expect(spies.close).toHaveBeenCalled();
-		// Idle keep-alive sockets hold the server open with no request behind
-		// them; releasing them is what lets a quiet server exit promptly.
-		expect(spies.closeIdleConnections).toHaveBeenCalled();
-	});
-
-	it("runs cleanup once draining completes, then exits zero", async () => {
-		const cleanup = vi.fn();
-		const { exit, signals, finishDraining } = install({ cleanup });
-		signals.get("SIGTERM")?.();
-		expect(cleanup).not.toHaveBeenCalled();
-		finishDraining();
-		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(0));
-		expect(cleanup).toHaveBeenCalledTimes(1);
-	});
-
-	it("ignores a second signal instead of running cleanup twice", async () => {
-		// An operator pressing ^C twice, or a SIGINT arriving after SIGTERM,
-		// must not start a second dispose over the first one's stores.
-		const cleanup = vi.fn();
-		const { signals, finishDraining, exit } = install({ cleanup });
-		signals.get("SIGTERM")?.();
-		signals.get("SIGINT")?.();
-		finishDraining();
-		await vi.waitFor(() => expect(exit).toHaveBeenCalled());
-		expect(cleanup).toHaveBeenCalledTimes(1);
-	});
-
-	it("forces the remaining connections closed when draining outruns the deadline", async () => {
-		vi.useFakeTimers();
-		try {
-			const { spies, signals, exit } = install({ drainTimeoutMs: 5_000 });
-			signals.get("SIGTERM")?.();
-			expect(spies.closeAllConnections).not.toHaveBeenCalled();
-			await vi.advanceTimersByTimeAsync(5_000);
-			expect(spies.closeAllConnections).toHaveBeenCalled();
-			expect(exit).toHaveBeenCalled();
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-
-	it("exits non-zero on a forced close, so the drain outcome is visible", async () => {
-		// An orchestrator that only ever sees exit 0 cannot tell a clean drain
-		// from one that ran out of time and cut requests off.
-		vi.useFakeTimers();
-		try {
-			const { signals, exit, logger } = install({ drainTimeoutMs: 5_000 });
-			signals.get("SIGTERM")?.();
-			await vi.advanceTimersByTimeAsync(5_000);
-			expect(exit).toHaveBeenCalledWith(1);
-			// Each stage is an event: object-first, a snake_case name.
-			expect(logger.info).toHaveBeenCalledWith(
-				{ drainTimeoutMs: 5_000, cleanupTimeoutMs: 5_000 },
-				"shutdown_draining",
-			);
-			expect(logger.error).toHaveBeenCalledWith(
-				{ drainTimeoutMs: 5_000 },
-				"shutdown_drain_deadline_exceeded",
-			);
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-
-	it("does not force-close a drain that finished in time", async () => {
-		vi.useFakeTimers();
-		try {
-			const { spies, signals, finishDraining, exit } = install({ drainTimeoutMs: 5_000 });
-			signals.get("SIGTERM")?.();
-			finishDraining();
-			await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(0));
-			await vi.advanceTimersByTimeAsync(10_000);
-			expect(spies.closeAllConnections).not.toHaveBeenCalled();
-			expect(exit).toHaveBeenCalledTimes(1);
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-
-	it("reports a cleanup failure through the app logger, not console, as loggableError's projection", async () => {
-		// Every other line this service emits is NDJSON through pino; a bare
-		// console.error on the shutdown path is the one a log pipeline drops.
-		// What a real `handle.dispose()` rejects with is an AggregateError of
-		// every cleanup's own error. The line names each member and its code,
-		// and carries nothing of what they hold: an OAuth library's refusal
-		// keeps the refresh answer it refused on a non-Error cause, an ioredis
-		// reply the write it refused.
-		const refusedRefresh = Object.assign(
-			new Error("invalid response encountered", {
-				cause: { body: { refresh_token: "1//0g-UPSTREAM-S3CRET" } },
-			}),
-			{ name: "ClientError", code: "OAUTH_INVALID_RESPONSE" },
-		);
-		const refusedWrite = Object.assign(
-			new Error("READONLY You can't write against a read only replica."),
-			{
-				name: "ReplyError",
-				command: { name: "set", args: ["fg:credential:grant-1", "1//0g-ARGS-S3CRET"] },
-			},
-		);
-		const failingCleanups = defineModule({
-			name: "test:failing-cleanups",
-			provides: {
-				replaySeenSet: () => createMemoryReplaySeenSet(),
-				challengeStore: () => ({}) as never,
-			},
-			lifecycle: {
-				replaySeenSet: {
-					eager: true,
-					cleanup: () => {
-						throw refusedRefresh;
-					},
-				},
-				challengeStore: {
-					eager: true,
-					cleanup: () => {
-						throw refusedWrite;
-					},
-				},
-			},
-		});
-		const handle = await createApp({
-			modules: [failingCleanups],
-			bootstrapComponents: {
-				config: makeValidCoreConfig(),
-				pathResolver: (path: string) => path,
-			} as unknown as BootstrapMap,
-		});
-		const { logger, lines } = serialiseEverythingLogger();
-		const { exit, signals, finishDraining } = install({
-			logger,
-			cleanup: () => handle.dispose(),
-		});
-		signals.get("SIGTERM")?.();
-		finishDraining();
-		await vi.waitFor(() => expect(exit).toHaveBeenCalled());
-		expect(logger.error).toHaveBeenCalledWith(
-			{
-				err: {
-					name: "AggregateError",
-					detail: expect.stringMatching(/^AppHandle\.dispose: 2 cleanup errors /),
-					stack: FRAMES,
-					aggregateErrors: expect.arrayContaining([
-						{
-							name: "ClientError",
-							detail: "invalid response encountered",
-							code: "OAUTH_INVALID_RESPONSE",
-							stack: FRAMES,
-						},
-						{
-							name: "ReplyError",
-							detail: "READONLY You can't write against a read only replica.",
-							command: { name: "set" },
-							stack: FRAMES,
-						},
-					]),
-				},
-			},
-			"shutdown_cleanup_failed",
-		);
-		for (const line of lines) {
-			expect(line).not.toContain("S3CRET");
-			expect(line).not.toContain("refresh_token");
-		}
-	});
-
-	it("still exits when cleanup throws — a failed dispose must not wedge the process", async () => {
-		const { exit, signals, finishDraining } = install({
-			cleanup: async () => {
-				throw new Error("dispose failed");
-			},
-		});
-		signals.get("SIGTERM")?.();
-		finishDraining();
-		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
-	});
-
-	it("does not report a failed close as a clean drain, and logs the failure as loggableError's projection", async () => {
-		// `server.close` reports through its callback -- "Server is not running"
-		// is the common one, but any listener teardown failure lands there.
-		// Exiting 0 on it would tell an orchestrator the listener came down
-		// when it did not. A real server that is not listening gives Node's
-		// own error; the line keeps its name, message, code and frames.
-		const server = createServer();
-		const { logger, lines } = serialiseEverythingLogger();
-		const exit = vi.fn();
-		const signals = new Map<string, () => void>();
-		installGracefulShutdown(server, {
-			logger,
-			exit,
-			onSignal: (name, handler) => signals.set(name, handler),
-			offSignal: (name) => signals.delete(name),
-		});
-		signals.get("SIGTERM")?.();
-		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
-		expect(logger.error).toHaveBeenCalledWith(
-			{
-				err: {
-					name: "Error",
-					detail: "Server is not running.",
-					code: "ERR_SERVER_NOT_RUNNING",
-					stack: FRAMES,
-				},
-			},
-			"shutdown_server_close_failed",
-		);
-		// The frames, never the header line that repeats the message.
-		for (const line of lines) expect(line).not.toContain("Error [ERR_SERVER_NOT_RUNNING]");
-	});
-
-	it("still runs cleanup when close reports a failure", async () => {
-		// The listener failing to come down is no reason to leak the Redis
-		// connections behind it.
-		const cleanup = vi.fn();
-		const { exit, signals, failClose } = install({ cleanup });
-		signals.get("SIGTERM")?.();
-		failClose(new Error("teardown failed"));
-		await vi.waitFor(() => expect(exit).toHaveBeenCalled());
-		expect(cleanup).toHaveBeenCalledTimes(1);
-	});
-
-	it("bounds cleanup so a hanging dispose cannot wedge the process", async () => {
-		// The drain deadline is already cleared when cleanup runs, so without a
-		// deadline of its own a dispose that never settles would keep `exit`
-		// from ever being reached.
-		vi.useFakeTimers();
-		try {
-			const { signals, finishDraining, exit, logger } = install({
-				cleanup: () => new Promise<void>(() => {}),
-				drainTimeoutMs: 5_000,
-			});
-			signals.get("SIGTERM")?.();
-			finishDraining();
-			await vi.advanceTimersByTimeAsync(5_000);
-			expect(logger.error).toHaveBeenCalledWith(
-				{ cleanupTimeoutMs: 5_000 },
-				"shutdown_cleanup_timed_out",
-			);
-			expect(exit).toHaveBeenCalledWith(1);
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-
-	it("does not penalise a cleanup that finishes inside its budget", async () => {
-		vi.useFakeTimers();
-		try {
-			const { signals, finishDraining, exit } = install({
-				cleanup: () => Promise.resolve(),
-				drainTimeoutMs: 5_000,
-			});
-			signals.get("SIGTERM")?.();
-			finishDraining();
-			await vi.advanceTimersByTimeAsync(10_000);
-			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-
-	it("defers the real exit a turn so a buffered log destination can flush", async () => {
-		// The scaffolded app logs NDJSON through pino, whose default destination is
-		// not synchronous: exiting in the same tick as the last `logger.error` can
-		// drop exactly the `cleanup failed` line an operator would look for.
-		const exitProcess = vi.fn();
-		deferExit(3, exitProcess);
-		expect(exitProcess).not.toHaveBeenCalled();
-		await new Promise((resolve) => setImmediate(resolve));
-		expect(exitProcess).toHaveBeenCalledWith(3);
-	});
-
-	it("reports the cleanup outcome as the reason, not the drain that preceded it", async () => {
-		// `reason` must agree with `exitCode` on the one line an operator alerts
-		// on. The drain outcome is carried under its own key, so neither fact is
-		// lost.
-		const { signals, finishDraining, logger, exit } = install({
-			cleanup: () => Promise.reject(new Error("teardown failed")),
-		});
-		signals.get("SIGTERM")?.();
-		finishDraining();
-		await new Promise((resolve) => setImmediate(resolve));
-		expect(logger.info).toHaveBeenCalledWith(
-			{ reason: "cleanup-failed", drain: "drained", exitCode: 1 },
-			"shutdown_complete",
-		);
-		expect(exit).toHaveBeenCalledWith(1);
-	});
-
-	it("keeps reason and drain identical when cleanup succeeds", async () => {
-		const { signals, finishDraining, logger } = install({ cleanup: () => Promise.resolve() });
-		signals.get("SIGTERM")?.();
-		finishDraining();
-		await new Promise((resolve) => setImmediate(resolve));
-		expect(logger.info).toHaveBeenCalledWith(
-			{ reason: "drained", drain: "drained", exitCode: 0 },
-			"shutdown_complete",
-		);
-	});
-
-	it("removes its own signal listeners once shutting down", async () => {
-		// Otherwise a repeated signal keeps re-entering a handler that has
-		// already handed the process over to `close`.
-		const { signals } = install();
-		signals.get("SIGTERM")?.();
-		expect(signals.size).toBe(0);
-	});
-});
-
-describe("the cleanup allowance the handle reports", () => {
-	it("gives cleanup the allowance when it is longer than the drain", async () => {
-		vi.useFakeTimers();
-		try {
-			const { signals, finishDraining, exit } = install({
-				cleanup: () => new Promise<void>((resolve) => setTimeout(resolve, 30_000)),
-				drainTimeoutMs: 5_000,
-				cleanupAllowanceMs: () => 45_000,
-			});
-			signals.get("SIGTERM")?.();
-			finishDraining();
-			await vi.advanceTimersByTimeAsync(31_000);
-			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-
-	it("gives up on cleanup at the allowance, and logs it as the budget", async () => {
-		vi.useFakeTimers();
-		try {
-			const { signals, finishDraining, exit, logger } = install({
-				cleanup: () => new Promise<void>(() => {}),
-				drainTimeoutMs: 5_000,
-				cleanupAllowanceMs: () => 45_000,
-			});
-			signals.get("SIGTERM")?.();
-			finishDraining();
-			await vi.advanceTimersByTimeAsync(44_999);
-			expect(exit).not.toHaveBeenCalled();
-			await vi.advanceTimersByTimeAsync(1);
-			expect(logger.error).toHaveBeenCalledWith(
-				{ cleanupTimeoutMs: 45_000 },
-				"shutdown_cleanup_timed_out",
-			);
-			expect(exit).toHaveBeenCalledExactlyOnceWith(1);
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-
-	it("keeps the longer budget when the allowance is shorter", async () => {
-		vi.useFakeTimers();
-		try {
-			const { signals, finishDraining, exit, logger } = install({
-				cleanup: () => new Promise<void>(() => {}),
-				drainTimeoutMs: 5_000,
-				cleanupAllowanceMs: () => 2_000,
-			});
-			signals.get("SIGTERM")?.();
-			finishDraining();
-			await vi.advanceTimersByTimeAsync(4_999);
-			expect(exit).not.toHaveBeenCalled();
-			await vi.advanceTimersByTimeAsync(1);
-			expect(logger.error).toHaveBeenCalledWith(
-				{ cleanupTimeoutMs: 5_000 },
-				"shutdown_cleanup_timed_out",
-			);
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-
-	it("leaves cleanup its own budget when the handle reports no allowance", async () => {
-		vi.useFakeTimers();
-		try {
-			const { signals, finishDraining, logger } = install({
-				cleanup: () => new Promise<void>(() => {}),
-				drainTimeoutMs: 5_000,
-				cleanupAllowanceMs: () => undefined,
-			});
-			signals.get("SIGTERM")?.();
-			finishDraining();
-			await vi.advanceTimersByTimeAsync(5_000);
-			expect(logger.error).toHaveBeenCalledWith(
-				{ cleanupTimeoutMs: 5_000 },
-				"shutdown_cleanup_timed_out",
-			);
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-
-	it("reads the allowance when the signal arrives, so a tail registered after install counts", async () => {
-		vi.useFakeTimers();
-		try {
-			let allowance: number | undefined;
-			const { signals, finishDraining, exit, logger } = install({
-				cleanup: () => new Promise<void>(() => {}),
-				drainTimeoutMs: 5_000,
-				cleanupAllowanceMs: () => allowance,
-			});
-			allowance = 60_000;
-			signals.get("SIGTERM")?.();
-			expect(logger.info).toHaveBeenCalledWith(
-				{ drainTimeoutMs: 5_000, cleanupTimeoutMs: 60_000 },
-				"shutdown_draining",
-			);
-			finishDraining();
-			await vi.advanceTimersByTimeAsync(59_999);
-			expect(exit).not.toHaveBeenCalled();
-			await vi.advanceTimersByTimeAsync(1);
-			expect(exit).toHaveBeenCalledExactlyOnceWith(1);
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-
-	it.each([Number.NaN, Number.POSITIVE_INFINITY, -1, 0, 1.5, 2_147_483_648])(
-		"treats an allowance of %s as absent: cleanup keeps its own budget",
-		async (allowance) => {
-			// Handed to a timer, NaN or a delay past 2147483647 fires after about a
-			// millisecond, which would turn the floor into no budget at all.
-			vi.useFakeTimers();
-			try {
-				const { signals, finishDraining, exit, logger } = install({
-					cleanup: () => new Promise<void>(() => {}),
-					drainTimeoutMs: 5_000,
-					cleanupAllowanceMs: () => allowance,
-				});
-				signals.get("SIGTERM")?.();
-				finishDraining();
-				await vi.advanceTimersByTimeAsync(4_999);
-				expect(exit).not.toHaveBeenCalled();
-				await vi.advanceTimersByTimeAsync(1);
-				expect(logger.error).toHaveBeenCalledWith(
-					{ cleanupTimeoutMs: 5_000 },
-					"shutdown_cleanup_timed_out",
-				);
-			} finally {
-				vi.useRealTimers();
-			}
-		},
-	);
-
-	it("treats an allowance that cannot be read as absent, and still shuts down", async () => {
-		vi.useFakeTimers();
-		try {
-			const { signals, finishDraining, exit, logger } = install({
-				cleanup: () => new Promise<void>(() => {}),
-				drainTimeoutMs: 5_000,
-				cleanupAllowanceMs: () => {
-					throw new Error("allowance unavailable");
-				},
-			});
-			signals.get("SIGTERM")?.();
-			finishDraining();
-			await vi.advanceTimersByTimeAsync(5_000);
-			expect(logger.error).toHaveBeenCalledWith(
-				{ cleanupTimeoutMs: 5_000 },
-				"shutdown_cleanup_timed_out",
-			);
-			expect(exit).toHaveBeenCalledExactlyOnceWith(1);
-		} finally {
-			vi.useRealTimers();
-		}
-	});
-});