@warlock.js/core 5.30.0 → 5.31.0

package/esm/http/server.mjs

@@ -26,17 +26,19 @@ function startHttpServer(options) {
 	const trustProxy = resolveTrustProxy(config.get("http.trustProxy", false));
 	const bodyLimit = config.get("http.bodyLimit") ?? void 0;
 	const configuredRewriteUrl = options?.rewriteUrl;
-	const forceCloseConnections = options?.forceCloseConnections ?? config.get("http.gracefulShutdown.forceCloseConnections", "idle");
+	const http2 = options?.http2 === true;
+	const requestedForceClose = options?.forceCloseConnections ?? config.get("http.gracefulShutdown.forceCloseConnections", http2 ? false : "idle");
+	const forceCloseConnections = http2 && requestedForceClose === "idle" ? false : requestedForceClose;
 	server = Fastify({
 		trustProxy,
 		...bodyLimit !== void 0 && { bodyLimit },
-		forceCloseConnections,
 		...options,
+		forceCloseConnections,
 		rewriteUrl(request) {
 			return normalizeRequestUrl(configuredRewriteUrl ? configuredRewriteUrl.call(this, request) : request.url ?? "/");
 		}
 	});
-	if (forceCloseConnections === "idle") trackConnectionsForDrain(server.server);
+	if (http2 || forceCloseConnections === "idle") trackConnectionsForDrain(server.server);
 	return server;
 }
 /**
@@ -52,11 +54,12 @@ const drainStates = /* @__PURE__ */ new WeakMap();
 * retired by {@link reapIdleConnections} after it finishes instead.
 */
 function retireAfterResponse(response) {
+	if ("stream" in response) return;
 	if (response.headersSent || response.writableEnded) return;
 	response.setHeader("Connection", "close");
 }
 function reapIdleConnections(rawServer) {
-	if (typeof rawServer.closeIdleConnections === "function") rawServer.closeIdleConnections();
+	if ("closeIdleConnections" in rawServer && typeof rawServer.closeIdleConnections === "function") rawServer.closeIdleConnections();
 }
 /**
 * Track in-flight responses on a Node HTTP server so a graceful drain can
@@ -74,9 +77,15 @@ function trackConnectionsForDrain(rawServer) {
 	if (!rawServer || typeof rawServer.on !== "function" || drainStates.has(rawServer)) return;
 	const state = {
 		inFlight: /* @__PURE__ */ new Set(),
+		sessions: /* @__PURE__ */ new Set(),
 		draining: false
 	};
 	drainStates.set(rawServer, state);
+	rawServer.on("session", (session) => {
+		state.sessions.add(session);
+		session.once("close", () => state.sessions.delete(session));
+		if (state.draining) session.close();
+	});
 	rawServer.on("request", (_request, response) => {
 		state.inFlight.add(response);
 		if (state.draining) retireAfterResponse(response);
@@ -100,6 +109,7 @@ function beginHttpDrain(rawServer) {
 	if (!state) return false;
 	state.draining = true;
 	for (const response of state.inFlight) retireAfterResponse(response);
+	for (const session of state.sessions) session.close();
 	reapIdleConnections(rawServer);
 	return true;
 }

package/esm/http/server.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"server.mjs","names":[],"sources":["../../../../../../../../packages/core/src/http/server.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport Fastify, { type FastifyServerOptions } from \"fastify\";\nimport type { Server as NodeHttpServer, ServerResponse } from \"node:http\";\nimport { normalizeRequestPath } from \"../router/normalize-request-path\";\nimport type { HttpServerOptions } from \"./types\";\n\nexport type FastifyInstance = ReturnType<typeof Fastify>;\n\n// Instantiate Fastify server\nlet server: FastifyInstance | undefined = undefined;\n\n/** Fastify's accepted, non-null `trustProxy` configuration shape. */\ntype TrustProxy = NonNullable<FastifyServerOptions[\"trustProxy\"]>;\ntype TrustProxyPredicate = (address: string, hop: number) => boolean;\n\nfunction isTrustProxyPredicate(value: unknown): value is TrustProxyPredicate {\n  return typeof value === \"function\";\n}\n\nfunction isTrustProxyList(value: unknown): value is string[] {\n  return (\n    Array.isArray(value) &&\n    value.length > 0 &&\n    value.every((entry) => typeof entry === \"string\" && entry.trim().length > 0)\n  );\n}\n\nfunction resolveTrustProxy(value: unknown): TrustProxy {\n  if (value === undefined || value === null) return false;\n\n  if (typeof value === \"boolean\" || isTrustProxyPredicate(value)) return value;\n\n  if (typeof value === \"string\" && value.trim().length > 0) return value;\n\n  if (isTrustProxyList(value)) return value;\n\n  const received = Array.isArray(value) ? \"array\" : typeof value;\n\n  throw new TypeError(\n    \"Invalid http.trustProxy configuration: expected a boolean, a non-empty IP/CIDR string, \" +\n      `a non-empty string array, or a predicate function; received ${received}.`,\n  );\n}\n\nfunction normalizeRequestUrl(url: string): string {\n  const queryIndex = url.indexOf(\"?\");\n\n  if (queryIndex === -1) return normalizeRequestPath(url);\n\n  return normalizeRequestPath(url.slice(0, queryIndex)) + url.slice(queryIndex);\n}\n\nexport function startHttpServer(options?: HttpServerOptions): FastifyInstance {\n  // `config.set(key, undefined)` stores null rather than unsetting, so an app\n  // that clears a key is treated the same as an app that never configured it.\n  const trustProxy = resolveTrustProxy(config.get(\"http.trustProxy\", false));\n\n  const bodyLimit = config.get(\"http.bodyLimit\") ?? undefined;\n  const configuredRewriteUrl = options?.rewriteUrl;\n  const forceCloseConnections =\n    options?.forceCloseConnections ??\n    config.get(\"http.gracefulShutdown.forceCloseConnections\", \"idle\");\n\n  server = Fastify({\n    // `X-Forwarded-For` is client-settable and spoofable, and `request.ip` is\n    // what @fastify/rate-limit keys its buckets on — so trusting it by default\n    // makes rate limiting bypassable on any deployment NOT behind a proxy that\n    // strips the header. Apps behind such a proxy opt in explicitly.\n    //\n    // Validated shapes resolve exactly as Fastify does: `true`, a CIDR/IP list\n    // (string, comma-separated string or array), or a predicate.\n    trustProxy,\n    // No default: an app that configures nothing keeps Fastify's own 1MB limit\n    // rather than the historical 200GB, which silently removed the protection\n    // Fastify provides. Per-route caps go through `serverOptions.bodyLimit`;\n    // the `maxBodySize()` middleware runs AFTER parsing and cannot reject\n    // before the bytes are resident.\n    ...(bodyLimit !== undefined && { bodyLimit }),\n    // Close idle keep-alive connections on shutdown while letting in-flight\n    // requests finish — the basis for graceful draining. Override via\n    // `http.gracefulShutdown.forceCloseConnections`.\n    forceCloseConnections,\n    ...options,\n    // Fastify calls this before route matching in both production `scan()` and\n    // the development wildcard dispatcher. Compose an app-supplied rewrite\n    // first, then apply the one framework request-path normalizer so the two\n    // modes cannot disagree about a terminal slash.\n    rewriteUrl(request) {\n      const rewritten = configuredRewriteUrl\n        ? configuredRewriteUrl.call(this, request)\n        : (request.url ?? \"/\");\n\n      return normalizeRequestUrl(rewritten);\n    },\n  });\n\n  // `\"idle\"` promises that idle keep-alive connections close on shutdown. Fastify\n  // only reaps the ones idle at the moment close starts; a connection whose\n  // request finishes DURING the drain stays open and holds `close()` until\n  // the shutdown budget expires (WR-014). Track responses so the drain can\n  // retire those connections as they go idle.\n  if (forceCloseConnections === \"idle\") {\n    trackConnectionsForDrain(server.server as NodeHttpServer);\n  }\n\n  return server;\n}\n\n/**\n * Expose the server to be publicly accessible\n */\nexport function getHttpServer(): FastifyInstance {\n  return server;\n}\n\n/**\n * Minimal shape needed to close a server — lets {@link closeServerWithTimeout}\n * be unit-tested with a fake instead of a real Fastify instance.\n */\nexport type ClosableServer = {\n  close: () => Promise<unknown>;\n  /** The underlying Node server, when there is one (a Fastify instance's `.server`). */\n  server?: unknown;\n};\n\n/**\n * Per-server drain state: the responses currently in flight, and whether a\n * graceful shutdown has begun.\n */\ntype DrainState = {\n  inFlight: Set<ServerResponse>;\n  draining: boolean;\n};\n\nconst drainStates = new WeakMap<object, DrainState>();\n\n/**\n * Mark a response so its connection closes once it is sent. Only possible\n * before the headers go out; a response that already streams its headers is\n * retired by {@link reapIdleConnections} after it finishes instead.\n */\nfunction retireAfterResponse(response: ServerResponse): void {\n  if (response.headersSent || response.writableEnded) return;\n\n  response.setHeader(\"Connection\", \"close\");\n}\n\nfunction reapIdleConnections(rawServer: NodeHttpServer): void {\n  if (typeof rawServer.closeIdleConnections === \"function\") {\n    rawServer.closeIdleConnections();\n  }\n}\n\n/**\n * Track in-flight responses on a Node HTTP server so a graceful drain can\n * close keep-alive connections that become idle AFTER `close()` started.\n *\n * Node's `server.close()` (and Fastify's `forceCloseConnections: \"idle\"`)\n * closes only the connections idle at that moment. A request in flight when\n * shutdown begins finishes its response, the client keeps the connection\n * alive, and `close()` waits on it until the shutdown budget runs out. Active\n * responses are never cut short: each one is told to close its connection\n * when it is done (`Connection: close`), and every connection is reaped as\n * soon as its response has finished.\n */\nexport function trackConnectionsForDrain(rawServer: NodeHttpServer): void {\n  if (!rawServer || typeof rawServer.on !== \"function\" || drainStates.has(rawServer)) return;\n\n  const state: DrainState = { inFlight: new Set(), draining: false };\n\n  drainStates.set(rawServer, state);\n\n  rawServer.on(\"request\", (_request, response: ServerResponse) => {\n    state.inFlight.add(response);\n\n    if (state.draining) retireAfterResponse(response);\n\n    response.once(\"close\", () => {\n      state.inFlight.delete(response);\n\n      // The socket becomes idle once Node finishes handling this response,\n      // which happens after the response's own `close` event.\n      if (state.draining) setImmediate(() => reapIdleConnections(rawServer));\n    });\n  });\n}\n\n/**\n * Begin a graceful drain on a server tracked by {@link trackConnectionsForDrain}:\n * every in-flight response closes its connection when it is done, and idle\n * keep-alive connections are closed now and whenever another one goes idle.\n * A server that is not tracked is left alone.\n *\n * @returns Whether the server was tracked (and is now draining).\n */\nexport function beginHttpDrain(rawServer: unknown): boolean {\n  if (!rawServer || typeof rawServer !== \"object\") return false;\n\n  const state = drainStates.get(rawServer);\n\n  if (!state) return false;\n\n  state.draining = true;\n\n  for (const response of state.inFlight) {\n    retireAfterResponse(response);\n  }\n\n  reapIdleConnections(rawServer as NodeHttpServer);\n\n  return true;\n}\n\n/**\n * Close a server, bounded by a timeout. Fastify's `close()` stops accepting new\n * requests (it answers 503 while closing) and drains the in-flight ones; this\n * wraps it so a single stuck request can't hang shutdown forever. When the\n * server's connections are tracked (the default `\"idle\"` mode), keep-alive\n * connections that go idle during the drain are closed too, so a finished\n * request does not hold the shutdown open.\n *\n * @returns `true` if the server drained cleanly, `false` if the timeout fired first.\n */\nexport async function closeServerWithTimeout(\n  server: ClosableServer,\n  timeoutMs: number,\n): Promise<boolean> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  beginHttpDrain(server.server);\n\n  const drained = server.close().then(() => true);\n\n  const timedOut = new Promise<boolean>((resolve) => {\n    timer = setTimeout(() => resolve(false), timeoutMs);\n  });\n\n  try {\n    return await Promise.race([drained, timedOut]);\n  } finally {\n    if (timer) {\n      clearTimeout(timer);\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"server.mjs","names":["createServer"],"sources":["../../../../../../../../packages/core/src/http/server.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport Fastify, { type FastifyServerOptions } from \"fastify\";\nimport type { Server as NodeHttpServer, ServerResponse } from \"node:http\";\nimport type {\n  Http2Server,\n  Http2SecureServer,\n  Http2ServerResponse,\n  ServerHttp2Session,\n} from \"node:http2\";\n\ntype DrainServer = NodeHttpServer | Http2Server | Http2SecureServer;\ntype DrainResponse = ServerResponse | Http2ServerResponse;\nimport { normalizeRequestPath } from \"../router/normalize-request-path\";\nimport type { HttpServerOptions } from \"./types\";\n\nexport type FastifyInstance = ReturnType<typeof Fastify>;\n\n// Instantiate Fastify server\nlet server: FastifyInstance | undefined = undefined;\n\n/** Fastify's accepted, non-null `trustProxy` configuration shape. */\ntype TrustProxy = NonNullable<FastifyServerOptions[\"trustProxy\"]>;\ntype TrustProxyPredicate = (address: string, hop: number) => boolean;\n\nfunction isTrustProxyPredicate(value: unknown): value is TrustProxyPredicate {\n  return typeof value === \"function\";\n}\n\nfunction isTrustProxyList(value: unknown): value is string[] {\n  return (\n    Array.isArray(value) &&\n    value.length > 0 &&\n    value.every((entry) => typeof entry === \"string\" && entry.trim().length > 0)\n  );\n}\n\nfunction resolveTrustProxy(value: unknown): TrustProxy {\n  if (value === undefined || value === null) return false;\n\n  if (typeof value === \"boolean\" || isTrustProxyPredicate(value)) return value;\n\n  if (typeof value === \"string\" && value.trim().length > 0) return value;\n\n  if (isTrustProxyList(value)) return value;\n\n  const received = Array.isArray(value) ? \"array\" : typeof value;\n\n  throw new TypeError(\n    \"Invalid http.trustProxy configuration: expected a boolean, a non-empty IP/CIDR string, \" +\n      `a non-empty string array, or a predicate function; received ${received}.`,\n  );\n}\n\nfunction normalizeRequestUrl(url: string): string {\n  const queryIndex = url.indexOf(\"?\");\n\n  if (queryIndex === -1) return normalizeRequestPath(url);\n\n  return normalizeRequestPath(url.slice(0, queryIndex)) + url.slice(queryIndex);\n}\n\nexport function startHttpServer(options?: HttpServerOptions): FastifyInstance {\n  // `config.set(key, undefined)` stores null rather than unsetting, so an app\n  // that clears a key is treated the same as an app that never configured it.\n  const trustProxy = resolveTrustProxy(config.get(\"http.trustProxy\", false));\n\n  const bodyLimit = config.get(\"http.bodyLimit\") ?? undefined;\n  const configuredRewriteUrl = options?.rewriteUrl;\n  const http2 = options?.http2 === true;\n  const requestedForceClose =\n    options?.forceCloseConnections ??\n    config.get(\"http.gracefulShutdown.forceCloseConnections\", http2 ? false : \"idle\");\n  // HTTP/2 has sessions rather than closeIdleConnections(); session tracking\n  // below supplies graceful draining even when Fastify cannot use idle mode.\n  const forceCloseConnections =\n    http2 && requestedForceClose === \"idle\" ? false : requestedForceClose;\n\n  // Keep the framework's established HTTP-compatible reply facade while\n  // accepting Fastify's HTTP/1 and HTTP/2 option overloads at this boundary.\n  const createServer = Fastify as (options: HttpServerOptions) => FastifyInstance;\n  server = createServer({\n    // `X-Forwarded-For` is client-settable and spoofable, and `request.ip` is\n    // what @fastify/rate-limit keys its buckets on — so trusting it by default\n    // makes rate limiting bypassable on any deployment NOT behind a proxy that\n    // strips the header. Apps behind such a proxy opt in explicitly.\n    //\n    // Validated shapes resolve exactly as Fastify does: `true`, a CIDR/IP list\n    // (string, comma-separated string or array), or a predicate.\n    trustProxy,\n    // No default: an app that configures nothing keeps Fastify's own 1MB limit\n    // rather than the historical 200GB, which silently removed the protection\n    // Fastify provides. Per-route caps go through `serverOptions.bodyLimit`;\n    // the `maxBodySize()` middleware runs AFTER parsing and cannot reject\n    // before the bytes are resident.\n    ...(bodyLimit !== undefined && { bodyLimit }),\n    // Close idle keep-alive connections on shutdown while letting in-flight\n    // requests finish — the basis for graceful draining. Override via\n    // `http.gracefulShutdown.forceCloseConnections`.\n    ...options,\n    forceCloseConnections,\n    // Fastify calls this before route matching in both production `scan()` and\n    // the development wildcard dispatcher. Compose an app-supplied rewrite\n    // first, then apply the one framework request-path normalizer so the two\n    // modes cannot disagree about a terminal slash.\n    rewriteUrl(request) {\n      const rewritten = configuredRewriteUrl\n        ? configuredRewriteUrl.call(this, request)\n        : (request.url ?? \"/\");\n\n      return normalizeRequestUrl(rewritten);\n    },\n  });\n\n  // `\"idle\"` promises that idle keep-alive connections close on shutdown. Fastify\n  // only reaps the ones idle at the moment close starts; a connection whose\n  // request finishes DURING the drain stays open and holds `close()` until\n  // the shutdown budget expires. Track responses so the drain can\n  // retire those connections as they go idle.\n  if (http2 || forceCloseConnections === \"idle\") {\n    trackConnectionsForDrain(server.server as DrainServer);\n  }\n\n  return server;\n}\n\n/**\n * Expose the server to be publicly accessible\n */\nexport function getHttpServer(): FastifyInstance {\n  return server;\n}\n\n/**\n * Minimal shape needed to close a server — lets {@link closeServerWithTimeout}\n * be unit-tested with a fake instead of a real Fastify instance.\n */\nexport type ClosableServer = {\n  close: () => Promise<unknown>;\n  /** The underlying Node server, when there is one (a Fastify instance's `.server`). */\n  server?: unknown;\n};\n\n/**\n * Per-server drain state: the responses currently in flight, and whether a\n * graceful shutdown has begun.\n */\ntype DrainState = {\n  inFlight: Set<DrainResponse>;\n  sessions: Set<ServerHttp2Session>;\n  draining: boolean;\n};\n\nconst drainStates = new WeakMap<object, DrainState>();\n\n/**\n * Mark a response so its connection closes once it is sent. Only possible\n * before the headers go out; a response that already streams its headers is\n * retired by {@link reapIdleConnections} after it finishes instead.\n */\nfunction retireAfterResponse(response: DrainResponse): void {\n  // HTTP/2 drains the session with GOAWAY; connection headers are forbidden.\n  if (\"stream\" in response) return;\n  if (response.headersSent || response.writableEnded) return;\n\n  response.setHeader(\"Connection\", \"close\");\n}\n\nfunction reapIdleConnections(rawServer: DrainServer): void {\n  if (\"closeIdleConnections\" in rawServer && typeof rawServer.closeIdleConnections === \"function\") {\n    rawServer.closeIdleConnections();\n  }\n}\n\n/**\n * Track in-flight responses on a Node HTTP server so a graceful drain can\n * close keep-alive connections that become idle AFTER `close()` started.\n *\n * Node's `server.close()` (and Fastify's `forceCloseConnections: \"idle\"`)\n * closes only the connections idle at that moment. A request in flight when\n * shutdown begins finishes its response, the client keeps the connection\n * alive, and `close()` waits on it until the shutdown budget runs out. Active\n * responses are never cut short: each one is told to close its connection\n * when it is done (`Connection: close`), and every connection is reaped as\n * soon as its response has finished.\n */\nexport function trackConnectionsForDrain(rawServer: DrainServer): void {\n  if (!rawServer || typeof rawServer.on !== \"function\" || drainStates.has(rawServer)) return;\n\n  const state: DrainState = { inFlight: new Set(), sessions: new Set(), draining: false };\n\n  drainStates.set(rawServer, state);\n\n  rawServer.on(\"session\", (session: ServerHttp2Session) => {\n    state.sessions.add(session);\n    session.once(\"close\", () => state.sessions.delete(session));\n    if (state.draining) session.close();\n  });\n\n  rawServer.on(\"request\", (_request: unknown, response: DrainResponse) => {\n    state.inFlight.add(response);\n\n    if (state.draining) retireAfterResponse(response);\n\n    response.once(\"close\", () => {\n      state.inFlight.delete(response);\n\n      // The socket becomes idle once Node finishes handling this response,\n      // which happens after the response's own `close` event.\n      if (state.draining) setImmediate(() => reapIdleConnections(rawServer));\n    });\n  });\n}\n\n/**\n * Begin a graceful drain on a server tracked by {@link trackConnectionsForDrain}:\n * every in-flight response closes its connection when it is done, and idle\n * keep-alive connections are closed now and whenever another one goes idle.\n * A server that is not tracked is left alone.\n *\n * @returns Whether the server was tracked (and is now draining).\n */\nexport function beginHttpDrain(rawServer: unknown): boolean {\n  if (!rawServer || typeof rawServer !== \"object\") return false;\n\n  const state = drainStates.get(rawServer);\n\n  if (!state) return false;\n\n  state.draining = true;\n\n  for (const response of state.inFlight) {\n    retireAfterResponse(response);\n  }\n\n  // close() sends GOAWAY and waits for active streams before closing the socket.\n  for (const session of state.sessions) session.close();\n\n  reapIdleConnections(rawServer as DrainServer);\n\n  return true;\n}\n\n/**\n * Close a server, bounded by a timeout. Fastify's `close()` stops accepting new\n * requests (it answers 503 while closing) and drains the in-flight ones; this\n * wraps it so a single stuck request can't hang shutdown forever. When the\n * server's connections are tracked (the default `\"idle\"` mode), keep-alive\n * connections that go idle during the drain are closed too, so a finished\n * request does not hold the shutdown open.\n *\n * @returns `true` if the server drained cleanly, `false` if the timeout fired first.\n */\nexport async function closeServerWithTimeout(\n  server: ClosableServer,\n  timeoutMs: number,\n): Promise<boolean> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  beginHttpDrain(server.server);\n\n  const drained = server.close().then(() => true);\n\n  const timedOut = new Promise<boolean>((resolve) => {\n    timer = setTimeout(() => resolve(false), timeoutMs);\n  });\n\n  try {\n    return await Promise.race([drained, timedOut]);\n  } finally {\n    if (timer) {\n      clearTimeout(timer);\n    }\n  }\n}\n"],"mappings":"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"}

package/esm/http/stream-transport.mjs

@@ -6,7 +6,7 @@ function createStreamTransport(raw, options) {
 	let disconnected = false;
 	const disconnectHandlers = [];
 	const disconnectController = new AbortController();
-	raw.on("close", () => {
+	const disconnect = () => {
 		if (closed) return;
 		closed = true;
 		disconnected = true;
@@ -17,7 +17,8 @@ function createStreamTransport(raw, options) {
 		} catch (error) {
 			log.error("http", "stream", error, { source: "onDisconnect handler" });
 		}
-	});
+	};
+	raw.on("close", disconnect);
 	return {
 		signal: disconnectController.signal,
 		get closed() {
@@ -32,6 +33,7 @@ function createStreamTransport(raw, options) {
 		finish() {
 			closed = true;
 		},
+		disconnect,
 		onDisconnect(handler) {
 			disconnectHandlers.push(handler);
 		},

package/esm/http/stream-transport.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"stream-transport.mjs","names":[],"sources":["../../../../../../../../packages/core/src/http/stream-transport.ts"],"sourcesContent":["import type { ServerResponse } from \"node:http\";\nimport { log } from \"@warlock.js/logger\";\n\n/**\n * Shared transport bookkeeping for the long-lived responses\n * (`response.sse()` and `response.stream()`): client-disconnect detection,\n * an `AbortSignal` for the work feeding the stream, and backpressure (WR-006).\n */\nexport type StreamTransport = {\n  /** Aborted when the client disconnects (not when the stream is ended). */\n  readonly signal: AbortSignal;\n  /** `true` once the stream was ended or the client disconnected. */\n  readonly closed: boolean;\n  /** `true` once the client disconnected before the stream was ended. */\n  readonly disconnected: boolean;\n  /** Whether the transport holds more than its high-water mark. */\n  readonly backpressured: boolean;\n  /** Mark the stream as ended by the server. */\n  finish(): void;\n  /** Call `handler` when the client disconnects. */\n  onDisconnect(handler: () => void): void;\n  /**\n   * Resolve once the transport has flushed what it buffered: `true` when the\n   * client can take more, `false` when the stream ended or the client left.\n   */\n  waitForDrain(): Promise<boolean>;\n};\n\nexport function createStreamTransport(\n  raw: ServerResponse,\n  options: { disconnectMessage: string; onClientDisconnected?: () => void },\n): StreamTransport {\n  let closed = false;\n  let disconnected = false;\n  const disconnectHandlers: Array<() => void> = [];\n  const disconnectController = new AbortController();\n\n  // Without this, background jobs keep writing to a dead socket after the\n  // client drops. `close` also fires after a normal `end()`; `closed` is\n  // already set by then.\n  raw.on(\"close\", () => {\n    if (closed) return;\n\n    closed = true;\n    disconnected = true;\n    options.onClientDisconnected?.();\n    disconnectController.abort(new DOMException(options.disconnectMessage, \"AbortError\"));\n\n    // Each handler is isolated: this runs inside the socket's `close`\n    // listener, so a throwing handler would otherwise become an uncaught\n    // exception (taking the process down) and skip the handlers after it.\n    for (const handler of disconnectHandlers) {\n      try {\n        handler();\n      } catch (error) {\n        log.error(\"http\", \"stream\", error as Error, { source: \"onDisconnect handler\" });\n      }\n    }\n  });\n\n  return {\n    signal: disconnectController.signal,\n\n    get closed() {\n      return closed;\n    },\n\n    get disconnected() {\n      return disconnected;\n    },\n\n    get backpressured() {\n      return !closed && raw.writableNeedDrain;\n    },\n\n    finish() {\n      closed = true;\n    },\n\n    onDisconnect(handler) {\n      disconnectHandlers.push(handler);\n    },\n\n    waitForDrain() {\n      if (closed) return Promise.resolve(false);\n\n      if (!raw.writableNeedDrain) return Promise.resolve(true);\n\n      return new Promise<boolean>((resolve) => {\n        const settle = (drained: boolean) => {\n          raw.off(\"drain\", onDrain);\n          raw.off(\"close\", onClose);\n          resolve(drained);\n        };\n        const onDrain = () => settle(!closed);\n        const onClose = () => settle(false);\n\n        raw.once(\"drain\", onDrain);\n        raw.once(\"close\", onClose);\n      });\n    },\n  };\n}\n\n/**\n * The most recent `limit` items, for logging/debugging a stream after it\n * ended. `limit` 0 (or missing/NaN) keeps nothing, so a long-lived stream\n * does not grow with its own history.\n */\nexport function createRetainedTail<T>(limit: number | undefined): {\n  push(item: T): void;\n  items: T[];\n} {\n  const max = limit === undefined || Number.isNaN(limit) ? 0 : Math.max(0, Math.floor(limit));\n  const items: T[] = [];\n\n  return {\n    items,\n    push(item) {\n      if (max === 0) return;\n\n      items.push(item);\n\n      if (items.length > max) items.shift();\n    },\n  };\n}\n"],"mappings":";;;AA4BA,SAAgB,sBACd,KACA,SACiB;CACjB,IAAI,SAAS;CACb,IAAI,eAAe;CACnB,MAAM,qBAAwC,CAAC;CAC/C,MAAM,uBAAuB,IAAI,gBAAgB;CAKjD,IAAI,GAAG,eAAe;EACpB,IAAI,QAAQ;EAEZ,SAAS;EACT,eAAe;EACf,QAAQ,uBAAuB;EAC/B,qBAAqB,MAAM,IAAI,aAAa,QAAQ,mBAAmB,YAAY,CAAC;EAKpF,KAAK,MAAM,WAAW,oBACpB,IAAI;GACF,QAAQ;EACV,SAAS,OAAO;GACd,IAAI,MAAM,QAAQ,UAAU,OAAgB,EAAE,QAAQ,uBAAuB,CAAC;EAChF;CAEJ,CAAC;CAED,OAAO;EACL,QAAQ,qBAAqB;EAE7B,IAAI,SAAS;GACX,OAAO;EACT;EAEA,IAAI,eAAe;GACjB,OAAO;EACT;EAEA,IAAI,gBAAgB;GAClB,OAAO,CAAC,UAAU,IAAI;EACxB;EAEA,SAAS;GACP,SAAS;EACX;EAEA,aAAa,SAAS;GACpB,mBAAmB,KAAK,OAAO;EACjC;EAEA,eAAe;GACb,IAAI,QAAQ,OAAO,QAAQ,QAAQ,KAAK;GAExC,IAAI,CAAC,IAAI,mBAAmB,OAAO,QAAQ,QAAQ,IAAI;GAEvD,OAAO,IAAI,SAAkB,YAAY;IACvC,MAAM,UAAU,YAAqB;KACnC,IAAI,IAAI,SAAS,OAAO;KACxB,IAAI,IAAI,SAAS,OAAO;KACxB,QAAQ,OAAO;IACjB;IACA,MAAM,gBAAgB,OAAO,CAAC,MAAM;IACpC,MAAM,gBAAgB,OAAO,KAAK;IAElC,IAAI,KAAK,SAAS,OAAO;IACzB,IAAI,KAAK,SAAS,OAAO;GAC3B,CAAC;EACH;CACF;AACF;;;;;;AAOA,SAAgB,mBAAsB,OAGpC;CACA,MAAM,MAAM,UAAU,UAAa,OAAO,MAAM,KAAK,IAAI,IAAI,KAAK,IAAI,GAAG,KAAK,MAAM,KAAK,CAAC;CAC1F,MAAM,QAAa,CAAC;CAEpB,OAAO;EACL;EACA,KAAK,MAAM;GACT,IAAI,QAAQ,GAAG;GAEf,MAAM,KAAK,IAAI;GAEf,IAAI,MAAM,SAAS,KAAK,MAAM,MAAM;EACtC;CACF;AACF"}
+{"version":3,"file":"stream-transport.mjs","names":[],"sources":["../../../../../../../../packages/core/src/http/stream-transport.ts"],"sourcesContent":["import type { ServerResponse } from \"node:http\";\nimport { log } from \"@warlock.js/logger\";\n\n/**\n * Shared transport bookkeeping for the long-lived responses\n * (`response.sse()` and `response.stream()`): client-disconnect detection,\n * an `AbortSignal` for the work feeding the stream, and backpressure.\n */\nexport type StreamTransport = {\n  /** Aborted when the client disconnects (not when the stream is ended). */\n  readonly signal: AbortSignal;\n  /** `true` once the stream was ended or the client disconnected. */\n  readonly closed: boolean;\n  /** `true` once the client disconnected before the stream was ended. */\n  readonly disconnected: boolean;\n  /** Whether the transport holds more than its high-water mark. */\n  readonly backpressured: boolean;\n  /** Mark the stream as ended by the server. */\n  finish(): void;\n  /** Abort the producer and notify disconnect handlers when a slow client is disconnected. */\n  disconnect(): void;\n  /** Call `handler` when the client disconnects. */\n  onDisconnect(handler: () => void): void;\n  /**\n   * Resolve once the transport has flushed what it buffered: `true` when the\n   * client can take more, `false` when the stream ended or the client left.\n   */\n  waitForDrain(): Promise<boolean>;\n};\n\nexport function createStreamTransport(\n  raw: ServerResponse,\n  options: { disconnectMessage: string; onClientDisconnected?: () => void },\n): StreamTransport {\n  let closed = false;\n  let disconnected = false;\n  const disconnectHandlers: Array<() => void> = [];\n  const disconnectController = new AbortController();\n\n  // Without this, background jobs keep writing to a dead socket after the\n  // client drops. `close` also fires after a normal `end()`; `closed` is\n  // already set by then.\n  const disconnect = () => {\n    if (closed) return;\n\n    closed = true;\n    disconnected = true;\n    options.onClientDisconnected?.();\n    disconnectController.abort(new DOMException(options.disconnectMessage, \"AbortError\"));\n\n    // Each handler is isolated: this runs inside the socket's `close`\n    // listener, so a throwing handler would otherwise become an uncaught\n    // exception (taking the process down) and skip the handlers after it.\n    for (const handler of disconnectHandlers) {\n      try {\n        handler();\n      } catch (error) {\n        log.error(\"http\", \"stream\", error as Error, { source: \"onDisconnect handler\" });\n      }\n    }\n  };\n  raw.on(\"close\", disconnect);\n\n  return {\n    signal: disconnectController.signal,\n\n    get closed() {\n      return closed;\n    },\n\n    get disconnected() {\n      return disconnected;\n    },\n\n    get backpressured() {\n      return !closed && raw.writableNeedDrain;\n    },\n\n    finish() {\n      closed = true;\n    },\n\n    disconnect,\n\n    onDisconnect(handler) {\n      disconnectHandlers.push(handler);\n    },\n\n    waitForDrain() {\n      if (closed) return Promise.resolve(false);\n\n      if (!raw.writableNeedDrain) return Promise.resolve(true);\n\n      return new Promise<boolean>((resolve) => {\n        const settle = (drained: boolean) => {\n          raw.off(\"drain\", onDrain);\n          raw.off(\"close\", onClose);\n          resolve(drained);\n        };\n        const onDrain = () => settle(!closed);\n        const onClose = () => settle(false);\n\n        raw.once(\"drain\", onDrain);\n        raw.once(\"close\", onClose);\n      });\n    },\n  };\n}\n\n/**\n * The most recent `limit` items, for logging/debugging a stream after it\n * ended. `limit` 0 (or missing/NaN) keeps nothing, so a long-lived stream\n * does not grow with its own history.\n */\nexport function createRetainedTail<T>(limit: number | undefined): {\n  push(item: T): void;\n  items: T[];\n} {\n  const max = limit === undefined || Number.isNaN(limit) ? 0 : Math.max(0, Math.floor(limit));\n  const items: T[] = [];\n\n  return {\n    items,\n    push(item) {\n      if (max === 0) return;\n\n      items.push(item);\n\n      if (items.length > max) items.shift();\n    },\n  };\n}\n"],"mappings":";;;AA8BA,SAAgB,sBACd,KACA,SACiB;CACjB,IAAI,SAAS;CACb,IAAI,eAAe;CACnB,MAAM,qBAAwC,CAAC;CAC/C,MAAM,uBAAuB,IAAI,gBAAgB;CAKjD,MAAM,mBAAmB;EACvB,IAAI,QAAQ;EAEZ,SAAS;EACT,eAAe;EACf,QAAQ,uBAAuB;EAC/B,qBAAqB,MAAM,IAAI,aAAa,QAAQ,mBAAmB,YAAY,CAAC;EAKpF,KAAK,MAAM,WAAW,oBACpB,IAAI;GACF,QAAQ;EACV,SAAS,OAAO;GACd,IAAI,MAAM,QAAQ,UAAU,OAAgB,EAAE,QAAQ,uBAAuB,CAAC;EAChF;CAEJ;CACA,IAAI,GAAG,SAAS,UAAU;CAE1B,OAAO;EACL,QAAQ,qBAAqB;EAE7B,IAAI,SAAS;GACX,OAAO;EACT;EAEA,IAAI,eAAe;GACjB,OAAO;EACT;EAEA,IAAI,gBAAgB;GAClB,OAAO,CAAC,UAAU,IAAI;EACxB;EAEA,SAAS;GACP,SAAS;EACX;EAEA;EAEA,aAAa,SAAS;GACpB,mBAAmB,KAAK,OAAO;EACjC;EAEA,eAAe;GACb,IAAI,QAAQ,OAAO,QAAQ,QAAQ,KAAK;GAExC,IAAI,CAAC,IAAI,mBAAmB,OAAO,QAAQ,QAAQ,IAAI;GAEvD,OAAO,IAAI,SAAkB,YAAY;IACvC,MAAM,UAAU,YAAqB;KACnC,IAAI,IAAI,SAAS,OAAO;KACxB,IAAI,IAAI,SAAS,OAAO;KACxB,QAAQ,OAAO;IACjB;IACA,MAAM,gBAAgB,OAAO,CAAC,MAAM;IACpC,MAAM,gBAAgB,OAAO,KAAK;IAElC,IAAI,KAAK,SAAS,OAAO;IACzB,IAAI,KAAK,SAAS,OAAO;GAC3B,CAAC;EACH;CACF;AACF;;;;;;AAOA,SAAgB,mBAAsB,OAGpC;CACA,MAAM,MAAM,UAAU,UAAa,OAAO,MAAM,KAAK,IAAI,IAAI,KAAK,IAAI,GAAG,KAAK,MAAM,KAAK,CAAC;CAC1F,MAAM,QAAa,CAAC;CAEpB,OAAO;EACL;EACA,KAAK,MAAM;GACT,IAAI,QAAQ,GAAG;GAEf,MAAM,KAAK,IAAI;GAEf,IAAI,MAAM,SAAS,KAAK,MAAM,MAAM;EACtC;CACF;AACF"}

package/esm/http/types.d.mts

@@ -1,4 +1,5 @@
 import { HttpRateLimitConfig } from "./build-rate-limit-options.mjs";
+import { StreamQueueOptions } from "./bounded-stream-queue.mjs";
 import { HttpLoggingConfig } from "./request-log-snapshot.mjs";
 import { Response } from "./response.mjs";
 import { CspConfig } from "./csp.mjs";
@@ -9,6 +10,7 @@ import { FastifyHttpOptions } from "fastify";
 import { CookieSerializeOptions } from "@fastify/cookie";
 import { FastifyCorsOptions } from "@fastify/cors";
 import { Server } from "node:http";
+import { SecureServerOptions } from "node:http2";
 import React from "react";
 
 //#region ../../packages/core/src/http/types.d.ts
@@ -188,7 +190,11 @@ interface PartialMiddleware {
  * `gracefulShutdown.forceCloseConnections`) have their own `http.*` keys;
  * setting them here as well overrides those keys.
  */
-type HttpServerOptions = FastifyHttpOptions<Server>;
+type HttpServerOptions = Omit<FastifyHttpOptions<Server>, "http2"> & {
+  /** Enable HTTP/2 while retaining the framework's HTTP-compatible reply API. */http2?: boolean;
+  https?: SecureServerOptions;
+  http2SessionTimeout?: number;
+};
 /**
  * Http Configurations list
  */
@@ -228,6 +234,14 @@ interface HttpConfigurations {
    * handling. See {@link HttpErrorMapper}.
    */
   errorMapper?: HttpErrorMapper;
+  /**
+   * In `warlock dev`, warn once per route about POST/PUT/PATCH/DELETE routes
+   * that have no auth middleware and no `public: true`. Development only;
+   * production never checks. Set `false` to silence the warning entirely.
+   *
+   * @default true
+   */
+  warnUnguardedRoutes?: boolean;
   /**
    * Server port
    */
@@ -453,6 +467,13 @@ interface HttpConfigurations {
      * @default "/ready"
      */
     readinessPath?: string;
+    /**
+     * Include built-in liveness/readiness probes in the global rate-limit policy.
+     * Leave false so client traffic cannot exhaust infrastructure probe quotas.
+     *
+     * @default false
+     */
+    rateLimit?: boolean;
   };
   /**
    * Host
@@ -485,7 +506,8 @@ interface HttpConfigurations {
 /**
  * Options for `response.stream()`.
  */
-type ResponseStreamOptions = {
+type ResponseStreamOptions = StreamQueueOptions & {
+  /** Application/cache headers override defaults before flushing; framing and connection headers are ignored. */headers?: Record<string, string>;
   /**
    * How many of the most recent chunks (from `send()`, `write()` and
    * `render()`) to keep on `response.body` after `end()`, for logging and
@@ -503,11 +525,13 @@ type ResponseStreamController = {
    * down to the client's pace instead of buffering. A silent no-op after the
    * client disconnected; throws after `end()`.
    */
-  send: (data: string | Uint8Array) => void;
+  send: (data: string | Uint8Array) => void; /** Bounded synchronous write; false when closed or overflow rejects this chunk. */
+  enqueue: (data: string | Uint8Array) => boolean;
   /**
    * Send data and wait until the transport can take more. Resolves `true`
    * when it can, `false` when the stream ended or the client disconnected —
-   * stop producing then.
+   * stop producing then. In drop mode, true means the stream is ready to continue;
+   * inspect dropped to detect rejected output and schedule a resync.
    */
   write: (data: string | Uint8Array) => Promise<boolean>;
   /**
@@ -536,7 +560,8 @@ type ResponseStreamController = {
   /**
    * Whether the transport is currently holding more than its high-water mark.
    */
-  backpressured: boolean;
+  backpressured: boolean; /** Chunks/events/comments rejected by onOverflow: "drop", including send/write/render paths. */
+  readonly dropped: number;
   /**
    * Detect whether stream is ended (by `end()` or a client disconnect)
    */
@@ -545,7 +570,8 @@ type ResponseStreamController = {
 /**
  * Options for `response.sse()`.
  */
-type ResponseSSEOptions = {
+type ResponseSSEOptions = StreamQueueOptions & {
+  /** Application/cache headers override defaults before flushing; framing and connection headers are ignored. */headers?: Record<string, string>;
   /**
    * How many of the most recent events to keep on `response.body` after
    * `end()`, for logging and debugging. Sent events are otherwise not kept,
@@ -555,6 +581,10 @@ type ResponseSSEOptions = {
    */
   retainEvents?: number;
 };
+/** Wire serialization for one SSE event. Raw strings are split into safe data lines. */
+type ResponseSSEMessageOptions = {
+  raw?: boolean;
+};
 type ResponseSSEController = {
   /**
    * Send an SSE event to the client. Does not wait for the client; for
@@ -564,13 +594,15 @@ type ResponseSSEController = {
    * @param data - Event data (will be JSON stringified)
    * @param id - Optional event ID for client-side Last-Event-ID tracking
    */
-  send: (event: string, data: any, id?: string) => ResponseSSEController;
+  send: (event: string | undefined, data: any, id?: string, options?: ResponseSSEMessageOptions) => ResponseSSEController; /** Bounded synchronous event; undefined event omits the event field. */
+  enqueue: (event: string | undefined, data: unknown, id?: string, options?: ResponseSSEMessageOptions) => boolean;
   /**
    * Send an SSE event and wait until the transport can take more.
    * Resolves `true` when it can, `false` when the stream ended or the client
-   * disconnected — stop producing then.
+   * disconnected — stop producing then. In drop mode, true means ready to continue;
+   * inspect dropped to detect rejected output and schedule a resync.
    */
-  write: (event: string, data: any, id?: string) => Promise<boolean>;
+  write: (event: string | undefined, data: any, id?: string, options?: ResponseSSEMessageOptions) => Promise<boolean>;
   /**
    * Wait until output buffered for the client has been flushed. Resolves
    * `true` immediately when nothing is backed up, `false` when the stream
@@ -585,7 +617,8 @@ type ResponseSSEController = {
   /**
    * Whether the transport is currently holding more than its high-water mark.
    */
-  backpressured: boolean;
+  backpressured: boolean; /** Chunks/events/comments rejected by onOverflow: "drop", including send/write/render paths. */
+  readonly dropped: number;
   /**
    * Send a comment to keep the connection alive (invisible to client)
    */
@@ -605,5 +638,5 @@ type ResponseSSEController = {
   ended: boolean;
 };
 //#endregion
-export { DecodedAccessToken, HttpConfigurations, HttpServerOptions, PartialMiddleware, RequestEvent, RequestLocals, ResponseEvent, ResponseSSEController, ResponseSSEOptions, ResponseStreamController, ResponseStreamOptions, ReturnedResponse };
+export { DecodedAccessToken, HttpConfigurations, HttpServerOptions, PartialMiddleware, RequestEvent, RequestLocals, ResponseEvent, ResponseSSEController, ResponseSSEMessageOptions, ResponseSSEOptions, ResponseStreamController, ResponseStreamOptions, ReturnedResponse };
 //# sourceMappingURL=types.d.mts.map

package/esm/http/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/types.ts"],"mappings":"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"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/types.ts"],"mappings":"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"}

package/esm/http/uploads/generate-image-variant.mjs

@@ -1,5 +1,5 @@
-import path from "node:path";
 import { randomBytes } from "node:crypto";
+import path from "node:path";
 import fs from "node:fs/promises";
 
 //#region ../../packages/core/src/http/uploads/generate-image-variant.ts

package/esm/http/uploads/generate-image-variants.d.mts

@@ -1,3 +1,4 @@
+import { StorageDriverName } from "../../storage/types.mjs";
 import { GeneratedImageDescriptor } from "./image-variant-types.mjs";
 
 //#region ../../packages/core/src/http/uploads/generate-image-variants.d.ts
@@ -9,7 +10,9 @@ type GenerateImageVariantsOptions = {
    * Limit generation to these variant names, instead of every variant in
    * `uploads.images.variants`.
    */
-  variants?: readonly string[];
+  variants?: readonly string[]; /** Disk holding the source; defaults to the active disk. */
+  disk?: StorageDriverName; /** Route prefix serving variants of this disk (and originals for local disks). Default /uploads. */
+  urlPrefix?: string;
 };
 /**
  * Render every configured variant of one uploaded image, right after it is
@@ -25,15 +28,15 @@ type GenerateImageVariantsOptions = {
  * The returned descriptor is plain JSON, safe to store next to the record
  * that owns the image, or to carry through loader data. On local storage the
  * `url`/`urls` already point at `uploadedFileController`; an app serving
- * uploads from object storage or a CDN should not proxy the remote files
- * through this route at all — store the descriptor once generation runs
- * against the same bucket the CDN serves from, or resolve its URLs through a
- * custom `ImageLoader` on the client instead.
+ * uploads from object storage use the driver URL for the original, and
+ * `options.urlPrefix` for the route serving locally cached derivatives.
+ * Ingest downloads a remote source once for all variants and formats.
+ * On-demand cache hits use ETag metadata; sources without ETags are hashed.
  *
  * @param relativePath - path of the saved upload, relative to the storage root
  * @param options.variants - limit generation to these variant names
- * @throws ImageVariantsConfigError when there is no local storage root, or
- * `uploads.images` is not configured — both are server misconfiguration, not
+ * @throws ImageVariantsConfigError when `uploads.images` is not
+ * configured — this is server misconfiguration, not
  * a bad request
  * @throws HttpError(400) when a name in `options.variants` is not declared in
  * `uploads.images.variants`

package/esm/http/uploads/generate-image-variants.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-image-variants.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/generate-image-variants.ts"],"mappings":";;;;;AAiCA;KAAY,4BAAA;;;AAKF;AA8EV;EA9EE,QAAQ;AAAA;;;;;;;;;;;;AAiFyB;;;;;;;;;;;;;;;;;;;;;iBAHb,qBAAA,CACpB,YAAA,UACA,OAAA,GAAS,4BAAA,GACR,OAAA,CAAQ,wBAAA"}
+{"version":3,"file":"generate-image-variants.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/generate-image-variants.ts"],"mappings":";;;;;;AAqCA;KAAY,4BAAA;;;;;EAKV,QAAA,sBAMA;EAHA,IAAA,GAAO,iBAAiB,EAGf;EAAT,SAAA;AAAA;;;;;;;;;;;;;AAuEiC;;;;;;;;;;;;;;;;;;;;iBAHb,qBAAA,CACpB,YAAA,UACA,OAAA,GAAS,4BAAA,GACR,OAAA,CAAQ,wBAAA"}

package/esm/http/uploads/generate-image-variants.mjs

@@ -1,28 +1,22 @@
 import { HttpError } from "../errors/errors.mjs";
+import { ImageVariantsConfigError } from "./image-variants-config-error.mjs";
 import { uploadsConfig } from "../uploads-config.mjs";
 import { variantCacheKey, variantCachePath, variantGenerationTag, variantSourceDirectory, variantSourceKey } from "./variant-cache-key.mjs";
 import { pruneStaleVariantGenerationsIfCurrent, retryOnVanishedDirectory, warnIfVariantCacheIsPublic } from "./image-variant-cache.mjs";
-import { storage } from "../../storage/storage.mjs";
-import "../../storage/index.mjs";
 import { Image } from "../../image/image.mjs";
 import "../../image/index.mjs";
-import { generateImageVariant } from "./generate-image-variant.mjs";
-import { ImageVariantsConfigError } from "./image-variants-config-error.mjs";
+import { localDiskRoot } from "./local-disk-root.mjs";
 import { loadVariantSource } from "./load-variant-source.mjs";
+import { remoteVariantDisk, remoteVariantSource } from "./remote-variant-source.mjs";
+import { generateImageVariant } from "./generate-image-variant.mjs";
 import { resolveImageVariantsConfig } from "./resolve-image-variants-config.mjs";
-import { resolveVariantCandidate } from "./resolve-variant-candidate.mjs";
+import { freshImageVariant, scheduleImageVariantCacheTrim } from "./trim-image-variant-cache.mjs";
 import { variantGenerations } from "./variant-generations.mjs";
+import { renderRemoteImageVariant } from "./resolve-remote-image-variant.mjs";
+import { resolveVariantCandidate } from "./resolve-variant-candidate.mjs";
 import fs from "node:fs/promises";
 
 //#region ../../packages/core/src/http/uploads/generate-image-variants.ts
-async function exists(target) {
-	try {
-		await fs.access(target);
-		return true;
-	} catch {
-		return false;
-	}
-}
 function encodeUploadsPath(relativePath) {
 	return relativePath.split("/").map(encodeURIComponent).join("/");
 }
@@ -58,15 +52,15 @@ function outputFormatsFor(sourceFormat, configuredFormats) {
 * The returned descriptor is plain JSON, safe to store next to the record
 * that owns the image, or to carry through loader data. On local storage the
 * `url`/`urls` already point at `uploadedFileController`; an app serving
-* uploads from object storage or a CDN should not proxy the remote files
-* through this route at all — store the descriptor once generation runs
-* against the same bucket the CDN serves from, or resolve its URLs through a
-* custom `ImageLoader` on the client instead.
+* uploads from object storage use the driver URL for the original, and
+* `options.urlPrefix` for the route serving locally cached derivatives.
+* Ingest downloads a remote source once for all variants and formats.
+* On-demand cache hits use ETag metadata; sources without ETags are hashed.
 *
 * @param relativePath - path of the saved upload, relative to the storage root
 * @param options.variants - limit generation to these variant names
-* @throws ImageVariantsConfigError when there is no local storage root, or
-* `uploads.images` is not configured — both are server misconfiguration, not
+* @throws ImageVariantsConfigError when `uploads.images` is not
+* configured — this is server misconfiguration, not
 * a bad request
 * @throws HttpError(400) when a name in `options.variants` is not declared in
 * `uploads.images.variants`
@@ -77,8 +71,8 @@ function outputFormatsFor(sourceFormat, configuredFormats) {
 * @throws HttpError(415) when the source is not jpeg, png, webp or avif
 */
 async function generateImageVariants(relativePath, options = {}) {
-	const storageRoot = storage.root();
-	if (!storageRoot || storageRoot === ".") throw new ImageVariantsConfigError("generateImageVariants needs a local storage driver with a root.");
+	const storageRoot = localDiskRoot(options.disk);
+	if (!storageRoot) return generateRemoteImageVariants(relativePath, options);
 	const images = resolveImageVariantsConfig(uploadsConfig("images"), storageRoot);
 	if (!images) throw new ImageVariantsConfigError("uploads.images is not configured.");
 	const names = options.variants ?? Object.keys(images.variants);
@@ -93,7 +87,7 @@ async function generateImageVariants(relativePath, options = {}) {
 	});
 	const { width: sourceWidth, height: sourceHeight } = await image.metadata();
 	warnIfVariantCacheIsPublic(images.cacheDirectory);
-	const src = `/uploads/${encodeUploadsPath(source.relativePath)}`;
+	const src = `${(options.urlPrefix ?? "/uploads").replace(/\/$/, "")}/${encodeUploadsPath(source.relativePath)}`;
 	const variants = {};
 	for (const name of names) {
 		const variant = images.variants[name];
@@ -114,14 +108,15 @@ async function generateImageVariants(relativePath, options = {}) {
 				sourceKey,
 				generation
 			}, hash, format);
-			if (!await exists(target)) await variantGenerations.run(target, async () => {
-				if (await exists(target)) return;
+			if (!await freshImageVariant(target, images.maxCacheAge)) await variantGenerations.run(target, async () => {
+				if (await freshImageVariant(target, images.maxCacheAge)) return;
 				await retryOnVanishedDirectory(() => generateImageVariant({
 					image: image.clone(),
 					variant,
 					format,
 					targetPath: target
 				}));
+				scheduleImageVariantCacheTrim(images, target);
 				await pruneStaleVariantGenerationsIfCurrent(source.absolutePath, variantSourceDirectory(images.cacheDirectory, sourceKey), generation);
 			});
 			if (dimensions === void 0) dimensions = await readDerivativeDimensions(target);
@@ -143,6 +138,48 @@ async function generateImageVariants(relativePath, options = {}) {
 		...images.formats.length > 0 ? { formats: images.formats } : {}
 	};
 }
+async function generateRemoteImageVariants(relativePath, options) {
+	const disk = remoteVariantDisk(options.disk);
+	const images = resolveImageVariantsConfig(uploadsConfig("images"), disk.cacheRoot);
+	if (!images) throw new ImageVariantsConfigError("uploads.images is not configured.");
+	const names = options.variants ?? Object.keys(images.variants);
+	for (const name of names) if (!Object.prototype.hasOwnProperty.call(images.variants, name)) throw new HttpError(400, `Unknown variant "${name}".`);
+	const source = await remoteVariantSource(relativePath, disk, images);
+	if (!source) throw new HttpError(404, "File Not Found");
+	try {
+		const { image, sourceFormat } = await source.load();
+		const { width, height } = await image.metadata();
+		const variantSrc = `${(options.urlPrefix ?? "/uploads").replace(/\/$/, "")}/${encodeUploadsPath(source.relativePath)}`;
+		const variants = {};
+		for (const name of names) {
+			let dimensions;
+			for (const format of outputFormatsFor(sourceFormat, images.formats)) {
+				const resolved = await renderRemoteImageVariant({
+					path: relativePath,
+					variant: name,
+					...format === sourceFormat ? {} : { format }
+				}, disk, images, source);
+				if (!resolved) throw new HttpError(404, "File Not Found");
+				dimensions ??= await readDerivativeDimensions(resolved.absolutePath);
+			}
+			variants[name] = {
+				width: dimensions?.width ?? 0,
+				height: dimensions?.height ?? 0,
+				url: variantUrl(variantSrc, name),
+				...images.formats.length ? { urls: Object.fromEntries(images.formats.map((format) => [format, variantUrl(variantSrc, name, format)])) } : {}
+			};
+		}
+		return {
+			src: disk.driver.url(source.relativePath),
+			width: width ?? 0,
+			height: height ?? 0,
+			variants,
+			...images.formats.length ? { formats: images.formats } : {}
+		};
+	} finally {
+		source.release();
+	}
+}
 
 //#endregion
 export { generateImageVariants };

package/esm/http/uploads/generate-image-variants.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"generate-image-variants.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/generate-image-variants.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport { Image } from \"../../image\";\nimport { storage } from \"../../storage\";\nimport { HttpError } from \"../errors\";\nimport { uploadsConfig } from \"../uploads-config\";\nimport type { ImageVariantOutputFormat } from \"../uploads-types\";\nimport { generateImageVariant } from \"./generate-image-variant\";\nimport {\n  pruneStaleVariantGenerationsIfCurrent,\n  retryOnVanishedDirectory,\n  warnIfVariantCacheIsPublic,\n} from \"./image-variant-cache\";\nimport { ImageVariantsConfigError } from \"./image-variants-config-error\";\nimport type {\n  GeneratedImageDescriptor,\n  GeneratedImageVariant,\n  VariantOutputFormat,\n} from \"./image-variant-types\";\nimport { loadVariantSource } from \"./load-variant-source\";\nimport { resolveImageVariantsConfig } from \"./resolve-image-variants-config\";\nimport { resolveVariantCandidate } from \"./resolve-variant-candidate\";\nimport {\n  variantCacheKey,\n  variantCachePath,\n  variantGenerationTag,\n  variantSourceDirectory,\n  variantSourceKey,\n} from \"./variant-cache-key\";\nimport { variantGenerations } from \"./variant-generations\";\n\n/**\n * Options for `generateImageVariants`\n */\nexport type GenerateImageVariantsOptions = {\n  /**\n   * Limit generation to these variant names, instead of every variant in\n   * `uploads.images.variants`.\n   */\n  variants?: readonly string[];\n};\n\nasync function exists(target: string): Promise<boolean> {\n  try {\n    await fs.access(target);\n\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction encodeUploadsPath(relativePath: string): string {\n  return relativePath.split(\"/\").map(encodeURIComponent).join(\"/\");\n}\n\nfunction variantUrl(src: string, name: string, format?: VariantOutputFormat): string {\n  const query = format\n    ? `variant=${encodeURIComponent(name)}&format=${format}`\n    : `variant=${encodeURIComponent(name)}`;\n\n  return `${src}?${query}`;\n}\n\nasync function readDerivativeDimensions(\n  target: string,\n): Promise<{ width: number; height: number }> {\n  const derivative = new Image(await fs.readFile(target));\n  const { width, height } = await derivative.metadata();\n\n  return { width: width ?? 0, height: height ?? 0 };\n}\n\n/**\n * Every distinct format a variant is rendered in: the source format plus\n * whatever `uploads.images.formats` adds, with duplicates dropped so a format\n * that is both the source format and an allowed format is generated once.\n */\nfunction outputFormatsFor(\n  sourceFormat: VariantOutputFormat,\n  configuredFormats: readonly ImageVariantOutputFormat[],\n): VariantOutputFormat[] {\n  return [...new Set<VariantOutputFormat>([sourceFormat, ...configuredFormats])];\n}\n\n/**\n * Render every configured variant of one uploaded image, right after it is\n * saved.\n *\n * Uses the exact same normalized config (`uploads.images`), cache key and\n * derivative path as `uploadedFileController`, so a variant generated here is\n * already on disk the first time `GET /uploads/<path>?variant=<name>` is\n * requested — no second render. `variantGenerations` (the single-flight used\n * by the route) is reused, so a concurrent request for a variant this call is\n * still generating joins the same run instead of starting a second one.\n *\n * The returned descriptor is plain JSON, safe to store next to the record\n * that owns the image, or to carry through loader data. On local storage the\n * `url`/`urls` already point at `uploadedFileController`; an app serving\n * uploads from object storage or a CDN should not proxy the remote files\n * through this route at all — store the descriptor once generation runs\n * against the same bucket the CDN serves from, or resolve its URLs through a\n * custom `ImageLoader` on the client instead.\n *\n * @param relativePath - path of the saved upload, relative to the storage root\n * @param options.variants - limit generation to these variant names\n * @throws ImageVariantsConfigError when there is no local storage root, or\n * `uploads.images` is not configured — both are server misconfiguration, not\n * a bad request\n * @throws HttpError(400) when a name in `options.variants` is not declared in\n * `uploads.images.variants`\n * @throws HttpError(404) when `relativePath` does not resolve to a file\n * inside the storage root\n * @throws HttpError(413) when the source is over `maxSourceBytes` or\n * `maxSourcePixels`\n * @throws HttpError(415) when the source is not jpeg, png, webp or avif\n */\nexport async function generateImageVariants(\n  relativePath: string,\n  options: GenerateImageVariantsOptions = {},\n): Promise<GeneratedImageDescriptor> {\n  const storageRoot = storage.root();\n\n  if (!storageRoot || storageRoot === \".\") {\n    throw new ImageVariantsConfigError(\n      \"generateImageVariants needs a local storage driver with a root.\",\n    );\n  }\n\n  const images = resolveImageVariantsConfig(uploadsConfig(\"images\"), storageRoot);\n\n  if (!images) {\n    throw new ImageVariantsConfigError(\"uploads.images is not configured.\");\n  }\n\n  const names = options.variants ?? Object.keys(images.variants);\n\n  for (const name of names) {\n    if (!Object.prototype.hasOwnProperty.call(images.variants, name)) {\n      throw new HttpError(400, `Unknown variant \"${name}\".`);\n    }\n  }\n\n  const candidate = await resolveVariantCandidate(relativePath, storageRoot, images);\n\n  if (!candidate) {\n    throw new HttpError(404, \"File Not Found\");\n  }\n\n  const { source, stats, sourceFormat } = candidate;\n\n  const image = await loadVariantSource(source.absolutePath, {\n    maxSourceBytes: images.maxSourceBytes,\n    maxSourcePixels: images.maxSourcePixels,\n    expectedFormat: sourceFormat,\n  });\n\n  const { width: sourceWidth, height: sourceHeight } = await image.metadata();\n  warnIfVariantCacheIsPublic(images.cacheDirectory);\n\n  const src = `/uploads/${encodeUploadsPath(source.relativePath)}`;\n  const variants: Record<string, GeneratedImageVariant> = {};\n\n  for (const name of names) {\n    const variant = images.variants[name];\n    if (variant === undefined) {\n      throw new HttpError(400, `Unknown variant \"${name}\".`);\n    }\n    const formats = outputFormatsFor(sourceFormat, images.formats);\n    let dimensions: { width: number; height: number } | undefined;\n\n    for (const format of formats) {\n      const hash = variantCacheKey({\n        relativePath: source.relativePath,\n        sourceSize: stats.size,\n        sourceMtimeMs: stats.mtimeMs,\n        variant,\n        format,\n      });\n      const sourceKey = variantSourceKey(source.root, source.relativePath);\n      const generation = variantGenerationTag(stats.size, stats.mtimeMs);\n      const target = variantCachePath(\n        images.cacheDirectory,\n        { sourceKey, generation },\n        hash,\n        format,\n      );\n\n      if (!(await exists(target))) {\n        // keyed on the target, which includes the disk root (see resolveImageVariant)\n        await variantGenerations.run(target, async () => {\n          if (await exists(target)) return;\n\n          await retryOnVanishedDirectory(() =>\n            generateImageVariant({ image: image.clone(), variant, format, targetPath: target }),\n          );\n          await pruneStaleVariantGenerationsIfCurrent(\n            source.absolutePath,\n            variantSourceDirectory(images.cacheDirectory, sourceKey),\n            generation,\n          );\n        });\n      }\n\n      if (dimensions === undefined) {\n        dimensions = await readDerivativeDimensions(target);\n      }\n    }\n\n    const urls: Partial<Record<ImageVariantOutputFormat, string>> = {};\n\n    for (const format of images.formats) {\n      urls[format] = variantUrl(src, name, format);\n    }\n\n    variants[name] = {\n      width: dimensions?.width ?? variant.width,\n      height:\n        dimensions?.height ??\n        variant.height ??\n        Math.round(variant.width * ((sourceHeight ?? 1) / (sourceWidth ?? 1))),\n      url: variantUrl(src, name),\n      ...(Object.keys(urls).length > 0 ? { urls } : {}),\n    };\n  }\n\n  return {\n    src,\n    width: sourceWidth ?? 0,\n    height: sourceHeight ?? 0,\n    variants,\n    ...(images.formats.length > 0 ? { formats: images.formats } : {}),\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"generate-image-variants.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/generate-image-variants.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport { Image } from \"../../image\";\nimport type { StorageDriverName } from \"../../storage/types\";\nimport { localDiskRoot } from \"./local-disk-root\";\nimport { remoteVariantDisk, remoteVariantSource } from \"./remote-variant-source\";\nimport { renderRemoteImageVariant } from \"./resolve-remote-image-variant\";\nimport { HttpError } from \"../errors\";\nimport { uploadsConfig } from \"../uploads-config\";\nimport type { ImageVariantOutputFormat } from \"../uploads-types\";\nimport { generateImageVariant } from \"./generate-image-variant\";\nimport {\n  pruneStaleVariantGenerationsIfCurrent,\n  retryOnVanishedDirectory,\n  warnIfVariantCacheIsPublic,\n} from \"./image-variant-cache\";\nimport { ImageVariantsConfigError } from \"./image-variants-config-error\";\nimport type {\n  GeneratedImageDescriptor,\n  GeneratedImageVariant,\n  VariantOutputFormat,\n} from \"./image-variant-types\";\nimport { loadVariantSource } from \"./load-variant-source\";\nimport { resolveImageVariantsConfig } from \"./resolve-image-variants-config\";\nimport { resolveVariantCandidate } from \"./resolve-variant-candidate\";\nimport {\n  variantCacheKey,\n  variantCachePath,\n  variantGenerationTag,\n  variantSourceDirectory,\n  variantSourceKey,\n} from \"./variant-cache-key\";\nimport { freshImageVariant, scheduleImageVariantCacheTrim } from \"./trim-image-variant-cache\";\nimport { variantGenerations } from \"./variant-generations\";\n\n/**\n * Options for `generateImageVariants`\n */\nexport type GenerateImageVariantsOptions = {\n  /**\n   * Limit generation to these variant names, instead of every variant in\n   * `uploads.images.variants`.\n   */\n  variants?: readonly string[];\n\n  /** Disk holding the source; defaults to the active disk. */\n  disk?: StorageDriverName;\n\n  /** Route prefix serving variants of this disk (and originals for local disks). Default /uploads. */\n  urlPrefix?: string;\n};\n\nfunction encodeUploadsPath(relativePath: string): string {\n  return relativePath.split(\"/\").map(encodeURIComponent).join(\"/\");\n}\n\nfunction variantUrl(src: string, name: string, format?: VariantOutputFormat): string {\n  const query = format\n    ? `variant=${encodeURIComponent(name)}&format=${format}`\n    : `variant=${encodeURIComponent(name)}`;\n\n  return `${src}?${query}`;\n}\n\nasync function readDerivativeDimensions(\n  target: string,\n): Promise<{ width: number; height: number }> {\n  const derivative = new Image(await fs.readFile(target));\n  const { width, height } = await derivative.metadata();\n\n  return { width: width ?? 0, height: height ?? 0 };\n}\n\n/**\n * Every distinct format a variant is rendered in: the source format plus\n * whatever `uploads.images.formats` adds, with duplicates dropped so a format\n * that is both the source format and an allowed format is generated once.\n */\nfunction outputFormatsFor(\n  sourceFormat: VariantOutputFormat,\n  configuredFormats: readonly ImageVariantOutputFormat[],\n): VariantOutputFormat[] {\n  return [...new Set<VariantOutputFormat>([sourceFormat, ...configuredFormats])];\n}\n\n/**\n * Render every configured variant of one uploaded image, right after it is\n * saved.\n *\n * Uses the exact same normalized config (`uploads.images`), cache key and\n * derivative path as `uploadedFileController`, so a variant generated here is\n * already on disk the first time `GET /uploads/<path>?variant=<name>` is\n * requested — no second render. `variantGenerations` (the single-flight used\n * by the route) is reused, so a concurrent request for a variant this call is\n * still generating joins the same run instead of starting a second one.\n *\n * The returned descriptor is plain JSON, safe to store next to the record\n * that owns the image, or to carry through loader data. On local storage the\n * `url`/`urls` already point at `uploadedFileController`; an app serving\n * uploads from object storage use the driver URL for the original, and\n * `options.urlPrefix` for the route serving locally cached derivatives.\n * Ingest downloads a remote source once for all variants and formats.\n * On-demand cache hits use ETag metadata; sources without ETags are hashed.\n *\n * @param relativePath - path of the saved upload, relative to the storage root\n * @param options.variants - limit generation to these variant names\n * @throws ImageVariantsConfigError when `uploads.images` is not\n * configured — this is server misconfiguration, not\n * a bad request\n * @throws HttpError(400) when a name in `options.variants` is not declared in\n * `uploads.images.variants`\n * @throws HttpError(404) when `relativePath` does not resolve to a file\n * inside the storage root\n * @throws HttpError(413) when the source is over `maxSourceBytes` or\n * `maxSourcePixels`\n * @throws HttpError(415) when the source is not jpeg, png, webp or avif\n */\nexport async function generateImageVariants(\n  relativePath: string,\n  options: GenerateImageVariantsOptions = {},\n): Promise<GeneratedImageDescriptor> {\n  const storageRoot = localDiskRoot(options.disk);\n\n  if (!storageRoot) return generateRemoteImageVariants(relativePath, options);\n\n  const images = resolveImageVariantsConfig(uploadsConfig(\"images\"), storageRoot);\n\n  if (!images) {\n    throw new ImageVariantsConfigError(\"uploads.images is not configured.\");\n  }\n\n  const names = options.variants ?? Object.keys(images.variants);\n\n  for (const name of names) {\n    if (!Object.prototype.hasOwnProperty.call(images.variants, name)) {\n      throw new HttpError(400, `Unknown variant \"${name}\".`);\n    }\n  }\n\n  const candidate = await resolveVariantCandidate(relativePath, storageRoot, images);\n\n  if (!candidate) {\n    throw new HttpError(404, \"File Not Found\");\n  }\n\n  const { source, stats, sourceFormat } = candidate;\n\n  const image = await loadVariantSource(source.absolutePath, {\n    maxSourceBytes: images.maxSourceBytes,\n    maxSourcePixels: images.maxSourcePixels,\n    expectedFormat: sourceFormat,\n  });\n\n  const { width: sourceWidth, height: sourceHeight } = await image.metadata();\n  warnIfVariantCacheIsPublic(images.cacheDirectory);\n\n  const src = `${(options.urlPrefix ?? \"/uploads\").replace(/\\/$/, \"\")}/${encodeUploadsPath(source.relativePath)}`;\n  const variants: Record<string, GeneratedImageVariant> = {};\n\n  for (const name of names) {\n    const variant = images.variants[name];\n    if (variant === undefined) {\n      throw new HttpError(400, `Unknown variant \"${name}\".`);\n    }\n    const formats = outputFormatsFor(sourceFormat, images.formats);\n    let dimensions: { width: number; height: number } | undefined;\n\n    for (const format of formats) {\n      const hash = variantCacheKey({\n        relativePath: source.relativePath,\n        sourceSize: stats.size,\n        sourceMtimeMs: stats.mtimeMs,\n        variant,\n        format,\n      });\n      const sourceKey = variantSourceKey(source.root, source.relativePath);\n      const generation = variantGenerationTag(stats.size, stats.mtimeMs);\n      const target = variantCachePath(\n        images.cacheDirectory,\n        { sourceKey, generation },\n        hash,\n        format,\n      );\n\n      if (!(await freshImageVariant(target, images.maxCacheAge))) {\n        // keyed on the target, which includes the disk root (see resolveImageVariant)\n        await variantGenerations.run(target, async () => {\n          if (await freshImageVariant(target, images.maxCacheAge)) return;\n\n          await retryOnVanishedDirectory(() =>\n            generateImageVariant({ image: image.clone(), variant, format, targetPath: target }),\n          );\n          scheduleImageVariantCacheTrim(images, target);\n          await pruneStaleVariantGenerationsIfCurrent(\n            source.absolutePath,\n            variantSourceDirectory(images.cacheDirectory, sourceKey),\n            generation,\n          );\n        });\n      }\n\n      if (dimensions === undefined) {\n        dimensions = await readDerivativeDimensions(target);\n      }\n    }\n\n    const urls: Partial<Record<ImageVariantOutputFormat, string>> = {};\n\n    for (const format of images.formats) {\n      urls[format] = variantUrl(src, name, format);\n    }\n\n    variants[name] = {\n      width: dimensions?.width ?? variant.width,\n      height:\n        dimensions?.height ??\n        variant.height ??\n        Math.round(variant.width * ((sourceHeight ?? 1) / (sourceWidth ?? 1))),\n      url: variantUrl(src, name),\n      ...(Object.keys(urls).length > 0 ? { urls } : {}),\n    };\n  }\n\n  return {\n    src,\n    width: sourceWidth ?? 0,\n    height: sourceHeight ?? 0,\n    variants,\n    ...(images.formats.length > 0 ? { formats: images.formats } : {}),\n  };\n}\n\nasync function generateRemoteImageVariants(\n  relativePath: string,\n  options: GenerateImageVariantsOptions,\n): Promise<GeneratedImageDescriptor> {\n  const disk = remoteVariantDisk(options.disk);\n  const images = resolveImageVariantsConfig(uploadsConfig(\"images\"), disk.cacheRoot);\n  if (!images) throw new ImageVariantsConfigError(\"uploads.images is not configured.\");\n  const names = options.variants ?? Object.keys(images.variants);\n  for (const name of names) {\n    if (!Object.prototype.hasOwnProperty.call(images.variants, name))\n      throw new HttpError(400, `Unknown variant \"${name}\".`);\n  }\n  const source = await remoteVariantSource(relativePath, disk, images);\n  if (!source) throw new HttpError(404, \"File Not Found\");\n  try {\n    const { image, sourceFormat } = await source.load();\n    const { width, height } = await image.metadata();\n    const variantSrc = `${(options.urlPrefix ?? \"/uploads\").replace(/\\/$/, \"\")}/${encodeUploadsPath(source.relativePath)}`;\n    const variants: Record<string, GeneratedImageVariant> = {};\n    for (const name of names) {\n      let dimensions: { width: number; height: number } | undefined;\n      for (const format of outputFormatsFor(sourceFormat, images.formats)) {\n        const resolved = await renderRemoteImageVariant(\n          {\n            path: relativePath,\n            variant: name,\n            ...(format === sourceFormat ? {} : { format }),\n          },\n          disk,\n          images,\n          source,\n        );\n        if (!resolved) throw new HttpError(404, \"File Not Found\");\n        dimensions ??= await readDerivativeDimensions(resolved.absolutePath);\n      }\n      variants[name] = {\n        width: dimensions?.width ?? 0,\n        height: dimensions?.height ?? 0,\n        url: variantUrl(variantSrc, name),\n        ...(images.formats.length\n          ? {\n              urls: Object.fromEntries(\n                images.formats.map((format) => [format, variantUrl(variantSrc, name, format)]),\n              ),\n            }\n          : {}),\n      };\n    }\n    return {\n      src: disk.driver.url(source.relativePath),\n      width: width ?? 0,\n      height: height ?? 0,\n      variants,\n      ...(images.formats.length ? { formats: images.formats } : {}),\n    };\n  } finally {\n    source.release();\n  }\n}\n"],"mappings":"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"}