@warlock.js/core 5.30.0 → 5.31.0

package/esm/http/lazy-static.mjs

@@ -0,0 +1,194 @@
+import path from "node:path";
+import { statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+//#region ../../packages/core/src/http/lazy-static.ts
+function optionError(field, message, valueError = false) {
+	return Object.assign(valueError ? /* @__PURE__ */ new TypeError(`"${field}" option ${message}`) : /* @__PURE__ */ new Error(`"${field}" option ${message}`), {
+		code: valueError ? "FST_STATIC_INVALID_OPTION_VALUE" : "FST_STATIC_INVALID_OPTION",
+		statusCode: 500
+	});
+}
+/** Validate without importing the plugin's directory-listing module. */
+function staticOptions(server, options) {
+	const root = options.root;
+	const normalize = (entry) => entry instanceof URL && entry.protocol === "file:" ? fileURLToPath(entry) : entry;
+	const normalized = Array.isArray(root) ? root.map(normalize) : root === void 0 ? void 0 : normalize(root);
+	if (options.serve !== false || normalized !== void 0) {
+		if (normalized === void 0) throw optionError("root", "is required");
+		if (Array.isArray(normalized) && normalized.length === 0) throw optionError("root", "array requires one or more paths");
+		if (Array.isArray(normalized) && new Set(normalized).size !== normalized.length) throw optionError("root", "array contains duplicate paths");
+		for (const entry of Array.isArray(normalized) ? normalized : [normalized]) {
+			if (typeof entry !== "string") throw optionError("root", "must be a string", true);
+			if (!path.isAbsolute(entry)) throw optionError("root", "must be an absolute path");
+			try {
+				if (!statSync(entry).isDirectory()) throw optionError("root", "must be a directory");
+			} catch (error) {
+				if (error.code !== "ENOENT") throw error;
+				if (!options.suppressWarning) server.log.warn(`"root" path "${entry}" must exist`);
+			}
+		}
+	}
+	if (options.setHeaders !== void 0 && typeof options.setHeaders !== "function") throw optionError("setHeaders", "must be a function", true);
+	if (options.serve !== false && options.wildcard && typeof options.wildcard !== "boolean") throw optionError("wildcard", "must be a boolean", true);
+	const list = options.list;
+	if (list) {
+		if (Array.isArray(normalized)) throw Object.assign(/* @__PURE__ */ new TypeError("multi-root with list option is not supported"), {
+			code: "FST_STATIC_MULTIROOT_LIST_CONFLICT",
+			statusCode: 500
+		});
+		if (typeof list === "object") {
+			if (list.format && list.format !== "json" && list.format !== "html") throw optionError("list.format", "must be json or html", true);
+			if (list.names && !Array.isArray(list.names)) throw optionError("list.names", "must be an array", true);
+			if (list.jsonFormat != null && list.jsonFormat !== "names" && list.jsonFormat !== "extended") throw optionError("list.jsonFormat", "must be names or extended", true);
+			if (list.format === "html" && typeof list.render !== "function") throw optionError("list.render", "must be a function and is required with html format", true);
+		}
+	}
+	return {
+		...options,
+		root: normalized
+	};
+}
+/** Mirror the plugin's boot-time route snapshot for wildcard:false. */
+async function fileRoutes(options, prefix) {
+	const { glob } = await import("glob");
+	const roots = Array.isArray(options.root) ? options.root : [options.root];
+	const routes = /* @__PURE__ */ new Map();
+	const indexes = new Set(options.index === void 0 ? ["index.html"] : options.index === false ? [] : [options.index].flat());
+	const indexDirectories = /* @__PURE__ */ new Map();
+	for (const root of roots) {
+		if (typeof root !== "string") continue;
+		const rootPath = root.split(path.win32.sep).join(path.posix.sep).replace(/\/?$/, "/");
+		const files = await glob("**/**", {
+			cwd: rootPath,
+			absolute: false,
+			follow: true,
+			nodir: true,
+			dot: options.serveDotFiles,
+			ignore: options.globIgnore
+		});
+		for (const fileName of files) {
+			const file = fileName.split(path.win32.sep).join(path.posix.sep);
+			const url = prefix + file;
+			if (routes.has(url)) continue;
+			routes.set(url, {
+				url,
+				file: `/${file}`,
+				rootPath
+			});
+			const key = path.posix.basename(url);
+			if (indexes.has(key) && !indexDirectories.has(key)) indexDirectories.set(path.posix.dirname(url), rootPath);
+		}
+	}
+	for (const [directory, rootPath] of indexDirectories) {
+		const url = directory + (directory.endsWith("/") ? "" : "/");
+		const file = "/" + url.replace(prefix, "");
+		routes.set(url, {
+			url,
+			file,
+			rootPath
+		});
+		if (options.redirect === true) routes.set(url.replace(/\/$/, ""), {
+			url: url.replace(/\/$/, ""),
+			file: file.replace(/\/$/, ""),
+			rootPath
+		});
+	}
+	return [...routes.values()];
+}
+/**
+* Queue public routes after earlier plugins, and capture upstream handlers on the
+* first file request. Only public Fastify methods are replaced on the facade;
+* the listening application's route/decorator table never changes after ready.
+*/
+function registerLazyStatic(server, input, mount = {}) {
+	const options = staticOptions(server, input);
+	server.register(Object.assign(async (instance) => prepareStatic(instance, options, mount), { [Symbol.for("skip-override")]: true }));
+}
+async function prepareStatic(server, options, mount) {
+	const originalPrefix = options.prefix ?? "/";
+	const prefix = options.prefixAvoidTrailingSlash || originalPrefix.endsWith("/") ? originalPrefix : `${originalPrefix}/`;
+	const handlers = /* @__PURE__ */ new Map();
+	const decorators = /* @__PURE__ */ new Map();
+	let initialized;
+	function initialize() {
+		return initialized ??= (async () => {
+			const facade = Object.create(server);
+			const capture = (route) => {
+				const url = route.url ?? route.path;
+				if (!url) throw new Error("Static plugin declared a route without a path.");
+				for (const method of [route.method].flat()) handlers.set(`${method} ${url}`, route.handler);
+				return facade;
+			};
+			Object.defineProperties(facade, {
+				route: { value: capture },
+				get: { value: (url, route, handler) => capture({
+					...route,
+					url,
+					method: ["GET", "HEAD"],
+					handler
+				}) },
+				decorateReply: { value: (name, handler) => {
+					decorators.set(name, handler);
+					return facade;
+				} }
+			});
+			const { default: staticPlugin } = await import("@fastify/static");
+			await staticPlugin(facade, {
+				...options,
+				decorateReply: true,
+				suppressWarning: true
+			});
+		})();
+	}
+	if (options.decorateReply !== false) for (const name of ["sendFile", "download"]) server.decorateReply(name, function(...args) {
+		initialize().then(() => {
+			const decorator = decorators.get(name);
+			if (!decorator) throw new Error(`Static plugin did not provide ${name}.`);
+			decorator.apply(this, args);
+		}).catch((error) => this.send(error));
+		return this;
+	});
+	if (options.serve === false) return;
+	const routes = options.wildcard === false ? await fileRoutes(options, prefix) : [{ url: prefix + "*" }];
+	if (options.wildcard !== false && options.redirect === true && prefix !== originalPrefix) routes.push({ url: originalPrefix });
+	const schema = { hide: options.schemaHide ?? true };
+	for (const route of routes) server.route({
+		url: route.url,
+		method: ["HEAD", "GET"],
+		constraints: options.constraints,
+		schema,
+		logLevel: options.logLevel,
+		config: {
+			...route.file ? {
+				file: route.file,
+				rootPath: route.rootPath
+			} : {},
+			...mount.rateLimit !== void 0 ? { rateLimit: mount.rateLimit } : {}
+		},
+		errorHandler(error, request, reply) {
+			if (error?.code === "ERR_STREAM_PREMATURE_CLOSE") {
+				reply.request.raw.destroy();
+				return;
+			}
+			return server.errorHandler(error, request, reply);
+		},
+		async handler(request, reply) {
+			await initialize();
+			const handler = handlers.get(`${request.method} ${route.url}`);
+			if (handler) {
+				await handler.call(server, request, reply);
+				return reply;
+			}
+			if (route.file) {
+				const sendFile = decorators.get("sendFile");
+				if (sendFile) return sendFile.call(reply, route.file, route.rootPath);
+			}
+			return reply.callNotFound();
+		}
+	});
+}
+
+//#endregion
+export { registerLazyStatic };
+//# sourceMappingURL=lazy-static.mjs.map

package/esm/http/lazy-static.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-static.mjs","names":[],"sources":["../../../../../../../../packages/core/src/http/lazy-static.ts"],"sourcesContent":["import type { FastifyStaticOptions } from \"@fastify/static\";\nimport { statSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport type {\n  FastifyInstance,\n  FastifyReply,\n  FastifyRequest,\n  FastifySchema,\n  RouteHandlerMethod,\n  RouteOptions,\n} from \"fastify\";\n\ntype FileRoute = { url: string; file?: string; rootPath?: string };\ntype ReplyDecorator = (this: FastifyReply, ...args: unknown[]) => FastifyReply;\n\nfunction optionError(field: string, message: string, valueError = false): Error {\n  return Object.assign(\n    valueError\n      ? new TypeError(`\"${field}\" option ${message}`)\n      : new Error(`\"${field}\" option ${message}`),\n    {\n      code: valueError ? \"FST_STATIC_INVALID_OPTION_VALUE\" : \"FST_STATIC_INVALID_OPTION\",\n      statusCode: 500,\n    },\n  );\n}\n\n/** Validate without importing the plugin's directory-listing module. */\nfunction staticOptions(\n  server: FastifyInstance,\n  options: FastifyStaticOptions,\n): FastifyStaticOptions {\n  const root = options.root;\n  const normalize = (entry: string | URL): string | URL =>\n    entry instanceof URL && entry.protocol === \"file:\" ? fileURLToPath(entry) : entry;\n  const normalized = Array.isArray(root)\n    ? root.map(normalize)\n    : root === undefined\n      ? undefined\n      : normalize(root);\n  if (options.serve !== false || normalized !== undefined) {\n    if (normalized === undefined) throw optionError(\"root\", \"is required\");\n    if (Array.isArray(normalized) && normalized.length === 0)\n      throw optionError(\"root\", \"array requires one or more paths\");\n    if (Array.isArray(normalized) && new Set(normalized).size !== normalized.length)\n      throw optionError(\"root\", \"array contains duplicate paths\");\n    for (const entry of Array.isArray(normalized) ? normalized : [normalized]) {\n      if (typeof entry !== \"string\") throw optionError(\"root\", \"must be a string\", true);\n      if (!path.isAbsolute(entry)) throw optionError(\"root\", \"must be an absolute path\");\n      try {\n        if (!statSync(entry).isDirectory()) throw optionError(\"root\", \"must be a directory\");\n      } catch (error) {\n        if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n        if (!options.suppressWarning) server.log.warn(`\"root\" path \"${entry}\" must exist`);\n      }\n    }\n  }\n  if (options.setHeaders !== undefined && typeof options.setHeaders !== \"function\")\n    throw optionError(\"setHeaders\", \"must be a function\", true);\n  if (options.serve !== false && options.wildcard && typeof options.wildcard !== \"boolean\")\n    throw optionError(\"wildcard\", \"must be a boolean\", true);\n  const list = options.list;\n  if (list) {\n    if (Array.isArray(normalized))\n      throw Object.assign(new TypeError(\"multi-root with list option is not supported\"), {\n        code: \"FST_STATIC_MULTIROOT_LIST_CONFLICT\",\n        statusCode: 500,\n      });\n    if (typeof list === \"object\") {\n      if (list.format && list.format !== \"json\" && list.format !== \"html\")\n        throw optionError(\"list.format\", \"must be json or html\", true);\n      if (list.names && !Array.isArray(list.names))\n        throw optionError(\"list.names\", \"must be an array\", true);\n      if (list.jsonFormat != null && list.jsonFormat !== \"names\" && list.jsonFormat !== \"extended\")\n        throw optionError(\"list.jsonFormat\", \"must be names or extended\", true);\n      if (list.format === \"html\" && typeof list.render !== \"function\")\n        throw optionError(\n          \"list.render\",\n          \"must be a function and is required with html format\",\n          true,\n        );\n    }\n  }\n  return { ...options, root: normalized } as FastifyStaticOptions;\n}\n\n/** Mirror the plugin's boot-time route snapshot for wildcard:false. */\nasync function fileRoutes(options: FastifyStaticOptions, prefix: string): Promise<FileRoute[]> {\n  const { glob } = await import(\"glob\");\n  const roots = Array.isArray(options.root) ? options.root : [options.root];\n  const routes = new Map<string, FileRoute>();\n  const indexes = new Set(\n    options.index === undefined\n      ? [\"index.html\"]\n      : options.index === false\n        ? []\n        : [options.index].flat(),\n  );\n  const indexDirectories = new Map<string, string>();\n  for (const root of roots) {\n    if (typeof root !== \"string\") continue;\n    const rootPath = root.split(path.win32.sep).join(path.posix.sep).replace(/\\/?$/, \"/\");\n    const files = await glob(\"**/**\", {\n      cwd: rootPath,\n      absolute: false,\n      follow: true,\n      nodir: true,\n      dot: options.serveDotFiles,\n      ignore: options.globIgnore,\n    });\n    for (const fileName of files) {\n      const file = fileName.split(path.win32.sep).join(path.posix.sep);\n      const url = prefix + file;\n      if (routes.has(url)) continue;\n      routes.set(url, { url, file: `/${file}`, rootPath });\n      // Match upstream: distinct index filenames in later roots replace the\n      // directory route, while duplicate file URLs keep the first root.\n      const key = path.posix.basename(url);\n      if (indexes.has(key) && !indexDirectories.has(key))\n        indexDirectories.set(path.posix.dirname(url), rootPath);\n    }\n  }\n  for (const [directory, rootPath] of indexDirectories) {\n    const url = directory + (directory.endsWith(\"/\") ? \"\" : \"/\");\n    const file = \"/\" + url.replace(prefix, \"\");\n    routes.set(url, { url, file, rootPath });\n    if (options.redirect === true)\n      routes.set(url.replace(/\\/$/, \"\"), {\n        url: url.replace(/\\/$/, \"\"),\n        file: file.replace(/\\/$/, \"\"),\n        rootPath,\n      });\n  }\n  return [...routes.values()];\n}\n\n/**\n * Queue public routes after earlier plugins, and capture upstream handlers on the\n * first file request. Only public Fastify methods are replaced on the facade;\n * the listening application's route/decorator table never changes after ready.\n */\nexport function registerLazyStatic(\n  server: FastifyInstance,\n  input: FastifyStaticOptions,\n  mount: LazyStaticMount = {},\n): void {\n  const options = staticOptions(server, input);\n  // Earlier plugins install onRoute hooks (including global rate limiting).\n  // Keep the decorators on the calling scope, as @fastify/static does.\n  server.register(\n    Object.assign(async (instance: FastifyInstance) => prepareStatic(instance, options, mount), {\n      [Symbol.for(\"skip-override\")]: true,\n    }),\n  );\n}\n\n/**\n * How the file routes of one static mount meet the rate limiter.\n */\nexport type LazyStaticMount = {\n  /**\n   * The `config.rateLimit` of every file route: `false` exempts the mount\n   * from the global limiter, an object gives it its own limit, and\n   * `undefined` leaves it under the global policy.\n   */\n  rateLimit?: false | Record<string, unknown>;\n};\n\nasync function prepareStatic(\n  server: FastifyInstance,\n  options: FastifyStaticOptions,\n  mount: LazyStaticMount,\n): Promise<void> {\n  const originalPrefix = options.prefix ?? \"/\";\n  const prefix =\n    options.prefixAvoidTrailingSlash || originalPrefix.endsWith(\"/\")\n      ? originalPrefix\n      : `${originalPrefix}/`;\n  const handlers = new Map<string, RouteHandlerMethod>();\n  const decorators = new Map<string, ReplyDecorator>();\n  let initialized: Promise<void> | undefined;\n\n  function initialize(): Promise<void> {\n    return (initialized ??= (async () => {\n      const facade = Object.create(server) as FastifyInstance;\n      const capture = (route: RouteOptions): FastifyInstance => {\n        const url = route.url ?? (route as RouteOptions & { path?: string }).path;\n        if (!url) throw new Error(\"Static plugin declared a route without a path.\");\n        for (const method of [route.method].flat()) handlers.set(`${method} ${url}`, route.handler);\n        return facade;\n      };\n      Object.defineProperties(facade, {\n        route: { value: capture },\n        get: {\n          value: (\n            url: string,\n            route: Omit<RouteOptions, \"method\" | \"url\" | \"handler\">,\n            handler: RouteHandlerMethod,\n          ) => capture({ ...route, url, method: [\"GET\", \"HEAD\"], handler }),\n        },\n        decorateReply: {\n          value: (name: string, handler: ReplyDecorator) => {\n            decorators.set(name, handler);\n            return facade;\n          },\n        },\n      });\n      const { default: staticPlugin } = await import(\"@fastify/static\");\n      await staticPlugin(facade, { ...options, decorateReply: true, suppressWarning: true });\n    })());\n  }\n\n  if (options.decorateReply !== false) {\n    for (const name of [\"sendFile\", \"download\"]) {\n      server.decorateReply(name, function (this: FastifyReply, ...args: unknown[]) {\n        void initialize()\n          .then(() => {\n            const decorator = decorators.get(name);\n            if (!decorator) throw new Error(`Static plugin did not provide ${name}.`);\n            decorator.apply(this, args);\n          })\n          .catch((error: unknown) => this.send(error));\n        return this;\n      });\n    }\n  }\n  if (options.serve === false) return;\n  const routes: FileRoute[] =\n    options.wildcard === false ? await fileRoutes(options, prefix) : [{ url: prefix + \"*\" }];\n  if (options.wildcard !== false && options.redirect === true && prefix !== originalPrefix)\n    routes.push({ url: originalPrefix });\n  const schema: FastifySchema & { hide: boolean } = { hide: options.schemaHide ?? true };\n  for (const route of routes) {\n    server.route({\n      url: route.url,\n      method: [\"HEAD\", \"GET\"],\n      constraints: options.constraints,\n      schema,\n      logLevel: options.logLevel,\n      config: {\n        ...(route.file ? { file: route.file, rootPath: route.rootPath } : {}),\n        ...(mount.rateLimit !== undefined ? { rateLimit: mount.rateLimit } : {}),\n      },\n      errorHandler(error, request, reply) {\n        if (error?.code === \"ERR_STREAM_PREMATURE_CLOSE\") {\n          reply.request.raw.destroy();\n          return;\n        }\n        return server.errorHandler(error, request, reply);\n      },\n      async handler(request: FastifyRequest, reply: FastifyReply) {\n        await initialize();\n        const handler = handlers.get(`${request.method} ${route.url}`);\n        if (handler) {\n          await handler.call(server, request, reply);\n          // Some upstream handlers start an async send without returning its\n          // promise. Returning the real reply keeps Fastify from auto-sending.\n          return reply;\n        }\n        // A wildcard:false file may disappear between boot and the first request.\n        if (route.file) {\n          const sendFile = decorators.get(\"sendFile\");\n          if (sendFile) return sendFile.call(reply, route.file, route.rootPath);\n        }\n        return reply.callNotFound();\n      },\n    });\n  }\n}\n"],"mappings":"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"}

package/esm/http/middleware/idempotency.middleware.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency.middleware.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/middleware/idempotency.middleware.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport type { Middleware } from \"../../router\";\nimport { HttpErrorCodes } from \"../error-codes\";\nimport type { Response } from \"../response\";\nimport { t } from \"./inject-request-context\";\nimport { buildIdempotencyCacheKey, hashBody, isValidIdempotencyKey } from \"./utils/idempotency-key\";\n\n/**\n * Options for the idempotency middleware.\n */\nexport type IdempotencyOptions = {\n  /**\n   * Cache TTL in seconds. Falls back to `http.idempotency.ttl`, then `86400` (24h).\n   */\n  ttl?: number;\n  /**\n   * TTL in seconds of the in-flight reservation held while the handler runs.\n   * Falls back to `http.idempotency.reservationTtl`, then `60`.\n   */\n  reservationTtl?: number;\n  /**\n   * Header name carrying the client's key. Falls back to\n   * `http.idempotency.headerName`, then `\"Idempotency-Key\"`.\n   */\n  headerName?: string;\n  /**\n   * HTTP methods eligible for idempotency. Falls back to\n   * `http.idempotency.methods`, then `[\"POST\",\"PUT\",\"PATCH\",\"DELETE\"]`.\n   * Safe methods (GET/HEAD) are skipped regardless.\n   */\n  methods?: string[];\n  /**\n   * Cache driver name. Falls back to `http.idempotency.driver`, then the\n   * default driver of the cache manager.\n   */\n  driver?: string;\n};\n\ntype CachedResponse = {\n  status: number;\n  body: unknown;\n  bodyHash: string;\n  contentType?: string;\n};\n\ntype InFlightReservation = {\n  state: \"in-flight\";\n  startedAt: number;\n};\n\nconst DEFAULT_METHODS = [\"POST\", \"PUT\", \"PATCH\", \"DELETE\"];\n\n/**\n * Dedupe non-idempotent writes by an `Idempotency-Key` header — same key,\n * same body, within TTL → cached replay; same key, different body → 422\n * `IdempotencyKeyConflict`.\n *\n * **Must run after `authMiddleware`** — the cache key is scoped per-user\n * (`idem:{userType}:{userId}:{key}`) so user A can't replay user B's key.\n * Anonymous requests fall back to IP scope.\n *\n * The replay sets `Idempotent-Replay: true` on the response for easy\n * client-side / observability detection.\n *\n * Eligible methods default to POST/PUT/PATCH/DELETE. GET/HEAD pass through\n * even with the header set (RFC: safe methods are already idempotent).\n *\n * @example\n * import { authMiddleware } from \"@warlock.js/auth\";\n * import { middleware } from \"@warlock.js/core\";\n *\n * router.post(\"/orders\", createOrderController, {\n *   middleware: [authMiddleware(\"client\"), middleware.idempotency()],\n * });\n *\n * router.post(\"/ai/summarize\", summarizeController, {\n *   middleware: [\n *     authMiddleware(\"client\"),\n *     middleware.idempotency({ ttl: 60 * 60 }), // 1h is enough for client retries\n *   ],\n * });\n */\nexport function idempotencyMiddleware(options: IdempotencyOptions = {}): Middleware {\n  return async ({ request, response }) => {\n    const headerName =\n      options.headerName || config.get(\"http.idempotency.headerName\", \"Idempotency-Key\");\n    const methods = options.methods || config.get(\"http.idempotency.methods\", DEFAULT_METHODS);\n    const ttl = options.ttl || config.get(\"http.idempotency.ttl\", 86400);\n    const reservationTtl =\n      options.reservationTtl || config.get(\"http.idempotency.reservationTtl\", 60);\n    const driverName = options.driver || config.get(\"http.idempotency.driver\");\n\n    if (!methods.includes(request.method.toUpperCase())) return;\n\n    const idempotencyKey = request.header(headerName.toLowerCase());\n\n    if (!idempotencyKey) return;\n\n    if (!isValidIdempotencyKey(idempotencyKey)) {\n      return response.badRequest({\n        error: t(\"http.idempotencyKeyInvalid\"),\n        errorCode: HttpErrorCodes.IdempotencyKeyInvalid,\n      });\n    }\n\n    const cacheDriver = driverName ? await cache.use(driverName) : cache;\n    const cacheKey = buildIdempotencyCacheKey(request, idempotencyKey);\n    const bodyHash = hashBody(request.body);\n\n    const respondToExisting = (existing: CachedResponse | InFlightReservation | undefined | null) => {\n      if (!existing || (existing as InFlightReservation).state === \"in-flight\") {\n        response.header(\"Retry-After\", \"1\");\n\n        return response.conflict({\n          error: \"A request with this Idempotency-Key is already in progress\",\n          errorCode: HttpErrorCodes.IdempotencyKeyConflict,\n        });\n      }\n\n      const cached = existing as CachedResponse;\n\n      if (cached.bodyHash !== bodyHash) {\n        return response.unprocessableEntity({\n          error: t(\"http.idempotencyKeyConflict\"),\n          errorCode: HttpErrorCodes.IdempotencyKeyConflict,\n        });\n      }\n\n      response.header(\"Idempotent-Replay\", \"true\");\n\n      return response.replay({\n        status: cached.status,\n        body: cached.body,\n        contentType: cached.contentType,\n      });\n    };\n\n    // Fast path: a finished (or in-flight) request is already recorded.\n    let existing: CachedResponse | InFlightReservation | null = null;\n\n    try {\n      existing = (await cacheDriver.get(cacheKey)) as CachedResponse | InFlightReservation | null;\n    } catch (error) {\n      // The cache is an optimisation of idempotency, not a gate on writes:\n      // when it is down, fail open (the handler runs) and log it.\n      log.error(\"idempotency-middleware\", \"get\", error);\n    }\n\n    if (existing) return respondToExisting(existing);\n\n    // Reserve the key atomically before the handler runs, so concurrent\n    // requests with the same key can't both execute it.\n    try {\n      const reservation = (await cacheDriver.set(\n        cacheKey,\n        { state: \"in-flight\", startedAt: Date.now() } satisfies InFlightReservation,\n        { onConflict: \"create\", ttl: reservationTtl },\n      )) as { wasSet?: boolean; existing?: CachedResponse | InFlightReservation } | undefined;\n\n      if (reservation && reservation.wasSet === false) {\n        return respondToExisting(reservation.existing);\n      }\n    } catch (error) {\n      log.error(\"idempotency-middleware\", \"reserve\", error);\n    }\n\n    response.onSent((sentResponse: Response) => {\n      // Don't cache server errors — clients should be able to retry past a 5xx.\n      // 4xx are deterministic outcomes of the request, so caching is fine.\n      // Free the reservation so a retry can run.\n      if (sentResponse.statusCode >= 500) {\n        // Wrapped so a synchronous throw is caught as well as a rejection.\n        Promise.resolve()\n          .then(() => cacheDriver.remove(cacheKey))\n          .catch((error: unknown) => {\n            log.error(\"idempotency-middleware\", \"remove\", error);\n          });\n\n        return;\n      }\n\n      const sentContentType = sentResponse.contentType;\n\n      // `set` is fire-and-forget inside `onSent`; without a `.catch` a rejected\n      // write (e.g. Redis down) would surface as an unhandledRejection.\n      cacheDriver\n        .set(\n          cacheKey,\n          {\n            status: sentResponse.statusCode,\n            body: sentResponse.parsedBody,\n            bodyHash,\n            contentType: typeof sentContentType === \"string\" ? sentContentType : undefined,\n          },\n          ttl,\n        )\n        .catch((error: unknown) => {\n          log.error(\"idempotency-middleware\", \"set\", error);\n        });\n    });\n  };\n}\n"],"mappings":";;;;;;;;AAoDA,MAAM,kBAAkB;CAAC;CAAQ;CAAO;CAAS;AAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCzD,SAAgB,sBAAsB,UAA8B,CAAC,GAAe;CAClF,OAAO,OAAO,EAAE,SAAS,eAAe;EACtC,MAAM,aACJ,QAAQ,cAAc,OAAO,IAAI,+BAA+B,iBAAiB;EACnF,MAAM,UAAU,QAAQ,WAAW,OAAO,IAAI,4BAA4B,eAAe;EACzF,MAAM,MAAM,QAAQ,OAAO,OAAO,IAAI,wBAAwB,KAAK;EACnE,MAAM,iBACJ,QAAQ,kBAAkB,OAAO,IAAI,mCAAmC,EAAE;EAC5E,MAAM,aAAa,QAAQ,UAAU,OAAO,IAAI,yBAAyB;EAEzE,IAAI,CAAC,QAAQ,SAAS,QAAQ,OAAO,YAAY,CAAC,GAAG;EAErD,MAAM,iBAAiB,QAAQ,OAAO,WAAW,YAAY,CAAC;EAE9D,IAAI,CAAC,gBAAgB;EAErB,IAAI,CAAC,sBAAsB,cAAc,GACvC,OAAO,SAAS,WAAW;GACzB,OAAO,EAAE,4BAA4B;GACrC;EACF,CAAC;EAGH,MAAM,cAAc,aAAa,MAAM,MAAM,IAAI,UAAU,IAAI;EAC/D,MAAM,WAAW,yBAAyB,SAAS,cAAc;EACjE,MAAM,WAAW,SAAS,QAAQ,IAAI;EAEtC,MAAM,qBAAqB,aAAsE;GAC/F,IAAI,CAAC,YAAa,SAAiC,UAAU,aAAa;IACxE,SAAS,OAAO,eAAe,GAAG;IAElC,OAAO,SAAS,SAAS;KACvB,OAAO;KACP;IACF,CAAC;GACH;GAEA,MAAM,SAAS;GAEf,IAAI,OAAO,aAAa,UACtB,OAAO,SAAS,oBAAoB;IAClC,OAAO,EAAE,6BAA6B;IACtC;GACF,CAAC;GAGH,SAAS,OAAO,qBAAqB,MAAM;GAE3C,OAAO,SAAS,OAAO;IACrB,QAAQ,OAAO;IACf,MAAM,OAAO;IACb,aAAa,OAAO;GACtB,CAAC;EACH;EAGA,IAAI,WAAwD;EAE5D,IAAI;GACF,WAAY,MAAM,YAAY,IAAI,QAAQ;EAC5C,SAAS,OAAO;GAGd,IAAI,MAAM,0BAA0B,OAAO,KAAK;EAClD;EAEA,IAAI,UAAU,OAAO,kBAAkB,QAAQ;EAI/C,IAAI;GACF,MAAM,cAAe,MAAM,YAAY,IACrC,UACA;IAAE,OAAO;IAAa,WAAW,KAAK,IAAI;GAAE,GAC5C;IAAE,YAAY;IAAU,KAAK;GAAe,CAC9C;GAEA,IAAI,eAAe,YAAY,WAAW,OACxC,OAAO,kBAAkB,YAAY,QAAQ;EAEjD,SAAS,OAAO;GACd,IAAI,MAAM,0BAA0B,WAAW,KAAK;EACtD;EAEA,SAAS,QAAQ,iBAA2B;GAI1C,IAAI,aAAa,cAAc,KAAK;IAElC,QAAQ,QAAQ,CAAC,CACd,WAAW,YAAY,OAAO,QAAQ,CAAC,CAAC,CACxC,OAAO,UAAmB;KACzB,IAAI,MAAM,0BAA0B,UAAU,KAAK;IACrD,CAAC;IAEH;GACF;GAEA,MAAM,kBAAkB,aAAa;GAIrC,YACG,IACC,UACA;IACE,QAAQ,aAAa;IACrB,MAAM,aAAa;IACnB;IACA,aAAa,OAAO,oBAAoB,WAAW,kBAAkB;GACvE,GACA,GACF,CAAC,CACA,OAAO,UAAmB;IACzB,IAAI,MAAM,0BAA0B,OAAO,KAAK;GAClD,CAAC;EACL,CAAC;CACH;AACF"}
+{"version":3,"file":"idempotency.middleware.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/middleware/idempotency.middleware.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport type { Middleware } from \"../../router\";\nimport { HttpErrorCodes } from \"../error-codes\";\nimport type { Response } from \"../response\";\nimport { t } from \"./inject-request-context\";\nimport { buildIdempotencyCacheKey, hashBody, isValidIdempotencyKey } from \"./utils/idempotency-key\";\n\n/**\n * Options for the idempotency middleware.\n */\nexport type IdempotencyOptions = {\n  /**\n   * Cache TTL in seconds. Falls back to `http.idempotency.ttl`, then `86400` (24h).\n   */\n  ttl?: number;\n  /**\n   * TTL in seconds of the in-flight reservation held while the handler runs.\n   * Falls back to `http.idempotency.reservationTtl`, then `60`.\n   */\n  reservationTtl?: number;\n  /**\n   * Header name carrying the client's key. Falls back to\n   * `http.idempotency.headerName`, then `\"Idempotency-Key\"`.\n   */\n  headerName?: string;\n  /**\n   * HTTP methods eligible for idempotency. Falls back to\n   * `http.idempotency.methods`, then `[\"POST\",\"PUT\",\"PATCH\",\"DELETE\"]`.\n   * Safe methods (GET/HEAD) are skipped regardless.\n   */\n  methods?: string[];\n  /**\n   * Cache driver name. Falls back to `http.idempotency.driver`, then the\n   * default driver of the cache manager.\n   */\n  driver?: string;\n};\n\ntype CachedResponse = {\n  status: number;\n  body: unknown;\n  bodyHash: string;\n  contentType?: string;\n};\n\ntype InFlightReservation = {\n  state: \"in-flight\";\n  startedAt: number;\n};\n\nconst DEFAULT_METHODS = [\"POST\", \"PUT\", \"PATCH\", \"DELETE\"];\n\n/**\n * Dedupe non-idempotent writes by an `Idempotency-Key` header — same key,\n * same body, within TTL → cached replay; same key, different body → 422\n * `IdempotencyKeyConflict`.\n *\n * **Must run after `authMiddleware`** — the cache key is scoped per-user\n * (`idem:{userType}:{userId}:{key}`) so user A can't replay user B's key.\n * Anonymous requests fall back to IP scope.\n *\n * The replay sets `Idempotent-Replay: true` on the response for easy\n * client-side / observability detection.\n *\n * Eligible methods default to POST/PUT/PATCH/DELETE. GET/HEAD pass through\n * even with the header set (RFC: safe methods are already idempotent).\n *\n * @example\n * import { authMiddleware } from \"@warlock.js/auth\";\n * import { middleware } from \"@warlock.js/core\";\n *\n * router.post(\"/orders\", createOrderController, {\n *   middleware: [authMiddleware(\"client\"), middleware.idempotency()],\n * });\n *\n * router.post(\"/ai/summarize\", summarizeController, {\n *   middleware: [\n *     authMiddleware(\"client\"),\n *     middleware.idempotency({ ttl: 60 * 60 }), // 1h is enough for client retries\n *   ],\n * });\n */\nexport function idempotencyMiddleware(options: IdempotencyOptions = {}): Middleware {\n  return async ({ request, response }) => {\n    const headerName =\n      options.headerName || config.get(\"http.idempotency.headerName\", \"Idempotency-Key\");\n    const methods = options.methods || config.get(\"http.idempotency.methods\", DEFAULT_METHODS);\n    const ttl = options.ttl || config.get(\"http.idempotency.ttl\", 86400);\n    const reservationTtl =\n      options.reservationTtl || config.get(\"http.idempotency.reservationTtl\", 60);\n    const driverName = options.driver || config.get(\"http.idempotency.driver\");\n\n    if (!methods.includes(request.method.toUpperCase())) return;\n\n    const idempotencyKey = request.header(headerName.toLowerCase());\n\n    if (!idempotencyKey) return;\n\n    if (!isValidIdempotencyKey(idempotencyKey)) {\n      return response.badRequest({\n        error: t(\"http.idempotencyKeyInvalid\"),\n        errorCode: HttpErrorCodes.IdempotencyKeyInvalid,\n      });\n    }\n\n    const cacheDriver = driverName ? await cache.use(driverName) : cache;\n    const cacheKey = buildIdempotencyCacheKey(request, idempotencyKey);\n    const bodyHash = hashBody(request.body);\n\n    const respondToExisting = (\n      existing: CachedResponse | InFlightReservation | undefined | null,\n    ) => {\n      if (!existing || (existing as InFlightReservation).state === \"in-flight\") {\n        response.header(\"Retry-After\", \"1\");\n\n        return response.conflict({\n          error: \"A request with this Idempotency-Key is already in progress\",\n          errorCode: HttpErrorCodes.IdempotencyKeyConflict,\n        });\n      }\n\n      const cached = existing as CachedResponse;\n\n      if (cached.bodyHash !== bodyHash) {\n        return response.unprocessableEntity({\n          error: t(\"http.idempotencyKeyConflict\"),\n          errorCode: HttpErrorCodes.IdempotencyKeyConflict,\n        });\n      }\n\n      response.header(\"Idempotent-Replay\", \"true\");\n\n      return response.replay({\n        status: cached.status,\n        body: cached.body,\n        contentType: cached.contentType,\n      });\n    };\n\n    // Fast path: a finished (or in-flight) request is already recorded.\n    let existing: CachedResponse | InFlightReservation | null = null;\n\n    try {\n      existing = (await cacheDriver.get(cacheKey)) as CachedResponse | InFlightReservation | null;\n    } catch (error) {\n      // The cache is an optimisation of idempotency, not a gate on writes:\n      // when it is down, fail open (the handler runs) and log it.\n      log.error(\"idempotency-middleware\", \"get\", error);\n    }\n\n    if (existing) return respondToExisting(existing);\n\n    // Reserve the key atomically before the handler runs, so concurrent\n    // requests with the same key can't both execute it.\n    try {\n      const reservation = (await cacheDriver.set(\n        cacheKey,\n        { state: \"in-flight\", startedAt: Date.now() } satisfies InFlightReservation,\n        { onConflict: \"create\", ttl: reservationTtl },\n      )) as { wasSet?: boolean; existing?: CachedResponse | InFlightReservation } | undefined;\n\n      if (reservation && reservation.wasSet === false) {\n        return respondToExisting(reservation.existing);\n      }\n    } catch (error) {\n      log.error(\"idempotency-middleware\", \"reserve\", error);\n    }\n\n    response.onSent((sentResponse: Response) => {\n      // Don't cache server errors — clients should be able to retry past a 5xx.\n      // 4xx are deterministic outcomes of the request, so caching is fine.\n      // Free the reservation so a retry can run.\n      if (sentResponse.statusCode >= 500) {\n        // Wrapped so a synchronous throw is caught as well as a rejection.\n        Promise.resolve()\n          .then(() => cacheDriver.remove(cacheKey))\n          .catch((error: unknown) => {\n            log.error(\"idempotency-middleware\", \"remove\", error);\n          });\n\n        return;\n      }\n\n      const sentContentType = sentResponse.contentType;\n\n      // `set` is fire-and-forget inside `onSent`; without a `.catch` a rejected\n      // write (e.g. Redis down) would surface as an unhandledRejection.\n      cacheDriver\n        .set(\n          cacheKey,\n          {\n            status: sentResponse.statusCode,\n            body: sentResponse.parsedBody,\n            bodyHash,\n            contentType: typeof sentContentType === \"string\" ? sentContentType : undefined,\n          },\n          ttl,\n        )\n        .catch((error: unknown) => {\n          log.error(\"idempotency-middleware\", \"set\", error);\n        });\n    });\n  };\n}\n"],"mappings":";;;;;;;;AAoDA,MAAM,kBAAkB;CAAC;CAAQ;CAAO;CAAS;AAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCzD,SAAgB,sBAAsB,UAA8B,CAAC,GAAe;CAClF,OAAO,OAAO,EAAE,SAAS,eAAe;EACtC,MAAM,aACJ,QAAQ,cAAc,OAAO,IAAI,+BAA+B,iBAAiB;EACnF,MAAM,UAAU,QAAQ,WAAW,OAAO,IAAI,4BAA4B,eAAe;EACzF,MAAM,MAAM,QAAQ,OAAO,OAAO,IAAI,wBAAwB,KAAK;EACnE,MAAM,iBACJ,QAAQ,kBAAkB,OAAO,IAAI,mCAAmC,EAAE;EAC5E,MAAM,aAAa,QAAQ,UAAU,OAAO,IAAI,yBAAyB;EAEzE,IAAI,CAAC,QAAQ,SAAS,QAAQ,OAAO,YAAY,CAAC,GAAG;EAErD,MAAM,iBAAiB,QAAQ,OAAO,WAAW,YAAY,CAAC;EAE9D,IAAI,CAAC,gBAAgB;EAErB,IAAI,CAAC,sBAAsB,cAAc,GACvC,OAAO,SAAS,WAAW;GACzB,OAAO,EAAE,4BAA4B;GACrC;EACF,CAAC;EAGH,MAAM,cAAc,aAAa,MAAM,MAAM,IAAI,UAAU,IAAI;EAC/D,MAAM,WAAW,yBAAyB,SAAS,cAAc;EACjE,MAAM,WAAW,SAAS,QAAQ,IAAI;EAEtC,MAAM,qBACJ,aACG;GACH,IAAI,CAAC,YAAa,SAAiC,UAAU,aAAa;IACxE,SAAS,OAAO,eAAe,GAAG;IAElC,OAAO,SAAS,SAAS;KACvB,OAAO;KACP;IACF,CAAC;GACH;GAEA,MAAM,SAAS;GAEf,IAAI,OAAO,aAAa,UACtB,OAAO,SAAS,oBAAoB;IAClC,OAAO,EAAE,6BAA6B;IACtC;GACF,CAAC;GAGH,SAAS,OAAO,qBAAqB,MAAM;GAE3C,OAAO,SAAS,OAAO;IACrB,QAAQ,OAAO;IACf,MAAM,OAAO;IACb,aAAa,OAAO;GACtB,CAAC;EACH;EAGA,IAAI,WAAwD;EAE5D,IAAI;GACF,WAAY,MAAM,YAAY,IAAI,QAAQ;EAC5C,SAAS,OAAO;GAGd,IAAI,MAAM,0BAA0B,OAAO,KAAK;EAClD;EAEA,IAAI,UAAU,OAAO,kBAAkB,QAAQ;EAI/C,IAAI;GACF,MAAM,cAAe,MAAM,YAAY,IACrC,UACA;IAAE,OAAO;IAAa,WAAW,KAAK,IAAI;GAAE,GAC5C;IAAE,YAAY;IAAU,KAAK;GAAe,CAC9C;GAEA,IAAI,eAAe,YAAY,WAAW,OACxC,OAAO,kBAAkB,YAAY,QAAQ;EAEjD,SAAS,OAAO;GACd,IAAI,MAAM,0BAA0B,WAAW,KAAK;EACtD;EAEA,SAAS,QAAQ,iBAA2B;GAI1C,IAAI,aAAa,cAAc,KAAK;IAElC,QAAQ,QAAQ,CAAC,CACd,WAAW,YAAY,OAAO,QAAQ,CAAC,CAAC,CACxC,OAAO,UAAmB;KACzB,IAAI,MAAM,0BAA0B,UAAU,KAAK;IACrD,CAAC;IAEH;GACF;GAEA,MAAM,kBAAkB,aAAa;GAIrC,YACG,IACC,UACA;IACE,QAAQ,aAAa;IACrB,MAAM,aAAa;IACnB;IACA,aAAa,OAAO,oBAAoB,WAAW,kBAAkB;GACvE,GACA,GACF,CAAC,CACA,OAAO,UAAmB;IACzB,IAAI,MAAM,0BAA0B,OAAO,KAAK;GAClD,CAAC;EACL,CAAC;CACH;AACF"}

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

@@ -1 +1 @@
-{"version":3,"file":"plugins.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/plugins.ts"],"mappings":";;;iBAYsB,mBAAA,CAAoB,MAAA,EAAQ,eAAA,GAAe,OAAA;;AAAjE;;;;;iBA+EgB,iBAAA,CAAkB,UAAmB"}
+{"version":3,"file":"plugins.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/plugins.ts"],"mappings":";;;iBAcsB,mBAAA,CAAoB,MAAA,EAAQ,eAAA,GAAe,OAAA;;AAAjE;;;;;iBAuFgB,iBAAA,CAAkB,UAAmB"}

package/esm/http/plugins.mjs

@@ -1,20 +1,22 @@
 import { rootPath } from "../utils/paths.mjs";
 import "../utils/index.mjs";
+import { registerLazyStatic } from "./lazy-static.mjs";
 import { buildCorsOptions } from "./build-cors-options.mjs";
+import { resolveStaticRateLimit } from "../router/resolve-route-rate-limit.mjs";
 import { router } from "../router/router.mjs";
 import "../router/index.mjs";
 import { buildRateLimitOptions } from "./build-rate-limit-options.mjs";
 import { parseUrlencodedBody } from "./parse-urlencoded-body.mjs";
 import config from "@mongez/config";
 import { log } from "@warlock.js/logger";
-import fastifyMultipart from "@fastify/multipart";
 import { existsSync } from "node:fs";
+import fastifyMultipart from "@fastify/multipart";
 
 //#region ../../packages/core/src/http/plugins.ts
 async function registerHttpPlugins(server) {
 	const rateLimitOptions = buildRateLimitOptions(config.get("http.rateLimit"));
 	if (rateLimitOptions) server.register(import("@fastify/rate-limit"), rateLimitOptions);
-	else if (router.list().some((route) => route.rateLimit)) log.warn("http", "rateLimit", "Routes declare `rateLimit`, but `http.rateLimit.enabled` is false so the rate-limit plugin is not registered: route rate limits (and their errorMessage) are inactive.");
+	else if (router.list().some((route) => typeof route.rateLimit === "object")) log.warn("http", "rateLimit", "Routes declare `rateLimit`, but `http.rateLimit.enabled` is false so the rate-limit plugin is not registered: route rate limits (and their errorMessage) are inactive.");
 	server.register(import("@fastify/cors"), buildCorsOptions());
 	server.register(fastifyMultipart, {
 		attachFieldsToBody: true,
@@ -33,14 +35,15 @@ async function registerHttpPlugins(server) {
 		}
 	});
 	const publicRoot = resolvePublicRoot(config.get("storage.publicRoot", rootPath("public")));
-	if (publicRoot !== void 0) server.register(import("@fastify/static"), {
+	if (publicRoot !== void 0) registerLazyStatic(server, {
 		root: publicRoot,
 		prefix: config.get("storage.publicPrefix", "/public/")
-	});
+	}, { rateLimit: resolveStaticRateLimit(void 0) });
 	server.register(import("@fastify/cookie"), {
 		secret: config.get("http.cookies.secret"),
 		parseOptions: config.get("http.cookies.options", {})
 	});
+	await server.after();
 }
 /**
 * The public folder(s) worth handing to `@fastify/static`, or `undefined`

package/esm/http/plugins.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"plugins.mjs","names":[],"sources":["../../../../../../../../packages/core/src/http/plugins.ts"],"sourcesContent":["import fastifyMultipart from \"@fastify/multipart\";\nimport config from \"@mongez/config\";\nimport { existsSync } from \"node:fs\";\nimport type { FastifyRequest } from \"fastify\";\nimport { log } from \"@warlock.js/logger\";\nimport { router } from \"../router\";\nimport { rootPath } from \"../utils\";\nimport { buildCorsOptions } from \"./build-cors-options\";\nimport { buildRateLimitOptions } from \"./build-rate-limit-options\";\nimport { parseUrlencodedBody } from \"./parse-urlencoded-body\";\nimport type { FastifyInstance } from \"./server\";\n\nexport async function registerHttpPlugins(server: FastifyInstance) {\n  // 👇🏻 register rate-limit plugin\n  const rateLimitOptions = buildRateLimitOptions(config.get(\"http.rateLimit\"));\n\n  if (rateLimitOptions) {\n    server.register(import(\"@fastify/rate-limit\"), rateLimitOptions);\n  } else if (router.list().some((route) => route.rateLimit)) {\n    log.warn(\n      \"http\",\n      \"rateLimit\",\n      \"Routes declare `rateLimit`, but `http.rateLimit.enabled` is false so the rate-limit plugin is not registered: route rate limits (and their errorMessage) are inactive.\",\n    );\n  }\n\n  // 👇🏻 register cors plugin\n  server.register(import(\"@fastify/cors\"), buildCorsOptions());\n\n  // 👇🏻 import multipart plugin\n  server.register(fastifyMultipart, {\n    attachFieldsToBody: true,\n    limits: {\n      // file size could be up to 10MB\n      fileSize: config.get(\"http.fileUploadLimit\", 10 * 1024 * 1024),\n      // every file part is buffered in memory (`attachFieldsToBody`), so cap the counts too;\n      // hitting any limit makes @fastify/multipart throw an error with statusCode 413\n      files: config.get(\"http.multipart.files\", 10),\n      fields: config.get(\"http.multipart.fields\", 100),\n      fieldSize: config.get(\"http.multipart.fieldSize\", 1024 * 1024),\n    },\n  });\n\n  // 👇🏻 parse application/x-www-form-urlencoded bodies (Apple's OAuth\n  // `form_post` callback, plain HTML forms). Fastify only parses JSON and\n  // text natively, so without this every urlencoded POST is rejected with\n  // FST_ERR_CTP_INVALID_MEDIA_TYPE before it reaches a route.\n  //\n  // No `bodyLimit` option here: Fastify falls back to the server's own\n  // `bodyLimit` (`server.ts`, from `http.bodyLimit`) whenever a content-type\n  // parser doesn't set one — the exact limit JSON bodies are already held to.\n  // Reading `http.bodyLimit` again here would duplicate that lookup and risk\n  // the two silently drifting.\n  server.addContentTypeParser(\n    \"application/x-www-form-urlencoded\",\n    { parseAs: \"string\" },\n    (_request: FastifyRequest, body: string, done: (err: Error | null, body?: any) => void) => {\n      try {\n        done(null, parseUrlencodedBody(body));\n      } catch (error) {\n        done(error as Error, undefined);\n      }\n    },\n  );\n\n  // 👇🏻 serve the public folder. Importing `@fastify/static` is not free (its\n  // directory-listing module calls `os.cpus()` at load), so it is only loaded\n  // when there is a folder to serve: `storage.publicRoot: false` turns public\n  // serving off, and a missing folder skips it (WR-027).\n  const publicRoot = resolvePublicRoot(config.get(\"storage.publicRoot\", rootPath(\"public\")));\n\n  if (publicRoot !== undefined) {\n    server.register(import(\"@fastify/static\"), {\n      root: publicRoot,\n      prefix: config.get(\"storage.publicPrefix\", \"/public/\"),\n    });\n  }\n\n  // 👇🏻 register cookie plugin\n  server.register(import(\"@fastify/cookie\"), {\n    secret: config.get(\"http.cookies.secret\"), // Optional: allow signed cookies\n    parseOptions: config.get(\"http.cookies.options\", {}),\n  });\n}\n\n/**\n * The public folder(s) worth handing to `@fastify/static`, or `undefined`\n * when there is nothing to serve: `false`, or a single path that does not\n * exist. An array is passed through unchanged; `@fastify/static` validates\n * each entry itself.\n */\nexport function resolvePublicRoot(publicRoot: unknown): string | string[] | undefined {\n  if (publicRoot === false || publicRoot === null || publicRoot === undefined) {\n    return undefined;\n  }\n\n  if (Array.isArray(publicRoot)) {\n    return publicRoot.length > 0 ? publicRoot : undefined;\n  }\n\n  if (typeof publicRoot === \"string\") {\n    return existsSync(publicRoot) ? publicRoot : undefined;\n  }\n\n  return publicRoot as string;\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,eAAsB,oBAAoB,QAAyB;CAEjE,MAAM,mBAAmB,sBAAsB,OAAO,IAAI,gBAAgB,CAAC;CAE3E,IAAI,kBACF,OAAO,SAAS,OAAO,wBAAwB,gBAAgB;MAC1D,IAAI,OAAO,KAAK,CAAC,CAAC,MAAM,UAAU,MAAM,SAAS,GACtD,IAAI,KACF,QACA,aACA,wKACF;CAIF,OAAO,SAAS,OAAO,kBAAkB,iBAAiB,CAAC;CAG3D,OAAO,SAAS,kBAAkB;EAChC,oBAAoB;EACpB,QAAQ;GAEN,UAAU,OAAO,IAAI,wBAAwB,KAAK,OAAO,IAAI;GAG7D,OAAO,OAAO,IAAI,wBAAwB,EAAE;GAC5C,QAAQ,OAAO,IAAI,yBAAyB,GAAG;GAC/C,WAAW,OAAO,IAAI,4BAA4B,OAAO,IAAI;EAC/D;CACF,CAAC;CAYD,OAAO,qBACL,qCACA,EAAE,SAAS,SAAS,IACnB,UAA0B,MAAc,SAAkD;EACzF,IAAI;GACF,KAAK,MAAM,oBAAoB,IAAI,CAAC;EACtC,SAAS,OAAO;GACd,KAAK,OAAgB,MAAS;EAChC;CACF,CACF;CAMA,MAAM,aAAa,kBAAkB,OAAO,IAAI,sBAAsB,SAAS,QAAQ,CAAC,CAAC;CAEzF,IAAI,eAAe,QACjB,OAAO,SAAS,OAAO,oBAAoB;EACzC,MAAM;EACN,QAAQ,OAAO,IAAI,wBAAwB,UAAU;CACvD,CAAC;CAIH,OAAO,SAAS,OAAO,oBAAoB;EACzC,QAAQ,OAAO,IAAI,qBAAqB;EACxC,cAAc,OAAO,IAAI,wBAAwB,CAAC,CAAC;CACrD,CAAC;AACH;;;;;;;AAQA,SAAgB,kBAAkB,YAAoD;CACpF,IAAI,eAAe,SAAS,eAAe,QAAQ,eAAe,QAChE;CAGF,IAAI,MAAM,QAAQ,UAAU,GAC1B,OAAO,WAAW,SAAS,IAAI,aAAa;CAG9C,IAAI,OAAO,eAAe,UACxB,OAAO,WAAW,UAAU,IAAI,aAAa;CAG/C,OAAO;AACT"}
+{"version":3,"file":"plugins.mjs","names":[],"sources":["../../../../../../../../packages/core/src/http/plugins.ts"],"sourcesContent":["import fastifyMultipart from \"@fastify/multipart\";\nimport config from \"@mongez/config\";\nimport { existsSync } from \"node:fs\";\nimport type { FastifyRequest } from \"fastify\";\nimport { log } from \"@warlock.js/logger\";\nimport { router } from \"../router\";\nimport { resolveStaticRateLimit } from \"../router/resolve-route-rate-limit\";\nimport { rootPath } from \"../utils\";\nimport { buildCorsOptions } from \"./build-cors-options\";\nimport { buildRateLimitOptions } from \"./build-rate-limit-options\";\nimport { registerLazyStatic } from \"./lazy-static\";\nimport { parseUrlencodedBody } from \"./parse-urlencoded-body\";\nimport type { FastifyInstance } from \"./server\";\n\nexport async function registerHttpPlugins(server: FastifyInstance) {\n  // 👇🏻 register rate-limit plugin\n  const rateLimitOptions = buildRateLimitOptions(config.get(\"http.rateLimit\"));\n\n  if (rateLimitOptions) {\n    server.register(import(\"@fastify/rate-limit\"), rateLimitOptions);\n  } else if (router.list().some((route) => typeof route.rateLimit === \"object\")) {\n    log.warn(\n      \"http\",\n      \"rateLimit\",\n      \"Routes declare `rateLimit`, but `http.rateLimit.enabled` is false so the rate-limit plugin is not registered: route rate limits (and their errorMessage) are inactive.\",\n    );\n  }\n\n  // 👇🏻 register cors plugin\n  server.register(import(\"@fastify/cors\"), buildCorsOptions());\n\n  // 👇🏻 import multipart plugin\n  server.register(fastifyMultipart, {\n    attachFieldsToBody: true,\n    limits: {\n      // file size could be up to 10MB\n      fileSize: config.get(\"http.fileUploadLimit\", 10 * 1024 * 1024),\n      // every file part is buffered in memory (`attachFieldsToBody`), so cap the counts too;\n      // hitting any limit makes @fastify/multipart throw an error with statusCode 413\n      files: config.get(\"http.multipart.files\", 10),\n      fields: config.get(\"http.multipart.fields\", 100),\n      fieldSize: config.get(\"http.multipart.fieldSize\", 1024 * 1024),\n    },\n  });\n\n  // 👇🏻 parse application/x-www-form-urlencoded bodies (Apple's OAuth\n  // `form_post` callback, plain HTML forms). Fastify only parses JSON and\n  // text natively, so without this every urlencoded POST is rejected with\n  // FST_ERR_CTP_INVALID_MEDIA_TYPE before it reaches a route.\n  //\n  // No `bodyLimit` option here: Fastify falls back to the server's own\n  // `bodyLimit` (`server.ts`, from `http.bodyLimit`) whenever a content-type\n  // parser doesn't set one — the exact limit JSON bodies are already held to.\n  // Reading `http.bodyLimit` again here would duplicate that lookup and risk\n  // the two silently drifting.\n  server.addContentTypeParser(\n    \"application/x-www-form-urlencoded\",\n    { parseAs: \"string\" },\n    (_request: FastifyRequest, body: string, done: (err: Error | null, body?: any) => void) => {\n      try {\n        done(null, parseUrlencodedBody(body));\n      } catch (error) {\n        done(error as Error, undefined);\n      }\n    },\n  );\n\n  // 👇🏻 serve the public folder. Importing `@fastify/static` is not free (its\n  // directory-listing module calls `os.cpus()` at load), so defer loading to\n  // the first file request even when the public folder already exists.\n  const publicRoot = resolvePublicRoot(config.get(\"storage.publicRoot\", rootPath(\"public\")));\n\n  if (publicRoot !== undefined) {\n    registerLazyStatic(\n      server,\n      {\n        root: publicRoot,\n        prefix: config.get(\"storage.publicPrefix\", \"/public/\"),\n      },\n      // Exempt from the global limiter unless `http.rateLimit.staticFiles`.\n      { rateLimit: resolveStaticRateLimit(undefined) },\n    );\n  }\n\n  // 👇🏻 register cookie plugin\n  server.register(import(\"@fastify/cookie\"), {\n    secret: config.get(\"http.cookies.secret\"), // Optional: allow signed cookies\n    parseOptions: config.get(\"http.cookies.options\", {}),\n  });\n\n  // Install plugin onRoute hooks before the connector registers health and app\n  // routes. after() waits for this queue without closing route registration.\n  await server.after();\n}\n\n/**\n * The public folder(s) worth handing to `@fastify/static`, or `undefined`\n * when there is nothing to serve: `false`, or a single path that does not\n * exist. An array is passed through unchanged; `@fastify/static` validates\n * each entry itself.\n */\nexport function resolvePublicRoot(publicRoot: unknown): string | string[] | undefined {\n  if (publicRoot === false || publicRoot === null || publicRoot === undefined) {\n    return undefined;\n  }\n\n  if (Array.isArray(publicRoot)) {\n    return publicRoot.length > 0 ? publicRoot : undefined;\n  }\n\n  if (typeof publicRoot === \"string\") {\n    return existsSync(publicRoot) ? publicRoot : undefined;\n  }\n\n  return publicRoot as string;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,eAAsB,oBAAoB,QAAyB;CAEjE,MAAM,mBAAmB,sBAAsB,OAAO,IAAI,gBAAgB,CAAC;CAE3E,IAAI,kBACF,OAAO,SAAS,OAAO,wBAAwB,gBAAgB;MAC1D,IAAI,OAAO,KAAK,CAAC,CAAC,MAAM,UAAU,OAAO,MAAM,cAAc,QAAQ,GAC1E,IAAI,KACF,QACA,aACA,wKACF;CAIF,OAAO,SAAS,OAAO,kBAAkB,iBAAiB,CAAC;CAG3D,OAAO,SAAS,kBAAkB;EAChC,oBAAoB;EACpB,QAAQ;GAEN,UAAU,OAAO,IAAI,wBAAwB,KAAK,OAAO,IAAI;GAG7D,OAAO,OAAO,IAAI,wBAAwB,EAAE;GAC5C,QAAQ,OAAO,IAAI,yBAAyB,GAAG;GAC/C,WAAW,OAAO,IAAI,4BAA4B,OAAO,IAAI;EAC/D;CACF,CAAC;CAYD,OAAO,qBACL,qCACA,EAAE,SAAS,SAAS,IACnB,UAA0B,MAAc,SAAkD;EACzF,IAAI;GACF,KAAK,MAAM,oBAAoB,IAAI,CAAC;EACtC,SAAS,OAAO;GACd,KAAK,OAAgB,MAAS;EAChC;CACF,CACF;CAKA,MAAM,aAAa,kBAAkB,OAAO,IAAI,sBAAsB,SAAS,QAAQ,CAAC,CAAC;CAEzF,IAAI,eAAe,QACjB,mBACE,QACA;EACE,MAAM;EACN,QAAQ,OAAO,IAAI,wBAAwB,UAAU;CACvD,GAEA,EAAE,WAAW,uBAAuB,MAAS,EAAE,CACjD;CAIF,OAAO,SAAS,OAAO,oBAAoB;EACzC,QAAQ,OAAO,IAAI,qBAAqB;EACxC,cAAc,OAAO,IAAI,wBAAwB,CAAC,CAAC;CACrD,CAAC;CAID,MAAM,OAAO,MAAM;AACrB;;;;;;;AAQA,SAAgB,kBAAkB,YAAoD;CACpF,IAAI,eAAe,SAAS,eAAe,QAAQ,eAAe,QAChE;CAGF,IAAI,MAAM,QAAQ,UAAU,GAC1B,OAAO,WAAW,SAAS,IAAI,aAAa;CAG9C,IAAI,OAAO,eAAe,UACxB,OAAO,WAAW,UAAU,IAAI,aAAa;CAG/C,OAAO;AACT"}

package/esm/http/rate-limit-cache-store.mjs

@@ -33,6 +33,7 @@ const UNSUPPORTED_DRIVERS = new Set(["null", "file"]);
 var UnsupportedRateLimitDriverError = class extends Error {
 	constructor(driverName) {
 		super(`Rate limiting with store: "cache" cannot use the "${driverName}" cache driver: ` + (driverName === "null" ? "it stores nothing, so the limit would never trip. " : "it never removes expired windows and its increment is not shared between processes. ") + "Use redis or pg (or a memory driver for a single process), or set store: \"memory\".");
+		this.code = "WL1003";
 		this.name = "UnsupportedRateLimitDriverError";
 	}
 };
@@ -75,7 +76,7 @@ async function incrementSharedRateLimit(namespace, group, windowMs, now = Date.n
 		onConflict: "create"
 	});
 	return {
-		current: await cache.increment(key),
+		current: await cache.increment(key, 1, { ttl: ttlSeconds }),
 		resetAt: (windowIndex + 1) * windowMs
 	};
 }

package/esm/http/rate-limit-cache-store.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit-cache-store.mjs","names":[],"sources":["../../../../../../../../packages/core/src/http/rate-limit-cache-store.ts"],"sourcesContent":["import type { FastifyRateLimitOptions, FastifyRateLimitStore } from \"@fastify/rate-limit\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport { createHash } from \"node:crypto\";\n\n/**\n * Rate-limit counting shared through `@warlock.js/cache`, so every process\n * that uses the same cache driver (Redis, Postgres) counts into the same\n * buckets. With a memory driver (`memory`, `lru`, `memoryExtended`) the\n * counts stay in the process, like the in-memory limiter.\n *\n * Windows are fixed and aligned to the clock: a 60 s window resets on the\n * minute, whichever process saw the first request. Each window has its own\n * key, created atomically with a TTL of two windows and incremented with the\n * driver's atomic increment, so a key cannot expire while its window counts.\n *\n * Two drivers are refused, with {@link UnsupportedRateLimitDriverError}:\n *\n * - `null` stores nothing, so every request would count as the first and the\n *   limit would never trip.\n * - `file` has no expiry sweeper, so every past window would stay on disk\n *   forever, and its increment is only serialized within one process, so\n *   workers sharing the directory would lose counts.\n */\n\nconst KEY_PREFIX = \"rate-limit\";\n\n/**\n * Cache drivers that cannot back a shared limiter (see the module comment).\n */\nconst UNSUPPORTED_DRIVERS = new Set([\"null\", \"file\"]);\n\n/**\n * Thrown when `store: \"cache\"` runs on a cache driver that cannot count.\n */\nexport class UnsupportedRateLimitDriverError extends Error {\n  public constructor(driverName: string) {\n    super(\n      `Rate limiting with store: \"cache\" cannot use the \"${driverName}\" cache driver: ` +\n        (driverName === \"null\"\n          ? \"it stores nothing, so the limit would never trip. \"\n          : \"it never removes expired windows and its increment is not shared between processes. \") +\n        'Use redis or pg (or a memory driver for a single process), or set store: \"memory\".',\n    );\n\n    this.name = \"UnsupportedRateLimitDriverError\";\n  }\n}\n\nfunction assertSupportedDriver(): void {\n  const driverName = cache.currentDriver?.name;\n\n  if (driverName && UNSUPPORTED_DRIVERS.has(driverName)) {\n    throw new UnsupportedRateLimitDriverError(driverName);\n  }\n}\n\n/**\n * Hash used for group keys and route namespaces before they reach the cache.\n */\nfunction shortHash(value: string): string {\n  return createHash(\"sha256\").update(value).digest(\"hex\").slice(0, 32);\n}\n\n/**\n * The group key (an IP, a user id, whatever `keyGenerator` returned) is\n * hashed before it reaches the cache: cache drivers log their keys, and a raw\n * IP or email in a key is personal data in a log line.\n *\n * The namespace (it carries a route path) is hashed as well: flattening\n * `/users/:id` and `/users/id` to one safe string merged their counters, and\n * the file driver would turn `/` into directories. A readable, flattened\n * prefix stays in front of the hash for debugging.\n */\nfunction windowKey(namespace: string, group: string, windowIndex: number): string {\n  const readable = namespace.replace(/[^A-Za-z0-9_-]+/g, \"_\").slice(0, 40);\n\n  return `${KEY_PREFIX}.${readable}-${shortHash(namespace).slice(0, 16)}.${shortHash(group)}.${windowIndex}`;\n}\n\n/**\n * Count one request for `group` in the current window.\n *\n * @returns the count so far in this window and when the window resets (epoch ms)\n * @throws {UnsupportedRateLimitDriverError} on the `null` or `file` driver\n */\nexport async function incrementSharedRateLimit(\n  namespace: string,\n  group: string,\n  windowMs: number,\n  now: number = Date.now(),\n): Promise<{ current: number; resetAt: number }> {\n  assertSupportedDriver();\n\n  const windowIndex = Math.floor(now / windowMs);\n  const key = windowKey(namespace, group, windowIndex);\n  const ttlSeconds = Math.max(1, Math.ceil((2 * windowMs) / 1000));\n\n  await cache.set(key, 0, { ttl: ttlSeconds, onConflict: \"create\" });\n\n  const current = await cache.increment(key);\n\n  return { current, resetAt: (windowIndex + 1) * windowMs };\n}\n\n/**\n * Read the count for `group` in the current window without counting a request\n */\nexport async function readSharedRateLimit(\n  namespace: string,\n  group: string,\n  windowMs: number,\n  now: number = Date.now(),\n): Promise<{ current: number; resetAt: number }> {\n  assertSupportedDriver();\n\n  const windowIndex = Math.floor(now / windowMs);\n  const value = await cache.get(windowKey(namespace, group, windowIndex));\n\n  return {\n    current: typeof value === \"number\" ? value : 0,\n    resetAt: (windowIndex + 1) * windowMs,\n  };\n}\n\n/**\n * How often a failing shared store is reported. A cache outage fails every\n * request, so logging each one would flood the log.\n */\nconst ERROR_LOG_INTERVAL_MS = 60_000;\n\nlet lastErrorLogAt = 0;\n\n/**\n * Log a shared rate-limit store failure, at most once per minute.\n */\nexport function logSharedRateLimitError(error: unknown, now: number = Date.now()): void {\n  if (now - lastErrorLogAt < ERROR_LOG_INTERVAL_MS) return;\n\n  lastErrorLogAt = now;\n  log.error(\"http\", \"rate-limit\", error);\n}\n\n/**\n * Forget when the last store error was logged (tests).\n */\nexport function resetSharedRateLimitErrorLog(): void {\n  lastErrorLogAt = 0;\n}\n\n/**\n * Route data `@fastify/rate-limit` passes to `child()`: the route's options\n * under `routeInfo` (`fastify.rateLimit()` hooks pass an empty one).\n */\ntype ChildRouteOptions = {\n  routeInfo?: { method?: unknown; url?: string; path?: string };\n};\n\n/**\n * `fastify.rateLimit()` hooks have no route; told apart by creation order,\n * which matches across processes running the same code.\n */\nlet nextHookNamespace = 0;\n\n/**\n * `@fastify/rate-limit` store backed by `@warlock.js/cache`. Selected with\n * `http.rateLimit.store: \"cache\"`; each route with its own `rateLimit` gets\n * its own namespace through `child()`.\n *\n * A failure (cache outage, unsupported driver) is logged at most once a\n * minute and passed to the plugin, which lets the request through because\n * Warlock registers it with `skipOnError: true` for this store.\n */\nexport class CacheRateLimitStore implements FastifyRateLimitStore {\n  public constructor(\n    _options?: FastifyRateLimitOptions,\n    protected readonly namespace: string = \"global\",\n  ) {}\n\n  public incr(\n    key: string,\n    callback: (error: Error | null, result?: { current: number; ttl: number }) => void,\n    timeWindow: number,\n  ): void {\n    incrementSharedRateLimit(this.namespace, key, timeWindow).then(\n      ({ current, resetAt }) => callback(null, { current, ttl: Math.max(0, resetAt - Date.now()) }),\n      (error: unknown) => {\n        logSharedRateLimitError(error);\n        callback(error instanceof Error ? error : new Error(String(error)));\n      },\n    );\n  }\n\n  public read(\n    key: string,\n    callback: (error: Error | null, result?: { current: number; ttl: number }) => void,\n    timeWindow: number,\n  ): void {\n    readSharedRateLimit(this.namespace, key, timeWindow).then(\n      ({ current, resetAt }) =>\n        callback(null, { current, ttl: current === 0 ? 0 : Math.max(0, resetAt - Date.now()) }),\n      (error: unknown) => {\n        logSharedRateLimitError(error);\n        callback(error instanceof Error ? error : new Error(String(error)));\n      },\n    );\n  }\n\n  public child(routeOptions: Parameters<FastifyRateLimitStore[\"child\"]>[0]): FastifyRateLimitStore {\n    // The plugin's declared type names the route options directly, but at\n    // runtime (11.x) it passes them merged under `routeInfo`.\n    const routeInfo = (routeOptions as unknown as ChildRouteOptions).routeInfo ?? {};\n    const method = Array.isArray(routeInfo.method)\n      ? routeInfo.method.join(\",\")\n      : String(routeInfo.method ?? \"\");\n    const url = routeInfo.url ?? routeInfo.path ?? \"\";\n\n    if (!method && !url) {\n      return new CacheRateLimitStore(undefined, `hook.${nextHookNamespace++}`);\n    }\n\n    return new CacheRateLimitStore(undefined, `route.${method} ${url}`);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"rate-limit-cache-store.mjs","names":[],"sources":["../../../../../../../../packages/core/src/http/rate-limit-cache-store.ts"],"sourcesContent":["import type { FastifyRateLimitOptions, FastifyRateLimitStore } from \"@fastify/rate-limit\";\nimport { cache } from \"@warlock.js/cache\";\nimport { log } from \"@warlock.js/logger\";\nimport { createHash } from \"node:crypto\";\n\n/**\n * Rate-limit counting shared through `@warlock.js/cache`, so every process\n * that uses the same cache driver (Redis, Postgres) counts into the same\n * buckets. With a memory driver (`memory`, `lru`, `memoryExtended`) the\n * counts stay in the process, like the in-memory limiter.\n *\n * Windows are fixed and aligned to the clock: a 60 s window resets on the\n * minute, whichever process saw the first request. Each window has its own\n * key, created atomically with a TTL of two windows and incremented with the\n * driver's atomic increment, so a key cannot expire while its window counts.\n *\n * Two drivers are refused, with {@link UnsupportedRateLimitDriverError}:\n *\n * - `null` stores nothing, so every request would count as the first and the\n *   limit would never trip.\n * - `file` has no expiry sweeper, so every past window would stay on disk\n *   forever, and its increment is only serialized within one process, so\n *   workers sharing the directory would lose counts.\n */\n\nconst KEY_PREFIX = \"rate-limit\";\n\n/**\n * Cache drivers that cannot back a shared limiter (see the module comment).\n */\nconst UNSUPPORTED_DRIVERS = new Set([\"null\", \"file\"]);\n\n/**\n * Thrown when `store: \"cache\"` runs on a cache driver that cannot count.\n */\nexport class UnsupportedRateLimitDriverError extends Error {\n  /** Stable Warlock error code; `warlock explain WL1003` prints the fix. */\n  public readonly code = \"WL1003\";\n\n  public constructor(driverName: string) {\n    super(\n      `Rate limiting with store: \"cache\" cannot use the \"${driverName}\" cache driver: ` +\n        (driverName === \"null\"\n          ? \"it stores nothing, so the limit would never trip. \"\n          : \"it never removes expired windows and its increment is not shared between processes. \") +\n        'Use redis or pg (or a memory driver for a single process), or set store: \"memory\".',\n    );\n\n    this.name = \"UnsupportedRateLimitDriverError\";\n  }\n}\n\nfunction assertSupportedDriver(): void {\n  const driverName = cache.currentDriver?.name;\n\n  if (driverName && UNSUPPORTED_DRIVERS.has(driverName)) {\n    throw new UnsupportedRateLimitDriverError(driverName);\n  }\n}\n\n/**\n * Hash used for group keys and route namespaces before they reach the cache.\n */\nfunction shortHash(value: string): string {\n  return createHash(\"sha256\").update(value).digest(\"hex\").slice(0, 32);\n}\n\n/**\n * The group key (an IP, a user id, whatever `keyGenerator` returned) is\n * hashed before it reaches the cache: cache drivers log their keys, and a raw\n * IP or email in a key is personal data in a log line.\n *\n * The namespace (it carries a route path) is hashed as well: flattening\n * `/users/:id` and `/users/id` to one safe string merged their counters, and\n * the file driver would turn `/` into directories. A readable, flattened\n * prefix stays in front of the hash for debugging.\n */\nfunction windowKey(namespace: string, group: string, windowIndex: number): string {\n  const readable = namespace.replace(/[^A-Za-z0-9_-]+/g, \"_\").slice(0, 40);\n\n  return `${KEY_PREFIX}.${readable}-${shortHash(namespace).slice(0, 16)}.${shortHash(group)}.${windowIndex}`;\n}\n\n/**\n * Count one request for `group` in the current window.\n *\n * @returns the count so far in this window and when the window resets (epoch ms)\n * @throws {UnsupportedRateLimitDriverError} on the `null` or `file` driver\n */\nexport async function incrementSharedRateLimit(\n  namespace: string,\n  group: string,\n  windowMs: number,\n  now: number = Date.now(),\n): Promise<{ current: number; resetAt: number }> {\n  assertSupportedDriver();\n\n  const windowIndex = Math.floor(now / windowMs);\n  const key = windowKey(namespace, group, windowIndex);\n  const ttlSeconds = Math.max(1, Math.ceil((2 * windowMs) / 1000));\n\n  await cache.set(key, 0, { ttl: ttlSeconds, onConflict: \"create\" });\n\n  const current = await cache.increment(key, 1, { ttl: ttlSeconds });\n\n  return { current, resetAt: (windowIndex + 1) * windowMs };\n}\n\n/**\n * Read the count for `group` in the current window without counting a request\n */\nexport async function readSharedRateLimit(\n  namespace: string,\n  group: string,\n  windowMs: number,\n  now: number = Date.now(),\n): Promise<{ current: number; resetAt: number }> {\n  assertSupportedDriver();\n\n  const windowIndex = Math.floor(now / windowMs);\n  const value = await cache.get(windowKey(namespace, group, windowIndex));\n\n  return {\n    current: typeof value === \"number\" ? value : 0,\n    resetAt: (windowIndex + 1) * windowMs,\n  };\n}\n\n/**\n * How often a failing shared store is reported. A cache outage fails every\n * request, so logging each one would flood the log.\n */\nconst ERROR_LOG_INTERVAL_MS = 60_000;\n\nlet lastErrorLogAt = 0;\n\n/**\n * Log a shared rate-limit store failure, at most once per minute.\n */\nexport function logSharedRateLimitError(error: unknown, now: number = Date.now()): void {\n  if (now - lastErrorLogAt < ERROR_LOG_INTERVAL_MS) return;\n\n  lastErrorLogAt = now;\n  log.error(\"http\", \"rate-limit\", error);\n}\n\n/**\n * Forget when the last store error was logged (tests).\n */\nexport function resetSharedRateLimitErrorLog(): void {\n  lastErrorLogAt = 0;\n}\n\n/**\n * Route data `@fastify/rate-limit` passes to `child()`: the route's options\n * under `routeInfo` (`fastify.rateLimit()` hooks pass an empty one).\n */\ntype ChildRouteOptions = {\n  routeInfo?: { method?: unknown; url?: string; path?: string };\n};\n\n/**\n * `fastify.rateLimit()` hooks have no route; told apart by creation order,\n * which matches across processes running the same code.\n */\nlet nextHookNamespace = 0;\n\n/**\n * `@fastify/rate-limit` store backed by `@warlock.js/cache`. Selected with\n * `http.rateLimit.store: \"cache\"`; each route with its own `rateLimit` gets\n * its own namespace through `child()`.\n *\n * A failure (cache outage, unsupported driver) is logged at most once a\n * minute and passed to the plugin, which lets the request through because\n * Warlock registers it with `skipOnError: true` for this store.\n */\nexport class CacheRateLimitStore implements FastifyRateLimitStore {\n  public constructor(\n    _options?: FastifyRateLimitOptions,\n    protected readonly namespace: string = \"global\",\n  ) {}\n\n  public incr(\n    key: string,\n    callback: (error: Error | null, result?: { current: number; ttl: number }) => void,\n    timeWindow: number,\n  ): void {\n    incrementSharedRateLimit(this.namespace, key, timeWindow).then(\n      ({ current, resetAt }) => callback(null, { current, ttl: Math.max(0, resetAt - Date.now()) }),\n      (error: unknown) => {\n        logSharedRateLimitError(error);\n        callback(error instanceof Error ? error : new Error(String(error)));\n      },\n    );\n  }\n\n  public read(\n    key: string,\n    callback: (error: Error | null, result?: { current: number; ttl: number }) => void,\n    timeWindow: number,\n  ): void {\n    readSharedRateLimit(this.namespace, key, timeWindow).then(\n      ({ current, resetAt }) =>\n        callback(null, { current, ttl: current === 0 ? 0 : Math.max(0, resetAt - Date.now()) }),\n      (error: unknown) => {\n        logSharedRateLimitError(error);\n        callback(error instanceof Error ? error : new Error(String(error)));\n      },\n    );\n  }\n\n  public child(routeOptions: Parameters<FastifyRateLimitStore[\"child\"]>[0]): FastifyRateLimitStore {\n    // The plugin's declared type names the route options directly, but at\n    // runtime (11.x) it passes them merged under `routeInfo`.\n    const routeInfo = (routeOptions as unknown as ChildRouteOptions).routeInfo ?? {};\n    const method = Array.isArray(routeInfo.method)\n      ? routeInfo.method.join(\",\")\n      : String(routeInfo.method ?? \"\");\n    const url = routeInfo.url ?? routeInfo.path ?? \"\";\n\n    if (!method && !url) {\n      return new CacheRateLimitStore(undefined, `hook.${nextHookNamespace++}`);\n    }\n\n    return new CacheRateLimitStore(undefined, `route.${method} ${url}`);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAyBA,MAAM,aAAa;;;;AAKnB,MAAM,sBAAsB,IAAI,IAAI,CAAC,QAAQ,MAAM,CAAC;;;;AAKpD,IAAa,kCAAb,cAAqD,MAAM;CAIzD,AAAO,YAAY,YAAoB;EACrC,MACE,qDAAqD,WAAW,qBAC7D,eAAe,SACZ,uDACA,0FACJ,sFACJ;cATqB;EAWrB,KAAK,OAAO;CACd;AACF;AAEA,SAAS,wBAA8B;CACrC,MAAM,aAAa,MAAM,eAAe;CAExC,IAAI,cAAc,oBAAoB,IAAI,UAAU,GAClD,MAAM,IAAI,gCAAgC,UAAU;AAExD;;;;AAKA,SAAS,UAAU,OAAuB;CACxC,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,GAAG,EAAE;AACrE;;;;;;;;;;;AAYA,SAAS,UAAU,WAAmB,OAAe,aAA6B;CAGhF,OAAO,GAAG,WAAW,GAFJ,UAAU,QAAQ,oBAAoB,GAAG,CAAC,CAAC,MAAM,GAAG,EAEtC,EAAE,GAAG,UAAU,SAAS,CAAC,CAAC,MAAM,GAAG,EAAE,EAAE,GAAG,UAAU,KAAK,EAAE,GAAG;AAC/F;;;;;;;AAQA,eAAsB,yBACpB,WACA,OACA,UACA,MAAc,KAAK,IAAI,GACwB;CAC/C,sBAAsB;CAEtB,MAAM,cAAc,KAAK,MAAM,MAAM,QAAQ;CAC7C,MAAM,MAAM,UAAU,WAAW,OAAO,WAAW;CACnD,MAAM,aAAa,KAAK,IAAI,GAAG,KAAK,KAAM,IAAI,WAAY,GAAI,CAAC;CAE/D,MAAM,MAAM,IAAI,KAAK,GAAG;EAAE,KAAK;EAAY,YAAY;CAAS,CAAC;CAIjE,OAAO;EAAE,eAFa,MAAM,UAAU,KAAK,GAAG,EAAE,KAAK,WAAW,CAAC;EAE/C,UAAU,cAAc,KAAK;CAAS;AAC1D;;;;AAKA,eAAsB,oBACpB,WACA,OACA,UACA,MAAc,KAAK,IAAI,GACwB;CAC/C,sBAAsB;CAEtB,MAAM,cAAc,KAAK,MAAM,MAAM,QAAQ;CAC7C,MAAM,QAAQ,MAAM,MAAM,IAAI,UAAU,WAAW,OAAO,WAAW,CAAC;CAEtE,OAAO;EACL,SAAS,OAAO,UAAU,WAAW,QAAQ;EAC7C,UAAU,cAAc,KAAK;CAC/B;AACF;;;;;AAMA,MAAM,wBAAwB;AAE9B,IAAI,iBAAiB;;;;AAKrB,SAAgB,wBAAwB,OAAgB,MAAc,KAAK,IAAI,GAAS;CACtF,IAAI,MAAM,iBAAiB,uBAAuB;CAElD,iBAAiB;CACjB,IAAI,MAAM,QAAQ,cAAc,KAAK;AACvC;;;;;AAqBA,IAAI,oBAAoB;;;;;;;;;;AAWxB,IAAa,sBAAb,MAAa,oBAAqD;CAChE,AAAO,YACL,UACA,AAAmB,YAAoB,UACvC;EADmB;CAClB;CAEH,AAAO,KACL,KACA,UACA,YACM;EACN,yBAAyB,KAAK,WAAW,KAAK,UAAU,CAAC,CAAC,MACvD,EAAE,SAAS,cAAc,SAAS,MAAM;GAAE;GAAS,KAAK,KAAK,IAAI,GAAG,UAAU,KAAK,IAAI,CAAC;EAAE,CAAC,IAC3F,UAAmB;GAClB,wBAAwB,KAAK;GAC7B,SAAS,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC,CAAC;EACpE,CACF;CACF;CAEA,AAAO,KACL,KACA,UACA,YACM;EACN,oBAAoB,KAAK,WAAW,KAAK,UAAU,CAAC,CAAC,MAClD,EAAE,SAAS,cACV,SAAS,MAAM;GAAE;GAAS,KAAK,YAAY,IAAI,IAAI,KAAK,IAAI,GAAG,UAAU,KAAK,IAAI,CAAC;EAAE,CAAC,IACvF,UAAmB;GAClB,wBAAwB,KAAK;GAC7B,SAAS,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC,CAAC;EACpE,CACF;CACF;CAEA,AAAO,MAAM,cAAoF;EAG/F,MAAM,YAAa,aAA8C,aAAa,CAAC;EAC/E,MAAM,SAAS,MAAM,QAAQ,UAAU,MAAM,IACzC,UAAU,OAAO,KAAK,GAAG,IACzB,OAAO,UAAU,UAAU,EAAE;EACjC,MAAM,MAAM,UAAU,OAAO,UAAU,QAAQ;EAE/C,IAAI,CAAC,UAAU,CAAC,KACd,OAAO,IAAI,oBAAoB,QAAW,QAAQ,qBAAqB;EAGzE,OAAO,IAAI,oBAAoB,QAAW,SAAS,OAAO,GAAG,KAAK;CACpE;AACF"}

package/esm/http/request-log-snapshot.d.mts

@@ -2,7 +2,7 @@
 /**
  * What a request's log entries carry of its input. Set globally under
  * `http.logging` and per route with the route's `logging` option; the route
- * wins key by key.
+ * wins key by key, unless a private URL policy suppresses that field.
  *
  * @example
  * // never log the body or the query string of this route, not even redacted
@@ -29,6 +29,12 @@ type RequestLoggingOptions = {
    */
   query?: boolean;
 };
+/** A URL policy that can only remove input from snapshots, even on unmatched requests. */
+type PrivateRequestLoggingRule = {
+  /** Path prefix at a segment boundary, or a regular expression over the normalized path. */path: string | RegExp;
+  body?: false;
+  query?: false;
+};
 /**
  * `http.logging`: the app-wide defaults for {@link RequestLoggingOptions},
  * plus query parameter names whose values are masked in logged URLs.
@@ -39,7 +45,8 @@ type HttpLoggingConfig = RequestLoggingOptions & {
    * logger's default secret-key denylist and {@link URL_CREDENTIAL_PARAMS}.
    * Matched like the logger's keys: case, `-` and `_` are ignored.
    */
-  redactQueryParams?: string[];
+  redactQueryParams?: string[]; /** URL policies applied before route logging; matching rules cannot be overridden by a route. */
+  private?: PrivateRequestLoggingRule[];
 };
 /**
  * The bounded, plain-data view of a request that Core puts in log entries in
@@ -86,9 +93,9 @@ declare function redactUrlCredentials(url: string, extraParams?: readonly string
 declare function redactQueryCredentials(query: Record<string, unknown>, extraParams?: readonly string[]): Record<string, unknown>;
 /**
  * The effective logging options for a request: `http.logging` overlaid by the
- * route's own `logging` option.
+ * route's own `logging` option, then restricted by matching private URL policies.
  */
-declare function resolveRequestLoggingOptions(routeOptions: RequestLoggingOptions | undefined): Required<RequestLoggingOptions> & {
+declare function resolveRequestLoggingOptions(routeOptions: RequestLoggingOptions | undefined, url?: string, routePath?: string): Required<RequestLoggingOptions> & {
   redactQueryParams: string[];
 };
 /**
@@ -119,5 +126,5 @@ type RequestLogSource = {
  */
 declare function buildRequestLogSnapshot(source: RequestLogSource): RequestLogSnapshot;
 //#endregion
-export { HttpLoggingConfig, RequestLogSnapshot, RequestLogSource, RequestLoggingOptions, URL_CREDENTIAL_PARAMS, buildRequestLogSnapshot, redactQueryCredentials, redactUrlCredentials, resolveRequestLoggingOptions };
+export { HttpLoggingConfig, PrivateRequestLoggingRule, RequestLogSnapshot, RequestLogSource, RequestLoggingOptions, URL_CREDENTIAL_PARAMS, buildRequestLogSnapshot, redactQueryCredentials, redactUrlCredentials, resolveRequestLoggingOptions };
 //# sourceMappingURL=request-log-snapshot.d.mts.map

package/esm/http/request-log-snapshot.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"request-log-snapshot.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/request-log-snapshot.ts"],"mappings":";;AAeA;;;;AAiBO;AAOP;;;;AAMmB;KA9BP,qBAAA;EAsCkB;;;;;;;;;EA5B5B,IAAA;EAuCA;;;;;AACa;EAjCb,KAAK;AAAA;;;AAkDN;AAmBD;KA9DY,iBAAA,GAAoB,qBAAqB;;;AA8DgC;AA4DrF;;EApHE,iBAAiB;AAAA;;;;;;KAQP,kBAAA;EACV,EAAA;EACA,MAAA;EAEA,GAAA,UAgJU;EA9IV,KAAA,WA8IS;EA5IT,IAAA;EACA,EAAA;EACA,SAAA;EACA,KAAA,GAAQ,MAAA;EACR,IAAA,GAAO,MAAM;AAAA;;AAwIyC;AAcxD;;;cA9Ia,qBAAA;;;;;;;;;;;;iBA4BG,oBAAA,CAAqB,GAAA,UAAa,WAAmC;;;;;;;;AA0HZ;iBA9DzD,sBAAA,CACd,KAAA,EAAO,MAAA,mBACP,WAAA,uBACC,MAAM;;;;;iBAmCO,4BAAA,CACd,YAAA,EAAc,qBAAA,eACb,QAAA,CAAS,qBAAA;EAA2B,iBAAA;AAAA;AAiC8C;;;;AAAA,KAnBzE,gBAAA;EACV,EAAA;EACA,MAAA;EACA,GAAA;EACA,EAAA;EACA,SAAA;EACA,KAAA,GAAQ,MAAA;EACR,IAAA,GAAO,MAAA;EACP,KAAA;IAAU,IAAA;IAAe,IAAA;IAAe,OAAA,GAAU,qBAAA;EAAA;AAAA;;;;;;;;;iBAWpC,uBAAA,CAAwB,MAAA,EAAQ,gBAAA,GAAmB,kBAAkB"}
+{"version":3,"file":"request-log-snapshot.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/http/request-log-snapshot.ts"],"mappings":";;AAeA;;;;AAiBO;AAIP;;;;;KArBY,qBAAA;EAwBV;;;AACK;AAOP;;;;;EAtBE,IAAA;EA8BA;;;AAAmC;AAQrC;;EA/BE,KAAK;AAAA;;KAIK,yBAAA;EA+BV,2FA7BA,IAAA,WAAe,MAAM;EACrB,IAAA;EACA,KAAA;AAAA;;;;;KAOU,iBAAA,GAAoB,qBAAA;EA4BjB;AAQf;;;;EA9BE,iBAAA,aA0Dc;EAxDd,OAAA,GAAU,yBAAyB;AAAA;;AAwDgD;AA4DrF;;;KA5GY,kBAAA;EACV,EAAA;EACA,MAAA,UA4GA;EA1GA,GAAA,UA2GO;EAzGP,KAAA,WA4Ic;EA1Id,IAAA;EACA,EAAA;EACA,SAAA;EACA,KAAA,GAAQ,MAAA;EACR,IAAA,GAAO,MAAM;AAAA;;;;;;cAQF,qBAAA;;;;AAkI2C;AAuGxD;;;;;;;iBA7MgB,oBAAA,CAAqB,GAAA,UAAa,WAAmC;;;;;;;;;iBA4DrE,sBAAA,CACd,KAAA,EAAO,MAAA,mBACP,WAAA,uBACC,MAAM;;;;;iBAmCO,4BAAA,CACd,YAAA,EAAc,qBAAA,cACd,GAAA,WACA,SAAA,YACC,QAAA,CAAS,qBAAA;EAA2B,iBAAA;AAAA;AA0HvC;;;;AAAA,KAnBY,gBAAA;EACV,EAAA;EACA,MAAA;EACA,GAAA;EACA,EAAA;EACA,SAAA;EACA,KAAA,GAAQ,MAAA;EACR,IAAA,GAAO,MAAA;EACP,KAAA;IAAU,IAAA;IAAe,IAAA;IAAe,OAAA,GAAU,qBAAA;EAAA;AAAA;;;;;;;;;iBAWpC,uBAAA,CAAwB,MAAA,EAAQ,gBAAA,GAAmB,kBAAkB"}

package/esm/http/request-log-snapshot.mjs

@@ -84,15 +84,94 @@ function redactQueryValue(value, isCredential) {
 }
 /**
 * The effective logging options for a request: `http.logging` overlaid by the
-* route's own `logging` option.
+* route's own `logging` option, then restricted by matching private URL policies.
 */
-function resolveRequestLoggingOptions(routeOptions) {
+function resolveRequestLoggingOptions(routeOptions, url, routePath) {
 	const global = config.get("http.logging") ?? {};
-	return {
+	const options = {
 		body: routeOptions?.body ?? global.body ?? true,
 		query: routeOptions?.query ?? global.query ?? true,
 		redactQueryParams: global.redactQueryParams ?? []
 	};
+	if (!global.private?.length || url === void 0) return options;
+	const candidates = loggingPathCandidates(url);
+	if (candidates === void 0) return {
+		...options,
+		body: false,
+		query: false
+	};
+	if (routePath) {
+		const routeCandidates = loggingPathCandidates(routePath);
+		if (!routeCandidates) return {
+			...options,
+			body: false,
+			query: false
+		};
+		candidates.push(...routeCandidates);
+	}
+	for (const rule of compiledPrivateRules(global.private)) {
+		let matches;
+		if (rule.type === "regex") {
+			const { regex, needsClone } = rule;
+			matches = candidates.some((candidate) => (needsClone ? new RegExp(regex.source, regex.flags) : regex).test(candidate));
+		} else {
+			const { prefixes } = rule;
+			matches = prefixes === void 0 || prefixes.some((prefix) => candidates.some((candidate) => prefix === "/" || candidate === prefix || candidate.startsWith(`${prefix}/`)));
+		}
+		if (!matches) continue;
+		if (rule.body === false) options.body = false;
+		if (rule.query === false) options.query = false;
+	}
+	return options;
+}
+/**
+* Compiled rules per configured `http.logging.private` array. Snapshots are
+* built several times per request, so each array's prefixes are normalised
+* once; replacing the array (a new config value) compiles the new one.
+*/
+const compiledRulesCache = /* @__PURE__ */ new WeakMap();
+function compiledPrivateRules(rules) {
+	let compiled = compiledRulesCache.get(rules);
+	if (compiled) return compiled;
+	compiled = rules.map((rule) => {
+		const { path, body, query } = rule;
+		if (path instanceof RegExp) return {
+			type: "regex",
+			regex: path,
+			needsClone: path.global || path.sticky,
+			body,
+			query
+		};
+		return {
+			type: "prefix",
+			prefixes: loggingPathCandidates(path),
+			body,
+			query
+		};
+	});
+	compiledRulesCache.set(rules, compiled);
+	return compiled;
+}
+/** Backslashes to slashes, repeated slashes collapsed, no trailing slash. */
+function collapseLoggingPath(path) {
+	return path.replace(/\\/g, "/").replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+}
+function loggingPathCandidates(url) {
+	try {
+		const pathname = url.replace(/^[a-z][a-z\d+.-]*:\/\/[^/?#]*/i, "").split(/[?#]/u)[0] || "/";
+		const raw = collapseLoggingPath(pathname);
+		const decoded = collapseLoggingPath(decodeURIComponent(pathname));
+		const segments = [];
+		for (const segment of decoded.split("/")) if (segment === "..") segments.pop();
+		else if (segment && segment !== ".") segments.push(segment);
+		return [...new Set([
+			raw,
+			decoded,
+			`/${segments.join("/")}`
+		])];
+	} catch {
+		return;
+	}
 }
 /**
 * Build the {@link RequestLogSnapshot} for a request, applying the route's
@@ -103,7 +182,7 @@ function resolveRequestLoggingOptions(routeOptions) {
 * Uploaded files are summarised (`{ file, mimeType }`) rather than walked.
 */
 function buildRequestLogSnapshot(source) {
-	const options = resolveRequestLoggingOptions(source.route?.logging);
+	const options = resolveRequestLoggingOptions(source.route?.logging, source.url, source.route?.path);
 	const url = options.query ? source.url : stripQuery(source.url);
 	const snapshot = {
 		id: source.id,