@daloyjs/core 0.36.0 → 0.37.0

package/dist/app.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");
@@ -261,6 +263,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 = [];
@@ -861,11 +869,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,
@@ -930,6 +943,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);
@@ -1082,6 +1102,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");
@@ -2666,6 +2846,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 +2874,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;

package/dist/asyncapi.js

@@ -0,0 +1,212 @@
+/**
+ * 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 { openapiToYAML } from "./openapi.js";
+/**
+ * Convert a Standard Schema to JSON Schema for an AsyncAPI message payload.
+ *
+ * Mirrors the OpenAPI generator's permissive strategy: use `toJSONSchema()`
+ * when the schema exposes it (Zod 4, Valibot, ...), and otherwise fall back to
+ * a permissive `{}` so generation never throws on an unconvertible schema.
+ *
+ * @param schema - The Standard Schema to convert, or `undefined`.
+ * @returns A JSON-Schema-shaped object, or `undefined` when no schema given.
+ */
+function toPayloadSchema(schema) {
+    if (!schema)
+        return undefined;
+    const anySchema = schema;
+    if (typeof anySchema.toJSONSchema === "function") {
+        try {
+            return anySchema.toJSONSchema();
+        }
+        catch {
+            /* fall through to permissive placeholder */
+        }
+    }
+    return {};
+}
+/**
+ * Derive a stable, unique channel/operation key from a WebSocket path.
+ *
+ * Strips the leading slash, drops `:param` / `{param}` markers, and camelCases
+ * the remaining segments (`/chat/:room/feed` → `chatRoomFeed`). Falls back to
+ * `root` for `/`. Collisions are de-duplicated by the caller.
+ *
+ * @param path - The registered WebSocket route path.
+ * @returns A safe identifier base for AsyncAPI keys.
+ */
+function pathToKey(path) {
+    const segments = path
+        .split("/")
+        .map((s) => s.replace(/[:{}]/g, ""))
+        .filter((s) => s.length > 0);
+    if (segments.length === 0)
+        return "root";
+    return segments
+        .map((seg, i) => {
+        const clean = seg.replace(/[^A-Za-z0-9]+/g, " ").trim();
+        const parts = clean.split(/\s+/).filter(Boolean);
+        return parts
+            .map((part, j) => i === 0 && j === 0
+            ? part.charAt(0).toLowerCase() + part.slice(1)
+            : part.charAt(0).toUpperCase() + part.slice(1))
+            .join("");
+    })
+        .join("");
+}
+/**
+ * Extract `:param` names from a WebSocket route path in declaration order.
+ *
+ * @param path - The registered WebSocket route path.
+ * @returns The list of path-parameter names (without the leading colon).
+ */
+function extractParams(path) {
+    const names = [];
+    for (const match of path.matchAll(/:([A-Za-z0-9_]+)/g)) {
+        names.push(match[1]);
+    }
+    return names;
+}
+/**
+ * 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 function generateAsyncAPI(app, options) {
+    const channels = {};
+    const operations = {};
+    const messages = {};
+    const usedKeys = new Set();
+    const entries = app.webSocketRoutes.list();
+    for (const entry of entries) {
+        const path = entry.path;
+        const meta = entry.handler.meta;
+        // Derive a unique channel key (operationId override > path-derived slug).
+        let key = meta?.operationId ?? pathToKey(path);
+        if (usedKeys.has(key)) {
+            let suffix = 2;
+            while (usedKeys.has(`${key}${suffix}`))
+                suffix += 1;
+            key = `${key}${suffix}`;
+        }
+        usedKeys.add(key);
+        const address = path.replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+        const paramNames = extractParams(path);
+        const channelMessages = {};
+        // Inbound: a WebSocket route can always receive client messages, so a
+        // `receive` operation is always emitted (permissive payload when no schema).
+        const receiveSchema = meta?.receive ?? entry.handler.request?.body;
+        const receiveMsgKey = `${key}Receive`;
+        messages[receiveMsgKey] = {
+            name: receiveMsgKey,
+            title: `${key} inbound message`,
+            payload: toPayloadSchema(receiveSchema) ?? {},
+        };
+        channelMessages.receiveMessage = {
+            $ref: `#/components/messages/${receiveMsgKey}`,
+        };
+        operations[receiveMsgKey] = {
+            action: "receive",
+            channel: { $ref: `#/channels/${key}` },
+            ...(meta?.summary ? { summary: meta.summary } : {}),
+            ...(meta?.description ? { description: meta.description } : {}),
+            ...(meta?.tags ? { tags: meta.tags.map((t) => ({ name: t })) } : {}),
+            messages: [{ $ref: `#/channels/${key}/messages/receiveMessage` }],
+        };
+        // Outbound: only emitted when the route declares an outbound schema.
+        const sendSchema = meta?.send;
+        if (sendSchema) {
+            const sendMsgKey = `${key}Send`;
+            messages[sendMsgKey] = {
+                name: sendMsgKey,
+                title: `${key} outbound message`,
+                payload: toPayloadSchema(sendSchema) ?? {},
+            };
+            channelMessages.sendMessage = {
+                $ref: `#/components/messages/${sendMsgKey}`,
+            };
+            operations[sendMsgKey] = {
+                action: "send",
+                channel: { $ref: `#/channels/${key}` },
+                ...(meta?.summary ? { summary: meta.summary } : {}),
+                ...(meta?.tags ? { tags: meta.tags.map((t) => ({ name: t })) } : {}),
+                messages: [{ $ref: `#/channels/${key}/messages/sendMessage` }],
+            };
+        }
+        const parameters = {};
+        for (const name of paramNames) {
+            parameters[name] = { description: `Path parameter \`${name}\`.` };
+        }
+        channels[key] = {
+            address,
+            ...(meta?.summary ? { summary: meta.summary } : {}),
+            ...(meta?.description ? { description: meta.description } : {}),
+            ...(paramNames.length ? { parameters } : {}),
+            messages: channelMessages,
+        };
+    }
+    return {
+        asyncapi: "3.0.0",
+        info: options.info,
+        ...(options.servers ? { servers: options.servers } : {}),
+        channels,
+        operations,
+        components: { messages },
+    };
+}
+/**
+ * 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 function asyncapiToYAML(doc) {
+    return openapiToYAML(doc);
+}