@nifrajs/core 1.9.1 → 1.11.0

package/dist/server/server.js

@@ -1,6 +1,9 @@
-import { admitDeadline, createRequestBudget, createUnboundedRequestBudget, NIFRA_DEADLINE_HEADER, } from "@nifrajs/budget";
+import { admitDeadline, createRequestBudget, createUnboundedRequestBudget, NIFRA_DEADLINE_HEADER, } from "../budget.js";
 import { FrameworkError, RouteConfigError } from "../errors.js";
+import { canonicalizeIdempotencyBody, computeIdempotencyFingerprint, DEFAULT_IDEMPOTENCY_HEADER, DEFAULT_IDEMPOTENCY_TTL_MS, IdempotencyResponseTooLargeError, MemoryIdempotencyStore, responseFromStored, serializeResponse, validIdempotencyKey, validIdempotencyNamespace, } from "../idempotency.js";
+import { CAPABILITY_GUARD, createCapabilityGuard, normalizeRouteCapabilities, } from "../internal/capability-runtime.js";
 import { assuranceDeclarationsOf, assuranceEvidenceFor, NIFRA_ASSURANCE_IDS, } from "../internal/route-assurance.js";
+import { attachEffectLedger, createRequestLedger, DEFAULT_MAX_ENTRIES, } from "../ledger.js";
 import { EMPTY_PARAMS, Router } from "../router/router.js";
 import { drainCapped, parseContentLength, readBoundedBytes } from "./body.js";
 import { parseCookies, serializeCookie } from "./cookies.js";
@@ -660,6 +663,12 @@ export class Server {
     gracefulSignals;
     /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
     capacityGate;
+    onCapabilityUse;
+    /** Effect-ledger defaults pinned at construction; per-route `ledgered` copies add route identity. */
+    effectLedger;
+    /** App-wide idempotency store (explicit option, else a lazily-created in-process default). */
+    configuredIdempotencyStore;
+    lazyIdempotencyStore;
     logger;
     /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
     defaultOnValidationError;
@@ -713,6 +722,27 @@ export class Server {
         }
         this.gracefulSignals = options.gracefulSignals ?? false;
         this.capacityGate = options.admission;
+        this.onCapabilityUse = options.onCapabilityUse;
+        if (options.effectLedger !== undefined) {
+            const ledger = options.effectLedger;
+            if (typeof ledger.sink !== "function") {
+                throw new TypeError("effectLedger.sink must be a function");
+            }
+            const maxEntries = ledger.maxEntries ?? DEFAULT_MAX_ENTRIES;
+            if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+                throw new RangeError("effectLedger.maxEntries must be a positive safe integer");
+            }
+            this.effectLedger = Object.freeze({
+                sink: ledger.sink,
+                maxEntries,
+                chain: ledger.chain ?? false,
+            });
+        }
+        else {
+            this.effectLedger = undefined;
+        }
+        this.configuredIdempotencyStore = options.idempotencyStore;
+        this.lazyIdempotencyStore = undefined;
         this.logger = options.logger ?? jsonLogger();
         this.defaultOnValidationError = options.onValidationError;
         this.bunServer = undefined;
@@ -989,24 +1019,50 @@ export class Server {
      * is the "compiled", order-scoped per-route chain.
      */
     register(method, path, schema, handler) {
+        const capabilities = normalizeRouteCapabilities(schema?.capabilities);
+        const handlerAssurance = assuranceDeclarationsOf(handler);
+        const invalidHandlerScope = handlerAssurance.find((declaration) => declaration.scope !== "plugin");
+        if (invalidHandlerScope !== undefined) {
+            throw new RouteConfigError("INVALID_ASSURANCE", `route handler assurance must use plugin scope (received ${invalidHandlerScope.scope})`);
+        }
+        const authenticated = assuranceEvidenceFor([...this.activeAssurance, ...handlerAssurance, ...this.globalAssurance], method, path).some((evidence) => evidence.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED);
+        const routeDecorations = { ...this.decorations };
+        if (capabilities.length > 0) {
+            routeDecorations[CAPABILITY_GUARD] = createCapabilityGuard(capabilities, method, path, this.onCapabilityUse);
+        }
+        const hasDecorations = Reflect.ownKeys(routeDecorations).length > 0;
+        // An idempotency route runs a dedupe lane that must buffer the body and capture the response, so it
+        // never takes the fused/native fast path — force it onto the portable matched lane (which routes
+        // through `fetchMatched`, where the dedupe wrapper lives).
+        const idempotent = this.resolveIdempotency(schema, authenticated);
+        // A ledgered route (capabilities declared + `server({ effectLedger })`) needs a per-request
+        // context to carry the ledger and a settle step to seal + sink it, so it too leaves the
+        // fused/contextless fast path. Resolved per route, at registration — like the capability guard.
+        const ledgered = capabilities.length > 0 && this.effectLedger !== undefined
+            ? Object.freeze({ ...this.effectLedger, method, path, declared: capabilities })
+            : undefined;
         const bare = schema?.body === undefined &&
             schema?.query === undefined &&
+            idempotent === undefined &&
+            ledgered === undefined &&
             this.derives.length === 0 &&
             this.beforeHandleHooks.length === 0 &&
             this.afterHandleHooks.length === 0 &&
             this.onErrorHooks.length === 0;
         const fusedWeb = bare && this.aroundHooks.length === 0
-            ? this.buildFusedWeb(handler, Object.keys(this.decorations).length > 0 ? { ...this.decorations } : undefined, isContextlessNoArgArrow(handler))
+            ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler))
             : undefined;
         const entry = {
             // (context: never) => unknown -> InternalHandler: the framework invokes it
             // with the concrete RawContext the typed handler expects, so this is sound.
             handler: handler,
             schema,
+            idempotent,
+            ledgered,
             fusedWeb,
             derives: [...this.derives],
-            decorations: { ...this.decorations },
-            hasDecorations: Object.keys(this.decorations).length > 0,
+            decorations: routeDecorations,
+            hasDecorations,
             beforeHandle: [...this.beforeHandleHooks],
             afterHandle: [...this.afterHandleHooks],
             onError: [...this.onErrorHooks],
@@ -1031,9 +1087,14 @@ export class Server {
                 this.onErrorHooks.length === 0,
         };
         this.router.add(method, path, entry);
-        const descriptor = { method, path, schema };
+        const descriptor = {
+            method,
+            path,
+            schema,
+            ...(capabilities.length > 0 ? { capabilities } : {}),
+        };
         this.routeList.push(descriptor);
-        const routeAssurance = [...this.activeAssurance];
+        const routeAssurance = [...this.activeAssurance, ...handlerAssurance];
         if (schema?.body !== undefined) {
             routeAssurance.push(Object.freeze({
                 id: NIFRA_ASSURANCE_IDS.BODY_BOUNDED,
@@ -1041,6 +1102,15 @@ export class Server {
                 scope: "plugin",
             }));
         }
+        // Declaring `schema.idempotency` is evidence for request replay only. It deliberately never proves
+        // durable command execution; that stronger evidence belongs to a command/outbox adapter.
+        if (schema?.idempotency !== undefined) {
+            routeAssurance.push(Object.freeze({
+                id: NIFRA_ASSURANCE_IDS.IDEMPOTENCY_KEY,
+                source: "route-schema",
+                scope: "plugin",
+            }));
+        }
         this.rawEntries.push({
             method,
             path,
@@ -1049,6 +1119,58 @@ export class Server {
             assurance: Object.freeze(routeAssurance),
         });
     }
+    /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
+    resolveIdempotency(schema, authenticated) {
+        const config = schema?.idempotency;
+        if (config === undefined)
+            return undefined;
+        if (schema?.sse !== undefined) {
+            throw new RouteConfigError("INVALID_IDEMPOTENCY", "streaming/SSE responses cannot be used on an idempotency route");
+        }
+        const store = config.store ?? this.defaultIdempotencyStore();
+        if (config.scope === "durable" && store.durability !== "durable") {
+            throw new RouteConfigError("INVALID_IDEMPOTENCY", 'durable idempotency requires a durable store (store.durability must be "durable")');
+        }
+        const ttlMs = config.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS;
+        if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+            throw new RouteConfigError("INVALID_IDEMPOTENCY", "idempotency ttlMs must be a finite positive number");
+        }
+        const headerName = (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase();
+        try {
+            new Headers().set(headerName, "probe");
+        }
+        catch {
+            throw new RouteConfigError("INVALID_IDEMPOTENCY", `invalid idempotency header name ${JSON.stringify(headerName)}`);
+        }
+        const namespace = config.namespace;
+        if (namespace === undefined) {
+            throw new RouteConfigError("INVALID_IDEMPOTENCY", "idempotency namespace is required; use a principal resolver or an explicit shared scope");
+        }
+        if (typeof namespace === "string" && !validIdempotencyNamespace(namespace)) {
+            throw new RouteConfigError("INVALID_IDEMPOTENCY", `invalid idempotency namespace ${JSON.stringify(namespace)}`);
+        }
+        if (authenticated && typeof namespace !== "function") {
+            throw new RouteConfigError("INVALID_IDEMPOTENCY", "authenticated idempotency routes require a principal namespace resolver");
+        }
+        const maxResponseBytes = config.maxResponseBytes ?? this.maxBodyBytes;
+        if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1) {
+            throw new RouteConfigError("INVALID_IDEMPOTENCY", "idempotency maxResponseBytes must be a positive integer");
+        }
+        return Object.freeze({
+            store,
+            ttlMs,
+            headerName,
+            namespace,
+            maxResponseBytes,
+        });
+    }
+    /** The app-wide idempotency store: the configured one, else a lazily-created shared in-process store. */
+    defaultIdempotencyStore() {
+        if (this.configuredIdempotencyStore !== undefined)
+            return this.configuredIdempotencyStore;
+        this.lazyIdempotencyStore ??= new MemoryIdempotencyStore();
+        return this.lazyIdempotencyStore;
+    }
     /**
      * Merge another server's routes into this one — the composition escape hatch for large apps.
      *
@@ -1179,15 +1301,11 @@ export class Server {
             release();
             throw error;
         }
-        if (outcome instanceof Promise) {
-            return outcome.then((response) => {
-                release();
-                return response;
-            }, (error) => {
-                release();
-                throw error;
-            });
-        }
+        // Release the slot once the response settles — on resolve OR reject — via `finally`, which passes
+        // the value/rejection through unchanged. (A single settle hook, rather than separate then-arms: the
+        // request pipeline resolves handler errors to a Response, so a rejection arm would be unreachable.)
+        if (outcome instanceof Promise)
+            return outcome.finally(release);
         release();
         return outcome;
     }
@@ -1329,7 +1447,7 @@ export class Server {
         const originalRequest = requestOf(source);
         let current = source;
         for (let i = 0; i < hooks.length; i++) {
-            const outcome = hooks[i](requestOf(current));
+            const outcome = hooks[i](requestOf(current), platform);
             if (outcome instanceof Promise) {
                 return outcome.then((early) => this.continueOnRequest(early, i + 1, originalRequest, current, platform, finalize, wrapResponse, onTimeout, webFast));
             }
@@ -1361,7 +1479,7 @@ export class Server {
             }
             if (index >= this.onRequestHooks.length)
                 break;
-            const outcome = this.onRequestHooks[index](requestOf(current));
+            const outcome = this.onRequestHooks[index](requestOf(current), platform);
             early = outcome instanceof Promise ? await outcome : outcome;
             index++;
         }
@@ -1399,6 +1517,118 @@ export class Server {
     }
     /** Run a route that has already been matched by the runtime or Nifra's portable router. */
     runMatched(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast) {
+        // An idempotency route runs its dedupe lane first; on a fresh key it delegates to the normal lanes
+        // (with the body buffered). All non-idempotent routes skip straight to the lanes — no added cost.
+        if (entry.idempotent !== undefined) {
+            return this.runIdempotent(source, platform, entry, params, search, wrapResponse);
+        }
+        return this.runMatchedLanes(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast);
+    }
+    /**
+     * Idempotency dedupe lane. Reads the `Idempotency-Key`, fingerprints the request, and consults the
+     * store: a fresh key runs the handler (via {@link runMatchedLanes} with the body buffered) and stores
+     * the response; a repeat key replays it without re-running; a key reused with a different body or an
+     * in-flight duplicate is rejected. Every branch materializes a `Response`, then adapts to `T` via the
+     * caller's `wrapResponse`, so it works on the Web fetch path and the Node-native outcome path alike.
+     */
+    async runIdempotent(source, platform, entry, params, search, wrapResponse) {
+        const config = entry.idempotent;
+        const req = requestOf(source);
+        const key = req.headers.get(config.headerName);
+        if (key === null || !validIdempotencyKey(key)) {
+            return wrapResponse(jsonError(400, "idempotency_key_required"));
+        }
+        const namespace = typeof config.namespace === "function"
+            ? await config.namespace(req.clone(), platform)
+            : config.namespace;
+        if (!validIdempotencyNamespace(namespace)) {
+            return wrapResponse(jsonError(500, "idempotency_namespace_invalid"));
+        }
+        const read = await readBoundedBytes(req, this.maxBodyBytes);
+        if (!read.ok) {
+            return wrapResponse(jsonError(read.status, read.status === 413 ? "payload_too_large" : "bad_request"));
+        }
+        const url = urlPartsOf(req.url);
+        const canonicalBody = canonicalizeIdempotencyBody(read.bytes, req.headers.get("content-type"));
+        const fingerprint = await computeIdempotencyFingerprint(req.method, `${url.pathname}${url.search}`, canonicalBody, req.headers.get("content-type") ?? "");
+        const begin = await config.store.begin({ namespace, key, fingerprint, ttlMs: config.ttlMs });
+        if (begin.state === "replay") {
+            return wrapResponse(responseFromStored(begin.response, { maxBytes: config.maxResponseBytes }));
+        }
+        if (begin.state === "mismatch")
+            return wrapResponse(jsonError(409, "idempotency_key_reused"));
+        if (begin.state === "in-flight") {
+            return wrapResponse(jsonError(409, "idempotency_in_progress", { "Retry-After": "1" }));
+        }
+        if (begin.state === "capacity") {
+            return wrapResponse(jsonError(503, "idempotency_store_capacity", { "Retry-After": "1" }));
+        }
+        const reservation = begin.reservation;
+        // Fresh key: re-expose the buffered body as a Request so the normal lanes can read + validate it,
+        // then run those lanes to a concrete Response.
+        const bufferedInit = {
+            method: req.method,
+            headers: req.headers,
+            signal: req.signal,
+        };
+        if (read.bytes.byteLength > 0)
+            bufferedInit.body = read.bytes;
+        const buffered = new Request(req.url, bufferedInit);
+        let response;
+        try {
+            response = await this.runMatchedLanes(buffered, platform, entry, params, search, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, false);
+        }
+        catch (err) {
+            // The lanes never throw (errors resolve to a 500 Response), but stay fail-safe: release the
+            // reservation so a retry isn't wedged, then re-throw.
+            await config.store.abandon({ namespace, key, reservation });
+            throw err;
+        }
+        // Cache only successful responses; release the key on any error so the client can retry.
+        if (response.status >= 200 && response.status < 300) {
+            let storedResponse;
+            try {
+                storedResponse = await serializeResponse(response, { maxBytes: config.maxResponseBytes });
+            }
+            catch (error) {
+                if (!(error instanceof IdempotencyResponseTooLargeError))
+                    throw error;
+                // The effect may already have happened, so never abandon and permit a duplicate execution.
+                // Commit a small terminal response under the winning key and return that same response now.
+                response = jsonError(507, "idempotency_response_too_large");
+                try {
+                    storedResponse = await serializeResponse(response, {
+                        maxBytes: config.maxResponseBytes,
+                    });
+                }
+                catch (terminalError) {
+                    if (!(terminalError instanceof IdempotencyResponseTooLargeError))
+                        throw terminalError;
+                    // Even an intentionally tiny bound must remain truthful. An empty 507 preserves terminal
+                    // status + replay safety without silently storing more bytes than the route permits.
+                    response = new Response(null, { status: 507 });
+                    storedResponse = await serializeResponse(response, {
+                        maxBytes: config.maxResponseBytes,
+                    });
+                }
+            }
+            const completed = await config.store.complete({
+                namespace,
+                key,
+                reservation,
+                response: storedResponse,
+            });
+            if (!completed) {
+                return wrapResponse(jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }));
+            }
+        }
+        else {
+            await config.store.abandon({ namespace, key, reservation });
+        }
+        return wrapResponse(response);
+    }
+    /** Run a matched route through its selected execution lane (fused/bare/bodyOnly/queryOnly/lifecycle). */
+    runMatchedLanes(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast) {
         // Translate the absolute wire deadline once, clamp it to local policy, then use the resulting
         // duration for both c.signal and c.budget. A client can only shorten work, never extend it.
         // Most requests have neither a local timeout nor a propagated deadline. Detect that case with
@@ -1446,6 +1676,20 @@ export class Server {
             // Build the context up front so `onError` always has it. Query, cookies, headers, and body helpers
             // stay lazy, but their accessors live on the prototype instead of allocating per-request closures.
             const ctx = new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes);
+            // Ledgered routes (capabilities + effectLedger) carry a bounded per-request ledger; the
+            // `useCapability` beacon appends to it, and the settle step below seals + sinks it. The route
+            // was forced off the fused/contextless lanes at registration, so this branch always runs.
+            let ledger;
+            if (entry.ledgered !== undefined) {
+                ledger = createRequestLedger({
+                    method: entry.ledgered.method,
+                    path: entry.ledgered.path,
+                    declared: entry.ledgered.declared,
+                    maxEntries: entry.ledgered.maxEntries,
+                    chain: entry.ledgered.chain,
+                });
+                attachEffectLedger(ctx, ledger);
+            }
             if (entry.around.length === 0) {
                 outcome = entry.bare
                     ? this.runBare(entry, ctx, finalize, wrapResponse)
@@ -1464,6 +1708,14 @@ export class Server {
                             ? this.runQueryOnly(entry, ctx, finalize, wrapResponse)
                             : this.runLifecycle(entry, source, ctx, finalize, wrapResponse), finalize, wrapResponse);
             }
+            // Settle step: seal the ledger and hand it to the sink BEFORE the response is released, on
+            // success and error responses alike (partial work is exactly what an audit must capture). The
+            // lanes above resolve handler errors to responses, so a plain resolve arm is sufficient.
+            if (ledger !== undefined) {
+                const resolved = entry.ledgered;
+                const active = ledger;
+                outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) => this.settleEffectLedger(active, resolved, value));
+            }
         }
         // The request timeout only bounds work that is actually pending — a synchronous (bare) result is
         // already complete and can't time out, so it's returned as-is (no 503 race, no promise).
@@ -1475,6 +1727,31 @@ export class Server {
         }
         return outcome;
     }
+    /**
+     * Seal a ledgered request and deliver the sealed ledger to the sink. An empty ledger (declared
+     * capabilities, none exercised) is not delivered — there is nothing to audit. This post-effect
+     * ledger is observational: transactional/durable audit belongs in
+     * the owned effect transaction, so a sink outage must not turn a successful effect into a retryable
+     * 500 that can duplicate it.
+     */
+    async settleEffectLedger(ledger, resolved, value) {
+        const sealed = await ledger.seal();
+        if (sealed.entries.length === 0)
+            return value;
+        try {
+            await resolved.sink(sealed);
+        }
+        catch (err) {
+            // Token-only logging: the route pattern and the failure name — never entry payloads (there are
+            // none) and never the request.
+            this.logger.error("effect ledger sink failed", {
+                method: resolved.method,
+                path: resolved.path,
+                name: err instanceof Error ? err.name : "Error",
+            });
+        }
+        return value;
+    }
     /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so
      * successful requests can skip allocating `RequestContext`. Errors still allocate one for logging. */
     runContextlessBare(entry, source, params, search, signal, budget, platform, finalize, wrapResponse) {