@plitzi/sdk-server 0.37.1 → 0.37.3

package/dist/core/oauth/consentPage.js

@@ -24,6 +24,8 @@ var STYLES = `
   img.logo { display: block; height: 32px; margin-bottom: 20px; }
   h1 { margin: 0 0 6px; font-size: 20px; font-weight: 600; }
   p.lede { margin: 0 0 24px; color: var(--muted); font-size: 14px; }
+  p.client { margin: -12px 0 24px; padding: 10px 12px; border: 1px solid var(--line); border-radius: 8px;
+    font-size: 14px; }
   input:focus-visible, button:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
   ul.targets { list-style: none; margin: 0 0 20px; padding: 0; display: grid; gap: 8px; }
   ul.targets label { display: flex; gap: 10px; align-items: flex-start; margin: 0; padding: 12px;
@@ -73,6 +75,14 @@ var anonymousFields = (view) => {
 	return `${view.guest ? guestButton(view.guest) : ""}${signIn}`;
 };
 /**
+* Who is asking and where the grant goes. The name is whatever the client registered as, so it is never shown alone:
+* the destination host is what a person can check against the app they just opened.
+*/
+var clientNotice = (client) => {
+	const destination = client.loopback ? "an app on this computer" : `<strong>${escapeHtml(client.redirectHost)}</strong>`;
+	return `<p class="client"><strong>${escapeHtml(client.name)}</strong> is asking for access. If you continue, it is sent to ${destination}.</p>`;
+};
+/**
 * The grant screen — the ONE page this server renders, and it never asks who anybody is.
 *
 * It used to be two steps, the first of which took a username and a password. That is gone: signing in happens on
@@ -99,6 +109,7 @@ var renderConsentPage = (view) => {
     ${logo}
     <h1>${escapeHtml(productName)}</h1>
     <p class="lede">${lede}</p>
+    ${clientNotice(view.client)}
     ${error}
     <form method="post" action="${escapeHtml(view.action)}">
       ${hiddenFields(view.hidden)}

package/dist/core/oauth/issueContext.d.ts

@@ -0,0 +1,14 @@
+import { OAuthConfig, OAuthIssueContext, SSRRequest } from '@plitzi/sdk-shared';
+/**
+ * What `issueToken` is told about who it issues to, beyond the person: the application, as it registered, and the
+ * request the credential is issued on.
+ *
+ * The application is read from its registration rather than trusted from the request — a client names itself once,
+ * when it registers, and every credential its grants mint carries that name. A registration that has aged out of the
+ * store (a grant renewed for longer than the client record lives) is still an application, just an unnamed one.
+ */
+export declare const issueContextFor: (config: OAuthConfig, clientId: string, extra?: {
+    req?: SSRRequest;
+    replaces?: string;
+    redirectUri?: string;
+}) => Promise<OAuthIssueContext>;

package/dist/core/oauth/issueContext.js

@@ -0,0 +1,32 @@
+import { forwardedIp } from "../requestParser.js";
+import { getClient } from "./records.js";
+//#region src/core/oauth/issueContext.ts
+/**
+* What `issueToken` is told about who it issues to, beyond the person: the application, as it registered, and the
+* request the credential is issued on.
+*
+* The application is read from its registration rather than trusted from the request — a client names itself once,
+* when it registers, and every credential its grants mint carries that name. A registration that has aged out of the
+* store (a grant renewed for longer than the client record lives) is still an application, just an unnamed one.
+*/
+var issueContextFor = async (config, clientId, extra = {}) => {
+	const client = await getClient(config.adapters.store, clientId);
+	const userAgent = extra.req?.headers["user-agent"];
+	const ip = extra.req ? extra.req.ip ?? forwardedIp(extra.req.headers) : "";
+	const request = {
+		...typeof userAgent === "string" && userAgent ? { userAgent } : {},
+		...ip ? { ip } : {}
+	};
+	return {
+		client: {
+			clientId,
+			name: client?.clientName ?? "Unnamed application",
+			...client?.softwareId ? { softwareId: client.softwareId } : {}
+		},
+		...request.userAgent || request.ip ? { request } : {},
+		...extra.replaces ? { replaces: extra.replaces } : {},
+		...extra.redirectUri ? { redirectUri: extra.redirectUri } : {}
+	};
+};
+//#endregion
+export { issueContextFor };

package/dist/core/oauth/records.d.ts

@@ -4,6 +4,8 @@ import { OAuthGrantTarget, OAuthStore, OAuthUser } from '@plitzi/sdk-shared';
 export type ClientRecord = {
     clientId: string;
     clientName: string;
+    /** RFC 7591 `software_id`, when the client sent one. */
+    softwareId?: string;
     redirectUris: string[];
     /** When this registration was first handed out, so re-registering the same client keeps reporting its real age. */
     issuedAt: number;
@@ -37,6 +39,11 @@ export type RefreshRecord = {
     scope?: string;
     user: OAuthUser;
     target: OAuthGrantTarget;
+    /**
+     * What `issueToken` last minted for this grant. Handed back as `replaces` on the renewal, so the deployment can
+     * rotate that credential instead of adding another, and to `revokeToken` when the grant is revoked.
+     */
+    credential?: string;
 };
 /** A bearer this server handed out. The token a client holds is an opaque handle minted here, and this record is
  *  what it stands for — including `credential`, the thing the deployment's own adapters understand, which never

package/dist/core/oauth/register.d.ts

@@ -1,4 +1,6 @@
 import { OAuthConfig, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/** Plain http on the loopback interface — the exception RFC 8252 carves out for a native app listening on a port. */
+export declare const isLoopbackRedirectUri: (value: string) => boolean;
 /** RFC 7591 dynamic client registration. A remote host has no way to be configured into this server ahead of
  *  time, so it registers itself on first connect; the record it gets back is only ever used to pin the redirect
  *  target, since a public client authenticates with PKCE rather than with credentials. */

package/dist/core/oauth/register.js

@@ -1,21 +1,38 @@
-import { randomId } from "./pkce.js";
 import { getClientByFingerprint, putClient, putClientFingerprint } from "./records.js";
+import { randomId } from "./pkce.js";
 import { sendErrorJson, sendJson } from "./respond.js";
 import { createHash } from "node:crypto";
 //#region src/core/oauth/register.ts
-var isUsableRedirectUri = (value) => {
-	let url;
+var parseUri = (value) => {
 	try {
-		url = new URL(value);
+		return new URL(value);
 	} catch {
-		return false;
+		return;
 	}
-	if (url.protocol === "https:") return true;
-	return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
 };
+/** Plain http on the loopback interface — the exception RFC 8252 carves out for a native app listening on a port. */
+var isLoopbackRedirectUri = (value) => {
+	const url = parseUri(value);
+	return url?.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+};
+/**
+* A redirect target must be one the user's browser can be sent to safely: https anywhere, or loopback. A deployment
+* whose clients are all native apps narrows that to loopback alone (see `OAuthConfig.loopbackRedirectsOnly`).
+*/
+var isUsableRedirectUri = (value, loopbackOnly) => isLoopbackRedirectUri(value) || !loopbackOnly && parseUri(value)?.protocol === "https:";
 var stringList = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
 var nowSeconds = () => Math.floor(Date.now() / 1e3);
 var fingerprintOf = (clientName, redirectUris) => createHash("sha256").update(JSON.stringify([clientName, [...redirectUris].sort()])).digest("base64url");
+/**
+* What a client calls itself is shown to the person it acts for — on the grant screen and in their list of devices — so
+* it is bounded: a name is a line of text, not a document a client can fill the screen with.
+*/
+var CLIENT_NAME_MAX = 120;
+var SOFTWARE_ID_MAX = 64;
+var textField = (value, max) => {
+	if (typeof value !== "string") return;
+	return value.trim().slice(0, max) || void 0;
+};
 /** RFC 7591 dynamic client registration. A remote host has no way to be configured into this server ahead of
 *  time, so it registers itself on first connect; the record it gets back is only ever used to pin the redirect
 *  target, since a public client authenticates with PKCE rather than with credentials. */
@@ -25,17 +42,20 @@ var handleRegister = async (config, res, body) => {
 		return;
 	}
 	const metadata = body;
-	const redirectUris = stringList(metadata["redirect_uris"]).filter(isUsableRedirectUri);
+	const loopbackOnly = config.loopbackRedirectsOnly === true;
+	const redirectUris = stringList(metadata["redirect_uris"]).filter((uri) => isUsableRedirectUri(uri, loopbackOnly));
 	if (redirectUris.length === 0) {
-		sendErrorJson(res, 400, "invalid_request", "redirect_uris must list at least one https (or loopback) URI.");
+		sendErrorJson(res, 400, "invalid_request", loopbackOnly ? "redirect_uris must list at least one loopback URI (http://127.0.0.1:<port>/…)." : "redirect_uris must list at least one https (or loopback) URI.");
 		return;
 	}
-	const clientName = typeof metadata["client_name"] === "string" ? metadata["client_name"] : "MCP client";
+	const clientName = textField(metadata["client_name"], CLIENT_NAME_MAX) ?? "MCP client";
+	const softwareId = textField(metadata["software_id"], SOFTWARE_ID_MAX);
 	const { store } = config.adapters;
 	const fingerprint = fingerprintOf(clientName, redirectUris);
 	const client = await getClientByFingerprint(store, fingerprint) ?? {
 		clientId: randomId(),
 		clientName,
+		...softwareId ? { softwareId } : {},
 		redirectUris,
 		issuedAt: nowSeconds()
 	};
@@ -45,6 +65,7 @@ var handleRegister = async (config, res, body) => {
 		client_id: client.clientId,
 		client_id_issued_at: client.issuedAt,
 		client_name: clientName,
+		...client.softwareId ? { software_id: client.softwareId } : {},
 		redirect_uris: redirectUris,
 		grant_types: config.refreshTtlSeconds === 0 ? ["authorization_code"] : ["authorization_code", "refresh_token"],
 		response_types: ["code"],
@@ -52,4 +73,4 @@ var handleRegister = async (config, res, body) => {
 	});
 };
 //#endregion
-export { handleRegister };
+export { handleRegister, isLoopbackRedirectUri };

package/dist/core/oauth/register.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/oauth/token.js

@@ -1,7 +1,8 @@
+import { dropAccess, dropCode, dropRefresh, getAccess, getCode, getRefresh, putAccess, putRefresh } from "./records.js";
+import { issueContextFor } from "./issueContext.js";
 import { scopesOf } from "./metadata.js";
 import { field, optionalField } from "./params.js";
 import { randomId, verifyChallenge } from "./pkce.js";
-import { dropAccess, dropCode, dropRefresh, getCode, getRefresh, putAccess, putRefresh } from "./records.js";
 import { sendErrorJson, sendJson } from "./respond.js";
 //#region src/core/oauth/token.ts
 var DEFAULT_REFRESH_TTL_SECONDS = 2592e3;
@@ -35,12 +36,21 @@ var sendTokens = async (config, res, credential, expiresInSeconds, grant) => {
 	const body = {
 		access_token: bearer,
 		token_type: "Bearer",
-		scope: scopeOf(config, grant.scope)
+		scope: scopeOf(config, grant.scope),
+		/**
+		* What the person chose on the grant screen — a space, the account. RFC 6749 §5.1 lets a token response carry
+		* parameters of its own, and this one is what a client that asked to CHOOSE needs back: without it, a native
+		* client granted "work in this space" would hold a credential and not know which space it was for.
+		*/
+		target: grant.target.value
 	};
 	if (expiresInSeconds !== void 0) body["expires_in"] = expiresInSeconds;
 	if (ttl > 0) {
 		const refreshToken = randomId();
-		await putRefresh(config.adapters.store, refreshToken, grant, ttl);
+		await putRefresh(config.adapters.store, refreshToken, {
+			...grant,
+			credential
+		}, ttl);
 		body["refresh_token"] = refreshToken;
 	}
 	sendJson(res, 200, body);
@@ -89,7 +99,7 @@ var exchangeRefresh = async (config, res, params) => {
 		sendErrorJson(res, 400, "invalid_grant", "The refresh token was issued to another client.");
 		return;
 	}
-	const issued = await config.adapters.issueToken(record.user, record.target);
+	const issued = await config.adapters.issueToken(record.user, record.target, await issueContextFor(config, record.clientId, { replaces: record.credential }));
 	if (!issued) {
 		sendErrorJson(res, 400, "invalid_grant", "The account no longer has access to this resource.");
 		return;
@@ -107,8 +117,13 @@ var exchangeRefresh = async (config, res, params) => {
 var handleRevoke = async (config, res, params) => {
 	const token = optionalField(params, "token");
 	if (token) {
-		await dropRefresh(config.adapters.store, token);
-		await dropAccess(config.adapters.store, token);
+		const { store, revokeToken } = config.adapters;
+		const refresh = await getRefresh(store, token);
+		const access = await getAccess(store, token);
+		await dropRefresh(store, token);
+		await dropAccess(store, token);
+		const credential = refresh?.credential ?? (access ? access.credential ?? token : void 0);
+		if (credential && revokeToken) await revokeToken(credential);
 	}
 	res.setStatus(200);
 	res.end();

package/dist/core/oauth/token.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/requestParser.d.ts

@@ -9,4 +9,8 @@ export declare const requestOrigin: (req: SSRRequest) => string;
  *  the original client first. All three are plain headers a direct client can forge, so this is log/diagnostic
  *  material — never an authorisation input. Falls back to the socket peer, which no client controls. */
 export declare const clientIp: (raw: IncomingMessage, req: SSRRequest) => string;
+/** The proxies' account of the client address, without the socket — for a caller that has headers and nothing else. */
+export declare const forwardedIp: (headers: Record<string, string | string[] | undefined>) => string;
+/** A request's body as it arrived, byte for byte — what a binary upload to a function's route needs. */
+export declare const readRawBytes: (raw: IncomingMessage) => Promise<Buffer>;
 export declare const readRawBody: (raw: IncomingMessage) => Promise<string>;

package/dist/core/requestParser.js

@@ -18,8 +18,10 @@ var parseRequest = (raw) => {
 		const sp = new URLSearchParams(search.slice(1));
 		for (const [k, v] of sp.entries()) query[k] = v;
 	}
+	const method = (headers[":method"] ?? raw.method ?? "GET").toUpperCase();
+	const ip = forwardedIp(headers) || unmapIpv4(raw.socket.remoteAddress ?? "");
 	return {
-		method: (headers[":method"] ?? raw.method ?? "GET").toUpperCase(),
+		method,
 		path,
 		search,
 		url: rawUrl,
@@ -27,6 +29,7 @@ var parseRequest = (raw) => {
 		protocol,
 		headers,
 		query,
+		...ip ? { ip } : {},
 		ctx: {}
 	};
 };
@@ -43,12 +46,15 @@ var unmapIpv4 = (address) => address.startsWith("::ffff:") && address.includes("
 *  peer it accepted in `cf-connecting-ip`, the ingress in `x-real-ip`, and `x-forwarded-for` lists the chain with
 *  the original client first. All three are plain headers a direct client can forge, so this is log/diagnostic
 *  material — never an authorisation input. Falls back to the socket peer, which no client controls. */
-var clientIp = (raw, req) => {
-	const forwardedFor = headerValue(req.headers["x-forwarded-for"]).split(",")[0] ?? "";
-	return unmapIpv4(headerValue(req.headers["cf-connecting-ip"]) || headerValue(req.headers["x-real-ip"]) || forwardedFor.trim() || raw.socket.remoteAddress || "");
+var clientIp = (raw, req) => forwardedIp(req.headers) || unmapIpv4(raw.socket.remoteAddress ?? "");
+/** The proxies' account of the client address, without the socket — for a caller that has headers and nothing else. */
+var forwardedIp = (headers) => {
+	const forwardedFor = headerValue(headers["x-forwarded-for"]).split(",")[0] ?? "";
+	return unmapIpv4(headerValue(headers["cf-connecting-ip"]) || headerValue(headers["x-real-ip"]) || forwardedFor.trim());
 };
 var MAX_BODY_BYTES = 1048576;
-var readRawBody = (raw) => new Promise((resolve, reject) => {
+/** A request's body as it arrived, byte for byte — what a binary upload to a function's route needs. */
+var readRawBytes = (raw) => new Promise((resolve, reject) => {
 	const chunks = [];
 	let size = 0;
 	raw.on("data", (chunk) => {
@@ -59,8 +65,9 @@ var readRawBody = (raw) => new Promise((resolve, reject) => {
 		}
 		chunks.push(chunk);
 	});
-	raw.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+	raw.on("end", () => resolve(Buffer.concat(chunks)));
 	raw.on("error", reject);
 });
+var readRawBody = async (raw) => (await readRawBytes(raw)).toString("utf8");
 //#endregion
-export { clientIp, parseRequest, readRawBody, requestOrigin };
+export { clientIp, forwardedIp, parseRequest, readRawBody, readRawBytes, requestOrigin };

package/dist/core/sdkAssets.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
-import { statSync } from "node:fs";
 import path from "node:path";
+import { statSync } from "node:fs";
 //#region src/core/sdkAssets.ts
 /** Where the rendered page is told to fetch the SDK bundle from. Emitted by the render, so it is also served. */
 var SDK_ASSETS_PREFIX = "/sdk-assets";

package/dist/core/server/baseServer.d.ts

@@ -4,6 +4,19 @@ export interface HttpServerParts {
     label: string;
     cache: CacheManager | null;
     plugins: PluginRegistry;
-    onDestroy?: () => void;
+    /** Started once the transport is bound: background work that should not run in a server nobody listened on. */
+    onListen?: () => void;
+    /**
+     * The server has stopped taking connections and is shutting down: what holds connections open for good — realtime
+     * sockets and streams — lets them go now, rather than being cut when the grace runs out.
+     */
+    onClosing?: () => void;
+    /** Awaited, so a server that holds work in flight — jobs, drains — can finish it before the sockets close. */
+    onDestroy?: () => void | Promise<void>;
+    /** What a plugin invalidated in another process of the fleet leaves to do here: forget it, in memory only. */
+    forgetPlugins?: (name?: string, version?: string) => void;
+    /** What the primary does once, before it starts the workers — work each of them would otherwise repeat, or race
+     *  the others to do. */
+    beforeFork?: () => Promise<void>;
 }
 export declare const createHttpServer: (config: SSRServerConfig, makeHandlerForPort: (port: number) => Handler, parts: HttpServerParts) => SSRServer;

package/dist/core/server/baseServer.js

@@ -1,4 +1,9 @@
+import { serverLog } from "../../helpers/serverLog.js";
+import { fleetRole, resolveWorkers } from "./fleet/role.js";
+import { channelName } from "./fleet/link.js";
 import { buildTransport, protoLabel } from "../transports.js";
+import { watchConnections } from "./drain.js";
+import { relayCache, relayPlugins } from "./fleet/relay.js";
 //#region src/core/server/baseServer.ts
 /**
 * What went wrong taking the port, and what to do about it.
@@ -19,13 +24,33 @@ var createHttpServer = (config, makeHandlerForPort, parts) => {
 	const version = config.httpVersion ?? (config.tls ? 2 : 1);
 	if (version >= 3 && !config.tls) throw new Error(`[${label}] httpVersion: ${version} requires a tls config with key and cert`);
 	let primary;
+	let connections;
 	let h3;
+	let fleet;
+	let closed = false;
+	const plan = resolveWorkers(config.workers);
+	const role = fleetRole(plan);
+	const channel = role === "single" ? void 0 : channelName(label);
 	return {
-		cache: parts.cache,
-		plugins: parts.plugins,
+		cache: channel && parts.cache ? relayCache(parts.cache, `${channel}.cache`) : parts.cache,
+		plugins: channel && parts.forgetPlugins ? relayPlugins(parts.plugins, parts.forgetPlugins, `${channel}.plugins`, label) : parts.plugins,
 		listen(port, host = "0.0.0.0") {
+			if (plan.requested !== void 0 && role !== "worker") serverLog.warn(label, `${plan.requested} workers asked for, ${plan.count} cores to run them on: starting ${plan.count}`);
+			if (role === "primary") {
+				(parts.beforeFork?.() ?? Promise.resolve()).catch((error) => serverLog.error(label, "preparing for the workers failed", error)).then(async () => {
+					const { startFleet } = await import("./fleet/supervisor.js");
+					if (closed) return;
+					fleet = startFleet(plan.count, label);
+					serverLog.info(label, `${plan.count} workers on ${host}:${port}`);
+				}).catch((error) => {
+					serverLog.error(label, "the workers could not start", error);
+					process.exitCode = 1;
+				});
+				return;
+			}
 			const handler = makeHandlerForPort(port);
 			({primary, h3} = buildTransport(config, handler, port, label));
+			connections = watchConnections(primary);
 			primary.on("error", (error) => {
 				if (config.onListenError) {
 					config.onListenError(error, {
@@ -35,28 +60,35 @@ var createHttpServer = (config, makeHandlerForPort, parts) => {
 					});
 					return;
 				}
-				console.error(bindFailure(error, port, label));
+				serverLog.error(label, bindFailure(error, port, label));
 				process.exitCode = 1;
 				process.exit(1);
 			});
 			primary.listen(port, host, () => {
-				console.log(`[${label}] ${protoLabel(version, !!config.tls)} - listening on ${host}:${port}`);
+				serverLog.info(label, `${protoLabel(version, !!config.tls)} - listening on ${host}:${port}`);
+				parts.onListen?.();
 			});
 		},
 		async close() {
-			parts.onDestroy?.();
-			const open = [primary, h3].filter((srv) => srv !== void 0);
+			closed = true;
+			await fleet?.stop();
+			fleet = void 0;
+			const draining = connections?.drain(label);
+			const quic = h3;
 			primary = void 0;
+			connections = void 0;
 			h3 = void 0;
-			await Promise.all(open.map((srv) => new Promise((resolve, reject) => {
-				srv.close((err) => {
-					if (err && err.code !== "ERR_SERVER_NOT_RUNNING") {
-						reject(err);
+			parts.onClosing?.();
+			await parts.onDestroy?.();
+			await Promise.all([draining, quic && new Promise((resolve, reject) => {
+				quic.close((error) => {
+					if (error && !("code" in error && error.code === "ERR_SERVER_NOT_RUNNING")) {
+						reject(error);
 						return;
 					}
 					resolve();
 				});
-			})));
+			})]);
 		}
 	};
 };

package/dist/core/server/closeOnSignals.d.ts

@@ -0,0 +1,28 @@
+/** Anything that closes the way a server from `createServer` does. */
+export type Closable = {
+    close: () => Promise<void>;
+};
+export type CloseOnSignalsOptions = {
+    /** Default `SIGTERM` (what an orchestrator sends before it replaces a replica) and `SIGINT` (^C). */
+    signals?: NodeJS.Signals[];
+    /** Runs once the server has closed: what the deployment opened itself — a pool, a client, a file — goes here. */
+    afterClose?: () => void | Promise<void>;
+};
+/**
+ * Closes the server when the process is told to stop, and only then lets the process exit.
+ *
+ * `close()` already does the waiting — the page server stops claiming jobs, finishes the ones it is running and lets
+ * go of its sockets — but nothing calls it when a deploy sends SIGTERM, and a process that simply exits leaves every
+ * running job to be retried by somebody else. This is that call, for a deployment that has no signal handling of its
+ * own. Opt in: a host that already manages its process's signals keeps doing so, and calls `close()` from there.
+ *
+ * ```ts
+ * const server = createServer(config);
+ * server.listen(3000);
+ * closeOnSignals(server, { afterClose: () => pool.end() });
+ * ```
+ *
+ * A second signal while it is closing exits at once — the ^C a person presses when waiting is not what they want.
+ * Answers a function that removes the handlers again.
+ */
+export declare const closeOnSignals: (server: Closable, { signals, afterClose }?: CloseOnSignalsOptions) => (() => void);

package/dist/core/server/closeOnSignals.js

@@ -0,0 +1,47 @@
+import { serverLog } from "../../helpers/serverLog.js";
+//#region src/core/server/closeOnSignals.ts
+/**
+* Closes the server when the process is told to stop, and only then lets the process exit.
+*
+* `close()` already does the waiting — the page server stops claiming jobs, finishes the ones it is running and lets
+* go of its sockets — but nothing calls it when a deploy sends SIGTERM, and a process that simply exits leaves every
+* running job to be retried by somebody else. This is that call, for a deployment that has no signal handling of its
+* own. Opt in: a host that already manages its process's signals keeps doing so, and calls `close()` from there.
+*
+* ```ts
+* const server = createServer(config);
+* server.listen(3000);
+* closeOnSignals(server, { afterClose: () => pool.end() });
+* ```
+*
+* A second signal while it is closing exits at once — the ^C a person presses when waiting is not what they want.
+* Answers a function that removes the handlers again.
+*/
+var closeOnSignals = (server, { signals = ["SIGTERM", "SIGINT"], afterClose } = {}) => {
+	let closing = false;
+	const onSignal = (signal) => {
+		if (closing) {
+			serverLog.warn("server", `${signal} again: exiting without waiting`);
+			process.exit(1);
+			return;
+		}
+		closing = true;
+		serverLog.info("server", `${signal}: finishing what is running, then exiting`);
+		(async () => {
+			try {
+				await server.close();
+				await afterClose?.();
+				process.exit(0);
+			} catch (error) {
+				serverLog.error("server", "could not close cleanly", error);
+				process.exit(1);
+			}
+		})();
+	};
+	for (const signal of signals) process.on(signal, onSignal);
+	return () => {
+		for (const signal of signals) process.off(signal, onSignal);
+	};
+};
+//#endregion
+export { closeOnSignals };

package/dist/core/server/closeOnSignals.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/server/drain.d.ts

@@ -0,0 +1,18 @@
+import { PrimaryServer } from '../transports';
+/**
+ * How long a server shutting down lets what it is answering finish before it cuts it: a render, an upload, an action
+ * called a moment ago. Well under the 30 seconds a cluster gives a pod between SIGTERM and SIGKILL.
+ */
+export declare const SHUTDOWN_GRACE_MS = 10000;
+/**
+ * The connections a server holds, watched from the moment it is built, so it can be shut down.
+ *
+ * Node's `server.close()` stops taking connections and then waits for every open one to end. A request ends; a
+ * WebSocket or an event stream does not — a board open in a tab, an agent's app listening — so a server with one open
+ * waited for ever, and a Ctrl+C or a SIGTERM hung until something killed it. `drain` stops taking connections, closes
+ * the idle ones, ends every event stream at once (a stream has nothing left to finish), gives what is still being
+ * answered `graceMs`, and then cuts what remains.
+ */
+export declare const watchConnections: (server: PrimaryServer) => {
+    drain: (label: string, graceMs?: number) => Promise<void>;
+};

package/dist/core/server/drain.js

@@ -0,0 +1,62 @@
+import { serverLog } from "../../helpers/serverLog.js";
+//#region src/core/server/drain.ts
+/**
+* How long a server shutting down lets what it is answering finish before it cuts it: a render, an upload, an action
+* called a moment ago. Well under the 30 seconds a cluster gives a pod between SIGTERM and SIGKILL.
+*/
+var SHUTDOWN_GRACE_MS = 1e4;
+/**
+* Whether a response is an event stream: said by its content type — or, since headers written with `writeHead(status,
+* headers)` are not kept where `getHeader` looks, by what it answers: a GET that asked for one, as an EventSource and
+* an MCP client's listening stream do.
+*/
+var isEventStream = (asking, answering) => {
+	const type = answering.getHeader("content-type");
+	const accept = asking.headers.accept;
+	return typeof type === "string" && type.startsWith("text/event-stream") || asking.method === "GET" && [accept].flat().some((value) => value?.includes("text/event-stream"));
+};
+/**
+* The connections a server holds, watched from the moment it is built, so it can be shut down.
+*
+* Node's `server.close()` stops taking connections and then waits for every open one to end. A request ends; a
+* WebSocket or an event stream does not — a board open in a tab, an agent's app listening — so a server with one open
+* waited for ever, and a Ctrl+C or a SIGTERM hung until something killed it. `drain` stops taking connections, closes
+* the idle ones, ends every event stream at once (a stream has nothing left to finish), gives what is still being
+* answered `graceMs`, and then cuts what remains.
+*/
+var watchConnections = (server) => {
+	const sockets = /* @__PURE__ */ new Set();
+	const answering = /* @__PURE__ */ new Map();
+	server.on("connection", (socket) => {
+		sockets.add(socket);
+		socket.once("close", () => sockets.delete(socket));
+	});
+	server.on("request", (request, response) => {
+		answering.set(response, request);
+		response.once("close", () => answering.delete(response));
+	});
+	return { drain: (label, graceMs = SHUTDOWN_GRACE_MS) => new Promise((resolve, reject) => {
+		const cut = setTimeout(() => {
+			if (sockets.size) serverLog.warn(label, `${sockets.size} connection(s) still open after ${graceMs} ms: closing them`);
+			sockets.forEach((socket) => socket.destroy());
+		}, graceMs);
+		cut.unref();
+		server.close((error) => {
+			clearTimeout(cut);
+			if (error && !("code" in error && error.code === "ERR_SERVER_NOT_RUNNING")) {
+				reject(error);
+				return;
+			}
+			resolve();
+		});
+		const closeIdle = () => {
+			if ("closeIdleConnections" in server) server.closeIdleConnections();
+		};
+		closeIdle();
+		answering.forEach((request, response) => {
+			if (isEventStream(request, response)) response.end(closeIdle);
+		});
+	}) };
+};
+//#endregion
+export { SHUTDOWN_GRACE_MS, watchConnections };

package/dist/core/server/drain.test.d.ts

@@ -0,0 +1 @@
+export {};