@daloyjs/core 1.2.0 → 1.3.0

package/dist/app.js

@@ -2,8 +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 { createAppTelemetry } from "./otlp.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";
@@ -13,7 +13,8 @@ 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 { createJobQueue, createJobWorker, JobConfigError, MemoryJobStore, } from "./jobs.js";
 import { securitySchemeRequiresPayloadAuth } from "./security-schemes.js";
 import { assertBehindProxy } from "./conn-info.js";
 const AUTO_SECURE_HEADERS_MARKER = Symbol.for("daloyjs.app.autoSecureHeaders");
@@ -428,6 +429,13 @@ export class App {
      * is tied to graceful shutdown.
      */
     scheduler;
+    /**
+     * Job queue / worker attached by {@link App.useJobs}. Both stay `undefined`
+     * unless the app opts in — serverless isolates must never start a poll
+     * loop implicitly.
+     */
+    jobQueue;
+    jobWorkerRef;
     /** Idle-connection close hooks (adapter-registered, sync). */
     idleConnectionCloseHooks = [];
     pluginInstalledListeners = [];
@@ -485,7 +493,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;
     }
@@ -498,7 +508,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;
     }
@@ -524,11 +537,14 @@ export class App {
         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",
-                        ...(telemetryWrite !== undefined ? { write: telemetryWrite } : {}),
+                        ...(telemetryWrite !== undefined
+                            ? { write: telemetryWrite }
+                            : {}),
                     });
         this.warnOnEnvMismatch();
         this.assertDisconnectStatusCode();
@@ -659,7 +675,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,
@@ -685,7 +703,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);
@@ -694,7 +713,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));
         }
     }
@@ -801,7 +822,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");
@@ -816,7 +840,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;
@@ -835,7 +861,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)))
@@ -940,7 +968,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"
@@ -1100,7 +1129,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 ` +
@@ -1194,7 +1224,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;
     }
     /**
@@ -1247,11 +1278,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",
@@ -1279,7 +1314,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,
@@ -1308,7 +1345,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",
@@ -1393,7 +1432,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 = () => {
@@ -1416,7 +1457,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() }),
         });
@@ -1429,7 +1472,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,
@@ -1574,7 +1619,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
@@ -1641,7 +1689,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;
@@ -1767,7 +1817,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" },
@@ -1802,8 +1854,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.
@@ -1812,7 +1869,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
@@ -1826,6 +1885,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.
@@ -1838,7 +1918,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",
@@ -1854,7 +1936,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++;
@@ -1922,7 +2007,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
@@ -1941,11 +2028,169 @@ export class App {
     get scheduledTasks() {
         return this.scheduler;
     }
+    /**
+     * Attach a queue-agnostic background-job queue (and optionally a worker)
+     * to this app. Opt-in by design: nothing in `new App()` starts a poll
+     * loop, so serverless isolates that only ever *enqueue* never pay for (or
+     * accidentally run) a worker.
+     *
+     * The queue answers *&ldquo;run this work somewhere, eventually&rdquo;* —
+     * durable, retried, at-least-once units of `{ name, payload }` that
+     * outlive the HTTP request and, with a durable {@link JobStore} adapter,
+     * the process itself. This is not a workflow engine: there is no replay,
+     * no durable function, no `await sleep("7 days")`.
+     *
+     * - `startWorker: true` creates a {@link JobWorker} over the same store,
+     *   starts it, and registers an `onClose` hook so in-flight jobs are
+     *   drained (then aborted past the grace period) on graceful shutdown.
+     *   Use it on long-lived Node/Bun/Deno processes only — never on Lambda /
+     *   Cloudflare Workers isolates.
+     * - {@link MemoryJobStore} under production config logs a high-severity
+     *   warning (it is process-local and loses every job on restart); pass
+     *   `strictProduction: true` to refuse to boot instead.
+     *
+     * @example
+     * ```ts
+     * app.useJobs({
+     *   store: new MemoryJobStore(), // production: your Redis/Postgres JobStore
+     *   handlers: {
+     *     "email.welcome": async ({ job, signal }) => {
+     *       await sendEmail(job.payload, { signal });
+     *     },
+     *   },
+     *   startWorker: true,
+     * });
+     *
+     * app.post("/users", contract, async (ctx) => {
+     *   const user = await db.insertUser(ctx.body);
+     *   await app.jobs!.enqueue({
+     *     name: "email.welcome",
+     *     payload: { userId: user.id },
+     *     idempotencyKey: jobIdempotencyKey({ tenant: ctx.state.tenant, name: "email.welcome", key: user.id }),
+     *   });
+     *   return { status: 201 as const, body: user };
+     * });
+     * ```
+     *
+     * @param opts - Store, optional handlers, worker and queue tuning.
+     * @returns This `App` instance for chaining.
+     * @throws {@link JobConfigError} when jobs are already configured, when
+     *   `startWorker` lacks handlers, or when `strictProduction` rejects a
+     *   {@link MemoryJobStore} under production config.
+     * @since 1.3.0
+     */
+    useJobs(opts) {
+        if (this.jobQueue !== undefined) {
+            throw new JobConfigError("invalid_option", "app.useJobs() was called twice; jobs are already configured on this app.");
+        }
+        if (opts.store instanceof MemoryJobStore && this.isProduction()) {
+            const message = "app.useJobs(): MemoryJobStore is not durable — jobs are lost on process restart " +
+                "and invisible to other replicas. Supply a shared JobStore (Redis/Postgres/SQS adapter) " +
+                "in production, or pass strictProduction: false to keep this warning-only posture.";
+            if (opts.strictProduction === true) {
+                throw new JobConfigError("invalid_option", message);
+            }
+            this.log.warn({ event: "jobs.memory_store_production", component: "jobs" }, message);
+        }
+        const logger = this.log.child({ component: "jobs" });
+        const queue = createJobQueue({ store: opts.store, logger, ...opts.queue });
+        let worker;
+        if (opts.startWorker === true) {
+            const handlers = opts.handlers;
+            if (handlers === undefined || Object.keys(handlers).length === 0) {
+                throw new JobConfigError("invalid_option", "app.useJobs(): startWorker: true requires a non-empty handlers map.");
+            }
+            worker = createJobWorker({
+                ...opts.worker,
+                queue,
+                handlers,
+                logger: opts.worker?.logger ?? logger,
+            });
+            worker.start();
+            // Drain the worker during the post-drain close phase so an in-flight
+            // job settles (or fails back to the queue) alongside other resources.
+            const startedWorker = worker;
+            this.onClose(() => startedWorker.stop());
+        }
+        this.jobQueue = queue;
+        this.jobWorkerRef = worker;
+        return this;
+    }
+    /**
+     * The {@link JobQueue} attached by {@link App.useJobs}, or `undefined`
+     * when jobs are not configured. Route handlers enqueue through this;
+     * delivery is at-least-once, so handlers must be idempotent.
+     *
+     * @since 1.3.0
+     */
+    get jobs() {
+        return this.jobQueue;
+    }
+    /**
+     * The {@link JobWorker} created by {@link App.useJobs} with
+     * `startWorker: true`, or `undefined`. Exposed for inspection
+     * (`getState()`) and tests (`runOnce()`); the lifecycle is owned by the app.
+     *
+     * @since 1.3.0
+     */
+    get jobWorker() {
+        return this.jobWorkerRef;
+    }
+    /**
+     * Register a cron task whose tick enqueues a job instead of running the
+     * side effect in-process. This is the production posture for scheduled
+     * work with global side effects (nightly reconciliation, invoice runs):
+     * every replica may tick, but the deterministic idempotency key
+     * `cron:{taskName}:{floor(scheduledFor / tickGranularity)}` collapses the
+     * duplicate enqueues into one job, and exactly one worker claims it.
+     *
+     * `tickGranularity` is the task's `intervalMs` for interval schedules and
+     * one minute for cron expressions (the finest cadence a cron expression
+     * can fire), so two replicas ticking the same slot always derive the same
+     * key. Use plain {@link App.cron} for process-local maintenance (cache
+     * sweeps that must happen in *this* process); use `cronEnqueue` for work
+     * that must happen once, cluster-wide, and survive a restart.
+     *
+     * @example
+     * ```ts
+     * app.cronEnqueue(
+     *   { name: "nightly-reconcile", cron: "0 2 * * *" },
+     *   { name: "ops.reconcile", payload: {} },
+     * );
+     * ```
+     *
+     * @param def - The task definition (schedule), same shape as {@link App.cron}.
+     * @param job - The job to enqueue on each tick. `payload` defaults to
+     *   `{ scheduledFor: <ISO time of the tick> }`.
+     * @returns This `App` instance for chaining.
+     * @throws {@link JobConfigError} (`store_required`) when called before
+     *   {@link App.useJobs} — fail fast at registration, not at the first tick.
+     * @since 1.3.0
+     */
+    cronEnqueue(def, job) {
+        const queue = this.jobQueue;
+        if (queue === undefined) {
+            throw new JobConfigError("store_required", "app.cronEnqueue() requires app.useJobs() first: attach a JobStore before scheduling job-producing ticks.");
+        }
+        const granularityMs = def.intervalMs !== undefined && def.intervalMs > 0 ? def.intervalMs : 60_000;
+        return this.cron(def, async ({ name, scheduledFor }) => {
+            const slot = Math.floor(scheduledFor.getTime() / granularityMs);
+            await queue.enqueue({
+                name: job.name,
+                payload: job.payload ?? { scheduledFor: scheduledFor.toISOString() },
+                ...(job.queue !== undefined ? { queue: job.queue } : {}),
+                ...(job.priority !== undefined ? { priority: job.priority } : {}),
+                idempotencyKey: `cron:${encodeURIComponent(name)}:${slot}`,
+            });
+        });
+    }
     registerHealthRoute(kind, opts, handler) {
         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,
@@ -1959,7 +2204,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",
@@ -1975,7 +2222,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++;
@@ -2033,8 +2283,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
@@ -2053,7 +2307,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++;
@@ -2143,8 +2400,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;
@@ -2152,7 +2412,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;
@@ -2172,6 +2435,7 @@ export class App {
         child.shutdownListeners = this.shutdownListeners;
         child.pendingPlugins = this.pendingPlugins;
         child.pluginBootError = this.pluginBootError;
+        child.telemetry = this.telemetry;
         register(child);
         return this;
     }
@@ -2204,7 +2468,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);
         }
@@ -2276,14 +2541,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);
@@ -2355,7 +2622,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.");
         }
@@ -2405,7 +2675,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)
@@ -2424,7 +2696,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
@@ -2643,7 +2917,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")) {
@@ -2655,7 +2931,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")) {
@@ -2703,7 +2981,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;
@@ -2733,7 +3011,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;
@@ -2757,7 +3037,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).
@@ -2783,7 +3065,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;
             }
@@ -2877,7 +3161,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, {
@@ -2935,7 +3221,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);
     }
@@ -3092,7 +3380,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}`;
 }
@@ -3120,7 +3410,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) {
@@ -3244,7 +3536,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) ||
@@ -3306,11 +3600,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
@@ -3420,7 +3719,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 = {
@@ -3450,7 +3751,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) {
@@ -3522,7 +3825,9 @@ function scalarConfigurationWithPreferredAuth(configuration, schemes) {
     return {
         ...(configuration ?? {}),
         authentication: {
-            ...(authentication && typeof authentication === "object" && !Array.isArray(authentication)
+            ...(authentication &&
+                typeof authentication === "object" &&
+                !Array.isArray(authentication)
                 ? authentication
                 : {}),
             preferredSecurityScheme,
@@ -3559,7 +3864,9 @@ function finishFinalize(res, ctx, 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`
@@ -3789,7 +4096,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();
@@ -3833,7 +4143,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);
             }
         }
@@ -3906,7 +4217,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("."),
     }));
 }
@@ -4037,7 +4348,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);
                 }
             }
@@ -4266,7 +4578,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 };