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

package/templates/standalone/src/shutdown.mts

@@ -14,59 +14,16 @@
  * limitations under the License.
  */
 
+/*
+ * Graceful shutdown for the scaffolded server, kept in the template so that
+ * "does SIGTERM wait for in-flight requests, and for how long?" is answerable
+ * from the code you deploy. See the template README, "Shutdown guarantees".
+ */
+
 import type { Server } from "node:http";
-import type { Logger } from "@o3co/auth-provider-core";
+import { type Logger, loggableError } from "@o3co/auth-provider-core";
 
-/**
- * Graceful shutdown for the scaffolded server (#290).
- *
- * ## Why this is in the template rather than a dependency
- *
- * It used to be `gracefulShutdown` from `@o3co/auth.utils@0.0.4`. The ops
- * review's objection was not that the package is bad — it is that for the
- * component which terminates every user session, "does SIGTERM wait for
- * in-flight requests, and for how long?" has to be answerable from the code an
- * operator deploys, and it was answerable only by reading a pre-1.0 package
- * with no contract pinned here.
- *
- * Reading it answered the question, and the answer was the reason to move it:
- * **there was no deadline**. `server.close()` waits for in-flight requests
- * indefinitely, so a single 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, arriving only under the load that produces
- * a stuck request. The cleanup-failure path also wrote to `console.error`, one
- * bare line in a service whose every other line is NDJSON.
- *
- * Neither is fixed by documenting or pinning the dependency, which is why this
- * is ~40 lines here with tests, rather than a version range and a README
- * paragraph.
- *
- * ## The guarantees, stated
- *
- * 1. **SIGTERM and SIGINT** both start it; the second signal is ignored rather
- *    than starting a second dispose over the first one's stores.
- * 2. **New connections stop immediately** (`server.close`), and idle keep-alive
- *    sockets are released (`closeIdleConnections`) — they hold the server open
- *    with no request behind them, so a quiet server would otherwise wait out
- *    the whole deadline for nothing.
- * 3. **In-flight requests are given `drainTimeoutMs`** (default 10s) to finish.
- * 4. **Past the deadline, remaining connections are cut** (`closeAllConnections`)
- *    and the process exits **non-zero** — an orchestrator that only ever sees
- *    `0` cannot tell a clean drain from one that ran out of time.
- * 5. **`cleanup` runs after draining, before exit**, and its failure is logged
- *    through the app logger and reflected in the exit code. It never wedges the
- *    process: a dispose that throws still exits, and one that never settles is
- *    cut off at `cleanupTimeoutMs`.
- * 6. **A `close` that fails is not reported as a clean drain.** `server.close`
- *    reports through its callback, and treating that as success would tell an
- *    orchestrator the listener came down when it did not.
- *
- * Size `drainTimeoutMs` plus `cleanupTimeoutMs` **below** the orchestrator's
- * own kill grace period (Kubernetes `terminationGracePeriodSeconds` is 30s by
- * default, compose `stop_grace_period` 10s; with federation grants on the sum
- * is 55s, so the grace is 60s or more) — the point is to close on our terms
- * before SIGKILL arrives on someone else's.
- */
+/** Options for {@link installGracefulShutdown}. */
 export interface GracefulShutdownOptions {
 	readonly logger: Logger;
 	/** Reverse-topological component cleanup — normally `handle.dispose()`. */
@@ -74,11 +31,19 @@ export interface GracefulShutdownOptions {
 	/** How long in-flight requests get before connections are cut. Default 10s. */
 	readonly drainTimeoutMs?: number;
 	/**
-	 * How long `cleanup` gets before the shutdown gives up on it. Defaults to
-	 * `drainTimeoutMs`, so the worst-case shutdown is the two budgets in
-	 * sequence — size both against the orchestrator's grace period, not one.
+	 * How long `cleanup` gets before the shutdown gives up on it, unless
+	 * `cleanupAllowanceMs` is longer. Defaults to `drainTimeoutMs`, so the
+	 * worst-case shutdown is the two budgets in sequence — size both against
+	 * the orchestrator's grace period, not one.
 	 */
 	readonly cleanupTimeoutMs?: number;
+	/**
+	 * The least `cleanup` gets, read when the signal arrives: normally
+	 * `() => handle.cleanupAllowanceMs`, the longest tail a module registered
+	 * its cleanup with. Absent, unreadable, or not a whole number of
+	 * milliseconds from 1 to 2147483647, the budget is `cleanupTimeoutMs` alone.
+	 */
+	readonly cleanupAllowanceMs?: () => number | undefined;
 	/** Injected in tests; defaults to {@link deferExit}. */
 	readonly exit?: (code: number) => void;
 	/** Injected in tests; defaults to `process.on`. */
@@ -103,71 +68,33 @@ export function deferExit(code: number, exitProcess: (code: number) => void = pr
 const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
 const SIGNALS: readonly NodeJS.Signals[] = ["SIGTERM", "SIGINT"];
 
-/**
- * The least cleanup allowance federation grants get (#593 slice 7): 45
- * seconds. The package's background registry drains on dispose — it waits for
- * a rotated upstream credential's write — and the longest tail one refresh
- * can have is the upstream hard timeout, the persist budget and the wait for
- * the grant's lock, back to back. With the shipped budgets (25 s + 3 s + 5 s)
- * and {@link FEDERATION_GRANTS_CLEANUP_MARGIN_MS} that is exactly this floor;
- * a deployment that raises a budget raises the allowance with it, below.
- * The ten-second drain that cleanup would otherwise inherit is shorter than
- * the tail, and a shutdown under it would abandon exactly the write the drain
- * exists to wait for, after the IdP had moved on to the new refresh token.
- *
- * A host policy, not a grant setting: what it bounds is `handle.dispose()`,
- * and the orchestrator's grace period has to cover the drain, this and an exit
- * margin — the compose files ship 60 seconds for the shipped budgets, and an
- * operator who raises a budget raises the grace to match.
- */
-export const FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS = 45_000;
-
-/** What the allowance adds to the longest refresh tail: an exit margin. */
-export const FEDERATION_GRANTS_CLEANUP_MARGIN_MS = 12_000;
-
-/**
- * The most a timer can be asked for: Node's `setTimeout` takes a 32-bit signed
- * delay, and a larger one fires after ~1 ms instead. A sum of budgets an
- * operator set high enough to reach it would otherwise turn the allowance
- * into no allowance at all (Copilot, #614).
- */
+/** The longest delay a timer takes; a larger one, or NaN, fires after about a millisecond. */
 const MAX_TIMER_MS = 2_147_483_647;
 
-/**
- * The `cleanupTimeoutMs` to hand {@link installGracefulShutdown}, from the
- * config: while the feature is on, the longer of the floor above and the
- * configured refresh tail plus the margin; while it is off, nothing — the
- * drain's own budget, as before. A fragment to spread, so an absent allowance
- * is absent rather than `undefined`. A config that carries no budgets (one
- * built by hand, without `reference.conf`) gets the floor.
- */
-export function cleanupAllowanceFor(config: {
-	readonly federationGrants?:
-		| {
-				readonly enabled?: boolean | undefined;
-				readonly upstreamHardTimeoutMs?: number | undefined;
-				readonly persistRetryBudgetMs?: number | undefined;
-				readonly lockWaitMs?: number | undefined;
-		  }
-		| undefined;
-}): { readonly cleanupTimeoutMs: number } | Record<string, never> {
-	const grants = config.federationGrants;
-	if (grants?.enabled !== true) return {};
-	const budgets = [grants.upstreamHardTimeoutMs, grants.persistRetryBudgetMs, grants.lockWaitMs];
-	const tail = budgets.every((budget) => typeof budget === "number" && Number.isFinite(budget))
-		? (budgets as number[]).reduce(
-				(sum, budget) => sum + budget,
-				FEDERATION_GRANTS_CLEANUP_MARGIN_MS,
-			)
-		: 0;
-	return {
-		cleanupTimeoutMs: Math.min(
-			Math.max(FEDERATION_GRANTS_CLEANUP_ALLOWANCE_MS, tail),
-			MAX_TIMER_MS,
-		),
-	};
+/** What `read` reports, when it is a delay a timer can wait; otherwise nothing. */
+function allowanceFrom(read: (() => number | undefined) | undefined): number | undefined {
+	let allowance: unknown;
+	try {
+		allowance = read?.();
+	} catch {
+		return undefined;
+	}
+	return typeof allowance === "number" &&
+		Number.isInteger(allowance) &&
+		allowance >= 1 &&
+		allowance <= MAX_TIMER_MS
+		? allowance
+		: undefined;
 }
 
+/**
+ * Install the graceful shutdown on `server`. The guarantees (a deadline on the
+ * drain, a non-zero exit past it, a bounded `cleanup` that never wedges the
+ * process), the log line of each stage and how to size `drainTimeoutMs` plus
+ * `cleanupTimeoutMs` below the orchestrator's kill grace period are in the
+ * template README, "Shutdown guarantees". Beyond them: a `close` that fails is
+ * not reported as a clean drain, and exits non-zero.
+ */
 export function installGracefulShutdown(server: Server, options: GracefulShutdownOptions): void {
 	const {
 		logger,
@@ -182,7 +109,8 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 		},
 	} = options;
 
-	const cleanupTimeoutMs = options.cleanupTimeoutMs ?? drainTimeoutMs;
+	// Settled when the signal arrives, with the allowance as it stands then.
+	let cleanupTimeoutMs = options.cleanupTimeoutMs ?? drainTimeoutMs;
 
 	let shuttingDown = false;
 	let finished = false;
@@ -226,7 +154,7 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 		let outcome = reason;
 		try {
 			if ((await runCleanup()) === CLEANUP_TIMED_OUT) {
-				logger.error({ cleanupTimeoutMs }, "graceful shutdown: cleanup timed out");
+				logger.error({ cleanupTimeoutMs }, "shutdown_cleanup_timed_out");
 				exitCode = 1;
 				outcome = "cleanup-timeout";
 			}
@@ -234,12 +162,14 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 			// Through the app logger, not `console.error`: a shutdown that
 			// failed to release its Redis connections is exactly the line an
 			// operator needs to find later, and a bare write is the one their
-			// pipeline drops.
-			logger.error({ err }, "graceful shutdown: cleanup failed");
+			// pipeline drops. The projection, not the error: `dispose()`
+			// rejects with every cleanup's own error on `errors`, a store's
+			// write — and what it wrote — among them.
+			logger.error({ err: loggableError(err) }, "shutdown_cleanup_failed");
 			exitCode = 1;
 			outcome = "cleanup-failed";
 		}
-		logger.info({ reason: outcome, drain: reason, exitCode }, "graceful shutdown: complete");
+		logger.info({ reason: outcome, drain: reason, exitCode }, "shutdown_complete");
 		exit(exitCode);
 	};
 
@@ -247,13 +177,11 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 		if (shuttingDown) return;
 		shuttingDown = true;
 		for (const signal of SIGNALS) offSignal(signal, handler);
-		logger.info({ drainTimeoutMs }, "graceful shutdown: draining");
+		cleanupTimeoutMs = Math.max(cleanupTimeoutMs, allowanceFrom(options.cleanupAllowanceMs) ?? 0);
+		logger.info({ drainTimeoutMs, cleanupTimeoutMs }, "shutdown_draining");
 
 		const deadline = setTimeout(() => {
-			logger.error(
-				{ drainTimeoutMs },
-				"graceful shutdown: drain deadline exceeded, closing remaining connections",
-			);
+			logger.error({ drainTimeoutMs }, "shutdown_drain_deadline_exceeded");
 			server.closeAllConnections();
 			void finish(1, "drain-timeout");
 		}, drainTimeoutMs);
@@ -269,7 +197,7 @@ export function installGracefulShutdown(server: Server, options: GracefulShutdow
 				// here. Reporting "drained" and exiting 0 on it would tell an
 				// orchestrator the shutdown went cleanly when the listener did
 				// not actually come down.
-				logger.error({ err }, "graceful shutdown: server close failed");
+				logger.error({ err: loggableError(err) }, "shutdown_server_close_failed");
 				void finish(1, "close-failed");
 				return;
 			}

package/templates/standalone/tests/index.test.js

@@ -32,7 +32,7 @@ const _extractCookies = (res) => (res.headers["set-cookie"] ?? []).join("; ");
 /**
  * The server's own origin, as a browser would report it.
  *
- * Since #272 `POST /session/login` and `POST /session/logout` reject a request
+ * `POST /session/login` and `POST /session/logout` reject a request
  * that carries neither a same-origin `Origin`/`Referer` nor a valid
  * double-submit CSRF token. A browser sets `Origin` on its own; a scripted
  * client like this one has to say it.
@@ -174,7 +174,7 @@ describe("POST /session/login", () => {
 	});
 });
 
-describe("CSRF on the state-changing session routes (#272)", () => {
+describe("CSRF on the state-changing session routes", () => {
 	it("rejects a login carrying neither an origin signal nor a token", async () => {
 		// The bypass this replaced: omitting `Origin` skipped the check entirely.
 		const res = await client.post("/session/login", {