@daloyjs/core 0.36.0 → 0.38.0

package/dist/app.js

@@ -2,7 +2,7 @@ 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 { validate } from "./schema.js";
-import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey } from "./security.js";
+import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey } from "./security.js";
 import { createLogger, noopLogger } from "./logger.js";
 import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
 import { docsContentSecurityPolicy, scalarHtml, swaggerUiHtml, } from "./docs.js";
@@ -10,6 +10,8 @@ import { secureHeaders as secureHeadersMiddleware, CORS_HOOK_MARKER, CORS_ORIGIN
 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 { securitySchemeRequiresPayloadAuth } from "./security-schemes.js";
 import { assertBehindProxy } from "./conn-info.js";
 const AUTO_SECURE_HEADERS_MARKER = Symbol.for("daloyjs.app.autoSecureHeaders");
@@ -147,6 +149,7 @@ function applySecurityPreset(options) {
 const DEFAULTS = {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 30_000,
+    maxHeaderCount: DEFAULT_MAX_HEADER_COUNT,
     validateResponses: true,
 };
 const TEXT_ENCODER = new TextEncoder();
@@ -179,58 +182,21 @@ export const DALOY_REQUEST_RAW_BODY = Symbol.for("daloyjs.request.rawBody");
  */
 export const DALOY_RAW_STREAM = Symbol.for("daloyjs.response.rawStream");
 /**
- * Contract-first HTTP application.
- *
- * `App` is the top-level entry point: register {@link RouteDefinition routes}
- * with {@link App.route}, layer cross-cutting behavior with
- * {@link App.use}/{@link App.register}, then expose the application to a
- * runtime via {@link App.fetch} (Web standard) or one of the adapter subpaths
- * such as `@daloyjs/core/node`, `@daloyjs/core/cloudflare`, or
- * `@daloyjs/core/lambda`.
- *
- * The same `App` instance powers:
- *
- *  - request routing (`Router` under the hood)
- *  - request/response validation against Standard-Schema validators
- *  - OpenAPI 3.1 generation (`generateOpenAPI(app)`)
- *  - typed in-process client (`createClient(app)`) and generated SDK
- *  - graceful shutdown and lifecycle observability
- *
- * `App` is **runtime-agnostic**: the same instance runs on Node, Bun, Deno,
- * Cloudflare Workers, Vercel Edge, AWS Lambda, and Fastly Compute via the
- * dedicated adapters.
- *
- * @example
- * ```ts
- * import { App, secureHeaders } from "@daloyjs/core";
- * import { z } from "zod";
- *
- * const app = new App({ title: "Books API", version: "1.0.0" });
- *
- * app.use(secureHeaders());
- *
- * app.route({
- *   method: "GET",
- *   path: "/books/:id",
- *   operationId: "getBook",
- *   request: { params: z.object({ id: z.uuid() }) },
- *   responses: {
- *     200: { description: "OK", body: z.object({ id: z.string(), title: z.string() }) },
- *   },
- *   handler: ({ params }) => ({ status: 200, body: { id: params.id, title: "Dune" } }),
- * });
- *
- * // Node:
- * import { serve } from "@daloyjs/core/node";
- * serve(app, { port: 3000 });
- * ```
- *
  * @since 0.1.0
  */
 export class App {
     options;
     log;
-    /** Public registry: enables OpenAPI gen, typed-client gen, dead-route detection. */
+    /**
+     * Public registry: enables OpenAPI gen, typed-client gen, dead-route detection.
+     *
+     * Statically the property is typed as the `Routes` tuple so that
+     * {@link App.route} can accumulate each registered route's literal
+     * `operationId`, request, and response types. The typed client
+     * (`createClient(app)`) reads this tuple to derive a precisely-typed method
+     * per route. At runtime it is an ordinary growable array — the tuple typing
+     * is a compile-time view only.
+     */
     routes = [];
     router = new Router();
     /**
@@ -261,6 +227,12 @@ export class App {
     installedPlugins = new Set();
     closeHooks = [];
     closeHooksRun = false;
+    /**
+     * Lazily-created in-process scheduler backing {@link App.cron}. Started on
+     * the first `cron()` call and stopped from an `onClose` hook so its lifecycle
+     * is tied to graceful shutdown.
+     */
+    scheduler;
     /** Idle-connection close hooks (adapter-registered, sync). */
     idleConnectionCloseHooks = [];
     pluginInstalledListeners = [];
@@ -320,6 +292,7 @@ export class App {
             validateResponses: resolved.validateResponses ?? DEFAULTS.validateResponses,
             bodyLimitBytes: resolved.bodyLimitBytes ?? DEFAULTS.bodyLimitBytes,
             requestTimeoutMs: resolved.requestTimeoutMs ?? DEFAULTS.requestTimeoutMs,
+            maxHeaderCount: resolved.maxHeaderCount ?? DEFAULTS.maxHeaderCount,
             ...resolved,
         };
         this.log =
@@ -448,6 +421,7 @@ export class App {
             trustProxy: o.trustProxy === undefined ? "unconfigured" : o.trustProxy,
             bodyLimitBytes: this.options.bodyLimitBytes,
             requestTimeoutMs: this.options.requestTimeoutMs,
+            maxHeaderCount: this.options.maxHeaderCount ?? DEFAULT_MAX_HEADER_COUNT,
             stripServerHeaders: o.stripServerHeaders !== false,
             production: this.isProduction(),
         });
@@ -861,11 +835,16 @@ export class App {
             handler: async () => {
                 const title = opts.title ?? (await resolveInfo()).title;
                 const html = ui === "swagger"
-                    ? swaggerUiHtml({ specUrl: openapiPath, title })
+                    ? swaggerUiHtml({
+                        specUrl: openapiPath,
+                        title,
+                        assets: opts.assets,
+                    })
                     : scalarHtml({
                         specUrl: openapiPath,
                         title,
                         configuration: opts.scalar,
+                        assets: opts.assets,
                     });
                 return {
                     status: 200,
@@ -902,8 +881,16 @@ export class App {
      * });
      * ```
      *
+     * The return type widens `Routes` with the freshly-registered route so
+     * that chained registration (`new App().route(a).route(b)`) accumulates a
+     * precise tuple. The typed client (`createClient(app)`) consumes that tuple
+     * to expose a method per `operationId` with parameters and responses
+     * inferred from the route's own schemas. Non-chained calls
+     * (`app.route(a); app.route(b);`) keep the variable's original type, so
+     * chain the calls when you want the inferred client surface.
+     *
      * @param def - The route definition.
-     * @returns This `App` instance for chaining.
+     * @returns This `App` instance (widened with the new route) for chaining.
      */
     route(def) {
         // Refuse non-canonical HTTP methods at runtime.
@@ -930,6 +917,13 @@ export class App {
             auth: def.auth ?? this.groupAuth,
         };
         this.assertRouteAuthPayloadConfig(merged);
+        // Normalize an optional RFC 8594 sunset date to a stable IMF-fixdate
+        // (HTTP date) string once, at registration time, so the hot response
+        // path can emit the `Sunset` header without re-parsing per request and
+        // a bad value fails fast rather than silently emitting garbage.
+        if (merged.sunset !== undefined) {
+            merged.sunset = normalizeSunset(merged.sunset, merged.method, fullPath);
+        }
         const sources = [...this.groupHooks, def.hooks ?? {}];
         const hooks = mergeHooks(sources);
         const corsOriginAllows = corsOriginAllowsFromHooks(sources);
@@ -945,6 +939,9 @@ export class App {
             ...sources,
         ]);
         this.router.add(def.method, fullPath, { def: merged, hooks, mergedHooks, hasFinalizeHook, corsOriginAllows, fullCorsOriginAllows }, def.operationId);
+        // `routes` is statically a readonly tuple so the typed client can infer
+        // per-route methods; at runtime it is a growable array, so we push through
+        // a mutable view.
         this.routes.push(merged);
         this.routeSecurityMarkers.push({
             method: merged.method,
@@ -1082,6 +1079,166 @@ export class App {
         });
         return this;
     }
+    /**
+     * Register an opt-in, auth-guarded Prometheus / OpenMetrics scrape route
+     * and install RED (Rate / Errors / Duration) instrumentation for every
+     * route registered **after** this call. The third observability pillar
+     * alongside the structured logger and the OpenTelemetry tracer.
+     *
+     * Exposes, in the Prometheus text exposition format:
+     * - `<prefix>http_requests_total{method,route,status}` — request counter,
+     * - `<prefix>http_request_duration_seconds{method,route}` — latency histogram,
+     * - `<prefix>http_requests_in_flight` — concurrency gauge,
+     * - process gauges (resident memory, heap used, uptime) on Node-like runtimes.
+     *
+     * The scrape route inherits the same hardened posture as
+     * {@link App.healthcheck}: optional bearer token compared via
+     * {@link timingSafeEqual}, a per-IP fixed-window rate limit, and a
+     * refuse-to-boot guard in production (an unauthenticated `/metrics`
+     * endpoint leaks internal route names, latency, and traffic volume) unless
+     * a token is supplied or `acknowledgeUnauthenticated: true` is passed.
+     *
+     * 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.
+     *
+     * @param opts - Path, auth, rate-limit, registry, and label configuration.
+     * @returns `this` for chaining.
+     * @since 0.37.0
+     */
+    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 token = opts.token;
+        // Refuse-to-boot: an unauthenticated metrics scrape in production is a
+        // documented info-disclosure surface (route inventory, latency
+        // distributions, request volume, process memory). Force an explicit
+        // acknowledgement, mirroring app.healthcheck().
+        if (this.options.secureDefaults !== false &&
+            this.isProduction() &&
+            token === undefined &&
+            opts.acknowledgeUnauthenticated !== true) {
+            throw new Error(`app.metrics() refused in production: provide opts.token to require ` +
+                `Authorization: Bearer <token>, or pass acknowledgeUnauthenticated: true ` +
+                `to acknowledge that this scrape endpoint is reachable without credentials.`);
+        }
+        // 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.
+        const exclude = (p) => p === path || (opts.exclude ? opts.exclude(p) : false);
+        this.groupHooks.push(httpMetrics({
+            registry,
+            route: opts.route,
+            maxRouteCardinality: opts.maxRouteCardinality,
+            buckets: opts.buckets,
+            exclude,
+        }));
+        const buckets = rateLimitConfig
+            ? new Map()
+            : null;
+        this.route({
+            method: "GET",
+            path,
+            operationId: "metrics",
+            tags: ["Observability"],
+            summary: "Prometheus metrics scrape endpoint",
+            handler: async ({ request }) => {
+                if (buckets && rateLimitConfig) {
+                    const key = healthRouteKey(request);
+                    const now = Date.now();
+                    const entry = buckets.get(key);
+                    if (!entry || entry.resetMs <= now) {
+                        buckets.set(key, { count: 1, resetMs: now + rateLimitConfig.windowMs });
+                    }
+                    else {
+                        entry.count++;
+                        if (entry.count > rateLimitConfig.limit) {
+                            throw new TooManyRequestsError(Math.ceil((entry.resetMs - now) / 1000));
+                        }
+                    }
+                }
+                if (token !== undefined) {
+                    const h = request.headers.get("authorization") ?? "";
+                    const m = /^Bearer\s+(.+)$/i.exec(h);
+                    if (!m) {
+                        throw new HttpError(401, {
+                            type: "https://daloyjs.dev/errors/unauthorized",
+                            title: "Unauthorized",
+                            detail: "Metrics scrape requires a bearer token.",
+                        }, { "www-authenticate": 'Bearer realm="metrics"' });
+                    }
+                    if (!timingSafeEqual(m[1], token)) {
+                        throw new ForbiddenError("Invalid metrics scrape token.");
+                    }
+                }
+                return {
+                    status: 200,
+                    body: registry.render(),
+                    headers: {
+                        "content-type": PROMETHEUS_CONTENT_TYPE,
+                        "cache-control": "no-store",
+                    },
+                };
+            },
+            responses: {
+                200: { description: "Prometheus metrics exposition." },
+                429: { description: "Too many scrape requests." },
+            },
+        });
+        return this;
+    }
+    /**
+     * Register an in-process scheduled task (cron). The first call lazily creates
+     * an app-managed {@link Scheduler}, wires it to the app logger, starts it,
+     * and registers an `onClose` hook so it is drained on graceful shutdown
+     * (in-flight runs are awaited, then aborted if they outlast the shutdown
+     * grace period).
+     *
+     * The schedule is **queue-agnostic** — it runs work in *this* process on a
+     * fixed interval or cron expression. Use it for periodic maintenance
+     * (cache sweeps, token refresh, reconciliation) rather than as a distributed
+     * job queue. Each task is **single-flight**: if a tick fires while the
+     * previous run is still in progress, the tick is skipped and counted, so a
+     * slow task can never pile up overlapping runs.
+     *
+     * @example
+     * ```ts
+     * app.cron({ name: "sweep", cron: "0 * * * *" }, async ({ signal }) => {
+     *   await purgeExpiredSessions({ signal });
+     * });
+     * ```
+     *
+     * @param def - The task definition. Exactly one of `intervalMs` or `cron`.
+     * @param handler - The function to run on each tick.
+     * @returns This `App` instance for chaining.
+     * @throws {RangeError} on invalid options (see {@link Scheduler.define}).
+     * @throws {@link CronParseError} if a `cron` expression is malformed.
+     */
+    cron(def, handler) {
+        if (this.scheduler === undefined) {
+            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
+            // work stops cleanly alongside database pools and other resources.
+            this.onClose(() => scheduler.stop());
+        }
+        this.scheduler.define(def, handler);
+        return this;
+    }
+    /**
+     * The app-managed {@link Scheduler} backing {@link App.cron}, or `undefined`
+     * if no scheduled task has been registered. Exposed for inspection
+     * (`getState()` / `list()`) and manual triggering (`runNow()`); the lifecycle
+     * is owned by the app.
+     */
+    get scheduledTasks() {
+        return this.scheduler;
+    }
     registerHealthRoute(kind, opts, handler) {
         const isHealth = kind === "healthcheck";
         const defaultPath = (isHealth ? "/healthz" : "/readyz");
@@ -1654,6 +1811,7 @@ export class App {
         try {
             assertNoDuplicateSingletonHeaders(request.headers);
             assertNoReservedInternalHeaders(request.headers);
+            assertHeaderCountWithinLimit(request.headers, this.options.maxHeaderCount ?? DEFAULT_MAX_HEADER_COUNT);
             this.assertTrustProxyConfigured(request);
             this.assertBootGuards();
             if (globalHooks.onRequest !== undefined) {
@@ -2666,6 +2824,23 @@ async function readBody(req, ct, limit, multipart) {
     const bytes = await readBodyLimited(req, limit);
     return new TextDecoder().decode(bytes);
 }
+/**
+ * Validate and normalize a route's RFC 8594 `sunset` value to an IMF-fixdate
+ * (HTTP date) string. Accepts an ISO-8601/parseable string or a `Date`.
+ * Throws at registration time when the value cannot be parsed into a valid
+ * date so a typo never silently ships a malformed `Sunset` header.
+ *
+ * @internal
+ */
+function normalizeSunset(value, method, path) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new Error(`app.route(): invalid sunset date for ${method} ${path}: ` +
+            `${JSON.stringify(value)}. Provide an ISO-8601 string, an HTTP date, ` +
+            `or a Date instance.`);
+    }
+    return date.toUTCString();
+}
 function serializeResult(result, def, validateResponses) {
     const spec = def.responses[result.status];
     if (!spec) {
@@ -2677,6 +2852,16 @@ function serializeResult(result, def, validateResponses) {
         const treatAsJson = !explicitCt || explicitCt.includes("application/json");
         if (!explicitCt)
             headers.set("content-type", "application/json");
+        // RFC 8594 deprecation lifecycle headers. A route with an explicit
+        // `sunset` date is implicitly deprecated. Never overwrite a value the
+        // handler set deliberately.
+        if (def.deprecated === true || def.sunset !== undefined) {
+            if (!headers.has("deprecation"))
+                headers.set("deprecation", "true");
+            if (def.sunset !== undefined && !headers.has("sunset")) {
+                headers.set("sunset", def.sunset);
+            }
+        }
         let body;
         let rawBody = null;
         let isStream = false;

package/dist/asyncapi.d.ts

@@ -0,0 +1,98 @@
+/**
+ * AsyncAPI 3.0 document generator for WebSocket surfaces.
+ *
+ * Built-in, dependency-free, and a deliberate mirror of the OpenAPI 3.1
+ * generator in `./openapi.ts`: it turns every `app.ws()` route into an
+ * AsyncAPI **channel** (the socket address + path parameters) and one or more
+ * **operations** (`receive` for client→server messages, `send` for
+ * server→client messages). The RFC 6455 stack and its CSWSH defenses finally
+ * get a contract/doc artifact, extending the contract-first story past HTTP.
+ *
+ * If a message schema exposes a `toJSONSchema()` method (Zod 4, Valibot, ...)
+ * we use it; otherwise we emit a permissive `{}` placeholder rather than fail
+ * — docs and tooling still work, just with looser types for that payload.
+ */
+import type { App } from "./app.js";
+/** AsyncAPI [Info Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#infoObject) header fields. */
+export interface AsyncAPIInfo {
+    /** Human-readable API title shown by AsyncAPI Studio / docs. */
+    title: string;
+    /** Semantic API version (independent of your package version). */
+    version: string;
+    /** Optional CommonMark long description rendered at the top of the docs. */
+    description?: string;
+}
+/**
+ * AsyncAPI [Server Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject).
+ * Unlike OpenAPI's `servers` array, AsyncAPI keys servers by name.
+ */
+export interface AsyncAPIServer {
+    /** Host (and optional port) the socket is reachable at, e.g. `api.example.com`. */
+    host: string;
+    /** Transport protocol, typically `ws` or `wss`. */
+    protocol: string;
+    /** Optional protocol version. */
+    protocolVersion?: string;
+    /** Optional base path prefixing channel addresses, e.g. `/realtime`. */
+    pathname?: string;
+    /** Optional human-readable server description. */
+    description?: string;
+}
+/** Options for {@link generateAsyncAPI}. */
+export interface AsyncAPIOptions {
+    /** Required `info` block (title + version). */
+    info: AsyncAPIInfo;
+    /**
+     * Optional named servers exposed in the document. AsyncAPI keys servers by
+     * name (`{ production: { host, protocol } }`), not by an array.
+     */
+    servers?: Record<string, AsyncAPIServer>;
+}
+/**
+ * Generate an AsyncAPI 3.0 document from a registered {@link App}'s WebSocket
+ * routes.
+ *
+ * Every `app.ws()` route becomes one channel (its address + path parameters)
+ * and one or more operations:
+ *
+ * - a `receive` operation for client→server messages — payload taken from the
+ *   route's `meta.receive` schema, falling back to the handler's
+ *   `request.body` schema (the same schema used for payload-size checks).
+ * - a `send` operation for server→client messages — emitted only when the
+ *   route declares a `meta.send` schema.
+ *
+ * The output is a plain JSON-serializable object: hand it to AsyncAPI Studio,
+ * write it to disk for codegen, or serve it from a route. When the app has no
+ * WebSocket routes the document still validates, with empty `channels` and
+ * `operations` maps.
+ *
+ * @example
+ * ```ts
+ * import { generateAsyncAPI } from "@daloyjs/core/asyncapi";
+ * import { writeFileSync } from "node:fs";
+ *
+ * const doc = generateAsyncAPI(app, {
+ *   info: { title: "Realtime API", version: "1.0.0" },
+ *   servers: { production: { host: "api.example.com", protocol: "wss" } },
+ * });
+ * writeFileSync("./generated/asyncapi.json", JSON.stringify(doc, null, 2));
+ * ```
+ *
+ * @param app - The application whose WebSocket routes are documented.
+ * @param options - Document metadata and optional named servers.
+ * @returns A JSON-serializable AsyncAPI 3.0 document.
+ * @since 0.37.0
+ */
+export declare function generateAsyncAPI(app: App, options: AsyncAPIOptions): Record<string, unknown>;
+/**
+ * Serialize an AsyncAPI document to YAML.
+ *
+ * Thin alias over the dependency-free YAML 1.2 emitter shared with the
+ * OpenAPI generator ({@link openapiToYAML}) — AsyncAPI and OpenAPI documents
+ * are both plain JSON-compatible objects, so the same emitter applies.
+ *
+ * @param doc - The AsyncAPI document produced by {@link generateAsyncAPI}.
+ * @returns The document rendered as a YAML string.
+ * @since 0.37.0
+ */
+export declare function asyncapiToYAML(doc: Record<string, unknown>): string;