@nifrajs/core 3.3.0 → 4.0.0

package/src/server/idempotency-lane.ts

@@ -12,6 +12,7 @@ import {
   canonicalizeIdempotencyBody,
   computeIdempotencyFingerprint,
   DEFAULT_IDEMPOTENCY_HEADER,
+  DEFAULT_IDEMPOTENCY_PENDING_TTL_MS,
   DEFAULT_IDEMPOTENCY_TTL_MS,
   IdempotencyResponseTooLargeError,
   type IdempotencyStore,
@@ -33,10 +34,20 @@ import { jsonError, urlPartsOf } from "./http.ts"
 import { INSTALL_IDEMPOTENCY } from "./install.ts"
 import type { AnyServer, IdentityPlugin } from "./server.ts"
 
+/** Requests whose route handler was entered. One rejected before it - by auth, validation, a guard -
+ * began no execution, so its key is released rather than stored. */
+const HANDLER_ENTERED = new WeakSet<Request>()
+
+/** Statuses that say the request was not carried out (RFC 9110). A handler answering with one, with no
+ * owned effect begun, releases its key, so a refused caller cannot hold a store entry for the TTL. */
+const REFUSALS = new Set([401, 403, 408, 409, 425, 429])
+
 /** Registration-resolved idempotency for a route: the config with its store + defaults pinned. */
 export interface ResolvedIdempotency {
   readonly store: IdempotencyStore
   readonly ttlMs: number
+  /** The lease renewed while a handler runs; unset when the store cannot renew. */
+  readonly pendingTtlMs: number | undefined
   readonly headerName: string
   readonly namespace: NonNullable<RouteSchema["idempotency"]>["namespace"]
   readonly maxResponseBytes: number
@@ -66,6 +77,10 @@ export interface IdempotencyRuntime {
     authenticated: boolean,
     maxBodyBytes: number,
   ): ResolvedIdempotency | undefined
+  /** Wrap an idempotent route's handler so the lane can tell a request rejected before it ran. */
+  wrapHandler<C extends { readonly req: Request }>(
+    handler: (context: C) => unknown,
+  ): (context: C) => unknown
   /** The dedupe lane: read the key, fingerprint the request, consult the store, run/replay/reject. */
   run<T>(
     config: ResolvedIdempotency,
@@ -122,6 +137,12 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
     trackEffect(context, committed) {
       markEffect(context, committed)
     },
+    wrapHandler(handler) {
+      return (context) => {
+        HANDLER_ENTERED.add(context.req)
+        return handler(context)
+      }
+    },
     resolve(schema, authenticated, maxBodyBytes) {
       const config = schema?.idempotency
       if (config === undefined) return undefined
@@ -145,6 +166,16 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
           "idempotency ttlMs must be a finite positive number",
         )
       }
+      const pendingTtlMs = config.pendingTtlMs
+      if (
+        pendingTtlMs !== undefined &&
+        (store.renew === undefined || !Number.isSafeInteger(pendingTtlMs) || pendingTtlMs <= 0)
+      ) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "idempotency pendingTtlMs must be a positive integer, on a store that implements renew()",
+        )
+      }
       const headerName = (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase()
       try {
         new Headers().set(headerName, "probe")
@@ -183,6 +214,10 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
       return Object.freeze({
         store,
         ttlMs,
+        pendingTtlMs:
+          store.renew === undefined
+            ? undefined
+            : (pendingTtlMs ?? DEFAULT_IDEMPOTENCY_PENDING_TTL_MS),
         headerName,
         namespace,
         maxResponseBytes,
@@ -216,7 +251,14 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
         req.headers.get("content-type") ?? "",
       )
 
-      const begin = await config.store.begin({ namespace, key, fingerprint, ttlMs: config.ttlMs })
+      const pendingTtlMs = config.pendingTtlMs
+      const begin = await config.store.begin({
+        namespace,
+        key,
+        fingerprint,
+        ttlMs: config.ttlMs,
+        pendingTtlMs,
+      })
       if (begin.state === "replay") {
         return wrapResponse(
           responseFromStored(begin.response, { maxBytes: config.maxResponseBytes }),
@@ -230,37 +272,115 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
         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: RequestInit = {
-        method: req.method,
-        headers: req.headers,
-        signal: req.signal,
+      let heartbeat: ReturnType<typeof setInterval> | undefined
+      if (pendingTtlMs !== undefined) {
+        // Renew the lease while the handler runs: only a process that died stops renewing, so its
+        // key frees after the lease rather than the replay TTL.
+        heartbeat = setInterval(() => {
+          // A failed renewal only lets the lease lapse, which completion then reports.
+          Promise.resolve()
+            .then(() => config.store.renew?.({ namespace, key, reservation, ttlMs: pendingTtlMs }))
+            .catch(() => undefined)
+        }, pendingTtlMs / 3)
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a Node or Bun timer has unref(); on other runtimes the optional call does nothing.
+        ;(heartbeat as { unref?: () => void }).unref?.()
       }
-      if (read.bytes.byteLength > 0)
-        bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
-      const buffered = new Request(req.url, bufferedInit)
-      beginRequestEffectTracking(buffered)
-      let response: Response
       try {
-        response = await host.runLanes(buffered, platform, entry, params, search)
-      } catch (err) {
-        const evidence = requestEffectEvidence(buffered)
-        if (!evidence.began) {
-          // The request-local boundary proves no owned effect started, so this is the one safe case
-          // where releasing the key cannot duplicate an effect.
-          await config.store.abandon({ namespace, key, reservation })
-          throw err
+        // 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: RequestInit = {
+          method: req.method,
+          headers: req.headers,
+          signal: req.signal,
+        }
+        if (read.bytes.byteLength > 0)
+          bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
+        const buffered = new Request(req.url, bufferedInit)
+        beginRequestEffectTracking(buffered)
+        // The handler threw, or its response body failed while being captured: no response to store.
+        const settleThrown = async (err: unknown): Promise<ReturnType<typeof wrapResponse>> => {
+          if (!requestEffectEvidence(buffered).began) {
+            // The request-local boundary proves no owned effect started, so this is the one safe case
+            // where releasing the key cannot duplicate an effect.
+            await config.store.abandon({ namespace, key, reservation })
+            throw err
+          }
+          // A committed or ambiguous effect must never be repeated. Persist a payload-free terminal
+          // response even though the normal handler lifecycle escaped without producing one.
+          const terminal = new Response(null, { status: 500 })
+          const completed = await config.store.complete({
+            namespace,
+            key,
+            reservation,
+            response: await serializeResponse(terminal, { maxBytes: config.maxResponseBytes }),
+          })
+          if (!completed) {
+            return wrapResponse(
+              jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }),
+            )
+          }
+          return wrapResponse(terminal)
+        }
+        let response: Response
+        try {
+          response = await host.runLanes(buffered, platform, entry, params, search)
+        } catch (err) {
+          return await settleThrown(err)
+        }
+        if (!HANDLER_ENTERED.has(buffered) && !requestEffectEvidence(buffered).began) {
+          // Rejected before the handler ran: no execution began, so there is nothing a retry could
+          // duplicate and no result is saved - storing every rejection would let callers who never
+          // pass auth fill the store and lock everyone else out.
+          const abandoned = await config.store.abandon({ namespace, key, reservation })
+          if (!abandoned) {
+            return wrapResponse(
+              jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }),
+            )
+          }
+          return wrapResponse(response)
+        }
+        if (
+          (REFUSALS.has(response.status) ||
+            (response.status >= 500 && requestIsSafeToRetry(buffered))) &&
+          !requestEffectEvidence(buffered).began
+        ) {
+          const abandoned = await config.store.abandon({ namespace, key, reservation })
+          if (!abandoned) {
+            return wrapResponse(
+              jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }),
+            )
+          }
+          return wrapResponse(response)
+        }
+        // Once the handler ran, every other concrete response is terminal for this key. A non-2xx may
+        // follow an already-committed external effect; abandoning it would let a retry duplicate it.
+        let storedResponse: Awaited<ReturnType<typeof serializeResponse>>
+        try {
+          storedResponse = await serializeResponse(response, { maxBytes: config.maxResponseBytes })
+        } catch (error) {
+          if (!(error instanceof IdempotencyResponseTooLargeError)) return await settleThrown(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,
+            })
+          }
         }
-        // A committed or ambiguous effect must never be repeated. Persist a payload-free terminal
-        // response even though the normal handler lifecycle escaped without producing one.
-        response = new Response(null, { status: 500 })
         const completed = await config.store.complete({
           namespace,
           key,
           reservation,
-          response: await serializeResponse(response, { maxBytes: config.maxResponseBytes }),
+          response: storedResponse,
         })
         if (!completed) {
           return wrapResponse(
@@ -268,54 +388,9 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
           )
         }
         return wrapResponse(response)
+      } finally {
+        clearInterval(heartbeat)
       }
-      if (
-        response.status >= 500 &&
-        requestIsSafeToRetry(buffered) &&
-        !requestEffectEvidence(buffered).began
-      ) {
-        const abandoned = await config.store.abandon({ namespace, key, reservation })
-        if (!abandoned) {
-          return wrapResponse(
-            jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }),
-          )
-        }
-        return wrapResponse(response)
-      }
-      // Once the handler ran, every concrete response is terminal for this key. A non-2xx may follow
-      // an already-committed external effect; abandoning it would let a retry duplicate that effect.
-      let storedResponse: Awaited<ReturnType<typeof serializeResponse>>
-      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" }))
-      }
-      return wrapResponse(response)
     },
   }
 }

package/src/server/install.ts

@@ -25,9 +25,15 @@ export const INSTALL_SSE: unique symbol = Symbol.for("@nifrajs/core/install-sse"
 /** @internal Install the Node-direct renderer on a server (called by the `nodeDirect()` plugin). */
 export const INSTALL_NODE_DIRECT: unique symbol = Symbol.for("@nifrajs/core/install-node-direct")
 
+/** @internal Install the not-found lane on a server (called by the `notFound()` plugin). */
+export const INSTALL_NOT_FOUND: unique symbol = Symbol.for("@nifrajs/core/install-not-found")
+
 /** @internal Install the WebSocket runtime on a server (called by the `websocket()` plugin). */
 export const INSTALL_WS: unique symbol = Symbol.for("@nifrajs/core/install-ws")
 
+/** @internal Read the installed WebSocket runtime when a server is composed into another server. */
+export const GET_WS_RUNTIME: unique symbol = Symbol.for("@nifrajs/core/get-ws-runtime")
+
 /** @internal Install the response-contract runtime on a server (called by the `responseContract()` plugin). */
 export const INSTALL_RESPONSE_CONTRACT: unique symbol = Symbol.for(
   "@nifrajs/core/install-response-contract",

package/src/server/methods.ts

@@ -0,0 +1,143 @@
+/**
+ * `all()` and `method()`. A method with no route on a path is still a `405`, and a runtime's HTTP
+ * parser may refuse a token it does not know before the server sees the request.
+ */
+import { RouteConfigError } from "../errors.ts"
+import { isRegistrableMethod, METHODS, type Method } from "../router/router.ts"
+import type { RouteSchema } from "./context.ts"
+import type { MethodRoutesPlugin } from "./plugin.ts"
+import type { OutputOf } from "./registry.ts"
+import type { Handler } from "./server.ts"
+
+export type { MethodRoutesPlugin } from "./plugin.ts"
+
+/** The part of a server these plugins use: one atomic batch registration. */
+interface RouteHost {
+  registerBatch(
+    routes: readonly {
+      readonly method: string
+      readonly path: string
+      readonly schema: RouteSchema | undefined
+      readonly handler: (context: never) => unknown
+    }[],
+  ): void
+}
+
+type ErasedHandler = (context: never) => unknown
+
+const ASCII_NAME = /^[A-Za-z0-9-]+$/
+
+function plugin(
+  methods: readonly string[],
+  path: string,
+  schemaOrHandler: RouteSchema | ErasedHandler,
+  handler: ErasedHandler | undefined,
+): (app: RouteHost) => RouteHost {
+  const schema = handler === undefined ? undefined : (schemaOrHandler as RouteSchema)
+  const run = handler ?? schemaOrHandler
+  if (typeof run !== "function") throw new TypeError("a route needs a handler function")
+  const routes = methods.map((method) => ({ method, path, schema, handler: run }))
+  return (app) => {
+    app.registerBatch(routes)
+    return app
+  }
+}
+
+/**
+ * Register one handler under every standard method: `app.use(all(path, handler))`.
+ *
+ * ```ts
+ * import { all } from "@nifrajs/core/methods"
+ *
+ * const app = server().use(all("/echo", (c) => ({ method: c.req.method })))
+ * ```
+ *
+ * It is the same as calling `get`, `post`, `put`, `patch`, `delete`, `head` and `options` with the
+ * one handler, as a single registration: a method already registered on the path makes the call
+ * throw and adds nothing. A schema applies to every method, so with a `body` schema a request that
+ * carries no body is refused under any of them, `GET` included.
+ */
+export function all<
+  Path extends string,
+  S extends RouteSchema,
+  H extends Handler<Path, S, Ctx>,
+  Ctx = NonNullable<unknown>,
+>(path: Path, schema: S, handler: H): MethodRoutesPlugin<Method, Path, S, OutputOf<H>, Ctx>
+export function all<
+  Path extends string,
+  H extends Handler<Path, RouteSchema, Ctx>,
+  Ctx = NonNullable<unknown>,
+>(path: Path, handler: H): MethodRoutesPlugin<Method, Path, Record<never, never>, OutputOf<H>, Ctx>
+export function all(
+  path: string,
+  schemaOrHandler: RouteSchema | ErasedHandler,
+  handler?: ErasedHandler,
+): unknown {
+  return plugin(METHODS, path, schemaOrHandler, handler)
+}
+
+/**
+ * Register one handler under the method, or the methods, you name:
+ * `app.use(method("PROPFIND", path, handler))`.
+ *
+ * ```ts
+ * import { method } from "@nifrajs/core/methods"
+ *
+ * const app = server()
+ *   .use(method("PROPFIND", "/dav/*path", (c) => listing(c.params.path)))
+ *   .use(method(["GET", "POST"], "/search", (c) => search(c.req)))
+ * ```
+ *
+ * A name is case-insensitive and is registered uppercase. It must be a token of letters, digits and
+ * hyphens that starts with a letter, at most 32 characters, and not `TRACE`, `CONNECT` or `TRACK`;
+ * anything else throws when `method()` is called. A list is one registration: every method is added,
+ * or none is.
+ *
+ * Only the standard methods among the names join the app's typed registry, so the typed client has
+ * a call for those and none for a custom token.
+ */
+export function method<
+  const M extends string,
+  Path extends string,
+  S extends RouteSchema,
+  H extends Handler<Path, S, Ctx>,
+  Ctx = NonNullable<unknown>,
+>(
+  name: M | readonly M[],
+  path: Path,
+  schema: S,
+  handler: H,
+): MethodRoutesPlugin<M, Path, S, OutputOf<H>, Ctx>
+export function method<
+  const M extends string,
+  Path extends string,
+  H extends Handler<Path, RouteSchema, Ctx>,
+  Ctx = NonNullable<unknown>,
+>(
+  name: M | readonly M[],
+  path: Path,
+  handler: H,
+): MethodRoutesPlugin<M, Path, Record<never, never>, OutputOf<H>, Ctx>
+export function method(
+  name: string | readonly string[],
+  path: string,
+  schemaOrHandler: RouteSchema | ErasedHandler,
+  handler?: ErasedHandler,
+): unknown {
+  const names = typeof name === "string" ? [name] : name
+  if (!Array.isArray(names) || names.length === 0) {
+    throw new RouteConfigError("INVALID_METHOD", "method() needs a method name or a list of them")
+  }
+  const methods = names.map((value: unknown) => {
+    // Checked before the case fold: a letter outside ASCII can fold to an ASCII one.
+    const upper = typeof value === "string" && ASCII_NAME.test(value) ? value.toUpperCase() : ""
+    if (!isRegistrableMethod(upper)) {
+      throw new RouteConfigError(
+        "INVALID_METHOD",
+        `unsupported HTTP method ${JSON.stringify(value)}`,
+      )
+    }
+    return upper
+  })
+  return plugin(methods, path, schemaOrHandler, handler)
+}