@o3co/create-auth-provider 0.14.0 → 0.16.0

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

@@ -30,10 +30,23 @@
  * and these tests are the contract the issue said was missing.
  */
 
-import type { Server } from "node:http";
-import type { Logger } from "@o3co/auth-provider-core";
+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";
+import {
+	cleanupAllowanceFor,
+	deferExit,
+	FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS,
+	FEDERATION_GRANTS_CLEANUP_MARGIN_MS,
+	installGracefulShutdown,
+} from "../shutdown.mjs";
 
 /** A `Server` double whose `close` callback fires only when we say so. */
 function makeServer() {
@@ -79,10 +92,53 @@ const makeLogger = () => {
 	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 } = {}) {
+function install(
+	opts: {
+		cleanup?: () => void | Promise<void>;
+		drainTimeoutMs?: number;
+		cleanupTimeoutMs?: number;
+		logger?: ReturnType<typeof makeLogger>;
+	} = {},
+) {
 	const { server, spies, finishDraining, failClose } = makeServer();
-	const logger = makeLogger();
+	const logger = opts.logger ?? makeLogger();
 	const exit = vi.fn();
 	const signals = new Map<string, () => void>();
 
@@ -90,6 +146,7 @@ function install(opts: { cleanup?: () => void | Promise<void>; drainTimeoutMs?:
 		logger,
 		cleanup: opts.cleanup ?? (() => {}),
 		...(opts.drainTimeoutMs === undefined ? {} : { drainTimeoutMs: opts.drainTimeoutMs }),
+		...(opts.cleanupTimeoutMs === undefined ? {} : { cleanupTimeoutMs: opts.cleanupTimeoutMs }),
 		exit,
 		onSignal: (name, handler) => signals.set(name, handler),
 		offSignal: (name) => signals.delete(name),
@@ -159,7 +216,12 @@ describe("installGracefulShutdown (#290)", () => {
 			signals.get("SIGTERM")?.();
 			await vi.advanceTimersByTimeAsync(5_000);
 			expect(exit).toHaveBeenCalledWith(1);
-			expect(logger.error).toHaveBeenCalled();
+			// Each stage is an event: object-first, a snake_case name.
+			expect(logger.info).toHaveBeenCalledWith({ drainTimeoutMs: 5_000 }, "shutdown_draining");
+			expect(logger.error).toHaveBeenCalledWith(
+				{ drainTimeoutMs: 5_000 },
+				"shutdown_drain_deadline_exceeded",
+			);
 		} finally {
 			vi.useRealTimers();
 		}
@@ -180,21 +242,91 @@ describe("installGracefulShutdown (#290)", () => {
 		}
 	});
 
-	it("reports a cleanup failure through the app logger, not console", async () => {
+	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.
-		const { logger, exit, signals, finishDraining } = install({
-			cleanup: () => {
-				throw new Error("redis quit failed");
+		// 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(
-			expect.objectContaining({ err: expect.any(Error) }),
-			expect.stringContaining("cleanup"),
+			{
+				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 () => {
@@ -208,19 +340,37 @@ describe("installGracefulShutdown (#290)", () => {
 		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
 	});
 
-	it("does not report a failed close as a clean drain", async () => {
+	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.
-		const { exit, logger, signals, failClose } = install();
+		// 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")?.();
-		failClose(new Error("Server is not running"));
 		await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
 		expect(logger.error).toHaveBeenCalledWith(
-			expect.objectContaining({ err: expect.any(Error) }),
-			expect.stringContaining("close"),
+			{
+				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 () => {
@@ -250,8 +400,8 @@ describe("installGracefulShutdown (#290)", () => {
 			finishDraining();
 			await vi.advanceTimersByTimeAsync(5_000);
 			expect(logger.error).toHaveBeenCalledWith(
-				expect.objectContaining({ cleanupTimeoutMs: 5_000 }),
-				expect.stringContaining("cleanup timed out"),
+				{ cleanupTimeoutMs: 5_000 },
+				"shutdown_cleanup_timed_out",
 			);
 			expect(exit).toHaveBeenCalledWith(1);
 		} finally {
@@ -298,7 +448,7 @@ describe("installGracefulShutdown (#290)", () => {
 		await new Promise((resolve) => setImmediate(resolve));
 		expect(logger.info).toHaveBeenCalledWith(
 			{ reason: "cleanup-failed", drain: "drained", exitCode: 1 },
-			"graceful shutdown: complete",
+			"shutdown_complete",
 		);
 		expect(exit).toHaveBeenCalledWith(1);
 	});
@@ -310,7 +460,7 @@ describe("installGracefulShutdown (#290)", () => {
 		await new Promise((resolve) => setImmediate(resolve));
 		expect(logger.info).toHaveBeenCalledWith(
 			{ reason: "drained", drain: "drained", exitCode: 0 },
-			"graceful shutdown: complete",
+			"shutdown_complete",
 		);
 	});
 
@@ -322,3 +472,84 @@ describe("installGracefulShutdown (#290)", () => {
 		expect(signals.size).toBe(0);
 	});
 });
+
+describe("#593 slice 7: the cleanup allowance federation grants need", () => {
+	it("is at least the 45 seconds the package asks for, and only when the feature is on", () => {
+		// The package's drain waits for a rotated credential's write; the
+		// default cleanup budget is the ten-second drain, which is shorter than
+		// the upstream hard timeout and persist budget the feature ships with —
+		// a shutdown under it abandons exactly the write the drain exists for.
+		expect(FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS).toBeGreaterThanOrEqual(45_000);
+		expect(cleanupAllowanceFor({ federationGrants: { enabled: true } })).toEqual({
+			cleanupTimeoutMs: FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS,
+		});
+		// Off, nothing: the cleanup budget stays the drain's, as it was.
+		expect(cleanupAllowanceFor({ federationGrants: { enabled: false } })).toEqual({});
+		expect(cleanupAllowanceFor({})).toEqual({});
+	});
+
+	it("grows with the configured refresh tail, so a raised budget is not cut off by a fixed timer (Copilot, #614)", () => {
+		// The longest tail one refresh has: the upstream hard timeout, the
+		// persist budget and the wait for the lock, back to back, plus an exit
+		// margin. The shipped budgets (25 s + 3 s + 5 s) land exactly on the
+		// floor; a deployment that doubles its upstream timeout gets more.
+		const shipped = {
+			upstreamHardTimeoutMs: 25_000,
+			persistRetryBudgetMs: 3_000,
+			lockWaitMs: 5_000,
+		};
+		expect(
+			25_000 + 3_000 + 5_000 + FEDERATION_GRANTS_CLEANUP_MARGIN_MS,
+			"the margin is what makes the shipped budgets the floor",
+		).toBe(FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS);
+		expect(cleanupAllowanceFor({ federationGrants: { enabled: true, ...shipped } })).toEqual({
+			cleanupTimeoutMs: FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS,
+		});
+		expect(
+			cleanupAllowanceFor({
+				federationGrants: { enabled: true, ...shipped, upstreamHardTimeoutMs: 60_000 },
+			}),
+		).toEqual({ cleanupTimeoutMs: 60_000 + 3_000 + 5_000 + FEDERATION_GRANTS_CLEANUP_MARGIN_MS });
+		// Lowered budgets never go below the documented minimum, and a config
+		// without budgets (built by hand) gets the floor rather than a guess.
+		expect(
+			cleanupAllowanceFor({
+				federationGrants: { enabled: true, ...shipped, upstreamHardTimeoutMs: 1_000 },
+			}),
+		).toEqual({ cleanupTimeoutMs: FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS });
+		expect(
+			cleanupAllowanceFor({ federationGrants: { enabled: true, upstreamHardTimeoutMs: 90_000 } }),
+		).toEqual({ cleanupTimeoutMs: FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS });
+	});
+
+	it("never asks a timer for more than Node can count: an oversized sum is capped, not overflowed (Copilot, #614)", () => {
+		// setTimeout takes a 32-bit signed delay; past it the timer fires after
+		// about a millisecond, which would turn a generous allowance into none.
+		const oversized = cleanupAllowanceFor({
+			federationGrants: {
+				enabled: true,
+				upstreamHardTimeoutMs: 2_000_000_000,
+				persistRetryBudgetMs: 2_000_000_000,
+				lockWaitMs: 5_000,
+			},
+		});
+		expect(oversized).toEqual({ cleanupTimeoutMs: 2_147_483_647 });
+	});
+
+	it("is honoured by the shutdown: a cleanup that needs longer than the drain is given it", async () => {
+		vi.useFakeTimers();
+		try {
+			const { signals, finishDraining, exit } = install({
+				cleanup: () => new Promise<void>((resolve) => setTimeout(resolve, 30_000)),
+				drainTimeoutMs: 5_000,
+				...cleanupAllowanceFor({ federationGrants: { enabled: true } }),
+			});
+			signals.get("SIGTERM")?.();
+			finishDraining();
+			await vi.advanceTimersByTimeAsync(31_000);
+			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+});

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

@@ -618,27 +618,46 @@ describe("standalone smoke test", () => {
 			expect(names).toContain("standalone:redis-clients");
 		});
 
-		it("buildModules honors legacy repositories.code.type='redis' with deprecation warn when oauth.code.adapter is absent", () => {
-			const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-			try {
-				const legacyConfig = {
-					...config,
-					oauth: { ...config.oauth, code: undefined },
-					repositories: {
-						...config.repositories,
-						code: { type: "redis" as const, defaultExpiresIn: 600 },
+		it("buildModules honors legacy repositories.code.type='redis' with one object-first deprecation warn when oauth.code.adapter is absent", () => {
+			const warn = vi.fn();
+			const logger = {
+				trace: vi.fn(),
+				debug: vi.fn(),
+				info: vi.fn(),
+				warn,
+				error: vi.fn(),
+				fatal: vi.fn(),
+				child: () => logger,
+			};
+			const legacyConfig = {
+				...config,
+				oauth: { ...config.oauth, code: undefined },
+				repositories: {
+					...config.repositories,
+					code: { type: "redis" as const, defaultExpiresIn: 600 },
+				},
+			};
+			const modules = buildModules(legacyConfig, {
+				keyStoreModule: testKeyStoreModule,
+				repositoriesModule: testRepositoriesModule,
+				refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
+				logger,
+			});
+			const names = modules.map((m) => m.name);
+			expect(names).toContain("redis-code-repository");
+			expect(warn.mock.calls).toEqual([
+				[
+					{
+						key: "repositories.code.type",
+						env: "CLIENT_CODE_TYPE",
+						replacement: "oauth.code.adapter",
+						replacementEnv: "OAUTH_CODE_ADAPTER",
 					},
-				};
-				const modules = buildModules(legacyConfig, {
-					keyStoreModule: testKeyStoreModule,
-					repositoriesModule: testRepositoriesModule,
-					refreshTokenFamilyModules: [memoryRefreshTokenFamilyStoreModule],
-				});
-				const names = modules.map((m) => m.name);
-				expect(names).toContain("redis-code-repository");
-				expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("repositories.code.type"));
-			} finally {
-				warnSpy.mockRestore();
+					"config_key_deprecated",
+				],
+			]);
+			for (const level of ["trace", "debug", "info", "error", "fatal"] as const) {
+				expect(logger[level]).not.toHaveBeenCalled();
 			}
 		});