@o3co/create-auth-provider 0.16.0 → 0.17.0-rc.2

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

@@ -15,19 +15,11 @@
  */
 
 /**
- * Issue #290 — shutdown was delegated to `@o3co/auth.utils@0.0.4`, whose
- * guarantees were not pinned by any contract this repository could check.
- *
- * Reading the 22 lines answered the question the issue asked, and the answer
- * was worth knowing: **there was no force-close deadline**. `server.close()`
- * waits for in-flight requests indefinitely, so one stuck request meant the
- * process never exited on its own and the orchestrator's SIGKILL took it down
- * mid-flight — the opposite of a graceful shutdown, and invisible until it
- * happened. The cleanup-failure path also wrote to `console.error`, a bare
- * line in a service whose every other line is NDJSON.
- *
- * So the behaviour lives here now, with a deadline and the app's own logger,
- * and these tests are the contract the issue said was missing.
+ * 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";
@@ -40,13 +32,7 @@ import {
 } from "@o3co/auth-provider-core";
 import { makeValidCoreConfig } from "@o3co/auth-provider-core/testing";
 import { describe, expect, it, vi } from "vitest";
-import {
-	cleanupAllowanceFor,
-	deferExit,
-	FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS,
-	FEDERATION_GRANTS_CLEANUP_MARGIN_MS,
-	installGracefulShutdown,
-} from "../shutdown.mjs";
+import { deferExit, installGracefulShutdown } from "../shutdown.mjs";
 
 /** A `Server` double whose `close` callback fires only when we say so. */
 function makeServer() {
@@ -74,8 +60,7 @@ function makeServer() {
 
 /**
  * A `Logger`-shaped spy. Typed rather than cast: `as never` would hide a real
- * mismatch the day the port gains a method, which is the whole reason the
- * shutdown path logs through the app logger instead of `console`.
+ * mismatch the day the port gains a method.
  */
 const makeLogger = () => {
 	const spy = {
@@ -134,6 +119,7 @@ function install(
 		cleanup?: () => void | Promise<void>;
 		drainTimeoutMs?: number;
 		cleanupTimeoutMs?: number;
+		cleanupAllowanceMs?: () => number | undefined;
 		logger?: ReturnType<typeof makeLogger>;
 	} = {},
 ) {
@@ -147,6 +133,9 @@ function install(
 		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),
@@ -155,7 +144,7 @@ function install(
 	return { spies, logger, exit, signals, finishDraining, failClose };
 }
 
-describe("installGracefulShutdown (#290)", () => {
+describe("installGracefulShutdown", () => {
 	it("listens for both SIGTERM and SIGINT", async () => {
 		const { signals } = install();
 		expect([...signals.keys()].sort()).toEqual(["SIGINT", "SIGTERM"]);
@@ -192,7 +181,6 @@ describe("installGracefulShutdown (#290)", () => {
 		expect(cleanup).toHaveBeenCalledTimes(1);
 	});
 
-	// The gap the audit was pointing at.
 	it("forces the remaining connections closed when draining outruns the deadline", async () => {
 		vi.useFakeTimers();
 		try {
@@ -217,7 +205,10 @@ describe("installGracefulShutdown (#290)", () => {
 			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 }, "shutdown_draining");
+			expect(logger.info).toHaveBeenCalledWith(
+				{ drainTimeoutMs: 5_000, cleanupTimeoutMs: 5_000 },
+				"shutdown_draining",
+			);
 			expect(logger.error).toHaveBeenCalledWith(
 				{ drainTimeoutMs: 5_000 },
 				"shutdown_drain_deadline_exceeded",
@@ -385,11 +376,9 @@ describe("installGracefulShutdown (#290)", () => {
 	});
 
 	it("bounds cleanup so a hanging dispose cannot wedge the process", async () => {
-		// The guarantees above say cleanup "never wedges the process", but `finish`
-		// awaited it with no deadline — and the drain deadline is already cleared
-		// by then, so a dispose that never settles meant `exit` was never reached.
-		// The same defect was found in auth.proxy#81 and auth.policy-verifier#210,
-		// both of which took this file as their starting point.
+		// 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({
@@ -437,9 +426,9 @@ describe("installGracefulShutdown (#290)", () => {
 	});
 
 	it("reports the cleanup outcome as the reason, not the drain that preceded it", async () => {
-		// `exitCode` became 1 while `reason` still said "drained", so the one line
-		// an operator alerts on contradicted itself. The drain outcome is still
-		// carried, under its own key, so neither fact is lost.
+		// `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")),
 		});
@@ -473,81 +462,159 @@ describe("installGracefulShutdown (#290)", () => {
 	});
 });
 
-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({});
+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("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("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("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("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("is honoured by the shutdown: a cleanup that needs longer than the drain is given it", async () => {
+	it("leaves cleanup its own budget when the handle reports no allowance", async () => {
 		vi.useFakeTimers();
 		try {
-			const { signals, finishDraining, exit } = install({
-				cleanup: () => new Promise<void>((resolve) => setTimeout(resolve, 30_000)),
+			const { signals, finishDraining, logger } = install({
+				cleanup: () => new Promise<void>(() => {}),
 				drainTimeoutMs: 5_000,
-				...cleanupAllowanceFor({ federationGrants: { enabled: true } }),
+				cleanupAllowanceMs: () => undefined,
 			});
 			signals.get("SIGTERM")?.();
 			finishDraining();
-			await vi.advanceTimersByTimeAsync(31_000);
-			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+			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();
 		}