@nifrajs/core 3.5.0 → 4.0.0

package/src/server/context.ts

@@ -15,6 +15,12 @@ export interface IdempotencyConfig {
   readonly scope: IdempotencyScope
   /** Retention for the stored response. Default 24h. */
   readonly ttlMs?: number
+  /**
+   * How long a key whose handler is still running stays reserved without a renewal. The server
+   * renews it every third of this while the handler runs, so only a dead process lets it lapse and a
+   * retry waits this long rather than `ttlMs`. Needs a store with `renew()`; default 60s with one.
+   */
+  readonly pendingTtlMs?: number
   /** Store override. Defaults to the server's shared in-memory store; inject a durable store here. */
   readonly store?: IdempotencyStore
   /** Header carrying the key. Default `idempotency-key`. */
@@ -42,26 +48,213 @@ export interface IdempotencyConfig {
 /** Flattens an intersection into a single object type for readable hovers. */
 export type Prettify<T> = { [K in keyof T]: T[K] } & {}
 
+type ParamNameStart =
+  | "a"
+  | "b"
+  | "c"
+  | "d"
+  | "e"
+  | "f"
+  | "g"
+  | "h"
+  | "i"
+  | "j"
+  | "k"
+  | "l"
+  | "m"
+  | "n"
+  | "o"
+  | "p"
+  | "q"
+  | "r"
+  | "s"
+  | "t"
+  | "u"
+  | "v"
+  | "w"
+  | "x"
+  | "y"
+  | "z"
+  | "A"
+  | "B"
+  | "C"
+  | "D"
+  | "E"
+  | "F"
+  | "G"
+  | "H"
+  | "I"
+  | "J"
+  | "K"
+  | "L"
+  | "M"
+  | "N"
+  | "O"
+  | "P"
+  | "Q"
+  | "R"
+  | "S"
+  | "T"
+  | "U"
+  | "V"
+  | "W"
+  | "X"
+  | "Y"
+  | "Z"
+  | "_"
+type ParamNameChar = ParamNameStart | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
+
+/** The longest parameter name at the start of `Text`, and the text after it. */
+type TakeParamName<
+  Text extends string,
+  Name extends string = "",
+> = Text extends `${infer Char}${infer Rest}`
+  ? Char extends (Name extends "" ? ParamNameStart : ParamNameChar)
+    ? TakeParamName<Rest, `${Name}${Char}`>
+    : [Name, Text]
+  : [Name, ""]
+
+/**
+ * Whether a colon is literal text: one with no name after it, or one that follows a name character
+ * and whose name runs to the end of the segment (`/things:batchGet`).
+ */
+type IsLiteralColon<
+  Before extends string,
+  Name extends string,
+  Rest extends string,
+> = Name extends ""
+  ? true
+  : Before extends `${string}${ParamNameChar}`
+    ? Rest extends "" | `/${string}`
+      ? true
+      : false
+    : false
+
 /**
  * Extracts `:param` and trailing `*wildcard` names from a route-path literal into
  * a string→string record: `/users/:id/posts/:postId` → `{ id: string; postId:
  * string }`, `/files/*path` → `{ path: string }`, `/files/*` → `{ "*": string }`.
+ * A name ends where the router ends it, at the first character that cannot be part of one, so
+ * `/files/:name.json` → `{ name: string }` and `/v:major.:minor` → `{ major: string; minor: string }`.
+ * A constraint does not change the type: `/users/:id{[0-9]+}` → `{ id: string }`.
  * A non-literal `string` path widens to `Record<string, string>`.
  */
 type RawParams<Path extends string> = string extends Path
   ? Record<string, string>
-  : Path extends `${infer _Start}:${infer Param}/${infer Rest}`
-    ? Record<Param, string> & RawParams<`/${Rest}`>
-    : Path extends `${infer _Start}:${infer Param}`
-      ? Record<Param, string>
-      : Path extends `${infer _Start}*${infer Wild}`
-        ? Record<Wild extends "" ? "*" : Wild, string>
-        : Record<never, string>
+  : Path extends `${infer Before}:${infer After}`
+    ? TakeParamName<After> extends [infer Name extends string, infer Rest extends string]
+      ? IsLiteralColon<Before, Name, Rest> extends true
+        ? RawParams<Rest>
+        : Record<Name, string> & RawParams<Rest>
+      : never
+    : Path extends `${infer _Start}*${infer Wild}`
+      ? Record<Wild extends "" ? "*" : Wild, string>
+      : Record<never, string>
+
+/** `[constraint, rest]` for a leading `{...}`, else `["", Text]`. One nested level, for `{[0-9]{2}}`. */
+type TakeConstraint<Text extends string> = Text extends `{${infer Inner}}${infer Rest}`
+  ? Inner extends `[${string}` | `\\${string}` | `${string}|${string}`
+    ? Inner extends `${string}{${string}`
+      ? Rest extends `}${infer After}`
+        ? [`{${Inner}}}`, After]
+        : ["", Text]
+      : [`{${Inner}}`, Rest]
+    : ["", Text]
+  : ["", Text]
+
+/**
+ * Whether `Run` is nothing but whole-segment optional parameters, each with or without a constraint:
+ * `/:a?`, `/:a?/:b?`, `/:id{[0-9]+}?`.
+ */
+type IsOptionalRun<Run extends string> = Run extends ""
+  ? true
+  : Run extends `/:${infer After}`
+    ? TakeParamName<After> extends [infer Name extends string, infer Tail extends string]
+      ? TakeConstraint<Tail> extends [string, `?${infer Rest}`]
+        ? Name extends ""
+          ? false
+          : IsOptionalRun<Rest>
+        : false
+      : false
+    : false
+
+/** `[head, run]` for a path ending in `:name?` segments, else `false`; the same cut the router makes. */
+type SplitOptionalRun<
+  Path extends string,
+  Head extends string = "",
+> = Path extends `${infer Before}/:${infer After}`
+  ? IsOptionalRun<`/:${After}`> extends true
+    ? [`${Head}${Before}`, `/:${After}`]
+    : SplitOptionalRun<After, `${Head}${Before}/:`>
+  : false
+
+/** `Head`, then `Head` with each longer prefix of `Run` appended - the `?` marks dropped. */
+type OptionalForms<Head extends string, Run extends string, Done extends string = ""> =
+  | (`${Head}${Done}` extends "" ? "/" : `${Head}${Done}`)
+  | (Run extends `/:${infer After}`
+      ? TakeParamName<After> extends [infer Name extends string, infer Tail extends string]
+        ? TakeConstraint<Tail> extends [infer Constraint extends string, `?${infer Rest}`]
+          ? OptionalForms<Head, Rest, `${Done}/:${Name}${Constraint}`>
+          : never
+        : never
+      : never)
 
-export type Params<Path extends string> = Prettify<RawParams<Path>>
+/** The registry keys of a route path: `/users/:id?` is `"/users" | "/users/:id"`, others are themselves. */
+export type RoutePaths<Path extends string> = Path extends `${string}?`
+  ? SplitOptionalRun<Path> extends [infer Head extends string, infer Run extends string]
+    ? OptionalForms<Head, Run>
+    : Path
+  : Path
+
+/** One concrete path's request text: each parameter replaced by `${string}`, literal text kept. */
+type PathText<Path extends string> = Path extends `${infer Before}:${infer After}`
+  ? TakeParamName<After> extends [infer Name extends string, infer Rest extends string]
+    ? IsLiteralColon<Before, Name, Rest> extends true
+      ? `${Before}:${Name}${PathText<Rest>}`
+      : TakeConstraint<Rest> extends [string, infer Tail extends string]
+        ? `${Before}${string}${PathText<Tail>}`
+        : never
+    : never
+  : Path extends `${infer Start}/*${string}`
+    ? `${Start}/${string}`
+    : Path
+
+/**
+ * The text of a request a route path serves, as a template: `/users/:id` → `` `/users/${string}` ``,
+ * `/files/:name.json` → `` `/files/${string}.json` ``, `/files/*path` → `` `/files/${string}` ``.
+ * Literal text is kept, so a value has to carry it. A constraint is not checked - `/users/:id{[0-9]+}`
+ * is `` `/users/${string}` `` - and a path ending in optional parameters is one template per form:
+ * `/users/:id?` → `` "/users" | `/users/${string}` ``. A non-literal `string` path stays `string`.
+ */
+export type RequestPath<Path extends string> = string extends Path
+  ? string
+  : RoutePaths<Path> extends infer Form extends string
+    ? Form extends unknown
+      ? PathText<Form>
+      : never
+    : never
+
+/**
+ * The params a handler for `Path` reads. A parameter in a trailing optional run is optional, since
+ * the one handler serves the path with and without it: `/users/:id?` → `{ id?: string }`.
+ */
+export type Params<Path extends string> = Path extends `${string}?`
+  ? SplitOptionalRun<Path> extends [infer Head extends string, infer Run extends string]
+    ? Prettify<RawParams<Head> & Partial<RawParams<Run>>>
+    : Prettify<RawParams<Path>>
+  : Prettify<RawParams<Path>>
 
 /** Per-route input schemas. Each is any Standard Schema (zod/valibot/arktype/…). */
 export interface RouteSchema {
+  /** Explicit external-protocol mode. The handler owns raw `c.req` parsing/streaming; no JSON body
+   * parser or schema-driven 422 path is installed. A finite transport cap still applies by default. */
+  readonly wire?: "raw"
+  /**
+   * Choose trust-boundary order for sensitive routes. Public routes validate first by default;
+   * routes with `authenticate()` default to auth first. `validate-before-auth` is an explicit
+   * compatibility escape hatch, while `auth-before-validation` can reject without parsing the body.
+   */
+  readonly validationOrder?: "validate-before-auth" | "auth-before-validation"
   /** Transport body cap for this route. Defaults to the server's maxBodyBytes. Use a finite
    * smaller/larger limit for a specific endpoint. The 'unlimited' value is an explicit
    * streaming/upload exemption and requires a non-empty bodyLimitReason for auditability.
@@ -122,6 +315,12 @@ export interface RouteSchema {
    * output is exposed as `c.headers`; use lower-case keys because HTTP header names are
    * case-insensitive. */
   readonly headers?: StandardSchemaV1
+  /** Optional request-cookie schema. It validates the cookies parsed from the `Cookie` header -
+   * names as sent, values URL-decoded strings, the first of a repeated name - before the handler
+   * runs, and the validated output is `c.cookies`. A failure is a `422`, like `headers`. A browser
+   * sends every cookie the site has set, so declare the ones the route reads with an open schema
+   * (`t.cookies`, `t.looseObject`) rather than rejecting the rest. */
+  readonly cookies?: StandardSchemaV1
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   /** Optional **response contract**. When declared: the handler's return is type-checked against it
@@ -146,7 +345,7 @@ export interface RouteSchema {
    */
   readonly sse?: StandardSchemaV1
   /**
-   * Hook fired when the request fails `headers`/`params`/`body`/`query` validation, before the handler
+   * Hook fired when the request fails `headers`/`cookies`/`params`/`body`/`query` validation, before the handler
    * runs. `kind` says which input failed. Its return value selects one of three outcomes (may be async):
    *   - a **`Response`** → returned as-is, short-circuiting the route (custom error envelope, redirect, …).
    *   - **any other value** → treated as a repaired payload and **re-validated once** against the same
@@ -161,7 +360,7 @@ export interface RouteSchema {
   readonly onValidationError?: (
     issues: ReadonlyArray<StandardIssue>,
     ctx: Context,
-    kind: "body" | "query" | "params" | "headers",
+    kind: "body" | "query" | "params" | "headers" | "cookies",
   ) => Response | unknown | Promise<Response | unknown>
 }
 
@@ -182,6 +381,13 @@ type HeadersOf<S extends RouteSchema> = S extends {
   ? InferOutput<H>
   : Readonly<Record<string, string>>
 
+/** The validated cookie type when a cookie schema is declared, else the parsed name → value record. */
+type CookiesOf<S extends RouteSchema> = S extends {
+  cookies: infer C extends StandardSchemaV1
+}
+  ? InferOutput<C>
+  : Readonly<Record<string, string>>
+
 /** The validated params type when a params schema is declared, else the path-inferred `Params<Path>`. */
 type ParamsOf<S extends RouteSchema, Path extends string> = S extends {
   params: infer P extends StandardSchemaV1
@@ -244,8 +450,9 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
   readonly query: QueryOf<S>
   readonly body: BodyOf<S>
   /** The request's cookies, parsed from the `Cookie` header (values URL-decoded). Parsed lazily on
-   * first access + cached. Signed cookies arrive as `value.signature` - verify with `unsignValue`. */
-  readonly cookies: Readonly<Record<string, string>>
+   * first access + cached; validated/coerced when `schema.cookies` is declared. Signed cookies arrive
+   * as `value.signature` - verify with `unsignValue`. */
+  readonly cookies: CookiesOf<S>
   readonly set: ResponseControls
   /**
    * Aborts when the server's `requestTimeoutMs` elapses (and never, when no timeout

package/src/server/contract.ts

@@ -1,10 +1,11 @@
 import type { DataClassification } from "../classification.ts"
 import { RouteConfigError } from "../errors.ts"
 import { normalizeRouteCapabilities } from "../internal/capability-runtime.ts"
+import { expandOptionalParams } from "../router/pattern.ts"
 import { METHODS, type Method } from "../router/router.ts"
 import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import { assertByteLimit } from "./body.ts"
-import type { Context, IdempotencyConfig, Params, RouteSchema } from "./context.ts"
+import type { Context, IdempotencyConfig, Params, RoutePaths, RouteSchema } from "./context.ts"
 import type { EmptyRegistry, OutputOf, Registry, RouteInfoFor } from "./registry.ts"
 import { Server } from "./server.ts"
 
@@ -33,7 +34,13 @@ export interface OperationDef {
   readonly params?: StandardSchemaV1
   /** Optional request-header schema (header names are normalized to lower-case). */
   readonly headers?: StandardSchemaV1
+  /** Optional request-cookie schema (see {@link RouteSchema.cookies}). */
+  readonly cookies?: StandardSchemaV1
   readonly body?: StandardSchemaV1
+  /** Explicit external-protocol mode; raw bytes/text are read by the handler from `c.req`. */
+  readonly wire?: "raw"
+  /** Run derive/beforeHandle authentication before body/query validation on sensitive routes. */
+  readonly validationOrder?: "validate-before-auth" | "auth-before-validation"
   readonly query?: StandardSchemaV1
   readonly response?: StandardSchemaV1
   /** Declared effect tokens, carried into route reflection and capability assurance. */
@@ -153,8 +160,10 @@ type RouteInfoForOp<O extends OperationDef> = {
 
 /** Re-key the name-keyed ops into the `path → method → RouteInfo` registry. */
 export type RegistryFor<C extends ContractShape> = {
-  [P in C[keyof C]["path"]]: {
-    [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: RouteInfoForOp<C[K]>
+  [P in RoutePaths<C[keyof C]["path"]>]: {
+    [K in keyof C as P extends RoutePaths<C[K]["path"]> ? C[K]["method"] : never]: RouteInfoForOp<
+      C[K]
+    >
   }
 }
 
@@ -166,6 +175,9 @@ type SchemaForOp<O extends OperationDef> = (O extends { body: infer B extends St
   (O extends { headers: infer H extends StandardSchemaV1 }
     ? { headers: H }
     : Record<never, never>) &
+  (O extends { cookies: infer K extends StandardSchemaV1 }
+    ? { cookies: K }
+    : Record<never, never>) &
   (O extends { params: infer P extends StandardSchemaV1 } ? { params: P } : Record<never, never>)
 
 type OpResponseSchemas<O extends OperationDef> = O extends {
@@ -267,12 +279,37 @@ export function defineContract<const C extends ContractShape>(contract: C): C {
         )
       }
     }
-    const key = `${method} ${op.path}`
-    if (seen.has(key)) {
-      throw new RouteConfigError("DUPLICATE_ROUTE", `duplicate operation route: ${key}`)
+    if (op.wire !== undefined && op.wire !== "raw") {
+      throw new RouteConfigError(
+        "INVALID_WIRE",
+        `operation "${name}": wire must be "raw" when specified`,
+      )
+    }
+    if (op.wire === "raw" && op.body !== undefined) {
+      throw new RouteConfigError(
+        "INVALID_WIRE",
+        `operation "${name}": wire: "raw" cannot be combined with a body schema`,
+      )
+    }
+    if (
+      op.validationOrder !== undefined &&
+      op.validationOrder !== "validate-before-auth" &&
+      op.validationOrder !== "auth-before-validation"
+    ) {
+      throw new RouteConfigError(
+        "INVALID_VALIDATION_ORDER",
+        `operation "${name}": validationOrder is invalid`,
+      )
+    }
+    // Compared per concrete path, so `/users` collides with the short form of `/users/:id?`.
+    for (const path of expandOptionalParams(op.path)) {
+      const key = `${method} ${path}`
+      if (seen.has(key)) {
+        throw new RouteConfigError("DUPLICATE_ROUTE", `duplicate operation route: ${key}`)
+      }
+      seen.add(key)
     }
     normalizeRouteCapabilities(op.capabilities)
-    seen.add(key)
   }
   return contract
 }
@@ -291,8 +328,10 @@ export type RegistryFromImpl<
   Ctx = NonNullable<unknown>,
   HookOutput = never,
 > = {
-  [P in C[keyof C]["path"]]: {
-    [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: H[K] extends AnyFn
+  [P in RoutePaths<C[keyof C]["path"]>]: {
+    [K in keyof C as P extends RoutePaths<C[K]["path"]>
+      ? C[K]["method"]
+      : never]: H[K] extends AnyFn
       ? RouteInfoFor<C[K]["path"], RouteSchemaForOp<C[K]>, OutputOf<H[K]>, HookOutput>
       : RouteInfoFor<C[K]["path"], RouteSchemaForOp<C[K]>, unknown, HookOutput>
   }
@@ -349,7 +388,10 @@ export function implement<
     const schema: RouteSchema | undefined =
       op.params !== undefined ||
       op.headers !== undefined ||
+      op.cookies !== undefined ||
       op.body !== undefined ||
+      op.wire !== undefined ||
+      op.validationOrder !== undefined ||
       op.query !== undefined ||
       op.response !== undefined ||
       (errors !== undefined && Object.keys(errors).length > 0) ||
@@ -362,7 +404,10 @@ export function implement<
         ? {
             ...(op.params !== undefined ? { params: op.params } : {}),
             ...(op.headers !== undefined ? { headers: op.headers } : {}),
+            ...(op.cookies !== undefined ? { cookies: op.cookies } : {}),
             ...(op.body !== undefined ? { body: op.body } : {}),
+            ...(op.wire !== undefined ? { wire: op.wire } : {}),
+            ...(op.validationOrder !== undefined ? { validationOrder: op.validationOrder } : {}),
             ...(op.query !== undefined ? { query: op.query } : {}),
             ...(op.response !== undefined ? { response: op.response } : {}),
             ...(errors !== undefined && Object.keys(errors).length > 0 ? { errors } : {}),

package/src/server/core-copies.ts

@@ -0,0 +1,21 @@
+/**
+ * Two physical copies of `@nifrajs/core` in one process (a linked sibling checkout, a nested install)
+ * split every piece of module-scoped identity: a route from one copy's `server()` merged into the
+ * other answers 500 from an internal TypeError as soon as it sets a cookie. The install is the
+ * defect, so it is named the moment the second copy loads, not at the first failing request.
+ * `nifra check` is the gate that fails the build on it; this is the runtime notice.
+ *
+ * Each copy records its module URL in a process-wide list. The query is dropped, so a dev server that
+ * re-evaluates this same file (HMR, `--hot`) is one copy, not two.
+ */
+const registry = globalThis as unknown as Record<symbol, string[] | undefined>
+const COPIES = Symbol.for("nifra.core.copies")
+registry[COPIES] ??= []
+const copies = registry[COPIES]
+const here = String(import.meta.url).split("?")[0] as string
+
+if (!copies.includes(here) && copies.push(here) > 1) {
+  console.warn(
+    `[nifra] @nifrajs/core is loaded ${copies.length} times; \`nifra check\` names each importer:\n  ${copies.join("\n  ")}`,
+  )
+}

package/src/server/edge.ts

@@ -140,6 +140,8 @@ export function toFetchHandler<Env = unknown>(
           outcome.attach(server, outcome.handler, outcome.data, {
             openNow: true,
             pubsub: outcome.pubsub,
+            // `wsMaxPayloadBytes`, as the Bun, Node, Deno and hub lanes enforce it.
+            maxPayloadBytes: outcome.maxPayloadBytes,
           })
           // `webSocket` is a Workers-only `ResponseInit` field (absent from the standard type), and a
           // 101 status is only valid on the Workers runtime - both gated by the `Pair` feature check.

package/src/server/http.ts

@@ -33,6 +33,40 @@ export function isSameOriginPath(value: string): boolean {
   return true
 }
 
+/**
+ * Whether `method` is a token a route can be registered under: uppercase ASCII letters, digits and
+ * hyphens, a letter first, 1 to 32 characters. That covers every method in the IANA registry.
+ *
+ * Every registered method has this shape and the router compares tokens exactly, so a request whose
+ * token does not have it can never reach a handler. The server uses this to keep such a request away
+ * from everything that runs around routing as well - `onRequest` hooks and mounted handlers - because
+ * those see the raw token, and code that tests `req.method === "POST"` would otherwise read a
+ * differently-cased token as a method it does not guard.
+ */
+export function isRoutableMethod(method: string): boolean {
+  // The common verbs first: a string switch settles them without walking the token, which keeps the
+  // check close to free on the lanes that run it per request.
+  switch (method) {
+    case "GET":
+    case "POST":
+    case "PUT":
+    case "PATCH":
+    case "DELETE":
+    case "HEAD":
+    case "OPTIONS":
+      return true
+  }
+  const length = method.length
+  if (length === 0 || length > 32) return false
+  for (let i = 0; i < length; i++) {
+    const code = method.charCodeAt(i)
+    if (code >= 65 && code <= 90) continue
+    if (i > 0 && (code === 45 || (code >= 48 && code <= 57))) continue
+    return false
+  }
+  return true
+}
+
 /** A uniform JSON error envelope: `{ ok: false, error }` at the given status. */
 export function jsonError(
   status: number,