@warlock.js/core 5.29.0 → 5.31.0

package/esm/http/server.d.mts

@@ -1,8 +1,12 @@
-import Fastify, { FastifyServerOptions } from "fastify";
+import { HttpServerOptions } from "./types.mjs";
+import Fastify from "fastify";
+import { Server } from "node:http";
+import { Http2SecureServer, Http2Server } from "node:http2";
 
-//#region ../core/src/http/server.d.ts
+//#region ../../packages/core/src/http/server.d.ts
+type DrainServer = Server | Http2Server | Http2SecureServer;
 type FastifyInstance$1 = ReturnType<typeof Fastify>;
-declare function startHttpServer(options?: FastifyServerOptions): FastifyInstance$1;
+declare function startHttpServer(options?: HttpServerOptions): FastifyInstance$1;
 /**
  * Expose the server to be publicly accessible
  */
@@ -12,16 +16,42 @@ declare function getHttpServer(): FastifyInstance$1;
  * be unit-tested with a fake instead of a real Fastify instance.
  */
 type ClosableServer = {
-  close: () => Promise<unknown>;
+  close: () => Promise<unknown>; /** The underlying Node server, when there is one (a Fastify instance's `.server`). */
+  server?: unknown;
 };
+/**
+ * Track in-flight responses on a Node HTTP server so a graceful drain can
+ * close keep-alive connections that become idle AFTER `close()` started.
+ *
+ * Node's `server.close()` (and Fastify's `forceCloseConnections: "idle"`)
+ * closes only the connections idle at that moment. A request in flight when
+ * shutdown begins finishes its response, the client keeps the connection
+ * alive, and `close()` waits on it until the shutdown budget runs out. Active
+ * responses are never cut short: each one is told to close its connection
+ * when it is done (`Connection: close`), and every connection is reaped as
+ * soon as its response has finished.
+ */
+declare function trackConnectionsForDrain(rawServer: DrainServer): void;
+/**
+ * Begin a graceful drain on a server tracked by {@link trackConnectionsForDrain}:
+ * every in-flight response closes its connection when it is done, and idle
+ * keep-alive connections are closed now and whenever another one goes idle.
+ * A server that is not tracked is left alone.
+ *
+ * @returns Whether the server was tracked (and is now draining).
+ */
+declare function beginHttpDrain(rawServer: unknown): boolean;
 /**
  * Close a server, bounded by a timeout. Fastify's `close()` stops accepting new
  * requests (it answers 503 while closing) and drains the in-flight ones; this
- * wraps it so a single stuck request can't hang shutdown forever.
+ * wraps it so a single stuck request can't hang shutdown forever. When the
+ * server's connections are tracked (the default `"idle"` mode), keep-alive
+ * connections that go idle during the drain are closed too, so a finished
+ * request does not hold the shutdown open.
  *
  * @returns `true` if the server drained cleanly, `false` if the timeout fired first.
  */
 declare function closeServerWithTimeout(server: ClosableServer, timeoutMs: number): Promise<boolean>;
 //#endregion
-export { ClosableServer, FastifyInstance$1 as FastifyInstance, closeServerWithTimeout, getHttpServer, startHttpServer };
+export { ClosableServer, FastifyInstance$1 as FastifyInstance, beginHttpDrain, closeServerWithTimeout, getHttpServer, startHttpServer, trackConnectionsForDrain };
 //# sourceMappingURL=server.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.mts","names":[],"sources":["../../../../../../../core/src/http/server.ts"],"mappings":";;;KAIY,iBAAA,GAAkB,UAAU,QAAQ,OAAA;AAAA,iBA8ChC,eAAA,CAAgB,OAAA,GAAU,oBAAA,GAAuB,iBAAe;AA9ChF;;;AAAA,iBA2FgB,aAAA,IAAiB,iBAAe;AA3FO;AA8CvD;;;AA9CuD,KAmG3C,cAAA;EAAmB,KAAA,QAAa,OAAO;AAAA;;;AArD6B;AA6ChF;;;;iBAiBsB,sBAAA,CACpB,MAAA,EAAQ,cAAA,EACR,SAAA,WACC,OAAO"}
+{"version":3,"file":"server.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/server.ts"],"mappings":";;;;;;KAUK,WAAA,GAAc,MAAA,GAAiB,WAAA,GAAc,iBAAA;AAAA,KAKtC,iBAAA,GAAkB,UAAU,QAAQ,OAAA;AAAA,iBA8ChC,eAAA,CAAgB,OAAA,GAAU,iBAAA,GAAoB,iBAAe;;;;iBAmE7D,aAAA,IAAiB,iBAAe;;;;;KAQpC,cAAA;EACV,KAAA,QAAa,OAAO,WA/H6C;EAiIjE,MAAA;AAAA;;;;AA5HqD;AA8CvD;;;;;;;;iBA4HgB,wBAAA,CAAyB,SAAsB,EAAX,WAAW;AAzD/D;;;;AAAgD;AAQhD;;;AARA,iBA6FgB,cAAA,CAAe,SAAkB;;;;;AAlFzC;AA8CR;;;;AAA+D;iBAmEzC,sBAAA,CACpB,MAAA,EAAQ,cAAA,EACR,SAAA,WACC,OAAO"}

package/esm/http/server.mjs

@@ -2,7 +2,7 @@ import { normalizeRequestPath } from "../router/normalize-request-path.mjs";
 import config from "@mongez/config";
 import Fastify from "fastify";
 
-//#region ../core/src/http/server.ts
+//#region ../../packages/core/src/http/server.ts
 let server = void 0;
 function isTrustProxyPredicate(value) {
 	return typeof value === "function";
@@ -26,15 +26,20 @@ function startHttpServer(options) {
 	const trustProxy = resolveTrustProxy(config.get("http.trustProxy", false));
 	const bodyLimit = config.get("http.bodyLimit") ?? void 0;
 	const configuredRewriteUrl = options?.rewriteUrl;
-	return server = Fastify({
+	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: config.get("http.gracefulShutdown.forceCloseConnections", "idle"),
 		...options,
+		forceCloseConnections,
 		rewriteUrl(request) {
 			return normalizeRequestUrl(configuredRewriteUrl ? configuredRewriteUrl.call(this, request) : request.url ?? "/");
 		}
 	});
+	if (http2 || forceCloseConnections === "idle") trackConnectionsForDrain(server.server);
+	return server;
 }
 /**
 * Expose the server to be publicly accessible
@@ -42,15 +47,85 @@ function startHttpServer(options) {
 function getHttpServer() {
 	return server;
 }
+const drainStates = /* @__PURE__ */ new WeakMap();
+/**
+* Mark a response so its connection closes once it is sent. Only possible
+* before the headers go out; a response that already streams its headers is
+* 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 ("closeIdleConnections" in rawServer && typeof rawServer.closeIdleConnections === "function") rawServer.closeIdleConnections();
+}
+/**
+* Track in-flight responses on a Node HTTP server so a graceful drain can
+* close keep-alive connections that become idle AFTER `close()` started.
+*
+* Node's `server.close()` (and Fastify's `forceCloseConnections: "idle"`)
+* closes only the connections idle at that moment. A request in flight when
+* shutdown begins finishes its response, the client keeps the connection
+* alive, and `close()` waits on it until the shutdown budget runs out. Active
+* responses are never cut short: each one is told to close its connection
+* when it is done (`Connection: close`), and every connection is reaped as
+* soon as its response has finished.
+*/
+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);
+		response.once("close", () => {
+			state.inFlight.delete(response);
+			if (state.draining) setImmediate(() => reapIdleConnections(rawServer));
+		});
+	});
+}
+/**
+* Begin a graceful drain on a server tracked by {@link trackConnectionsForDrain}:
+* every in-flight response closes its connection when it is done, and idle
+* keep-alive connections are closed now and whenever another one goes idle.
+* A server that is not tracked is left alone.
+*
+* @returns Whether the server was tracked (and is now draining).
+*/
+function beginHttpDrain(rawServer) {
+	if (!rawServer || typeof rawServer !== "object") return false;
+	const state = drainStates.get(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;
+}
 /**
 * Close a server, bounded by a timeout. Fastify's `close()` stops accepting new
 * requests (it answers 503 while closing) and drains the in-flight ones; this
-* wraps it so a single stuck request can't hang shutdown forever.
+* wraps it so a single stuck request can't hang shutdown forever. When the
+* server's connections are tracked (the default `"idle"` mode), keep-alive
+* connections that go idle during the drain are closed too, so a finished
+* request does not hold the shutdown open.
 *
 * @returns `true` if the server drained cleanly, `false` if the timeout fired first.
 */
 async function closeServerWithTimeout(server, timeoutMs) {
 	let timer;
+	beginHttpDrain(server.server);
 	const drained = server.close().then(() => true);
 	const timedOut = new Promise((resolve) => {
 		timer = setTimeout(() => resolve(false), timeoutMs);
@@ -63,5 +138,5 @@ async function closeServerWithTimeout(server, timeoutMs) {
 }
 
 //#endregion
-export { closeServerWithTimeout, getHttpServer, startHttpServer };
+export { beginHttpDrain, closeServerWithTimeout, getHttpServer, startHttpServer, trackConnectionsForDrain };
 //# sourceMappingURL=server.mjs.map

package/esm/http/server.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"server.mjs","names":[],"sources":["../../../../../../../core/src/http/server.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport Fastify, { type FastifyServerOptions } from \"fastify\";\nimport { normalizeRequestPath } from \"../router/normalize-request-path\";\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?: FastifyServerOptions): 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\n  return (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: config.get(\"http.gracefulShutdown.forceCloseConnections\", \"idle\"),\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\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 = { close: () => Promise<unknown> };\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.\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  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":";;;;;AAOA,IAAI,SAAsC;AAM1C,SAAS,sBAAsB,OAA8C;CAC3E,OAAO,OAAO,UAAU;AAC1B;AAEA,SAAS,iBAAiB,OAAmC;CAC3D,OACE,MAAM,QAAQ,KAAK,KACnB,MAAM,SAAS,KACf,MAAM,OAAO,UAAU,OAAO,UAAU,YAAY,MAAM,KAAK,CAAC,CAAC,SAAS,CAAC;AAE/E;AAEA,SAAS,kBAAkB,OAA4B;CACrD,IAAI,UAAU,UAAa,UAAU,MAAM,OAAO;CAElD,IAAI,OAAO,UAAU,aAAa,sBAAsB,KAAK,GAAG,OAAO;CAEvE,IAAI,OAAO,UAAU,YAAY,MAAM,KAAK,CAAC,CAAC,SAAS,GAAG,OAAO;CAEjE,IAAI,iBAAiB,KAAK,GAAG,OAAO;CAIpC,MAAM,IAAI,UACR,sJAHe,MAAM,QAAQ,KAAK,IAAI,UAAU,OAAO,MAImB,EAC5E;AACF;AAEA,SAAS,oBAAoB,KAAqB;CAChD,MAAM,aAAa,IAAI,QAAQ,GAAG;CAElC,IAAI,eAAe,IAAI,OAAO,qBAAqB,GAAG;CAEtD,OAAO,qBAAqB,IAAI,MAAM,GAAG,UAAU,CAAC,IAAI,IAAI,MAAM,UAAU;AAC9E;AAEA,SAAgB,gBAAgB,SAAiD;CAG/E,MAAM,aAAa,kBAAkB,OAAO,IAAI,mBAAmB,KAAK,CAAC;CAEzE,MAAM,YAAY,OAAO,IAAI,gBAAgB,KAAK;CAClD,MAAM,uBAAuB,SAAS;CAEtC,OAAQ,SAAS,QAAQ;EAQvB;EAMA,GAAI,cAAc,UAAa,EAAE,UAAU;EAI3C,uBAAuB,OAAO,IAAI,+CAA+C,MAAM;EACvF,GAAG;EAKH,WAAW,SAAS;GAKlB,OAAO,oBAJW,uBACd,qBAAqB,KAAK,MAAM,OAAO,IACtC,QAAQ,OAAO,GAEgB;EACtC;CACF,CAAC;AACH;;;;AAKA,SAAgB,gBAAiC;CAC/C,OAAO;AACT;;;;;;;;AAeA,eAAsB,uBACpB,QACA,WACkB;CAClB,IAAI;CAEJ,MAAM,UAAU,OAAO,MAAM,CAAC,CAAC,WAAW,IAAI;CAE9C,MAAM,WAAW,IAAI,SAAkB,YAAY;EACjD,QAAQ,iBAAiB,QAAQ,KAAK,GAAG,SAAS;CACpD,CAAC;CAED,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,SAAS,QAAQ,CAAC;CAC/C,UAAU;EACR,IAAI,OACF,aAAa,KAAK;CAEtB;AACF"}
+{"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-react-response.d.mts

@@ -1,6 +1,6 @@
 import { OutgoingHttpHeaders, ServerResponse } from "node:http";
 
-//#region ../core/src/http/stream-react-response.d.ts
+//#region ../../packages/core/src/http/stream-react-response.d.ts
 /**
  * The subset of React's server `PipeableStream` (`react-dom/server`) this
  * helper needs — piping the render onto a Node writable and aborting it

package/esm/http/stream-react-response.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-react-response.d.mts","names":[],"sources":["../../../../../../../core/src/http/stream-react-response.ts"],"mappings":";;;;;AAUA;;;;;;KAAY,mBAAA;EACV,IAAA,qBAAyB,MAAA,CAAO,cAAA,EAAgB,WAAA,EAAa,WAAA,GAAc,WAAA;EAC3E,KAAA,CAAM,MAAA;AAAA;;KAII,0BAAA;EALmD,qFAO7D,GAAA,EAAK,cAAA;EAPsE;;;;AACrD;AAIxB;EASE,UAAA;;;;;;;;EAQA,OAAA,EAAS,mBAAA,EART;EAUA,cAAA,EAAgB,mBAAA;AAAA;;;;AAAmB;AA6BrC;;;;;;;;AAAiF;;;;;;;;;;;;;;iBAAjE,mBAAA,CAAoB,OAAA,EAAS,0BAAA,GAA6B,OAAO"}
+{"version":3,"file":"stream-react-response.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/stream-react-response.ts"],"mappings":";;;;;AAUA;;;;;;KAAY,mBAAA;EACV,IAAA,qBAAyB,MAAA,CAAO,cAAA,EAAgB,WAAA,EAAa,WAAA,GAAc,WAAA;EAC3E,KAAA,CAAM,MAAA;AAAA;;KAII,0BAAA;EALmD,qFAO7D,GAAA,EAAK,cAAA;EAPsE;;;;AACrD;AAIxB;EASE,UAAA;;;;;;;;EAQA,OAAA,EAAS,mBAAA,EART;EAUA,cAAA,EAAgB,mBAAA;AAAA;;;;AAAmB;AA6BrC;;;;;;;;AAAiF;;;;;;;;;;;;;;iBAAjE,mBAAA,CAAoB,OAAA,EAAS,0BAAA,GAA6B,OAAO"}

package/esm/http/stream-react-response.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/http/stream-react-response.ts
+//#region ../../packages/core/src/http/stream-react-response.ts
 /**
 * Write the committed status/headers to the raw Node response and pipe a
 * React server stream onto it — the ONE place in the framework that turns a

package/esm/http/stream-react-response.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"stream-react-response.mjs","names":[],"sources":["../../../../../../../core/src/http/stream-react-response.ts"],"sourcesContent":["import type { OutgoingHttpHeaders, ServerResponse } from \"node:http\";\n\n/**\n * The subset of React's server `PipeableStream` (`react-dom/server`) this\n * helper needs — piping the render onto a Node writable and aborting it\n * early. Declared locally, structurally compatible with React's own type,\n * so this file carries no `react-dom` import: `@warlock.js/core` has no peer\n * dependency on React, only the caller that already imported\n * `renderToPipeableStream` does.\n */\nexport type PipeableReactStream = {\n  pipe<Destination extends NodeJS.WritableStream>(destination: Destination): Destination;\n  abort(reason?: unknown): void;\n};\n\n/** Options for {@link streamReactResponse}. */\nexport type StreamReactResponseOptions = {\n  /** The raw Node response, obtained via core's `Response` — never handed to `web`. */\n  raw: ServerResponse;\n  /**\n   * The committed HTTP status. Decided by the caller BEFORE this runs —\n   * loaders, middleware short-circuits, validation and error escalation have\n   * all already settled, so this is the one and only status this response\n   * will carry.\n   */\n  statusCode: number;\n  /**\n   * The committed response headers, read once before piping starts.\n   * `Set-Cookie` entries already committed via the framework's ordinary\n   * cookie APIs are expected to already be present here (Fastify writes a\n   * cookie to the header as soon as it is set), so this helper does not\n   * take a separate cookie list.\n   */\n  headers: OutgoingHttpHeaders;\n  /** The already-ready React server stream (its shell, or the whole tree, resolved by the caller). */\n  pipeableStream: PipeableReactStream;\n};\n\n/**\n * Write the committed status/headers to the raw Node response and pipe a\n * React server stream onto it — the ONE place in the framework that turns a\n * `PipeableStream` into bytes on the wire (Stage 1 streaming SSR). `web`\n * never touches `raw` itself; it goes through this helper (or\n * `Response.streamReact`, which wraps it) exclusively.\n *\n * Aborts the React render when the client disconnects before the stream\n * finishes, so a dropped connection does not leave the render running to\n * completion for nobody.\n *\n * Resolves once the underlying response has finished sending. Rejects if the\n * raw response errors while writing.\n *\n * @example\n * ```ts\n * const pipeableStream = await new Promise<PipeableStream>((resolve, reject) => {\n *   const stream = renderToPipeableStream(element, {\n *     onShellReady: () => resolve(stream),\n *     onShellError: reject,\n *   });\n * });\n *\n * await streamReactResponse({ raw: response.raw, statusCode, headers, pipeableStream });\n * ```\n */\nexport function streamReactResponse(options: StreamReactResponseOptions): Promise<void> {\n  const { raw, statusCode, headers, pipeableStream } = options;\n\n  return new Promise<void>((resolve, reject) => {\n    raw.writeHead(statusCode, headers);\n\n    const onDisconnect = (): void => {\n      // A normal completion also fires \"close\" after \"finish\" — aborting an\n      // already-finished React stream is a documented no-op, but the\n      // `writableEnded` guard keeps that fact from ever mattering here.\n      if (raw.writableEnded) return;\n\n      pipeableStream.abort();\n    };\n\n    raw.once(\"close\", onDisconnect);\n    raw.once(\"aborted\", onDisconnect);\n\n    raw.once(\"finish\", () => resolve());\n    raw.once(\"error\", (error) => reject(error));\n\n    pipeableStream.pipe(raw);\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,oBAAoB,SAAoD;CACtF,MAAM,EAAE,KAAK,YAAY,SAAS,mBAAmB;CAErD,OAAO,IAAI,SAAe,SAAS,WAAW;EAC5C,IAAI,UAAU,YAAY,OAAO;EAEjC,MAAM,qBAA2B;GAI/B,IAAI,IAAI,eAAe;GAEvB,eAAe,MAAM;EACvB;EAEA,IAAI,KAAK,SAAS,YAAY;EAC9B,IAAI,KAAK,WAAW,YAAY;EAEhC,IAAI,KAAK,gBAAgB,QAAQ,CAAC;EAClC,IAAI,KAAK,UAAU,UAAU,OAAO,KAAK,CAAC;EAE1C,eAAe,KAAK,GAAG;CACzB,CAAC;AACH"}
+{"version":3,"file":"stream-react-response.mjs","names":[],"sources":["../../../../../../../../packages/core/src/http/stream-react-response.ts"],"sourcesContent":["import type { OutgoingHttpHeaders, ServerResponse } from \"node:http\";\n\n/**\n * The subset of React's server `PipeableStream` (`react-dom/server`) this\n * helper needs — piping the render onto a Node writable and aborting it\n * early. Declared locally, structurally compatible with React's own type,\n * so this file carries no `react-dom` import: `@warlock.js/core` has no peer\n * dependency on React, only the caller that already imported\n * `renderToPipeableStream` does.\n */\nexport type PipeableReactStream = {\n  pipe<Destination extends NodeJS.WritableStream>(destination: Destination): Destination;\n  abort(reason?: unknown): void;\n};\n\n/** Options for {@link streamReactResponse}. */\nexport type StreamReactResponseOptions = {\n  /** The raw Node response, obtained via core's `Response` — never handed to `web`. */\n  raw: ServerResponse;\n  /**\n   * The committed HTTP status. Decided by the caller BEFORE this runs —\n   * loaders, middleware short-circuits, validation and error escalation have\n   * all already settled, so this is the one and only status this response\n   * will carry.\n   */\n  statusCode: number;\n  /**\n   * The committed response headers, read once before piping starts.\n   * `Set-Cookie` entries already committed via the framework's ordinary\n   * cookie APIs are expected to already be present here (Fastify writes a\n   * cookie to the header as soon as it is set), so this helper does not\n   * take a separate cookie list.\n   */\n  headers: OutgoingHttpHeaders;\n  /** The already-ready React server stream (its shell, or the whole tree, resolved by the caller). */\n  pipeableStream: PipeableReactStream;\n};\n\n/**\n * Write the committed status/headers to the raw Node response and pipe a\n * React server stream onto it — the ONE place in the framework that turns a\n * `PipeableStream` into bytes on the wire (Stage 1 streaming SSR). `web`\n * never touches `raw` itself; it goes through this helper (or\n * `Response.streamReact`, which wraps it) exclusively.\n *\n * Aborts the React render when the client disconnects before the stream\n * finishes, so a dropped connection does not leave the render running to\n * completion for nobody.\n *\n * Resolves once the underlying response has finished sending. Rejects if the\n * raw response errors while writing.\n *\n * @example\n * ```ts\n * const pipeableStream = await new Promise<PipeableStream>((resolve, reject) => {\n *   const stream = renderToPipeableStream(element, {\n *     onShellReady: () => resolve(stream),\n *     onShellError: reject,\n *   });\n * });\n *\n * await streamReactResponse({ raw: response.raw, statusCode, headers, pipeableStream });\n * ```\n */\nexport function streamReactResponse(options: StreamReactResponseOptions): Promise<void> {\n  const { raw, statusCode, headers, pipeableStream } = options;\n\n  return new Promise<void>((resolve, reject) => {\n    raw.writeHead(statusCode, headers);\n\n    const onDisconnect = (): void => {\n      // A normal completion also fires \"close\" after \"finish\" — aborting an\n      // already-finished React stream is a documented no-op, but the\n      // `writableEnded` guard keeps that fact from ever mattering here.\n      if (raw.writableEnded) return;\n\n      pipeableStream.abort();\n    };\n\n    raw.once(\"close\", onDisconnect);\n    raw.once(\"aborted\", onDisconnect);\n\n    raw.once(\"finish\", () => resolve());\n    raw.once(\"error\", (error) => reject(error));\n\n    pipeableStream.pipe(raw);\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,oBAAoB,SAAoD;CACtF,MAAM,EAAE,KAAK,YAAY,SAAS,mBAAmB;CAErD,OAAO,IAAI,SAAe,SAAS,WAAW;EAC5C,IAAI,UAAU,YAAY,OAAO;EAEjC,MAAM,qBAA2B;GAI/B,IAAI,IAAI,eAAe;GAEvB,eAAe,MAAM;EACvB;EAEA,IAAI,KAAK,SAAS,YAAY;EAC9B,IAAI,KAAK,WAAW,YAAY;EAEhC,IAAI,KAAK,gBAAgB,QAAQ,CAAC;EAClC,IAAI,KAAK,UAAU,UAAU,OAAO,KAAK,CAAC;EAE1C,eAAe,KAAK,GAAG;CACzB,CAAC;AACH"}

package/esm/http/stream-transport.mjs

@@ -0,0 +1,77 @@
+import { log } from "@warlock.js/logger";
+
+//#region ../../packages/core/src/http/stream-transport.ts
+function createStreamTransport(raw, options) {
+	let closed = false;
+	let disconnected = false;
+	const disconnectHandlers = [];
+	const disconnectController = new AbortController();
+	const disconnect = () => {
+		if (closed) return;
+		closed = true;
+		disconnected = true;
+		options.onClientDisconnected?.();
+		disconnectController.abort(new DOMException(options.disconnectMessage, "AbortError"));
+		for (const handler of disconnectHandlers) try {
+			handler();
+		} catch (error) {
+			log.error("http", "stream", error, { source: "onDisconnect handler" });
+		}
+	};
+	raw.on("close", disconnect);
+	return {
+		signal: disconnectController.signal,
+		get closed() {
+			return closed;
+		},
+		get disconnected() {
+			return disconnected;
+		},
+		get backpressured() {
+			return !closed && raw.writableNeedDrain;
+		},
+		finish() {
+			closed = true;
+		},
+		disconnect,
+		onDisconnect(handler) {
+			disconnectHandlers.push(handler);
+		},
+		waitForDrain() {
+			if (closed) return Promise.resolve(false);
+			if (!raw.writableNeedDrain) return Promise.resolve(true);
+			return new Promise((resolve) => {
+				const settle = (drained) => {
+					raw.off("drain", onDrain);
+					raw.off("close", onClose);
+					resolve(drained);
+				};
+				const onDrain = () => settle(!closed);
+				const onClose = () => settle(false);
+				raw.once("drain", onDrain);
+				raw.once("close", onClose);
+			});
+		}
+	};
+}
+/**
+* The most recent `limit` items, for logging/debugging a stream after it
+* ended. `limit` 0 (or missing/NaN) keeps nothing, so a long-lived stream
+* does not grow with its own history.
+*/
+function createRetainedTail(limit) {
+	const max = limit === void 0 || Number.isNaN(limit) ? 0 : Math.max(0, Math.floor(limit));
+	const items = [];
+	return {
+		items,
+		push(item) {
+			if (max === 0) return;
+			items.push(item);
+			if (items.length > max) items.shift();
+		}
+	};
+}
+
+//#endregion
+export { createRetainedTail, createStreamTransport };
+//# sourceMappingURL=stream-transport.mjs.map

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

@@ -0,0 +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.\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/tracing/trace-id.d.mts

@@ -1,4 +1,4 @@
-//#region ../core/src/http/tracing/trace-id.d.ts
+//#region ../../packages/core/src/http/tracing/trace-id.d.ts
 /**
  * Extract the trace id from a raw `traceparent` header value, or `undefined`
  * when the header is missing, malformed, or carries the reserved all-zero id.

package/esm/http/tracing/trace-id.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-id.d.mts","names":[],"sources":["../../../../../../../../core/src/http/tracing/trace-id.ts"],"mappings":";;AAkBA;;;iBAAgB,uBAAA,CAAwB,MAA0B;AAAA;AAkBlE;;;AAlBkE,iBAkBlD,aAAA,CAAc,iBAAA,sBAAuC,SAAiB"}
+{"version":3,"file":"trace-id.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/tracing/trace-id.ts"],"mappings":";;AAkBA;;;iBAAgB,uBAAA,CAAwB,MAA0B;AAAA;AAkBlE;;;AAlBkE,iBAkBlD,aAAA,CAAc,iBAAA,sBAAuC,SAAiB"}

package/esm/http/tracing/trace-id.mjs

@@ -1,4 +1,4 @@
-//#region ../core/src/http/tracing/trace-id.ts
+//#region ../../packages/core/src/http/tracing/trace-id.ts
 /**
 * W3C `traceparent` trace-id extraction.
 *

package/esm/http/tracing/trace-id.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"trace-id.mjs","names":[],"sources":["../../../../../../../../core/src/http/tracing/trace-id.ts"],"sourcesContent":["/**\n * W3C `traceparent` trace-id extraction.\n *\n * Format: `version-traceid-parentid-flags`, e.g.\n * `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01`. Only version\n * `00` is accepted (later versions may change the field layout, and nothing\n * in this codebase needs to interoperate with one yet); the trace id must be\n * 32 hex characters and not all zero (the spec reserves all-zero as \"no\n * trace\"). Anything else is treated as absent, not as an error — a\n * malformed header must never fail the request.\n */\nconst TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/;\nconst ALL_ZERO_TRACE_ID = \"0\".repeat(32);\n\n/**\n * Extract the trace id from a raw `traceparent` header value, or `undefined`\n * when the header is missing, malformed, or carries the reserved all-zero id.\n */\nexport function parseTraceparentTraceId(header: string | undefined): string | undefined {\n  if (!header) return undefined;\n\n  const match = TRACEPARENT_PATTERN.exec(header.trim());\n\n  if (!match) return undefined;\n\n  const traceId = match[1];\n\n  if (traceId === ALL_ZERO_TRACE_ID) return undefined;\n\n  return traceId;\n}\n\n/**\n * Resolve the trace id to carry for a request: the inbound `traceparent`'s\n * trace id when valid, otherwise `requestId`.\n */\nexport function deriveTraceId(traceparentHeader: string | undefined, requestId: string): string {\n  return parseTraceparentTraceId(traceparentHeader) ?? requestId;\n}\n"],"mappings":";;;;;;;;;;;;AAWA,MAAM,sBAAsB;AAC5B,MAAM,oBAAoB,IAAI,OAAO,EAAE;;;;;AAMvC,SAAgB,wBAAwB,QAAgD;CACtF,IAAI,CAAC,QAAQ,OAAO;CAEpB,MAAM,QAAQ,oBAAoB,KAAK,OAAO,KAAK,CAAC;CAEpD,IAAI,CAAC,OAAO,OAAO;CAEnB,MAAM,UAAU,MAAM;CAEtB,IAAI,YAAY,mBAAmB,OAAO;CAE1C,OAAO;AACT;;;;;AAMA,SAAgB,cAAc,mBAAuC,WAA2B;CAC9F,OAAO,wBAAwB,iBAAiB,KAAK;AACvD"}
+{"version":3,"file":"trace-id.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/tracing/trace-id.ts"],"sourcesContent":["/**\n * W3C `traceparent` trace-id extraction.\n *\n * Format: `version-traceid-parentid-flags`, e.g.\n * `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01`. Only version\n * `00` is accepted (later versions may change the field layout, and nothing\n * in this codebase needs to interoperate with one yet); the trace id must be\n * 32 hex characters and not all zero (the spec reserves all-zero as \"no\n * trace\"). Anything else is treated as absent, not as an error — a\n * malformed header must never fail the request.\n */\nconst TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/;\nconst ALL_ZERO_TRACE_ID = \"0\".repeat(32);\n\n/**\n * Extract the trace id from a raw `traceparent` header value, or `undefined`\n * when the header is missing, malformed, or carries the reserved all-zero id.\n */\nexport function parseTraceparentTraceId(header: string | undefined): string | undefined {\n  if (!header) return undefined;\n\n  const match = TRACEPARENT_PATTERN.exec(header.trim());\n\n  if (!match) return undefined;\n\n  const traceId = match[1];\n\n  if (traceId === ALL_ZERO_TRACE_ID) return undefined;\n\n  return traceId;\n}\n\n/**\n * Resolve the trace id to carry for a request: the inbound `traceparent`'s\n * trace id when valid, otherwise `requestId`.\n */\nexport function deriveTraceId(traceparentHeader: string | undefined, requestId: string): string {\n  return parseTraceparentTraceId(traceparentHeader) ?? requestId;\n}\n"],"mappings":";;;;;;;;;;;;AAWA,MAAM,sBAAsB;AAC5B,MAAM,oBAAoB,IAAI,OAAO,EAAE;;;;;AAMvC,SAAgB,wBAAwB,QAAgD;CACtF,IAAI,CAAC,QAAQ,OAAO;CAEpB,MAAM,QAAQ,oBAAoB,KAAK,OAAO,KAAK,CAAC;CAEpD,IAAI,CAAC,OAAO,OAAO;CAEnB,MAAM,UAAU,MAAM;CAEtB,IAAI,YAAY,mBAAmB,OAAO;CAE1C,OAAO;AACT;;;;;AAMA,SAAgB,cAAc,mBAAuC,WAA2B;CAC9F,OAAO,wBAAwB,iBAAiB,KAAK;AACvD"}

package/esm/http/tracing/tracing-dispatcher.d.mts

@@ -1,6 +1,6 @@
 import { TracingContext, TracingHooks, TracingPhaseInfo, TracingRequestEndInfo } from "./tracing.type.mjs";
 
-//#region ../core/src/http/tracing/tracing-dispatcher.d.ts
+//#region ../../packages/core/src/http/tracing/tracing-dispatcher.d.ts
 type ResolvedTracing = {
   configEnabled: boolean;
   hooks: TracingHooks[];

package/esm/http/tracing/tracing-dispatcher.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"tracing-dispatcher.d.mts","names":[],"sources":["../../../../../../../../core/src/http/tracing/tracing-dispatcher.ts"],"mappings":";;;KAmBK,eAAA;EACH,aAAA;EACA,KAAA,EAAO,YAAY;AAAA;;;;;;KAYT,oBAAA;EACV,OAAA;EACA,EAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;IAAU,IAAA;EAAA;AAAA;;;;;AAAI;iBAQA,oBAAA,IAAwB,eAAe;;iBAevC,gBAAA;;AAfuC;AAevD;;;;iBAYgB,oBAAA,CAAqB,KAAmB,EAAZ,YAAY;AAAxD;AAAA,iBAmBgB,0BAAA;;iBAQA,mBAAA,CAAoB,OAAA,EAAS,oBAAA,GAAuB,cAAc;AA3B1B;AAAA,iBA+ExC,oBAAA,CAAqB,GAAmB,EAAd,cAAc;;iBAexC,kBAAA,CAAmB,GAAA,EAAK,cAAA,EAAgB,MAAA,EAAQ,qBAAqB;;iBAerE,aAAA,CAAc,GAAA,EAAK,cAAA,EAAgB,KAAA,EAAO,gBAAgB"}
+{"version":3,"file":"tracing-dispatcher.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/tracing/tracing-dispatcher.ts"],"mappings":";;;KAmBK,eAAA;EACH,aAAA;EACA,KAAA,EAAO,YAAY;AAAA;;;;;;KAYT,oBAAA;EACV,OAAA;EACA,EAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;IAAU,IAAA;EAAA;AAAA;;;;;AAAI;iBAQA,oBAAA,IAAwB,eAAe;;iBAevC,gBAAA;;AAfuC;AAevD;;;;iBAYgB,oBAAA,CAAqB,KAAmB,EAAZ,YAAY;AAAxD;AAAA,iBAmBgB,0BAAA;;iBAQA,mBAAA,CAAoB,OAAA,EAAS,oBAAA,GAAuB,cAAc;AA3B1B;AAAA,iBA+ExC,oBAAA,CAAqB,GAAmB,EAAd,cAAc;;iBAexC,kBAAA,CAAmB,GAAA,EAAK,cAAA,EAAgB,MAAA,EAAQ,qBAAqB;;iBAerE,aAAA,CAAc,GAAA,EAAK,cAAA,EAAgB,KAAA,EAAO,gBAAgB"}

package/esm/http/tracing/tracing-dispatcher.mjs

@@ -1,7 +1,7 @@
 import config from "@mongez/config";
 import { log } from "@warlock.js/logger";
 
-//#region ../core/src/http/tracing/tracing-dispatcher.ts
+//#region ../../packages/core/src/http/tracing/tracing-dispatcher.ts
 /**
 * Tracing hook dispatch.
 *

package/esm/http/tracing/tracing-dispatcher.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"tracing-dispatcher.mjs","names":[],"sources":["../../../../../../../../core/src/http/tracing/tracing-dispatcher.ts"],"sourcesContent":["/**\n * Tracing hook dispatch.\n *\n * `http.tracing` is resolved once — lazily, on first read, then cached for\n * the life of the process — never per request. Every call site gates on\n * `isTracingEnabled()` BEFORE doing anything else (building a context\n * object, calling `performance.now()`), so a disabled app pays exactly one\n * boolean check per call site and never allocates the attrs/context payload.\n */\nimport config from \"@mongez/config\";\nimport { log } from \"@warlock.js/logger\";\nimport type {\n  HttpTracingConfig,\n  TracingContext,\n  TracingHooks,\n  TracingPhaseInfo,\n  TracingRequestEndInfo,\n} from \"./tracing.type\";\n\ntype ResolvedTracing = {\n  configEnabled: boolean;\n  hooks: TracingHooks[];\n};\n\nlet resolved: ResolvedTracing | undefined;\nlet tracingEnabled: boolean | undefined;\nlet runtimeHooks: TracingHooks[] = [];\n\n/**\n * Minimal request shape `buildTracingContext` needs. Kept structural (not a\n * `Request` import) so this module never creates an import cycle with\n * `../request`, which itself calls into this module.\n */\nexport type TracingContextSource = {\n  traceId: string;\n  id: string;\n  method: string;\n  path: string;\n  route?: { path: string };\n};\n\n/**\n * Resolve `http.tracing` once per process and cache it. Safe to call from\n * every hot-path call site — after the first call this is a plain field\n * read, no config lookup.\n */\nexport function resolveTracingConfig(): ResolvedTracing {\n  if (resolved) return resolved;\n\n  const tracing = config.get(\"http.tracing\", {} as HttpTracingConfig) ?? {};\n\n  resolved = {\n    configEnabled: tracing.enabled === true,\n    hooks: tracing.hooks ?? [],\n  };\n  tracingEnabled = resolved.configEnabled || runtimeHooks.length > 0;\n\n  return resolved;\n}\n\n/** The single boolean check every instrumented call site guards on. */\nexport function isTracingEnabled(): boolean {\n  if (tracingEnabled === undefined) resolveTracingConfig();\n\n  return tracingEnabled === true;\n}\n\n/**\n * Register request tracing hooks independently of `http.tracing` config.\n *\n * Runtime hooks are called after configured hooks. Registering a hook enables\n * tracing immediately; the returned function removes that registration.\n */\nexport function registerTracingHooks(hooks: TracingHooks): () => void {\n  runtimeHooks.push(hooks);\n  tracingEnabled = true;\n\n  let registered = true;\n\n  return () => {\n    if (!registered) return;\n\n    registered = false;\n    const index = runtimeHooks.indexOf(hooks);\n    if (index !== -1) runtimeHooks.splice(index, 1);\n\n    const { configEnabled } = resolveTracingConfig();\n    tracingEnabled = configEnabled || runtimeHooks.length > 0;\n  };\n}\n\n/** Test-only: resets resolved config and removes all runtime tracing hooks. */\nexport function resetTracingConfigForTests(): void {\n  resolved = undefined;\n  tracingEnabled = undefined;\n  runtimeHooks = [];\n  reportedHooks = new WeakMap();\n}\n\n/** Build the per-request context handed to every hook call. */\nexport function buildTracingContext(request: TracingContextSource): TracingContext {\n  return {\n    traceId: request.traceId,\n    requestId: request.id,\n    method: request.method,\n    route: request.route?.path,\n    path: request.path,\n  };\n}\n\n/**\n * Tracks which (hook, verb) pairs have already been reported, so a hook that\n * throws on every request is reported to the error sink exactly once per\n * process rather than flooding it.\n */\nlet reportedHooks = new WeakMap<TracingHooks, Set<string>>();\n\nfunction reportHookErrorOnce(hook: TracingHooks, verb: string, error: unknown): void {\n  let reportedVerbs = reportedHooks.get(hook);\n\n  if (!reportedVerbs) {\n    reportedVerbs = new Set();\n    reportedHooks.set(hook, reportedVerbs);\n  }\n\n  if (reportedVerbs.has(verb)) return;\n\n  reportedVerbs.add(verb);\n\n  // Never swallow the only copy of an error — but a throwing hook must never\n  // break the request it was only meant to observe, so this is reported, not\n  // re-thrown.\n  log.error(\"http\", \"tracing-hook\", error, { hook: verb });\n}\n\nfunction safeInvoke<Verb extends keyof TracingHooks>(\n  hook: TracingHooks,\n  verb: Verb,\n  invoke: (fn: NonNullable<TracingHooks[Verb]>) => void,\n): void {\n  const fn = hook[verb];\n\n  if (!fn) return;\n\n  try {\n    invoke(fn as NonNullable<TracingHooks[Verb]>);\n  } catch (error) {\n    reportHookErrorOnce(hook, verb, error);\n  }\n}\n\n/** Dispatch `onRequestStart` to every configured and runtime hook. No-op when disabled. */\nexport function dispatchRequestStart(ctx: TracingContext): void {\n  if (!isTracingEnabled()) return;\n\n  const { hooks } = resolveTracingConfig();\n\n  for (const hook of hooks) {\n    safeInvoke(hook, \"onRequestStart\", (fn) => fn(ctx));\n  }\n\n  for (const hook of runtimeHooks) {\n    safeInvoke(hook, \"onRequestStart\", (fn) => fn(ctx));\n  }\n}\n\n/** Dispatch `onRequestEnd` to every configured and runtime hook. No-op when disabled. */\nexport function dispatchRequestEnd(ctx: TracingContext, result: TracingRequestEndInfo): void {\n  if (!isTracingEnabled()) return;\n\n  const { hooks } = resolveTracingConfig();\n\n  for (const hook of hooks) {\n    safeInvoke(hook, \"onRequestEnd\", (fn) => fn(ctx, result));\n  }\n\n  for (const hook of runtimeHooks) {\n    safeInvoke(hook, \"onRequestEnd\", (fn) => fn(ctx, result));\n  }\n}\n\n/** Dispatch `onPhase` to every configured and runtime hook. No-op when disabled. */\nexport function dispatchPhase(ctx: TracingContext, phase: TracingPhaseInfo): void {\n  if (!isTracingEnabled()) return;\n\n  const { hooks } = resolveTracingConfig();\n  const phaseInfo =\n    phase.startedAt === undefined\n      ? {\n          ...phase,\n          startedAt: performance.timeOrigin + performance.now() - phase.durationMs,\n        }\n      : phase;\n\n  for (const hook of hooks) {\n    safeInvoke(hook, \"onPhase\", (fn) => fn(ctx, phaseInfo));\n  }\n\n  for (const hook of runtimeHooks) {\n    safeInvoke(hook, \"onPhase\", (fn) => fn(ctx, phaseInfo));\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"tracing-dispatcher.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/tracing/tracing-dispatcher.ts"],"sourcesContent":["/**\n * Tracing hook dispatch.\n *\n * `http.tracing` is resolved once — lazily, on first read, then cached for\n * the life of the process — never per request. Every call site gates on\n * `isTracingEnabled()` BEFORE doing anything else (building a context\n * object, calling `performance.now()`), so a disabled app pays exactly one\n * boolean check per call site and never allocates the attrs/context payload.\n */\nimport config from \"@mongez/config\";\nimport { log } from \"@warlock.js/logger\";\nimport type {\n  HttpTracingConfig,\n  TracingContext,\n  TracingHooks,\n  TracingPhaseInfo,\n  TracingRequestEndInfo,\n} from \"./tracing.type\";\n\ntype ResolvedTracing = {\n  configEnabled: boolean;\n  hooks: TracingHooks[];\n};\n\nlet resolved: ResolvedTracing | undefined;\nlet tracingEnabled: boolean | undefined;\nlet runtimeHooks: TracingHooks[] = [];\n\n/**\n * Minimal request shape `buildTracingContext` needs. Kept structural (not a\n * `Request` import) so this module never creates an import cycle with\n * `../request`, which itself calls into this module.\n */\nexport type TracingContextSource = {\n  traceId: string;\n  id: string;\n  method: string;\n  path: string;\n  route?: { path: string };\n};\n\n/**\n * Resolve `http.tracing` once per process and cache it. Safe to call from\n * every hot-path call site — after the first call this is a plain field\n * read, no config lookup.\n */\nexport function resolveTracingConfig(): ResolvedTracing {\n  if (resolved) return resolved;\n\n  const tracing = config.get(\"http.tracing\", {} as HttpTracingConfig) ?? {};\n\n  resolved = {\n    configEnabled: tracing.enabled === true,\n    hooks: tracing.hooks ?? [],\n  };\n  tracingEnabled = resolved.configEnabled || runtimeHooks.length > 0;\n\n  return resolved;\n}\n\n/** The single boolean check every instrumented call site guards on. */\nexport function isTracingEnabled(): boolean {\n  if (tracingEnabled === undefined) resolveTracingConfig();\n\n  return tracingEnabled === true;\n}\n\n/**\n * Register request tracing hooks independently of `http.tracing` config.\n *\n * Runtime hooks are called after configured hooks. Registering a hook enables\n * tracing immediately; the returned function removes that registration.\n */\nexport function registerTracingHooks(hooks: TracingHooks): () => void {\n  runtimeHooks.push(hooks);\n  tracingEnabled = true;\n\n  let registered = true;\n\n  return () => {\n    if (!registered) return;\n\n    registered = false;\n    const index = runtimeHooks.indexOf(hooks);\n    if (index !== -1) runtimeHooks.splice(index, 1);\n\n    const { configEnabled } = resolveTracingConfig();\n    tracingEnabled = configEnabled || runtimeHooks.length > 0;\n  };\n}\n\n/** Test-only: resets resolved config and removes all runtime tracing hooks. */\nexport function resetTracingConfigForTests(): void {\n  resolved = undefined;\n  tracingEnabled = undefined;\n  runtimeHooks = [];\n  reportedHooks = new WeakMap();\n}\n\n/** Build the per-request context handed to every hook call. */\nexport function buildTracingContext(request: TracingContextSource): TracingContext {\n  return {\n    traceId: request.traceId,\n    requestId: request.id,\n    method: request.method,\n    route: request.route?.path,\n    path: request.path,\n  };\n}\n\n/**\n * Tracks which (hook, verb) pairs have already been reported, so a hook that\n * throws on every request is reported to the error sink exactly once per\n * process rather than flooding it.\n */\nlet reportedHooks = new WeakMap<TracingHooks, Set<string>>();\n\nfunction reportHookErrorOnce(hook: TracingHooks, verb: string, error: unknown): void {\n  let reportedVerbs = reportedHooks.get(hook);\n\n  if (!reportedVerbs) {\n    reportedVerbs = new Set();\n    reportedHooks.set(hook, reportedVerbs);\n  }\n\n  if (reportedVerbs.has(verb)) return;\n\n  reportedVerbs.add(verb);\n\n  // Never swallow the only copy of an error — but a throwing hook must never\n  // break the request it was only meant to observe, so this is reported, not\n  // re-thrown.\n  log.error(\"http\", \"tracing-hook\", error, { hook: verb });\n}\n\nfunction safeInvoke<Verb extends keyof TracingHooks>(\n  hook: TracingHooks,\n  verb: Verb,\n  invoke: (fn: NonNullable<TracingHooks[Verb]>) => void,\n): void {\n  const fn = hook[verb];\n\n  if (!fn) return;\n\n  try {\n    invoke(fn as NonNullable<TracingHooks[Verb]>);\n  } catch (error) {\n    reportHookErrorOnce(hook, verb, error);\n  }\n}\n\n/** Dispatch `onRequestStart` to every configured and runtime hook. No-op when disabled. */\nexport function dispatchRequestStart(ctx: TracingContext): void {\n  if (!isTracingEnabled()) return;\n\n  const { hooks } = resolveTracingConfig();\n\n  for (const hook of hooks) {\n    safeInvoke(hook, \"onRequestStart\", (fn) => fn(ctx));\n  }\n\n  for (const hook of runtimeHooks) {\n    safeInvoke(hook, \"onRequestStart\", (fn) => fn(ctx));\n  }\n}\n\n/** Dispatch `onRequestEnd` to every configured and runtime hook. No-op when disabled. */\nexport function dispatchRequestEnd(ctx: TracingContext, result: TracingRequestEndInfo): void {\n  if (!isTracingEnabled()) return;\n\n  const { hooks } = resolveTracingConfig();\n\n  for (const hook of hooks) {\n    safeInvoke(hook, \"onRequestEnd\", (fn) => fn(ctx, result));\n  }\n\n  for (const hook of runtimeHooks) {\n    safeInvoke(hook, \"onRequestEnd\", (fn) => fn(ctx, result));\n  }\n}\n\n/** Dispatch `onPhase` to every configured and runtime hook. No-op when disabled. */\nexport function dispatchPhase(ctx: TracingContext, phase: TracingPhaseInfo): void {\n  if (!isTracingEnabled()) return;\n\n  const { hooks } = resolveTracingConfig();\n  const phaseInfo =\n    phase.startedAt === undefined\n      ? {\n          ...phase,\n          startedAt: performance.timeOrigin + performance.now() - phase.durationMs,\n        }\n      : phase;\n\n  for (const hook of hooks) {\n    safeInvoke(hook, \"onPhase\", (fn) => fn(ctx, phaseInfo));\n  }\n\n  for (const hook of runtimeHooks) {\n    safeInvoke(hook, \"onPhase\", (fn) => fn(ctx, phaseInfo));\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAwBA,IAAI;AACJ,IAAI;AACJ,IAAI,eAA+B,CAAC;;;;;;AAoBpC,SAAgB,uBAAwC;CACtD,IAAI,UAAU,OAAO;CAErB,MAAM,UAAU,OAAO,IAAI,gBAAgB,CAAC,CAAsB,KAAK,CAAC;CAExE,WAAW;EACT,eAAe,QAAQ,YAAY;EACnC,OAAO,QAAQ,SAAS,CAAC;CAC3B;CACA,iBAAiB,SAAS,iBAAiB,aAAa,SAAS;CAEjE,OAAO;AACT;;AAGA,SAAgB,mBAA4B;CAC1C,IAAI,mBAAmB,QAAW,qBAAqB;CAEvD,OAAO,mBAAmB;AAC5B;;;;;;;AAQA,SAAgB,qBAAqB,OAAiC;CACpE,aAAa,KAAK,KAAK;CACvB,iBAAiB;CAEjB,IAAI,aAAa;CAEjB,aAAa;EACX,IAAI,CAAC,YAAY;EAEjB,aAAa;EACb,MAAM,QAAQ,aAAa,QAAQ,KAAK;EACxC,IAAI,UAAU,IAAI,aAAa,OAAO,OAAO,CAAC;EAE9C,MAAM,EAAE,kBAAkB,qBAAqB;EAC/C,iBAAiB,iBAAiB,aAAa,SAAS;CAC1D;AACF;;AAGA,SAAgB,6BAAmC;CACjD,WAAW;CACX,iBAAiB;CACjB,eAAe,CAAC;CAChB,gCAAgB,IAAI,QAAQ;AAC9B;;AAGA,SAAgB,oBAAoB,SAA+C;CACjF,OAAO;EACL,SAAS,QAAQ;EACjB,WAAW,QAAQ;EACnB,QAAQ,QAAQ;EAChB,OAAO,QAAQ,OAAO;EACtB,MAAM,QAAQ;CAChB;AACF;;;;;;AAOA,IAAI,gCAAgB,IAAI,QAAmC;AAE3D,SAAS,oBAAoB,MAAoB,MAAc,OAAsB;CACnF,IAAI,gBAAgB,cAAc,IAAI,IAAI;CAE1C,IAAI,CAAC,eAAe;EAClB,gCAAgB,IAAI,IAAI;EACxB,cAAc,IAAI,MAAM,aAAa;CACvC;CAEA,IAAI,cAAc,IAAI,IAAI,GAAG;CAE7B,cAAc,IAAI,IAAI;CAKtB,IAAI,MAAM,QAAQ,gBAAgB,OAAO,EAAE,MAAM,KAAK,CAAC;AACzD;AAEA,SAAS,WACP,MACA,MACA,QACM;CACN,MAAM,KAAK,KAAK;CAEhB,IAAI,CAAC,IAAI;CAET,IAAI;EACF,OAAO,EAAqC;CAC9C,SAAS,OAAO;EACd,oBAAoB,MAAM,MAAM,KAAK;CACvC;AACF;;AAGA,SAAgB,qBAAqB,KAA2B;CAC9D,IAAI,CAAC,iBAAiB,GAAG;CAEzB,MAAM,EAAE,UAAU,qBAAqB;CAEvC,KAAK,MAAM,QAAQ,OACjB,WAAW,MAAM,mBAAmB,OAAO,GAAG,GAAG,CAAC;CAGpD,KAAK,MAAM,QAAQ,cACjB,WAAW,MAAM,mBAAmB,OAAO,GAAG,GAAG,CAAC;AAEtD;;AAGA,SAAgB,mBAAmB,KAAqB,QAAqC;CAC3F,IAAI,CAAC,iBAAiB,GAAG;CAEzB,MAAM,EAAE,UAAU,qBAAqB;CAEvC,KAAK,MAAM,QAAQ,OACjB,WAAW,MAAM,iBAAiB,OAAO,GAAG,KAAK,MAAM,CAAC;CAG1D,KAAK,MAAM,QAAQ,cACjB,WAAW,MAAM,iBAAiB,OAAO,GAAG,KAAK,MAAM,CAAC;AAE5D;;AAGA,SAAgB,cAAc,KAAqB,OAA+B;CAChF,IAAI,CAAC,iBAAiB,GAAG;CAEzB,MAAM,EAAE,UAAU,qBAAqB;CACvC,MAAM,YACJ,MAAM,cAAc,SAChB;EACE,GAAG;EACH,WAAW,YAAY,aAAa,YAAY,IAAI,IAAI,MAAM;CAChE,IACA;CAEN,KAAK,MAAM,QAAQ,OACjB,WAAW,MAAM,YAAY,OAAO,GAAG,KAAK,SAAS,CAAC;CAGxD,KAAK,MAAM,QAAQ,cACjB,WAAW,MAAM,YAAY,OAAO,GAAG,KAAK,SAAS,CAAC;AAE1D"}

package/esm/http/tracing/tracing.type.d.mts

@@ -1,4 +1,4 @@
-//#region ../core/src/http/tracing/tracing.type.d.ts
+//#region ../../packages/core/src/http/tracing/tracing.type.d.ts
 /**
  * Vendor-neutral request-tracing hook surface.
  *

package/esm/http/tracing/tracing.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.type.d.mts","names":[],"sources":["../../../../../../../../core/src/http/tracing/tracing.type.ts"],"mappings":";;AAkBA;;;;;;;;;;AAUM;AAIN;;;;;KAdY,cAAA;EAkBV;;;;EAbA,OAAA,UAkBU;EAhBV,SAAA;EACA,MAAA;EACA,KAAA;EACA,IAAA;AAAA;;KAIU,gBAAA;EACV,IAAA;EACA,UAAA,UAoBsB;EAlBtB,SAAA;EACA,KAAA,GAAQ,MAAM;AAAA;;KAIJ,qBAAA;EACV,MAAA;EACA,UAAA;EACA,KAAA;AAAA;;;;;;;;KAUU,YAAA;EACV,cAAA,EAAgB,GAAA,EAAK,cAAA;EACrB,YAAA,EAAc,GAAA,EAAK,cAAA,EAAgB,MAAA,EAAQ,qBAAA;EAC3C,OAAA,EAAS,GAAA,EAAK,cAAA,EAAgB,KAAA,EAAO,gBAAA;AAAA;;AAAgB;AASvD;;;;KAAY,iBAAA;EAGV,qBADA,OAAA;EACA,KAAA,GAAQ,YAAY;AAAA"}
+{"version":3,"file":"tracing.type.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/http/tracing/tracing.type.ts"],"mappings":";;AAkBA;;;;;;;;;;AAUM;AAIN;;;;;KAdY,cAAA;EAkBV;;;;EAbA,OAAA,UAkBU;EAhBV,SAAA;EACA,MAAA;EACA,KAAA;EACA,IAAA;AAAA;;KAIU,gBAAA;EACV,IAAA;EACA,UAAA,UAoBsB;EAlBtB,SAAA;EACA,KAAA,GAAQ,MAAM;AAAA;;KAIJ,qBAAA;EACV,MAAA;EACA,UAAA;EACA,KAAA;AAAA;;;;;;;;KAUU,YAAA;EACV,cAAA,EAAgB,GAAA,EAAK,cAAA;EACrB,YAAA,EAAc,GAAA,EAAK,cAAA,EAAgB,MAAA,EAAQ,qBAAA;EAC3C,OAAA,EAAS,GAAA,EAAK,cAAA,EAAgB,KAAA,EAAO,gBAAA;AAAA;;AAAgB;AASvD;;;;KAAY,iBAAA;EAGV,qBADA,OAAA;EACA,KAAA,GAAQ,YAAY;AAAA"}