@warlock.js/core 5.29.0 → 5.31.0

package/esm/router/route-registry.mjs

@@ -1,7 +1,7 @@
 import { normalizeRequestPath } from "./normalize-request-path.mjs";
 import FindMyWay from "find-my-way";
 
-//#region ../core/src/router/route-registry.ts
+//#region ../../packages/core/src/router/route-registry.ts
 /**
 * The concrete HTTP verbs an `all` route expands into.
 * Mirrors the set Fastify's `.all()` answers in production, so `router.any()`

package/esm/router/route-registry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"route-registry.mjs","names":[],"sources":["../../../../../../../core/src/router/route-registry.ts"],"sourcesContent":["import FindMyWay, { type HTTPMethod, type Instance } from \"find-my-way\";\nimport { normalizeRequestPath } from \"./normalize-request-path\";\nimport type { RequestMethod, Route } from \"./types\";\n\n/**\n * The concrete HTTP verbs an `all` route expands into.\n * Mirrors the set Fastify's `.all()` answers in production, so `router.any()`\n * routes behave identically under the dev server and prod Fastify.\n */\nconst ALL_METHODS: Exclude<RequestMethod, \"all\">[] = [\n  \"GET\",\n  \"POST\",\n  \"PUT\",\n  \"PATCH\",\n  \"DELETE\",\n  \"OPTIONS\",\n  \"HEAD\",\n];\n\n/**\n * Route Registry\n * Manages dynamic route matching using find-my-way for HMR support\n */\nexport class RouteRegistry {\n  private router: Instance<any>;\n\n  public constructor() {\n    this.router = FindMyWay({\n      // Request paths are normalized explicitly in `find`; leaving this off\n      // makes that shared normalizer, rather than a second router option, the\n      // reason development accepts a terminal slash.\n      ignoreTrailingSlash: false,\n      caseSensitive: true,\n    });\n  }\n\n  /**\n   * Register all routes from the router's internal list\n   */\n  public register(routes: Route[]): void {\n    // Register each route\n    for (const route of routes) {\n      if (route.method === \"all\") {\n        for (const method of ALL_METHODS) {\n          this.registerRoute({\n            ...route,\n            method,\n          });\n        }\n      } else {\n        this.registerRoute(route);\n      }\n    }\n  }\n\n  /**\n   * Register a single route\n   */\n  public registerRoute(route: Route): void {\n    this.router.on(route.method as HTTPMethod, route.path, (req, res, params) => {\n      // Store the route and params for later use\n      return { route, params };\n    });\n  }\n\n  /**\n   * Find a matching route for the given method and URL\n   * @returns Matched route with extracted params, or null if no match\n   */\n  public find(\n    method: string,\n    url: string,\n  ): { route: Route; params: Record<string, string> } | null {\n    // Strip query string from URL (find-my-way expects just the path)\n    const path = normalizeRequestPath(url.split(\"?\")[0] ?? \"/\");\n\n    // HEAD falls back to the GET route, as Fastify's implicit HEAD does in production.\n    const match =\n      this.router.find(method as HTTPMethod, path) ??\n      (method === \"HEAD\" ? this.router.find(\"GET\", path) : null);\n\n    if (!match) {\n      return null;\n    }\n\n    // find-my-way handler expects (req, res, params, store, searchParams)\n    // We only care about the return value which contains { route, params }\n    return match.handler(null as any, null as any, match.params, match.store, {});\n  }\n\n  /**\n   * Get all registered routes count (for debugging)\n   */\n  public getRouteCount(): number {\n    return this.router\n      .prettyPrint()\n      .split(\"\\n\")\n      .filter((line) => line.trim()).length;\n  }\n}\n"],"mappings":";;;;;;;;;AASA,MAAM,cAA+C;CACnD;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;AAMA,IAAa,gBAAb,MAA2B;CAGzB,AAAO,cAAc;EACnB,KAAK,SAAS,UAAU;GAItB,qBAAqB;GACrB,eAAe;EACjB,CAAC;CACH;;;;CAKA,AAAO,SAAS,QAAuB;EAErC,KAAK,MAAM,SAAS,QAClB,IAAI,MAAM,WAAW,OACnB,KAAK,MAAM,UAAU,aACnB,KAAK,cAAc;GACjB,GAAG;GACH;EACF,CAAC;OAGH,KAAK,cAAc,KAAK;CAG9B;;;;CAKA,AAAO,cAAc,OAAoB;EACvC,KAAK,OAAO,GAAG,MAAM,QAAsB,MAAM,OAAO,KAAK,KAAK,WAAW;GAE3E,OAAO;IAAE;IAAO;GAAO;EACzB,CAAC;CACH;;;;;CAMA,AAAO,KACL,QACA,KACyD;EAEzD,MAAM,OAAO,qBAAqB,IAAI,MAAM,GAAG,CAAC,CAAC,MAAM,GAAG;EAG1D,MAAM,QACJ,KAAK,OAAO,KAAK,QAAsB,IAAI,MAC1C,WAAW,SAAS,KAAK,OAAO,KAAK,OAAO,IAAI,IAAI;EAEvD,IAAI,CAAC,OACH,OAAO;EAKT,OAAO,MAAM,QAAQ,MAAa,MAAa,MAAM,QAAQ,MAAM,OAAO,CAAC,CAAC;CAC9E;;;;CAKA,AAAO,gBAAwB;EAC7B,OAAO,KAAK,OACT,YAAY,CAAC,CACb,MAAM,IAAI,CAAC,CACX,QAAQ,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC;CACnC;AACF"}
+{"version":3,"file":"route-registry.mjs","names":[],"sources":["../../../../../../../../packages/core/src/router/route-registry.ts"],"sourcesContent":["import FindMyWay, { type HTTPMethod, type Instance } from \"find-my-way\";\nimport { normalizeRequestPath } from \"./normalize-request-path\";\nimport type { RequestMethod, Route } from \"./types\";\n\n/**\n * The concrete HTTP verbs an `all` route expands into.\n * Mirrors the set Fastify's `.all()` answers in production, so `router.any()`\n * routes behave identically under the dev server and prod Fastify.\n */\nconst ALL_METHODS: Exclude<RequestMethod, \"all\">[] = [\n  \"GET\",\n  \"POST\",\n  \"PUT\",\n  \"PATCH\",\n  \"DELETE\",\n  \"OPTIONS\",\n  \"HEAD\",\n];\n\n/**\n * Route Registry\n * Manages dynamic route matching using find-my-way for HMR support\n */\nexport class RouteRegistry {\n  private router: Instance<any>;\n\n  public constructor() {\n    this.router = FindMyWay({\n      // Request paths are normalized explicitly in `find`; leaving this off\n      // makes that shared normalizer, rather than a second router option, the\n      // reason development accepts a terminal slash.\n      ignoreTrailingSlash: false,\n      caseSensitive: true,\n    });\n  }\n\n  /**\n   * Register all routes from the router's internal list\n   */\n  public register(routes: Route[]): void {\n    // Register each route\n    for (const route of routes) {\n      if (route.method === \"all\") {\n        for (const method of ALL_METHODS) {\n          this.registerRoute({\n            ...route,\n            method,\n          });\n        }\n      } else {\n        this.registerRoute(route);\n      }\n    }\n  }\n\n  /**\n   * Register a single route\n   */\n  public registerRoute(route: Route): void {\n    this.router.on(route.method as HTTPMethod, route.path, (req, res, params) => {\n      // Store the route and params for later use\n      return { route, params };\n    });\n  }\n\n  /**\n   * Find a matching route for the given method and URL\n   * @returns Matched route with extracted params, or null if no match\n   */\n  public find(\n    method: string,\n    url: string,\n  ): { route: Route; params: Record<string, string> } | null {\n    // Strip query string from URL (find-my-way expects just the path)\n    const path = normalizeRequestPath(url.split(\"?\")[0] ?? \"/\");\n\n    // HEAD falls back to the GET route, as Fastify's implicit HEAD does in production.\n    const match =\n      this.router.find(method as HTTPMethod, path) ??\n      (method === \"HEAD\" ? this.router.find(\"GET\", path) : null);\n\n    if (!match) {\n      return null;\n    }\n\n    // find-my-way handler expects (req, res, params, store, searchParams)\n    // We only care about the return value which contains { route, params }\n    return match.handler(null as any, null as any, match.params, match.store, {});\n  }\n\n  /**\n   * Get all registered routes count (for debugging)\n   */\n  public getRouteCount(): number {\n    return this.router\n      .prettyPrint()\n      .split(\"\\n\")\n      .filter((line) => line.trim()).length;\n  }\n}\n"],"mappings":";;;;;;;;;AASA,MAAM,cAA+C;CACnD;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;AAMA,IAAa,gBAAb,MAA2B;CAGzB,AAAO,cAAc;EACnB,KAAK,SAAS,UAAU;GAItB,qBAAqB;GACrB,eAAe;EACjB,CAAC;CACH;;;;CAKA,AAAO,SAAS,QAAuB;EAErC,KAAK,MAAM,SAAS,QAClB,IAAI,MAAM,WAAW,OACnB,KAAK,MAAM,UAAU,aACnB,KAAK,cAAc;GACjB,GAAG;GACH;EACF,CAAC;OAGH,KAAK,cAAc,KAAK;CAG9B;;;;CAKA,AAAO,cAAc,OAAoB;EACvC,KAAK,OAAO,GAAG,MAAM,QAAsB,MAAM,OAAO,KAAK,KAAK,WAAW;GAE3E,OAAO;IAAE;IAAO;GAAO;EACzB,CAAC;CACH;;;;;CAMA,AAAO,KACL,QACA,KACyD;EAEzD,MAAM,OAAO,qBAAqB,IAAI,MAAM,GAAG,CAAC,CAAC,MAAM,GAAG;EAG1D,MAAM,QACJ,KAAK,OAAO,KAAK,QAAsB,IAAI,MAC1C,WAAW,SAAS,KAAK,OAAO,KAAK,OAAO,IAAI,IAAI;EAEvD,IAAI,CAAC,OACH,OAAO;EAKT,OAAO,MAAM,QAAQ,MAAa,MAAa,MAAM,QAAQ,MAAM,OAAO,CAAC,CAAC;CAC9E;;;;CAKA,AAAO,gBAAwB;EAC7B,OAAO,KAAK,OACT,YAAY,CAAC,CACb,MAAM,IAAI,CAAC,CACX,QAAQ,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC;CACnC;AACF"}

package/esm/router/router.d.mts

@@ -1,10 +1,10 @@
 import { FastifyInstance } from "../http/server.mjs";
-import { GroupedRoutesOptions, NamedApiRoute, NamedApiRoutesOptions, RequestHandler, RequestHandlerType, ResourceMethod, Route, RouteOptions, RouteResource, RouterGroupCallback, RouterStacks } from "./types.mjs";
+import { GroupedRoutesOptions, NamedApiRoute, NamedApiRoutesOptions, RequestHandler, RequestHandlerType, ResourceMethod, Route, RouteOptions, RouteResource, RouterGroupCallback, RouterStacks, StaticMountOptions } from "./types.mjs";
 import { RouteBuilder } from "./route-builder.mjs";
 import { FastifyHttpProxyOptions } from "@fastify/http-proxy";
 import { FastifyStaticOptions } from "@fastify/static";
 
-//#region ../core/src/router/router.d.ts
+//#region ../../packages/core/src/router/router.d.ts
 declare class Router {
   /**
    * Routes list
@@ -24,6 +24,11 @@ declare class Router {
    * {@link routes}; mutations and collision checks use this isolated draft.
    */
   private routeReplacementTransaction?;
+  /**
+   * Set by the dev server: whether to warn about mutating routes that have no
+   * auth middleware and no `public: true` (`http.warnUnguardedRoutes`).
+   */
+  private warnUnguardedRoutes;
   /**
    * Router Instance
    */
@@ -31,7 +36,10 @@ declare class Router {
   /**
    * Static paths
    */
-  protected staticDirectories: FastifyStaticOptions[];
+  protected staticDirectories: {
+    options: FastifyStaticOptions;
+    rateLimit: StaticMountOptions["rateLimit"];
+  }[];
   /**
    * Event listeners
    */
@@ -59,25 +67,43 @@ declare class Router {
    */
   redirect(from: string, to: string, redirectMode?: "temporary" | "permanent"): this;
   /**
-   * Server static folder
+   * Serve a static folder.
+   *
+   * Static mounts are exempt from the global rate limiter by default; set
+   * `http.rateLimit.staticFiles: true` to count every mount, or pass
+   * `{ rateLimit }` to decide for this mount alone: `true` counts it against
+   * the global limiter, `false` exempts it, and an object gives it its own
+   * limit and bucket.
+   *
+   * @example
+   * router.directory({ root: rootPath("docs"), prefix: "/docs/" });
+   * router.directory({ root: rootPath("exports"), prefix: "/exports/" }, { rateLimit: true });
+   */
+  directory(options: FastifyStaticOptions, mountOptions?: StaticMountOptions): this;
+  /** Declare static routes at boot; load the upstream sender on the first file request. */
+  protected registerStaticDirectories(server: FastifyInstance): void;
+  /**
+   * Register a GET route that serves a static file. Like `directory()`, it is
+   * exempt from the global rate limiter unless `http.rateLimit.staticFiles`
+   * or its own `rateLimit` says otherwise.
    */
-  directory(options: FastifyStaticOptions): this;
+  protected addStaticFileRoute(path: string, handler: RequestHandler, mountOptions?: StaticMountOptions): this;
   /**
    * Serve file
    */
-  file(path: string, location: string, cacheTime?: number): this;
+  file(path: string, location: string, cacheTime?: number, mountOptions?: StaticMountOptions): this;
   /**
    * Serve cached file, it will cache the file to 1 year by default
    */
-  cachedFile(path: string, location: string, cacheTime?: number): this;
+  cachedFile(path: string, location: string, cacheTime?: number, mountOptions?: StaticMountOptions): this;
   /**
    * Serve list of files
    */
-  files(files: Record<string, string>, cacheTime?: number): void;
+  files(files: Record<string, string>, cacheTime?: number, mountOptions?: StaticMountOptions): void;
   /**
    * Serve list of cached files, it will cache the file to 1 year by default
    */
-  cachedFiles(files: Record<string, string>, cacheTime?: number): void;
+  cachedFiles(files: Record<string, string>, cacheTime?: number, mountOptions?: StaticMountOptions): void;
   /**
    * Add proxy route
    */

package/esm/router/router.d.mts.map

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

package/esm/router/router.mjs

@@ -1,25 +1,31 @@
+import { config as config$1 } from "../config/config-getter.mjs";
 import { buildTracingContext, dispatchPhase, isTracingEnabled } from "../http/tracing/tracing-dispatcher.mjs";
 import "../http/tracing/index.mjs";
 import { normalizeRoutePath } from "./normalize-route-path.mjs";
 import { forgetPositionalHandlerSuspects, inspectHandlerSignature, reportPositionalHandlerSuspects } from "./positional-handler-diagnostics.mjs";
 import { routeNameMethodSuffix } from "./route-name-method-suffix.mjs";
+import { WarlockError } from "../errors/warlock-error.mjs";
+import { RouteNameTakenError } from "./route-name-taken-error.mjs";
 import { RouteRegistry } from "./route-registry.mjs";
 import { container } from "../container/index.mjs";
+import { registerLazyStatic } from "../http/lazy-static.mjs";
 import { buildCorsOptions } from "../http/build-cors-options.mjs";
 import { Response } from "../http/response.mjs";
+import { buildRequestLogSnapshot } from "../http/request-log-snapshot.mjs";
 import { Request } from "../http/request.mjs";
 import { describeRouteForLog } from "./describe-route-for-log.mjs";
 import { logRequestLifecycle } from "./log-request-lifecycle.mjs";
+import { reportUnguardedMutatingRoutes } from "./unguarded-route-diagnostics.mjs";
 import { RouteBuilder } from "./route-builder.mjs";
-import { buildRouteRateLimit } from "./build-route-rate-limit.mjs";
+import { resolveRouteRateLimit, resolveStaticRateLimit } from "./resolve-route-rate-limit.mjs";
 import { DEV_DISPATCH_METHODS, buildNotFoundBody, createDevRateLimiter } from "./dev-dispatch.mjs";
+import config from "@mongez/config";
 import { log } from "@warlock.js/logger";
 import { isEmpty } from "@mongez/supportive-is";
 import { ltrim, merge, toCamelCase, trim } from "@mongez/reinforcements";
 import proxy from "@fastify/http-proxy";
-import fastifyStatic from "@fastify/static";
 
-//#region ../core/src/router/router.ts
+//#region ../../packages/core/src/router/router.ts
 /**
 * The pre-handler phases the dev server forwards from a route's `serverOptions`.
 *
@@ -94,6 +100,7 @@ var Router = class Router {
 	constructor() {
 		this.routes = [];
 		this.routesVersion = 0;
+		this.warnUnguardedRoutes = false;
 		this.staticDirectories = [];
 		this.eventListeners = {};
 		this.stacks = {
@@ -125,43 +132,71 @@ var Router = class Router {
 		});
 	}
 	/**
-	* Server static folder
+	* Serve a static folder.
+	*
+	* Static mounts are exempt from the global rate limiter by default; set
+	* `http.rateLimit.staticFiles: true` to count every mount, or pass
+	* `{ rateLimit }` to decide for this mount alone: `true` counts it against
+	* the global limiter, `false` exempts it, and an object gives it its own
+	* limit and bucket.
+	*
+	* @example
+	* router.directory({ root: rootPath("docs"), prefix: "/docs/" });
+	* router.directory({ root: rootPath("exports"), prefix: "/exports/" }, { rateLimit: true });
+	*/
+	directory(options, mountOptions = {}) {
+		this.staticDirectories.push({
+			options,
+			rateLimit: mountOptions.rateLimit
+		});
+		return this;
+	}
+	/** Declare static routes at boot; load the upstream sender on the first file request. */
+	registerStaticDirectories(server) {
+		for (const directory of this.staticDirectories) registerLazyStatic(server, {
+			...directory.options,
+			decorateReply: false
+		}, { rateLimit: resolveStaticRateLimit(directory.rateLimit) });
+	}
+	/**
+	* Register a GET route that serves a static file. Like `directory()`, it is
+	* exempt from the global rate limiter unless `http.rateLimit.staticFiles`
+	* or its own `rateLimit` says otherwise.
 	*/
-	directory(options) {
-		this.staticDirectories.push(options);
+	addStaticFileRoute(path, handler, mountOptions = {}) {
+		this.get(path, handler, mountOptions.rateLimit === void 0 ? {} : { rateLimit: mountOptions.rateLimit });
+		const routes = this.routeReplacementTransaction?.routes ?? this.routes;
+		const route = routes[routes.length - 1];
+		if (route) route.$staticFile = true;
 		return this;
 	}
 	/**
 	* Serve file
 	*/
-	file(path, location, cacheTime) {
-		return this.get(path, ({ response }) => {
+	file(path, location, cacheTime, mountOptions = {}) {
+		return this.addStaticFileRoute(path, ({ response }) => {
 			response.sendFile(location, cacheTime);
-		});
+		}, mountOptions);
 	}
 	/**
 	* Serve cached file, it will cache the file to 1 year by default
 	*/
-	cachedFile(path, location, cacheTime) {
-		return this.get(path, ({ response }) => {
+	cachedFile(path, location, cacheTime, mountOptions = {}) {
+		return this.addStaticFileRoute(path, ({ response }) => {
 			response.sendCachedFile(location, cacheTime);
-		});
+		}, mountOptions);
 	}
 	/**
 	* Serve list of files
 	*/
-	files(files, cacheTime) {
-		for (const [path, location] of Object.entries(files)) this.get(path, ({ response }) => {
-			response.sendFile(location, cacheTime);
-		});
+	files(files, cacheTime, mountOptions = {}) {
+		for (const [path, location] of Object.entries(files)) this.file(path, location, cacheTime, mountOptions);
 	}
 	/**
 	* Serve list of cached files, it will cache the file to 1 year by default
 	*/
-	cachedFiles(files, cacheTime) {
-		for (const [path, location] of Object.entries(files)) this.get(path, ({ response }) => {
-			response.sendCachedFile(location, cacheTime);
-		});
+	cachedFiles(files, cacheTime, mountOptions = {}) {
+		for (const [path, location] of Object.entries(files)) this.cachedFile(path, location, cacheTime, mountOptions);
 	}
 	proxy(...args) {
 		this.beforeScanning((_router, server) => {
@@ -193,9 +228,10 @@ var Router = class Router {
 		options = { ...options };
 		if (middlewarePrecedence === "before") options.middleware = [...options.middleware || [], ...this.stacks.middleware];
 		else options.middleware = [...this.stacks.middleware, ...options.middleware || []];
+		if (options.public === void 0 && (this.stacks.public ?? 0) > 0) options.public = true;
 		if (Array.isArray(handler)) {
 			const [controller, action] = handler;
-			if (typeof controller[action] !== "function") throw new Error(`Invalid controller action "${action}" for controller "${controller.constructor.name}"`);
+			if (typeof controller[action] !== "function") throw new WarlockError("WL3002", `Invalid controller action "${action}" for controller "${controller.constructor.name}"`);
 			handler = controller[action].bind(controller);
 			copyResponseSchema(controller[action], handler);
 			if (!handler.validation) {
@@ -218,7 +254,7 @@ var Router = class Router {
 		const routes = this.routeReplacementTransaction?.routes ?? this.routes;
 		if (routeData.name) {
 			const route = routes.find((route) => route.name === routeData.name);
-			if (route) if (route.method === routeData.method) throw new Error(`Route name "${routeData.name}" is already taken.\n  already registered: ${describeRouteClaimant(route)}\n  now being added:    ${describeRouteClaimant(routeData)}\nPages and API routes share one route-name namespace, so a name can only be claimed once. Rename one of them via the "name" route option.`);
+			if (route) if (route.method === routeData.method) throw new RouteNameTakenError(routeData.name, `Route name "${routeData.name}" is already taken.\n  already registered: ${describeRouteClaimant(route)}\n  now being added:    ${describeRouteClaimant(routeData)}\nPages and API routes share one route-name namespace, so a name can only be claimed once. Rename one of them via the "name" route option.`);
 			else routeData.name += routeNameMethodSuffix(routeData.method);
 		}
 		if (this.routeReplacementTransaction) this.routeReplacementTransaction.addedRoutes.push(routeData);
@@ -353,7 +389,8 @@ var Router = class Router {
 	* Group routes with options
 	*/
 	group(options, callback) {
-		const { prefix, name = prefix ? trim(prefix.replace(/\//g, "."), ".") : void 0, middleware } = options;
+		const { prefix, name = prefix ? trim(prefix.replace(/\//g, "."), ".") : void 0, middleware, public: isPublic } = options;
+		if (isPublic) this.stacks.public = (this.stacks.public ?? 0) + 1;
 		if (prefix) this.stacks.prefix.push(prefix);
 		if (name) this.stacks.name.push(name);
 		if (middleware) this.stacks.middleware.push(...middleware);
@@ -363,6 +400,7 @@ var Router = class Router {
 			if (prefix) this.stacks.prefix.pop();
 			if (name) this.stacks.name.pop();
 			if (middleware) this.stacks.middleware.splice(this.stacks.middleware.length - middleware.length, middleware.length);
+			if (isPublic) this.stacks.public = (this.stacks.public ?? 1) - 1;
 		}
 		return this;
 	}
@@ -451,6 +489,7 @@ var Router = class Router {
 			for (const sourceFile of transaction.removedSourceFiles) forgetPositionalHandlerSuspects(sourceFile);
 			const committedRoutes = new Set(transaction.routes);
 			for (const route of transaction.addedRoutes) if (committedRoutes.has(route)) inspectHandlerSignature(route.handler, route);
+			if (this.warnUnguardedRoutes) reportUnguardedMutatingRoutes(transaction.addedRoutes.filter((route) => committedRoutes.has(route)));
 			this.routesVersion++;
 			return result;
 		} catch (error) {
@@ -556,7 +595,7 @@ var Router = class Router {
 				...requestMethod === "get" && explicitHeadPaths.has(route.path) && { exposeHeadRoute: false },
 				config: {
 					...route.serverOptions?.config,
-					...route.rateLimit && { rateLimit: buildRouteRateLimit(route.rateLimit) }
+					rateLimit: resolveRouteRateLimit(route)
 				}
 			};
 			requestMethodFunction(route.path, options, async (baseRequest, reply) => {
@@ -564,10 +603,7 @@ var Router = class Router {
 				return output || response.baseResponse;
 			});
 		});
-		for (const directoryOptions of this.staticDirectories) server.register(fastifyStatic, {
-			...directoryOptions,
-			decorateReply: false
-		});
+		this.registerStaticDirectories(server);
 		this.eventListeners.afterScanning?.forEach((callback) => callback(this, server));
 	}
 	/**
@@ -576,10 +612,12 @@ var Router = class Router {
 	*/
 	scanDevServer(server) {
 		reportPositionalHandlerSuspects();
+		this.warnUnguardedRoutes = config$1.key("http.warnUnguardedRoutes", true) !== false;
+		if (this.warnUnguardedRoutes) reportUnguardedMutatingRoutes(this.routes);
 		this.eventListeners.beforeScan?.forEach((callback) => callback(this, server));
 		let routeRegistry;
 		let registryVersion = -1;
-		const applyDevRateLimit = createDevRateLimiter(server);
+		const applyDevRateLimit = createDevRateLimiter(server, config.get("http.rateLimit.global") !== false);
 		const resolveRouteRegistry = () => {
 			if (routeRegistry && registryVersion === this.routesVersion) return routeRegistry;
 			routeRegistry = new RouteRegistry();
@@ -611,7 +649,12 @@ var Router = class Router {
 			} catch (error) {
 				log.error("router", "dev-dispatch", error, {
 					method: fastifyRequest.method,
-					url: fastifyRequest.url
+					url: buildRequestLogSnapshot({
+						id: fastifyRequest.id,
+						method: fastifyRequest.method,
+						url: fastifyRequest.url,
+						route: match.route
+					}).url
 				});
 				throw error;
 			}
@@ -626,13 +669,11 @@ var Router = class Router {
 				method,
 				url: "*",
 				...method === "GET" && { exposeHeadRoute: false },
+				config: { rateLimit: false },
 				handler: wildcardHandler
 			});
 		}
-		for (const directoryOptions of this.staticDirectories) server.register(fastifyStatic, {
-			...directoryOptions,
-			decorateReply: false
-		});
+		this.registerStaticDirectories(server);
 		this.eventListeners.afterScanning?.forEach((callback) => callback(this, server));
 	}
 	/**
@@ -640,13 +681,13 @@ var Router = class Router {
 	*/
 	getRoute(name, params = {}) {
 		const route = this.routes.find((route) => route.name === name);
-		if (!route) throw new Error(`Route name "${name}" not found`);
+		if (!route) throw new WarlockError("WL3003", `Route name "${name}" not found`);
 		const used = /* @__PURE__ */ new Set();
 		const path = route.path.replace(/:([A-Za-z0-9_]+)(\?)?/g, (_match, key, optional) => {
 			const value = params[key];
 			if (value === void 0 || value === null) {
 				if (optional) return "";
-				throw new Error(`Route "${name}" is missing the "${key}" param`);
+				throw new WarlockError("WL3004", `Route "${name}" is missing the "${key}" param`);
 			}
 			used.add(key);
 			return encodeURIComponent(String(value));
@@ -681,10 +722,7 @@ var Router = class Router {
 				module: "route",
 				action: describeRouteForLog(route.method, route.path),
 				requestId: request.id,
-				context: {
-					request,
-					response
-				},
+				context: { request: request.toLogSnapshot() },
 				request,
 				statusCode: () => fastifyResponse.statusCode
 			}, () => request.execute());