@daloyjs/core 1.2.0 → 1.2.1

package/README.md

@@ -664,9 +664,9 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `idempotency()` with `Idempotency-Key` fingerprinting + byte-for-byte response replay, in-flight `409`, `422` on key reuse with a different payload, and a pluggable `IdempotencyStore` (in-memory default) at `@daloyjs/core/idempotency`.
 - `responseCache()` server-side body cache (cache-key + TTL with `s-maxage`/`max-age` orchestration, request `no-store`/`no-cache` directives, recursion-safe stale-while-revalidate, proactive `varyHeaders` keying, `X-Cache` HIT/MISS/STALE marker, pluggable `ResponseCacheStore` whose in-memory default is bounded on both entry count and retained bytes) at `@daloyjs/core/response-cache`. Never caches `Set-Cookie`, `private`/`no-store`/`no-cache`, or `Vary: *` responses, and strips `Age`/hop-by-hop/`X-Request-Id` from stored entries so a hit never replays another request's correlation id. **Fail-closed on every principal dimension (CWE-524):** the key is the full _effective request URI_ including the authority (RFC 9111 §4), so hostnames never share entries; requests carrying `Authorization` **or** `Cookie` bypass the shared cache unless a `principal` names the caller (then each gets its own entry) or the header is explicitly declared shareable; a tenant resolved by `tenancy()` is folded into the key automatically — with a boot guard that refuses to start if the cache is mounted ahead of `tenancy()`; and the response's **own `Vary` header** is honoured as a secondary key (RFC 9111 §4.1), so the `Vary: Origin` written by `cors()` and the `Vary: Accept-Encoding` written by `compression()` keep one caller's allowed origin — or their gzipped bytes — from being served to the next, with each variant stored separately so they all stay warm. Complements `etag()`/`compression()`, which do not cache bodies.
 - `paginationQuery()` / `encodeCursor()` / `decodeCursor()` / `buildPageLinks()` / `buildLinkHeader()` cursor-pagination helpers at `@daloyjs/core/pagination`: opaque base64url cursors (length-capped, prototype-pollution-safe decode → `400` on tamper), RFC 8288 `Link` header emission with CRLF / header-injection guards, and a Standard Schema that validates `cursor`/`limit` and auto-wires both into the OpenAPI spec + typed client via `toJSONSchema()`.
-- `app.metrics()` + `MetricsRegistry` / `httpMetrics()` Prometheus / OpenMetrics exposition at `@daloyjs/core/metrics`: dependency-free counters / gauges / histograms, RED instrumentation (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`) plus process gauges, exposition-injection-safe name/label validation, a per-metric cardinality cap, and an opt-in `/metrics` route with the same hardened posture as `app.healthcheck()` (bearer token + `timingSafeEqual`, per-IP rate limit, refuse-to-boot unauthenticated in production). The repo ships an `examples/observability/` Docker Compose stack that starts a pre-configured Prometheus + Grafana pair (with an auto-provisioned RED + heatmap dashboard) against any local app via `docker compose -f examples/observability/docker-compose.yml up`.
+- `app.metrics()` + `MetricsRegistry` / `httpMetrics()` Prometheus / OpenMetrics exposition at `@daloyjs/core/metrics`: dependency-free counters / gauges / histograms, RED instrumentation (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`, `route` from the matched template) plus unprefixed process gauges (`process_resident_memory_bytes`), exposition-injection-safe name/label validation, a per-metric cardinality cap (`daloy_metrics_series_dropped_total`), and an opt-in `/metrics` route with the same hardened posture as `app.healthcheck()` (bearer token + portable `timingSafeEqual`, per-IP rate limit, refuse-to-boot unauthenticated in production). Pull scrape is for long-lived processes; on Workers / Lambda / Vercel use `telemetry: true` (OTLP push). The repo ships an `examples/observability/` Docker Compose stack that starts a pre-configured Prometheus + Grafana pair (with an auto-provisioned RED + heatmap dashboard) against any local app via `docker compose -f examples/observability/docker-compose.yml up`.
 - `otelTracing()` OpenTelemetry-compatible distributed tracing at `@daloyjs/core/tracing`: a dependency-free `Hooks` bundle that opens one `SERVER` span per request, attaches HTTP semantic-convention attributes (`http.request.method`, `url.path`, `server.address` / `server.port`, `http.response.status_code`, …), records exceptions + escalates `5xx` to `ERROR`, guarantees a single `span.end()`, and exposes the live span on `ctx.state.otelSpan`. Bring any tracer matching the small `TracingTracer` interface (the real `@opentelemetry/api` SDK on Node, or a custom exporter on Workers/Deno) plus your own propagator via `contextFromRequest` for `traceparent` continuation — no OTel SDK is forced into your install. The `examples/observability/` stack also runs **Jaeger**, and `examples/otel-tracing-demo.ts` ships a ~120-line dependency-free OTLP/HTTP exporter that streams spans straight to it.
-- `new App({ telemetry: true })` native OpenTelemetry OTLP push export at `@daloyjs/core/otlp`: one flag tees the app logger to the collector as OTLP logs and records `http.server.request.duration` per the OTel HTTP semantic conventions (spec attributes incl. `http.route` from the matched route template via the new `ctx.routePath`, spec bucket boundaries), pushed as dependency-free OTLP/HTTP JSON to the endpoint in the standard `OTEL_EXPORTER_OTLP_*` env vars — zero config on collector-based platforms that inject them, silent no-op without them. Standalone `createOtlpLogExporter()` / `createOtlpMetricsExporter()` (cumulative temporality — totals survive failed pushes) / `semconvHttpMetrics()` exports; fail-safe by contract (bounded queues, series-cardinality cap, a dead collector never affects serving, tenant-routing header values never logged).
+- `new App({ telemetry: true })` native OpenTelemetry OTLP push export at `@daloyjs/core/otlp`: one flag tees the app logger to the collector as OTLP logs and records `http.server.request.duration` per the OTel HTTP semantic conventions (spec attributes incl. `http.route` from the matched route template via the new `ctx.routePath`, spec bucket boundaries), pushed as dependency-free OTLP/HTTP JSON to the endpoint in the standard `OTEL_EXPORTER_OTLP_*` env vars — zero config on collector-based platforms that inject them, silent no-op without them. Standalone `createOtlpLogExporter()` / `createOtlpMetricsExporter()` (cumulative temporality — totals survive failed pushes) / `semconvHttpMetrics()` exports; fail-safe by contract (bounded queues, series-cardinality cap, a 5s export timeout, a dead collector never affects serving, tenant-routing header values never logged). Isolate runtimes flush per request through `toFetchHandler` (Cloudflare `waitUntil`, Vercel) and `toLambdaHandler` (awaited); Node/Bun/Deno flush on an interval plus shutdown.
 - `tenancy()` secure-by-default multitenancy at `@daloyjs/core/tenancy`: a dependency-free `Hooks` bundle that resolves the calling tenant once per request and exposes it on `ctx.state.tenant`. Pluggable resolution (`tenantFromSubdomain` PSL-aware, `tenantFromHeader`, `tenantFromPathPrefix`, `tenantFromClaim`, or a custom `(ctx) => string`, tried in array order). **Refuse-unresolved by default** (no ambient "default" tenant leak), **format-validated ids** (rejects key/log-injection + cache-poisoning payloads before they reach a key), **no-enumeration `404`** for unknown tenants, and **host-spoof-safe** subdomain resolution. A `tenantScope()` key helper drops straight into `rateLimit` `keyGenerator` and `concurrencyLimit` / `idempotency` `scope` to partition each per tenant (CWE-524 cross-tenant cache defense); `responseCache()` needs no wiring at all — it reads the resolved tenant itself and refuses to boot if mounted ahead of `tenancy()`. Runnable `examples/multitenancy-demo.ts`.
 - `resilientFetch()` + `CircuitBreaker` outbound resilience at `@daloyjs/core/fetch-resilience`: a dependency-free circuit breaker (`closed → open → half-open`), retry-with-backoff (exponential + full jitter, idempotent-method/transient-status scoped, honours `Retry-After`), and a per-call timeout (`AbortController` → `FetchTimeoutError`) designed to layer **on top of** `fetchGuard()` — an `SsrfBlockedError` is a terminal refusal that is never retried and never trips the breaker, so SSRF protection stays intact under the resilience layer.
 - `createWebhookSender()` + `MemoryWebhookDeadLetterSink` outbound webhook delivery at `@daloyjs/core/webhook-delivery`: the outbound counterpart to `verifyWebhookSignature()` — timestamped HMAC-signed `POST`s (`webhook-id` / `webhook-timestamp` / `webhook-signature`, computed over `"<timestamp>.<body>"` and reused across retries for safe deduping), bounded retry-with-backoff (transient-status + network scoped, honours `Retry-After`), per-attempt timeout, and dead-letter semantics. Transport defaults to `fetchGuard()`, so a subscriber URL pointing at cloud metadata or a private range is refused with a terminal `SsrfBlockedError` (never retried, dead-lettered once). Zero runtime dependencies.

package/dist/adapters/cloudflare.d.ts

@@ -18,7 +18,11 @@
 import type { App } from "../app.js";
 /** Module shape expected by the Cloudflare Workers runtime as `export default`. */
 export interface ExportedFetchHandler<Env = unknown> {
-    /** Worker entry point: forwards the request to {@link App.fetch}. `env`/`ctx` are accepted but unused by the adapter. */
+    /**
+     * Worker entry point: forwards the request to {@link App.fetch}. After the
+     * response is produced, `ctx.waitUntil` is used to flush OTLP telemetry so
+     * the isolate stays alive long enough for the export POST to finish.
+     */
     fetch: (request: Request, env?: Env, ctx?: ExecutionContextLike) => Promise<Response>;
 }
 interface ExecutionContextLike {
@@ -28,6 +32,9 @@ interface ExecutionContextLike {
 /**
  * Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts.
  *
+ * After each request, OTLP telemetry is flushed via `ctx.waitUntil` so the
+ * isolate stays alive long enough for the export POST to finish.
+ *
  * @param app - The DaloyJS {@link App} that serves each incoming request.
  * @returns An {@link ExportedFetchHandler} suitable as the module's `export default`.
  */

package/dist/adapters/cloudflare.js

@@ -1,11 +1,25 @@
 /**
  * Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts.
  *
+ * After each request, OTLP telemetry is flushed via `ctx.waitUntil` so the
+ * isolate stays alive long enough for the export POST to finish.
+ *
  * @param app - The DaloyJS {@link App} that serves each incoming request.
  * @returns An {@link ExportedFetchHandler} suitable as the module's `export default`.
  */
 export function toFetchHandler(app) {
     return {
-        fetch: (req) => app.fetch(req),
+        async fetch(req, _env, ctx) {
+            const res = await app.fetch(req);
+            const telemetry = app.telemetry;
+            if (telemetry !== undefined) {
+                const pending = telemetry.flush();
+                if (ctx?.waitUntil !== undefined)
+                    ctx.waitUntil(pending);
+                else
+                    void pending;
+            }
+            return res;
+        },
     };
 }

package/dist/adapters/lambda.js

@@ -20,6 +20,9 @@ export function toLambdaHandler(app) {
             return responseToLambda(badRequestResponse(), isV2Event(event));
         }
         const response = await app.fetch(request);
+        // Lambda freezes when the handler resolves; await the export so OTLP
+        // actually leaves the isolate. `flush()` never rejects.
+        await app.telemetry?.flush();
         return responseToLambda(response, isV2Event(event));
     };
 }
@@ -49,6 +52,7 @@ export function toLambdaStreamHandler(app) {
             return;
         }
         await streamLambdaResponse(await app.fetch(request), rawStream, runtime);
+        await app.telemetry?.flush();
     });
 }
 function eventToRequest(event) {
@@ -75,13 +79,17 @@ function eventToRequest(event) {
         : (event.path ?? event.requestContext?.path ?? "/");
     const host = headers.get("host") ?? event.requestContext?.domainName ?? "localhost";
     const proto = headers.get("x-forwarded-proto") ?? "https";
-    const rawQueryString = isV2Event(event) ? (event.rawQueryString ?? "") : queryStringForV1(event);
+    const rawQueryString = isV2Event(event)
+        ? (event.rawQueryString ?? "")
+        : queryStringForV1(event);
     const qs = rawQueryString ? `?${rawQueryString}` : "";
     const path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
     const url = `${proto}://${host}${path}${qs}`;
     const init = { method, headers };
     if (method !== "GET" && method !== "HEAD" && event.body != null) {
-        init.body = event.isBase64Encoded ? base64ToBytes(event.body) : event.body;
+        init.body = event.isBase64Encoded
+            ? base64ToBytes(event.body)
+            : event.body;
     }
     const request = new Request(url, init);
     // Fulfil the conn-info contract with the caller address API Gateway saw
@@ -171,8 +179,7 @@ function badRequestResponse() {
     }, { status: 400, headers: { "content-type": "application/problem+json" } });
 }
 function lambdaStreamingRuntime() {
-    const runtime = globalThis
-        .awslambda;
+    const runtime = globalThis.awslambda;
     if (!runtime ||
         typeof runtime.streamifyResponse !== "function" ||
         typeof runtime.HttpResponseStream?.from !== "function") {
@@ -182,7 +189,10 @@ function lambdaStreamingRuntime() {
 }
 async function streamLambdaResponse(response, rawStream, runtime) {
     const { headers, cookies } = responseHeaders(response);
-    const metadata = { statusCode: response.status, headers };
+    const metadata = {
+        statusCode: response.status,
+        headers,
+    };
     if (cookies.length)
         metadata.multiValueHeaders = { "set-cookie": cookies };
     const responseStream = runtime.HttpResponseStream.from(rawStream, metadata);

package/dist/adapters/vercel.d.ts

@@ -32,6 +32,11 @@ export type RouteHandlers = Record<(typeof NEXT_METHODS)[number], WebHandler>;
 /**
  * Wrap an {@link App} as a single web-standard fetch handler.
  *
+ * After the response is produced, any OTLP telemetry is flushed. When the
+ * runtime exposes `globalThis.waitUntil` (Vercel Fluid / Edge), that is used
+ * so the export can finish after the response is sent; otherwise the flush
+ * is started fire-and-forget.
+ *
  * @param app - The DaloyJS {@link App} that serves each incoming request.
  * @returns A {@link WebHandler} delegating to {@link App.fetch}.
  */

package/dist/adapters/vercel.js

@@ -1,12 +1,37 @@
-const NEXT_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
+const NEXT_METHODS = [
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "OPTIONS",
+    "HEAD",
+];
 /**
  * Wrap an {@link App} as a single web-standard fetch handler.
  *
+ * After the response is produced, any OTLP telemetry is flushed. When the
+ * runtime exposes `globalThis.waitUntil` (Vercel Fluid / Edge), that is used
+ * so the export can finish after the response is sent; otherwise the flush
+ * is started fire-and-forget.
+ *
  * @param app - The DaloyJS {@link App} that serves each incoming request.
  * @returns A {@link WebHandler} delegating to {@link App.fetch}.
  */
 export function toWebHandler(app) {
-    return (req) => app.fetch(req);
+    return async (req) => {
+        const res = await app.fetch(req);
+        const telemetry = app.telemetry;
+        if (telemetry !== undefined) {
+            const pending = telemetry.flush();
+            const waitUntil = globalThis.waitUntil;
+            if (typeof waitUntil === "function")
+                waitUntil(pending);
+            else
+                void pending;
+        }
+        return res;
+    };
 }
 /**
  * Build the default `{ fetch }` export expected by Vercel Node.js Functions

package/dist/app.d.ts

@@ -81,8 +81,9 @@ export interface AppOptions {
      * per the OTel HTTP semantic conventions, pushed to the collector named by
      * the standard `OTEL_EXPORTER_OTLP_*` environment variables. A silent no-op
      * when no endpoint is configured, so it is safe to keep enabled in
-     * development. Export failures never affect request serving. See
-     * {@link TelemetryOptions}.
+     * development. Export failures never affect request serving. Isolate
+     * runtimes must go through `toFetchHandler` / `toLambdaHandler` so a
+     * per-request flush actually runs. See {@link TelemetryOptions}.
      *
      * @since 1.2.0
      */
@@ -656,15 +657,15 @@ export interface MetricsRouteOptions {
      */
     registry?: MetricsRegistry;
     /**
-     * Resolve the low-cardinality `route` label. Strongly recommended: return
-     * the route template (e.g. `/books/:id`) instead of the raw path.
-     * Forwarded to {@link httpMetrics}.
+     * Resolve the low-cardinality `route` label. When omitted, the matched
+     * route template (`ctx.routePath`, e.g. `/books/:id`) is used. Forwarded
+     * to {@link httpMetrics}.
      */
     route?: HttpMetricsOptions["route"];
     /**
-     * Maximum distinct values for the default pathname-derived `route` label
-     * before further values collapse to `"<other>"`. Forwarded to
-     * {@link httpMetrics}. Default `100`.
+     * Maximum distinct values for the pathname fallback `route` label (no
+     * template on the context). Forwarded to {@link httpMetrics}. Default
+     * `100`.
      */
     maxRouteCardinality?: number;
     /** Latency histogram buckets, in seconds. Forwarded to {@link httpMetrics}. */
@@ -1443,8 +1444,13 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *
      * 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.