@daloyjs/core 1.1.1 → 1.2.1

package/dist/app.js

@@ -2,7 +2,8 @@ import { Router } from "./router.js";
 import { WebSocketRegistry, normalizeWebSocketOptions, } from "./websocket.js";
 import { BadRequestError, ForbiddenError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, TooManyRequestsError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
 import { readBodyLimited, safeJsonParseLimited, randomId, assertInboundHeaderGuards, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey, } from "./security.js";
-import { createLogger, noopLogger, sanitizeUrlForLog } from "./logger.js";
+import { createLogger, noopLogger, sanitizeUrlForLog, } from "./logger.js";
+import { createAppTelemetry, } from "./otlp.js";
 import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
 import { isSchemaValidatedResponse } from "./internal-response.js";
 import { asyncapiHtml, docsContentSecurityPolicy, redocHtml, scalarHtml, swaggerUiHtml, } from "./docs.js";
@@ -12,7 +13,7 @@ import { COMPRESSION_HOOK_MARKER } from "./compression.js";
 import { SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER } from "./session.js";
 import { loadShedding as loadSheddingMiddleware, } from "./load-shedding.js";
 import { httpMetrics, MetricsRegistry, PROMETHEUS_CONTENT_TYPE, } from "./metrics.js";
-import { Scheduler } from "./scheduler.js";
+import { Scheduler, } from "./scheduler.js";
 import { securitySchemeRequiresPayloadAuth } from "./security-schemes.js";
 import { assertBehindProxy } from "./conn-info.js";
 const AUTO_SECURE_HEADERS_MARKER = Symbol.for("daloyjs.app.autoSecureHeaders");
@@ -374,6 +375,13 @@ export class App {
     options;
     /** Structured logger for the app. Defaults to a JSON-lines console logger; override via `options.logger`. */
     log;
+    /**
+     * OTLP telemetry wiring created by the `telemetry` option; `undefined` when
+     * the option is off. Exposed for tests and advanced flushing.
+     *
+     * @since 1.2.0
+     */
+    telemetry;
     /**
      * Public registry: enables OpenAPI gen, typed-client gen, dead-route detection.
      *
@@ -477,7 +485,9 @@ export class App {
     }
     get globalCorsAllows() {
         if (this._globalCorsAllowsCache === undefined) {
-            this._globalCorsAllowsCache = corsOriginAllowsFromHooks([this.options.hooks ?? {}]);
+            this._globalCorsAllowsCache = corsOriginAllowsFromHooks([
+                this.options.hooks ?? {},
+            ]);
         }
         return this._globalCorsAllowsCache;
     }
@@ -490,7 +500,10 @@ export class App {
     _coldPathHooksCache;
     get coldPathHooks() {
         if (this._coldPathHooksCache === undefined) {
-            this._coldPathHooksCache = mergeHooks([this.options.hooks ?? {}, ...this.groupHooks]);
+            this._coldPathHooksCache = mergeHooks([
+                this.options.hooks ?? {},
+                ...this.groupHooks,
+            ]);
         }
         return this._coldPathHooksCache;
     }
@@ -505,12 +518,26 @@ export class App {
             jsonMaxDepth: resolved.jsonMaxDepth ?? DEFAULTS.jsonMaxDepth,
             ...resolved,
         };
+        // Telemetry is resolved before the logger so the logger's write sink can
+        // tee into the OTLP log exporter. Inert when no endpoint is configured.
+        const telemetryOpt = options.telemetry;
+        this.telemetry =
+            telemetryOpt === undefined || telemetryOpt === false
+                ? undefined
+                : createAppTelemetry(telemetryOpt === true ? {} : telemetryOpt);
+        const telemetryWrite = this.telemetry?.logWrite;
         this.log =
             options.logger === false
                 ? noopLogger
-                : options.logger && typeof options.logger.info === "function"
+                : options.logger &&
+                    typeof options.logger.info === "function"
                     ? options.logger
-                    : createLogger({ level: options.logger?.level ?? "info" });
+                    : createLogger({
+                        level: options.logger?.level ?? "info",
+                        ...(telemetryWrite !== undefined
+                            ? { write: telemetryWrite }
+                            : {}),
+                    });
         this.warnOnEnvMismatch();
         this.assertDisconnectStatusCode();
         assertBehindProxy(this.options.behindProxy);
@@ -522,6 +549,20 @@ export class App {
         this.maybeInstallCrashHandlers();
         this.maybeMountDocs();
         this.maybeMountAsyncAPI();
+        if (this.telemetry !== undefined) {
+            if (this.telemetry.hooks !== undefined)
+                this.use(this.telemetry.hooks);
+            const telemetry = this.telemetry;
+            this.onClose(() => telemetry.flush());
+            this.log.info({
+                event: "telemetry.otlp",
+                active: telemetry.endpoint !== null,
+                // Endpoint only — OTLP headers may carry tenant credentials.
+                endpoint: telemetry.endpoint ?? undefined,
+            }, telemetry.endpoint !== null
+                ? "OTLP telemetry export active"
+                : "Telemetry enabled but no OTEL_EXPORTER_OTLP_ENDPOINT configured; export disabled");
+        }
     }
     /**
      * Validate {@link AppOptions.disconnectStatusCode}.
@@ -626,7 +667,9 @@ export class App {
             secureHeaders: o.secureDefaults !== false && o.secureHeaders !== false,
             corsCrossOriginGuard: o.secureDefaults !== false && o.corsCrossOriginGuard !== false,
             csrf: o.csrf === "off" ? "off" : "on",
-            crashOnUnhandledRejection: o.crashOnUnhandledRejection === undefined ? "default" : o.crashOnUnhandledRejection,
+            crashOnUnhandledRejection: o.crashOnUnhandledRejection === undefined
+                ? "default"
+                : o.crashOnUnhandledRejection,
             trustProxy: o.trustProxy === undefined ? "unconfigured" : o.trustProxy,
             bodyLimitBytes: this.options.bodyLimitBytes,
             requestTimeoutMs: this.options.requestTimeoutMs,
@@ -652,7 +695,8 @@ export class App {
         if (this.options.secureDefaults === false)
             return;
         if (this.options.secureHeaders !== false) {
-            const opts = this.options.secureHeaders && typeof this.options.secureHeaders === "object"
+            const opts = this.options.secureHeaders &&
+                typeof this.options.secureHeaders === "object"
                 ? this.options.secureHeaders
                 : {};
             const auto = secureHeadersMiddleware(opts);
@@ -661,7 +705,9 @@ export class App {
         }
         // Opt-in load-shedding pressure monitor.
         if (this.options.loadShedding) {
-            const lsOpts = typeof this.options.loadShedding === "object" ? this.options.loadShedding : {};
+            const lsOpts = typeof this.options.loadShedding === "object"
+                ? this.options.loadShedding
+                : {};
             this.groupHooks.push(loadSheddingMiddleware(lsOpts));
         }
     }
@@ -768,7 +814,10 @@ export class App {
             return;
         if (this.options.corsCrossOriginGuard === false)
             return;
-        if (method !== "POST" && method !== "PUT" && method !== "PATCH" && method !== "DELETE") {
+        if (method !== "POST" &&
+            method !== "PUT" &&
+            method !== "PATCH" &&
+            method !== "DELETE") {
             return;
         }
         const origin = request.headers.get("origin");
@@ -783,7 +832,9 @@ export class App {
         // are identical on both paths.
         const fastHeaderOrigin = getOriginFast(origin);
         if (fastHeaderOrigin !== undefined) {
-            const fastReqOrigin = typeof requestUrl === "string" ? getOriginFast(requestUrl) : requestUrl.origin;
+            const fastReqOrigin = typeof requestUrl === "string"
+                ? getOriginFast(requestUrl)
+                : requestUrl.origin;
             if (fastReqOrigin !== undefined) {
                 if (fastHeaderOrigin === fastReqOrigin)
                     return;
@@ -802,7 +853,9 @@ export class App {
             // Malformed Origin header — refuse loudly.
             throw new ForbiddenError("Cross-origin state-changing request rejected: malformed Origin header.");
         }
-        const reqOrigin = typeof requestUrl === "string" ? new URL(requestUrl).origin : requestUrl.origin;
+        const reqOrigin = typeof requestUrl === "string"
+            ? new URL(requestUrl).origin
+            : requestUrl.origin;
         if (originUrl.origin === reqOrigin)
             return;
         if (corsOriginAllows.some((allows) => allows(origin)))
@@ -907,7 +960,8 @@ export class App {
      * `test`, which is a known, non-production answer).
      */
     isEnvIndeterminate() {
-        if (this.options.env !== undefined || this.options.production !== undefined) {
+        if (this.options.env !== undefined ||
+            this.options.production !== undefined) {
             return false;
         }
         const nodeEnv = typeof process !== "undefined" && typeof process.env !== "undefined"
@@ -1067,7 +1121,8 @@ export class App {
         // follow them there because its `keyGenerator` is caller-supplied and may
         // read `ctx.state`, so the unsafe order is refused instead.
         const replayBeforeBudget = this.routeSecurityMarkers.find((r) => r.replayBeforeBudget !== null);
-        if (replayBeforeBudget !== undefined && this.bootGuard.error === undefined) {
+        if (replayBeforeBudget !== undefined &&
+            this.bootGuard.error === undefined) {
             this.bootGuard.error = new Error(`Route ${replayBeforeBudget.method} ${replayBeforeBudget.path} runs ` +
                 `${replayBeforeBudget.replayBeforeBudget} before rateLimit() / loginThrottle() in its ` +
                 `effective hook chain. Both act from beforeHandle, so a cache hit or an idempotent ` +
@@ -1161,7 +1216,8 @@ export class App {
         // refusal must stay visible — but drop the stack, so a client cannot
         // multiply the bytes it pushes into the error tier by replaying the header.
         // The actionable message is logged once per process by the warn above.
-        refusal[OMIT_STACK_IN_LOG] = true;
+        refusal[OMIT_STACK_IN_LOG] =
+            true;
         throw refusal;
     }
     /**
@@ -1214,11 +1270,15 @@ export class App {
         };
         const generate = async () => generateOpenAPI(this, {
             info: resolveInfo(),
-            ...(this.options.openapi?.servers ? { servers: this.options.openapi.servers } : {}),
+            ...(this.options.openapi?.servers
+                ? { servers: this.options.openapi.servers }
+                : {}),
             ...(this.options.openapi?.securitySchemes
                 ? { securitySchemes: this.options.openapi.securitySchemes }
                 : {}),
-            ...(this.options.openapi?.webhooks ? { webhooks: this.options.openapi.webhooks } : {}),
+            ...(this.options.openapi?.webhooks
+                ? { webhooks: this.options.openapi.webhooks }
+                : {}),
         });
         this.route({
             method: "GET",
@@ -1246,7 +1306,9 @@ export class App {
                 summary: "OpenAPI 3.1 document (YAML)",
                 acknowledgeNoResponseBodySchema: true,
                 responses: {
-                    200: { description: "OpenAPI 3.1 document for this application, in YAML." },
+                    200: {
+                        description: "OpenAPI 3.1 document for this application, in YAML.",
+                    },
                 },
                 handler: async () => ({
                     status: 200,
@@ -1275,7 +1337,9 @@ export class App {
             ...(ui === "redoc"
                 ? { ...opts.csp, allowBlobWorkers: opts.csp?.allowBlobWorkers ?? true }
                 : opts.csp),
-            ...(docsConnectOrigins.length ? { connectOrigins: docsConnectOrigins } : {}),
+            ...(docsConnectOrigins.length
+                ? { connectOrigins: docsConnectOrigins }
+                : {}),
         });
         this.route({
             method: "GET",
@@ -1360,7 +1424,9 @@ export class App {
      */
     mountAsyncAPI(opts) {
         const jsonPath = (opts.jsonPath ?? "/asyncapi.json");
-        const yamlPath = opts.yamlPath === false ? null : (opts.yamlPath ?? "/asyncapi.yaml");
+        const yamlPath = opts.yamlPath === false
+            ? null
+            : (opts.yamlPath ?? "/asyncapi.yaml");
         const uiPath = (opts.path ?? "/asyncapi");
         const tags = opts.tags ?? ["AsyncAPI"];
         const resolveInfo = () => {
@@ -1383,7 +1449,9 @@ export class App {
             // Framework-owned bodies on the AsyncAPI surface, like mountDocs above.
             acknowledgeNoResponseBodySchema: true,
             responses: {
-                200: { description: "AsyncAPI 3.0 document for this application's WebSocket channels." },
+                200: {
+                    description: "AsyncAPI 3.0 document for this application's WebSocket channels.",
+                },
             },
             handler: async () => ({ status: 200, body: await generate() }),
         });
@@ -1396,7 +1464,9 @@ export class App {
                 summary: "AsyncAPI 3.0 document (YAML)",
                 acknowledgeNoResponseBodySchema: true,
                 responses: {
-                    200: { description: "AsyncAPI 3.0 document for this application, in YAML." },
+                    200: {
+                        description: "AsyncAPI 3.0 document for this application, in YAML.",
+                    },
                 },
                 handler: async () => ({
                     status: 200,
@@ -1541,7 +1611,10 @@ export class App {
             ...corsOriginAllowsFromHooks([globalHookLayer]),
             ...corsOriginAllows,
         ];
-        const securityMarkers = securityMarkersFromHooks([globalHookLayer, ...sources]);
+        const securityMarkers = securityMarkersFromHooks([
+            globalHookLayer,
+            ...sources,
+        ]);
         // Capture the decorations of this route's scope at registration time so the
         // dispatch hot path reads the scope-local bag rather than the root app's.
         // `this.decorations` is this scope's own bag (the root's, or the child's
@@ -1608,7 +1681,9 @@ export class App {
         return this.addHttpShorthand("HEAD", path, options, handler);
     }
     addHttpShorthand(method, path, options, possibleHandler) {
-        if (options === null || typeof options !== "object" || typeof possibleHandler !== "function") {
+        if (options === null ||
+            typeof options !== "object" ||
+            typeof possibleHandler !== "function") {
             throw new TypeError(`app.${method.toLowerCase()}(): expected (path, contract, handler); opaque responses require an explicit contract with acknowledgeNoResponseBodySchema: true`);
         }
         const contract = options;
@@ -1734,7 +1809,9 @@ export class App {
      */
     readinesscheck(opts = {}) {
         this.registerHealthRoute("readinesscheck", opts, () => {
-            if (this.draining || this.pendingPlugins.size > 0 || this.pluginBootError.failed) {
+            if (this.draining ||
+                this.pendingPlugins.size > 0 ||
+                this.pluginBootError.failed) {
                 return {
                     status: 503,
                     body: { status: "not-ready" },
@@ -1769,8 +1846,13 @@ export class App {
      *
      * Call this **before** registering the routes you want measured — like any
      * `app.use(...)` middleware, the instrumentation only wraps routes added
-     * afterwards. Pass `opts.registry` to register custom application metrics
-     * that are rendered alongside the built-in HTTP series.
+     * afterwards. Calling it after routes already exist logs a
+     * `metrics.late_install` warning listing the uninstrumented paths.
+     * Pass `opts.registry` to register custom application metrics that are
+     * rendered alongside the built-in HTTP series. Default series names are
+     * unprefixed (`http_requests_total`, `process_resident_memory_bytes`);
+     * construct the registry with `prefix: "daloy_"` if you want the old
+     * names.
      *
      * @param opts - Path, auth, rate-limit, registry, and label configuration.
      * @returns `this` for chaining.
@@ -1779,7 +1861,9 @@ export class App {
     metrics(opts = {}) {
         const path = (opts.path ?? "/metrics");
         const registry = opts.registry ?? new MetricsRegistry();
-        const rateLimitConfig = opts.rateLimit === false ? null : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
+        const rateLimitConfig = opts.rateLimit === false
+            ? null
+            : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
         const token = opts.token;
         // Refuse-to-boot: an unauthenticated metrics scrape in production is a
         // documented info-disclosure surface (route inventory, latency
@@ -1793,6 +1877,27 @@ export class App {
                 `Authorization: Bearer <token>, or pass acknowledgeUnauthenticated: true ` +
                 `to acknowledge that this scrape endpoint is reachable without credentials.`);
         }
+        // Group hooks only wrap routes registered *after* this call. Framework
+        // auto-mounts (docs / health / metrics / reporting) are tagged and
+        // ignored; anything else already on `this.routes` is a footgun.
+        const skipLateTags = new Set([
+            "Docs",
+            "Observability",
+            "Health",
+            "Reporting",
+        ]);
+        const late = this.routes.filter((r) => {
+            const tags = r.tags ?? [];
+            return !tags.some((t) => skipLateTags.has(t));
+        });
+        if (late.length > 0) {
+            const listed = late.slice(0, 20).map((r) => `${r.method} ${r.path}`);
+            this.log.warn({
+                event: "metrics.late_install",
+                count: late.length,
+                routes: listed,
+            }, `app.metrics() was called after ${late.length} route(s) were registered; those routes are not RED-instrumented. Call app.metrics() before app.get/post/...`);
+        }
         // Install RED instrumentation as a group hook so it wraps every route
         // registered after this call. Always exclude the scrape path itself, plus
         // any caller-supplied predicate.
@@ -1805,7 +1910,9 @@ export class App {
             exclude,
         }));
         this._coldPathHooksCache = undefined;
-        const buckets = rateLimitConfig ? new Map() : null;
+        const buckets = rateLimitConfig
+            ? new Map()
+            : null;
         const trustProxyHeaders = appTrustsProxyHeaders(this.options);
         this.route({
             method: "GET",
@@ -1821,7 +1928,10 @@ export class App {
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
-                        buckets.set(key, { count: 1, resetMs: now + rateLimitConfig.windowMs });
+                        buckets.set(key, {
+                            count: 1,
+                            resetMs: now + rateLimitConfig.windowMs,
+                        });
                     }
                     else {
                         entry.count++;
@@ -1889,7 +1999,9 @@ export class App {
      */
     cron(def, handler) {
         if (this.scheduler === undefined) {
-            const scheduler = new Scheduler({ logger: this.log.child({ component: "scheduler" }) });
+            const scheduler = new Scheduler({
+                logger: this.log.child({ component: "scheduler" }),
+            });
             this.scheduler = scheduler;
             scheduler.start();
             // Drain the scheduler during the post-drain close phase so periodic
@@ -1912,7 +2024,9 @@ export class App {
         const isHealth = kind === "healthcheck";
         const defaultPath = (isHealth ? "/healthz" : "/readyz");
         const path = (opts.path ?? defaultPath);
-        const rateLimitConfig = opts.rateLimit === false ? null : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
+        const rateLimitConfig = opts.rateLimit === false
+            ? null
+            : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
         const token = opts.token;
         // Refuse-to-boot: unauthenticated health/ready probes in
         // production are a documented info-disclosure surface (process uptime,
@@ -1926,7 +2040,9 @@ export class App {
                 `Authorization: Bearer <token>, or pass acknowledgeUnauthenticated: true ` +
                 `to acknowledge that this probe is reachable without credentials.`);
         }
-        const buckets = rateLimitConfig ? new Map() : null;
+        const buckets = rateLimitConfig
+            ? new Map()
+            : null;
         const trustProxyHeaders = appTrustsProxyHeaders(this.options);
         this.route({
             method: "GET",
@@ -1942,7 +2058,10 @@ export class App {
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
-                        buckets.set(key, { count: 1, resetMs: now + rateLimitConfig.windowMs });
+                        buckets.set(key, {
+                            count: 1,
+                            resetMs: now + rateLimitConfig.windowMs,
+                        });
                     }
                     else {
                         entry.count++;
@@ -2000,8 +2119,12 @@ export class App {
         if (!Number.isInteger(maxBytes) || maxBytes <= 0 || maxBytes > HARD_MAX) {
             throw new Error(`cspReportRoute(): maxBodyBytes must be a positive integer <= ${HARD_MAX}.`);
         }
-        const rateLimitConfig = opts.rateLimit === false ? null : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
-        const buckets = rateLimitConfig ? new Map() : null;
+        const rateLimitConfig = opts.rateLimit === false
+            ? null
+            : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
+        const buckets = rateLimitConfig
+            ? new Map()
+            : null;
         const trustProxyHeaders = appTrustsProxyHeaders(this.options);
         const log = this.log;
         // Only log report bodies when explicitly enabled. In
@@ -2020,7 +2143,10 @@ export class App {
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
-                        buckets.set(key, { count: 1, resetMs: now + rateLimitConfig.windowMs });
+                        buckets.set(key, {
+                            count: 1,
+                            resetMs: now + rateLimitConfig.windowMs,
+                        });
                     }
                     else {
                         entry.count++;
@@ -2110,8 +2236,11 @@ export class App {
             this.assertSecureHookConfig(config.hooks);
         // Child apps share the parent's router/routes/etc. Disable docs auto-mount
         // on the child so it does not re-register the parent's `/openapi.json` and
-        // `/docs` routes (which would throw "Duplicate route").
-        const child = new App({ ...this.options, docs: false });
+        // `/docs` routes (which would throw "Duplicate route"). Disable telemetry
+        // too: spreading `this.options` would otherwise construct a second pair of
+        // OTLP exporters, `unref`'d flush timers, and a duplicate `telemetry.otlp`
+        // boot line per group/plugin. The parent's wiring is copied below.
+        const child = new App({ ...this.options, docs: false, telemetry: false });
         child.router = this.router;
         child.routes = this.routes;
         child.webSocketRoutes = this.webSocketRoutes;
@@ -2119,7 +2248,10 @@ export class App {
         child.bootGuard = this.bootGuard;
         child.log = this.log;
         child.prefix = joinPath(this.prefix, prefix);
-        child.groupHooks = [...this.groupHooks, ...(config.hooks ? [config.hooks] : [])];
+        child.groupHooks = [
+            ...this.groupHooks,
+            ...(config.hooks ? [config.hooks] : []),
+        ];
         child.corsOriginAllows = corsOriginAllowsFromHooks(child.groupHooks);
         child.groupTags = [...this.groupTags, ...(config.tags ?? [])];
         child.groupAuth = config.auth ?? this.groupAuth;
@@ -2139,6 +2271,7 @@ export class App {
         child.shutdownListeners = this.shutdownListeners;
         child.pendingPlugins = this.pendingPlugins;
         child.pluginBootError = this.pluginBootError;
+        child.telemetry = this.telemetry;
         register(child);
         return this;
     }
@@ -2171,7 +2304,8 @@ export class App {
         // "set only if absent" semantics mean the second installation would be
         // a silent no-op).
         if (hooks[SECURE_HEADERS_MARKER] === true) {
-            const autoIdx = this.groupHooks.findIndex((h) => h[AUTO_SECURE_HEADERS_MARKER] === true);
+            const autoIdx = this.groupHooks.findIndex((h) => h[AUTO_SECURE_HEADERS_MARKER] ===
+                true);
             if (autoIdx >= 0)
                 this.groupHooks.splice(autoIdx, 1);
         }
@@ -2243,14 +2377,16 @@ export class App {
      * @throws Error if `key` is already decorated and `opts.override` is not `true`.
      */
     decorate(key, value, opts = {}) {
-        if (Object.prototype.hasOwnProperty.call(this.decorations, key) && opts.override !== true) {
+        if (Object.prototype.hasOwnProperty.call(this.decorations, key) &&
+            opts.override !== true) {
             // Namespace-protected decorators. Refuse to silently
             // shadow an existing decoration; emit a once-per-process warn naming
             // both decorators on the explicit-override path.
             throw new Error(`decorate(): key "${key}" is already decorated. ` +
                 `Pass { override: true } to replace, or rename to avoid the collision.`);
         }
-        if (opts.override === true && Object.prototype.hasOwnProperty.call(this.decorations, key)) {
+        if (opts.override === true &&
+            Object.prototype.hasOwnProperty.call(this.decorations, key)) {
             this.log.warn({ event: "decorate.override", key }, `decorate("${key}") replaced an existing decoration.`);
         }
         const hadKey = Object.prototype.hasOwnProperty.call(this.decorations, key);
@@ -2322,7 +2458,10 @@ export class App {
         const dedupKey = name ? (seed ? `${name}#${seed}` : name) : undefined;
         const dependencies = descriptor?.dependencies ?? [];
         const stateful = descriptor?.stateful ?? false;
-        if (stateful && !name && this.isProduction() && this.options.secureDefaults !== false) {
+        if (stateful &&
+            !name &&
+            this.isProduction() &&
+            this.options.secureDefaults !== false) {
             throw new Error("register(): anonymous stateful plugin refused in production. " +
                 "Declare { name } (and optional { seed }) so the plugin can be deduplicated.");
         }
@@ -2372,7 +2511,9 @@ export class App {
             throw err;
         });
         this.pendingPlugins.add(tracked);
-        void tracked.finally(() => this.pendingPlugins.delete(tracked)).catch(() => { });
+        void tracked
+            .finally(() => this.pendingPlugins.delete(tracked))
+            .catch(() => { });
     }
     firePluginInstalled(event) {
         if (this.pluginInstalledListeners.length === 0)
@@ -2391,7 +2532,9 @@ export class App {
                 this.log.error({ err, plugin: event.name }, "onPluginInstalled listener failed");
             }
         }
-        return promises.length > 0 ? Promise.all(promises).then(() => undefined) : undefined;
+        return promises.length > 0
+            ? Promise.all(promises).then(() => undefined)
+            : undefined;
     }
     /**
      * Wait until every async plugin registered with {@link App.register} has
@@ -2610,7 +2753,9 @@ export class App {
                 }
                 if (coldPreBody !== undefined) {
                     const guardResult = coldPreBody(ctx);
-                    const guarded = isPromiseLike(guardResult) ? await guardResult : guardResult;
+                    const guarded = isPromiseLike(guardResult)
+                        ? await guardResult
+                        : guardResult;
                     if (guarded instanceof Response) {
                         copyContextHeaders(ctx, guarded);
                         if (!guarded.headers.has("x-request-id")) {
@@ -2622,7 +2767,9 @@ export class App {
                 }
                 if (coldGuards !== undefined) {
                     const guardResult = coldGuards(ctx);
-                    const guarded = isPromiseLike(guardResult) ? await guardResult : guardResult;
+                    const guarded = isPromiseLike(guardResult)
+                        ? await guardResult
+                        : guardResult;
                     if (guarded instanceof Response) {
                         copyContextHeaders(ctx, guarded);
                         if (!guarded.headers.has("x-request-id")) {
@@ -2670,7 +2817,7 @@ export class App {
                 }
                 throw new NotFoundError(`No route for ${request.method} ${pathname}`);
             }
-            const { def, hooks, mergedHooks: allHooks, hasFinalizeHook } = match.handler;
+            const { def, hooks, mergedHooks: allHooks, hasFinalizeHook, } = match.handler;
             activeErrorHook = allHooks.onError;
             activeResponseHook = allHooks.onResponse;
             activeSendHook = allHooks.onSend;
@@ -2683,6 +2830,8 @@ export class App {
             // perimeter hooks can reject unauthenticated callers without consuming
             // an attacker-controlled request stream.
             ctx = createPreBodyContext(request, getUrl, match.params);
+            // Matched route template for low-cardinality labels (`http.route`).
+            ctx.routePath = def.path;
             // Stable two-field write keeps `ctx.state`'s hidden class consistent across
             // requests for the common no-decorator case. The decorations spread only
             // fires when `app.decorate()` was actually called.
@@ -2698,7 +2847,9 @@ export class App {
                 Object.assign(state, routeDecorations);
             if (allHooks.preBody !== undefined) {
                 const preBodyResult = allHooks.preBody(ctx);
-                const preBody = isPromiseLike(preBodyResult) ? await preBodyResult : preBodyResult;
+                const preBody = isPromiseLike(preBodyResult)
+                    ? await preBodyResult
+                    : preBodyResult;
                 const overriddenId = state.requestId;
                 if (typeof overriddenId === "string" && overriddenId.length > 0) {
                     requestId = overriddenId;
@@ -2722,7 +2873,9 @@ export class App {
             ctx = isPromiseLike(validatedCtx) ? await validatedCtx : validatedCtx;
             if (allHooks.beforeHandle !== undefined) {
                 const beforeResult = allHooks.beforeHandle(ctx);
-                const before = isPromiseLike(beforeResult) ? await beforeResult : beforeResult;
+                const before = isPromiseLike(beforeResult)
+                    ? await beforeResult
+                    : beforeResult;
                 // Honor any request id override applied by middleware (e.g. the
                 // `requestId()` Hooks bundle replaces the framework-generated value
                 // with a trusted incoming header or a user-supplied generator).
@@ -2748,7 +2901,9 @@ export class App {
             let result = isPromiseLike(runResult) ? await runResult : runResult;
             if (allHooks.afterHandle !== undefined) {
                 const afterResult = allHooks.afterHandle(ctx, result);
-                const afterReturn = isPromiseLike(afterResult) ? await afterResult : afterResult;
+                const afterReturn = isPromiseLike(afterResult)
+                    ? await afterResult
+                    : afterResult;
                 if (afterReturn !== undefined)
                     result = afterReturn;
             }
@@ -2842,7 +2997,9 @@ export class App {
             // `err instanceof HttpError` first: the framework's own thrown
             // problem errors short-circuit before any signal/option lookup.
             const isHttp = err instanceof HttpError;
-            const disconnectCode = isHttp ? 0 : (this.options.disconnectStatusCode ?? 499);
+            const disconnectCode = isHttp
+                ? 0
+                : (this.options.disconnectStatusCode ?? 499);
             if (disconnectCode > 0 && request.signal?.aborted === true) {
                 log.info({ event: "request.disconnected", status: disconnectCode }, "Client disconnected before response was sent");
                 const res = new Response(null, {
@@ -2900,7 +3057,9 @@ export class App {
      * @returns Fulfills with the `Response` produced by the matching handler.
      */
     request(input, init) {
-        const url = typeof input === "string" && input.startsWith("/") ? `http://test.local${input}` : input;
+        const url = typeof input === "string" && input.startsWith("/")
+            ? `http://test.local${input}`
+            : input;
         const req = url instanceof Request ? url : new Request(url, init);
         return this.fetch(req);
     }
@@ -3057,7 +3216,9 @@ function inferOperationId(method, path) {
     const suffix = path
         .slice(1)
         .split("/")
-        .map((segment) => segment.startsWith(":") ? `By${capitalizeWords(segment.slice(1))}` : capitalizeWords(segment))
+        .map((segment) => segment.startsWith(":")
+        ? `By${capitalizeWords(segment.slice(1))}`
+        : capitalizeWords(segment))
         .join("");
     return `${method.toLowerCase()}${suffix}`;
 }
@@ -3085,7 +3246,9 @@ function joinPath(a, b) {
 function healthRouteKey(request, trustProxyHeaders) {
     if (!trustProxyHeaders)
         return "global";
-    return request.headers.get("x-real-ip") ?? request.headers.get("fly-client-ip") ?? "global";
+    return (request.headers.get("x-real-ip") ??
+        request.headers.get("fly-client-ip") ??
+        "global");
 }
 /** True when the app declared a trusted reverse-proxy posture. */
 function appTrustsProxyHeaders(options) {
@@ -3209,7 +3372,9 @@ export function topoSortExtensions(exts) {
             const bHeaders = b.responseHeaders;
             if (!bHeaders || bHeaders.length === 0)
                 continue;
-            const overlap = bHeaders.map((h) => h.toLowerCase()).filter((h) => aSet.has(h));
+            const overlap = bHeaders
+                .map((h) => h.toLowerCase())
+                .filter((h) => aSet.has(h));
             if (overlap.length === 0)
                 continue;
             const declared = (a.before ?? []).includes(b.name) ||
@@ -3271,11 +3436,16 @@ function securityMarkersFromHooks(layers) {
         hasCsrf,
         hasAuth,
         cacheBeforeTenancy: cacheIndex !== -1 && tenancyIndex !== -1 && cacheIndex < tenancyIndex,
-        replayBeforeBudget: replayIndex !== -1 && budgetIndex !== -1 && replayIndex < budgetIndex ? replayName : null,
+        replayBeforeBudget: replayIndex !== -1 && budgetIndex !== -1 && replayIndex < budgetIndex
+            ? replayName
+            : null,
     };
 }
 function isStateChangingMethod(method) {
-    return method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
+    return (method === "POST" ||
+        method === "PUT" ||
+        method === "PATCH" ||
+        method === "DELETE");
 }
 /**
  * Extract the pathname from a fully-qualified request URL without
@@ -3385,7 +3555,9 @@ function getOriginFast(url) {
     return url.slice(0, end);
 }
 function mergeHooks(layers) {
-    const pick = (key) => layers.map((h) => h[key]).filter((f) => typeof f === "function");
+    const pick = (key) => layers
+        .map((h) => h[key])
+        .filter((f) => typeof f === "function");
     const requiredScopes = requiredScopesFromHooks(layers);
     const beforeHandle = mergeBeforeHandle(firstResponse(pick("beforeHandle")), requiredScopes);
     const hooks = {
@@ -3415,7 +3587,9 @@ function requiredScopesFromHooks(layers) {
 }
 function stampRequiredScopes(hooks, scopes) {
     if (scopes.length > 0) {
-        hooks[REQUIRE_SCOPES_HOOK_MARKER] = [...scopes];
+        hooks[REQUIRE_SCOPES_HOOK_MARKER] = [
+            ...scopes,
+        ];
     }
 }
 function mergeBeforeHandle(beforeHandle, requiredScopes) {
@@ -3487,7 +3661,9 @@ function scalarConfigurationWithPreferredAuth(configuration, schemes) {
     return {
         ...(configuration ?? {}),
         authentication: {
-            ...(authentication && typeof authentication === "object" && !Array.isArray(authentication)
+            ...(authentication &&
+                typeof authentication === "object" &&
+                !Array.isArray(authentication)
                 ? authentication
                 : {}),
             preferredSecurityScheme,
@@ -3502,21 +3678,21 @@ function finalizeResponse(res, ctx, hooks, stripFingerprint = true) {
             return sentResult.then((sent) => {
                 if (sent instanceof Response)
                     final = sent;
-                return finishFinalize(final, hooks, stripFingerprint);
+                return finishFinalize(final, ctx, hooks, stripFingerprint);
             });
         }
         if (sentResult instanceof Response)
             final = sentResult;
     }
-    return finishFinalize(final, hooks, stripFingerprint);
+    return finishFinalize(final, ctx, hooks, stripFingerprint);
 }
-function finishFinalize(res, hooks, stripFingerprint) {
+function finishFinalize(res, ctx, hooks, stripFingerprint) {
     if (stripFingerprint) {
         res.headers.delete("server");
         res.headers.delete("x-powered-by");
     }
     if (hooks.onResponse !== undefined) {
-        const onResponseResult = hooks.onResponse(res);
+        const onResponseResult = hooks.onResponse(res, ctx);
         if (isPromiseLike(onResponseResult)) {
             return onResponseResult.then(() => res);
         }
@@ -3524,7 +3700,9 @@ function finishFinalize(res, hooks, stripFingerprint) {
     return res;
 }
 function isPromiseLike(value) {
-    return value !== null && typeof value === "object" && typeof value.then === "function";
+    return (value !== null &&
+        typeof value === "object" &&
+        typeof value.then === "function");
 }
 /**
  * Allocation-free finalizer for the common case (no `onSend`/`onResponse`
@@ -3703,6 +3881,7 @@ class RequestContext {
     body = undefined;
     state;
     set;
+    routePath = undefined;
     _q = undefined;
     _qBuilder = undefined;
     _qSet = false;
@@ -3753,7 +3932,10 @@ function validateContext(ctx, def, opts) {
     const rawParams = ctx.params;
     const buildHeaders = () => ctx.headers;
     const buildQuery = () => ctx.query;
-    const hasSchema = def.request?.params || def.request?.query || def.request?.headers || def.request?.body;
+    const hasSchema = def.request?.params ||
+        def.request?.query ||
+        def.request?.headers ||
+        def.request?.body;
     const finishContext = () => ctx;
     if (!hasSchema) {
         return finishContext();
@@ -3797,7 +3979,8 @@ function validateContext(ctx, def, opts) {
         const declared = request.headers.get("content-length");
         if (declared !== null) {
             const declaredBytes = Number(declared);
-            if (Number.isFinite(declaredBytes) && declaredBytes > opts.bodyLimitBytes) {
+            if (Number.isFinite(declaredBytes) &&
+                declaredBytes > opts.bodyLimitBytes) {
                 throw new PayloadTooLargeError(opts.bodyLimitBytes);
             }
         }
@@ -3870,7 +4053,7 @@ function toIssues(issues) {
     return issues.map((i) => ({
         message: i.message,
         path: (i.path ?? [])
-            .map((p) => (typeof p === "object" && p && "key" in p ? p.key : p))
+            .map((p) => typeof p === "object" && p && "key" in p ? p.key : p)
             .join("."),
     }));
 }
@@ -4001,7 +4184,8 @@ async function readBodySlow(req, ct, limit, multipart) {
                 typeof v.arrayBuffer === "function";
             if (isFile) {
                 files++;
-                if (multipart?.maxFileBytes !== undefined && v.size > multipart.maxFileBytes) {
+                if (multipart?.maxFileBytes !== undefined &&
+                    v.size > multipart.maxFileBytes) {
                     throw new PayloadTooLargeError(multipart.maxFileBytes);
                 }
             }
@@ -4230,7 +4414,8 @@ function withTimeout(p, ms, request) {
 const OMIT_STACK_IN_LOG = Symbol.for("daloyjs.error.omitStackInLog");
 function serializeErr(err) {
     if (err instanceof Error) {
-        if (err[OMIT_STACK_IN_LOG] === true) {
+        if (err[OMIT_STACK_IN_LOG] ===
+            true) {
             return { name: err.name, message: err.message };
         }
         return { name: err.name, message: err.message, stack: err.stack };