@nifrajs/core 1.12.0 → 2.0.0

package/src/server/mcp-hook.ts

@@ -0,0 +1,41 @@
+import type { StandardSchemaV1 } from "../schema/standard.ts"
+import type { Context, RouteSchema } from "./context.ts"
+import type {
+  McpPromptDescriptor,
+  McpResourceDescriptor,
+  PromptArgument,
+  RouteDescriptor,
+  ToolAnnotations,
+} from "./server-types.ts"
+
+export interface McpToolConfig {
+  readonly description: string
+  readonly input: StandardSchemaV1
+  readonly output?: StandardSchemaV1
+  readonly annotations?: ToolAnnotations
+}
+
+export interface McpToolPlan {
+  readonly path: string
+  readonly schema: RouteSchema
+  readonly run: (context: Context) => unknown
+  readonly descriptor: NonNullable<RouteDescriptor["tool"]>
+}
+
+export interface McpRuntime {
+  tool(
+    name: string,
+    config: McpToolConfig,
+    handler: (input: unknown, context: Context) => unknown,
+  ): McpToolPlan
+  resource(
+    uri: string,
+    config: { readonly name: string; readonly description?: string; readonly mimeType?: string },
+    read: McpResourceDescriptor["read"],
+  ): McpResourceDescriptor
+  prompt(
+    name: string,
+    config: { readonly description: string; readonly arguments?: readonly PromptArgument[] },
+    handler: McpPromptDescriptor["handler"],
+  ): McpPromptDescriptor
+}

package/src/server/node-outcome-hook.ts

@@ -0,0 +1,9 @@
+/** Lazy Node-direct renderer seam. The base server retains the typed method but not its renderer. */
+import type { NodeServeOutcome } from "./node-outcome.ts"
+import type { CtxSet } from "./server.ts"
+
+export interface NodeOutcomeRuntime {
+  toOutcome(result: unknown, set: CtxSet): NodeServeOutcome
+  fromResponse(response: Response): NodeServeOutcome
+  timeout(): NodeServeOutcome
+}

package/src/server/node-outcome.ts

@@ -0,0 +1,112 @@
+/**
+ * Node-direct outcome shaping: the `@nifrajs/node` bridge's render form and the `Response` -> outcome
+ * conversion. Mirrors `respond.ts` but skips the undici `Response` build where the adapter can write a
+ * plain-data render straight to the socket. Imports only runtime-core + respond + the spine types.
+ */
+import { appendCookiesToResponse } from "./respond.ts"
+import { type HandlerResult, isResponseResult } from "./runtime-core.ts"
+import type { CtxSet } from "./server.ts"
+
+/**
+ * What {@link Server.resolveNode} returns: either a plain-data render the `@nifrajs/node` adapter writes
+ * to the socket directly (`kind: "json"` - status + headers + cookies + a pre-stringified body, **no**
+ * undici `Response` built or drained), a marked buffered response body (`kind: "body"` - e.g.
+ * @nifrajs/web's non-deferred SSR HTML), or a `Response` (`kind: "response"`) for everything else
+ * (redirects, 404/405/errors, unmarked or streaming bodies). Internal to the nifra<->node bridge.
+ */
+export type NodeServeOutcome =
+  | { readonly kind: "response"; readonly response: Response }
+  | {
+      readonly kind: "json"
+      readonly status: number
+      /** `c.set.headers` backing, or `undefined` when the handler never set a header. */
+      readonly headers: Readonly<Record<string, string>> | undefined
+      /** Queued `Set-Cookie` lines, or `undefined`; the adapter emits one header line each. */
+      readonly cookies: readonly string[] | undefined
+      /** The JSON body already stringified, or `null` for an empty (204) response. */
+      readonly body: string | null
+    }
+  | {
+      readonly kind: "body"
+      readonly status: number
+      readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined
+      readonly body: string | Uint8Array
+    }
+
+/**
+ * `finalize` for the node-direct path - mirror of `toResponse` that skips the `Response` build:
+ * a plain value becomes pre-stringified JSON primitives (the adapter `JSON.stringify`s once, here, not
+ * via `Response.json` + a body drain); a handler-returned `Response` is wrapped as-is, with queued
+ * cookies appended exactly as `toResponse` does (so the set-cookie-then-`redirect()` pattern still
+ * works on Node).
+ */
+export function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutcome {
+  if (isResponseResult(result)) {
+    const body = result.toNodeBody?.()
+    if (body !== undefined) {
+      return {
+        kind: "body",
+        status: body.status,
+        headers: appendCookiesToNodeHeaders(body.headers, set._cookies),
+        body: body.body,
+      }
+    }
+    return nodeOutcomeFromResponse(appendCookiesToResponse(result.toResponse(), set))
+  }
+  if (result instanceof Response) {
+    return nodeOutcomeFromResponse(appendCookiesToResponse(result, set))
+  }
+  const status = set.status ?? (result === undefined ? 204 : 200)
+  return {
+    kind: "json",
+    status,
+    headers: set._headers,
+    cookies: set._cookies,
+    body: result === undefined ? null : JSON.stringify(result),
+  }
+}
+
+const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body")
+
+export function nodeOutcomeFromResponse(response: Response): NodeServeOutcome {
+  const body = nodeResponseBody(response)
+  return body === undefined
+    ? { kind: "response", response }
+    : { kind: "body", status: response.status, headers: responseHeadersForNode(response), body }
+}
+
+function nodeResponseBody(response: Response): string | Uint8Array | undefined {
+  if (response.bodyUsed) return undefined
+  const body = (response as { readonly [NODE_RESPONSE_BODY]?: unknown })[NODE_RESPONSE_BODY]
+  return typeof body === "string" || body instanceof Uint8Array ? body : undefined
+}
+
+function responseHeadersForNode(
+  response: Response,
+): Readonly<Record<string, string | readonly string[]>> | undefined {
+  let headers: Record<string, string | readonly string[]> | undefined
+  response.headers.forEach((value, key) => {
+    headers ??= {}
+    headers[key] = value
+  })
+  const setCookies = response.headers.getSetCookie?.()
+  if (setCookies !== undefined && setCookies.length > 0) {
+    headers ??= {}
+    headers["set-cookie"] = setCookies
+  }
+  return headers
+}
+
+function appendCookiesToNodeHeaders(
+  headers: Readonly<Record<string, string | readonly string[]>> | undefined,
+  cookies: readonly string[] | undefined,
+): Readonly<Record<string, string | readonly string[]>> | undefined {
+  if (cookies === undefined || cookies.length === 0) return headers
+  const out: Record<string, string | readonly string[]> =
+    headers === undefined ? {} : { ...headers }
+  const existing = out["set-cookie"]
+  const setCookies =
+    existing === undefined ? [] : typeof existing === "string" ? [existing] : [...existing]
+  out["set-cookie"] = [...setCookies, ...cookies]
+  return out
+}

package/src/server/plugin.ts

@@ -0,0 +1,92 @@
+/**
+ * Plugin definers and their types. A plugin is a function that augments an app (calling
+ * `use`/`derive`/`decorate` and/or registering routes) and returns it; these helpers attach a name
+ * for idempotent dedupe and pin the type-threading so `.use()` preserves the caller's typed server.
+ */
+import type { AnyServer } from "./server.ts"
+
+/**
+ * A nifra **plugin**: a function that augments an app - calling `use`/`derive`/`decorate` and/or
+ * registering routes - and returns it. Because `derive`/`decorate` are type-threaded, an **inline**
+ * `app.use((a) => a.derive(...).decorate(...))` carries the added context to handlers defined after
+ * it (the `use` overload is generic over the concrete `this`). Wrap with {@link definePlugin} to
+ * attach a name for idempotent dedupe (applying the same named plugin twice - e.g. transitively - is
+ * a no-op).
+ */
+export type NifraPlugin<In extends AnyServer = AnyServer, Out extends AnyServer = In> = ((
+  app: In,
+) => Out) & { readonly pluginName?: string }
+
+/**
+ * A named type-identity plugin built with {@link defineIdentityPlugin}. It returns the same concrete
+ * server type it receives, preserving the caller's typed registry and context across `.use()` while
+ * still allowing the plugin to register runtime hooks or handlers.
+ */
+export type IdentityPlugin = (<S extends AnyServer>(app: S) => S) & {
+  readonly pluginName?: string
+}
+
+/**
+ * Name + ergonomics for a plugin that **adds typed context** (`derive`/`decorate`). `app.use(myPlugin)`
+ * applies it once; a second `use` of the same name is skipped (idempotent), so plugins can depend on each
+ * other without double-registering hooks.
+ *
+ * ```ts
+ * export const requestId = definePlugin("requestId", (app) => app.derive(() => ({ requestId: uuid() })))
+ * app.use(requestId)   // downstream handlers see c.requestId
+ * ```
+ *
+ * FOOTGUN: only use this for a plugin that adds context. For a plugin that **mounts routes/hooks but adds
+ * NO context** (an auth router, an audit logger), use {@link defineRouterPlugin} ({@link defineIdentityPlugin}).
+ * `definePlugin((app) => app.get(...))` infers `app: Server<any, any>`, so `.use()` returns `Server<any, any>`
+ * and your whole typed client silently collapses to `any` - no type error, no runtime error.
+ */
+export function definePlugin<In extends AnyServer, Out extends AnyServer>(
+  name: string,
+  apply: (app: In) => Out,
+): NifraPlugin<In, Out> {
+  return Object.assign(apply, { pluginName: name }) as NifraPlugin<In, Out>
+}
+
+/**
+ * Define a type-**identity** plugin: it registers routes/hooks as a side effect but returns the app with
+ * its `Registry` + `Context` UNCHANGED. Use this (not {@link definePlugin}) for any plugin that doesn't
+ * add context types - e.g. one mounting an auth handler. It threads the caller's *concrete* server type
+ * through `use`, so routes declared after `app.use(plugin)` keep their types.
+ *
+ * Why a dedicated helper: `definePlugin((app) => app)` infers `app: Server<any, any>`, so `use` returns
+ * `Server<any, any>` and the whole typed client collapses to `any`. The explicit generic return type here
+ * (which a plain `Object.assign` can't preserve) is what keeps `use` returning the precise server type.
+ *
+ * ```ts
+ * export const audit = defineIdentityPlugin("audit", (app) => app.onResponse(logResponse))
+ * const api = server().get("/a", h).use(audit).get("/b", h) // /a AND /b stay typed
+ * ```
+ */
+export function defineIdentityPlugin(
+  name: string,
+  apply: <S extends AnyServer>(app: S) => S,
+): IdentityPlugin {
+  return Object.assign(apply, { pluginName: name }) as IdentityPlugin
+}
+
+/**
+ * Alias of {@link defineIdentityPlugin} with a name that says what it's FOR: a plugin that **mounts
+ * routes/hooks but adds no context type** (an auth router, an audit logger). Use this - not
+ * {@link definePlugin} - for any such plugin, or the typed client silently collapses to `any`. The
+ * "identity" in {@link defineIdentityPlugin} refers to the type-identity it preserves; `defineRouterPlugin`
+ * is the same thing under a clearer name.
+ *
+ * Mount routes as a **side effect**, then return the app unchanged (registering via `.get`/`.post` would
+ * change the type away from the identity `S`; the mounted routes run but aren't in the caller's typed
+ * registry - that's the trade that keeps everything else typed):
+ *
+ * ```ts
+ * export const scim = defineRouterPlugin("scim", (app) => {
+ *   app.get("/scim/v2/Users", listUsers) // side effect: mounted at runtime
+ *   return app                           // return S unchanged → routes added after .use(scim) stay typed
+ * })
+ * const api = server().get("/a", h).use(scim).get("/b", h) // /a AND /b stay typed
+ * ```
+ */
+export const defineRouterPlugin: typeof defineIdentityPlugin = defineIdentityPlugin

package/src/server/query.ts

@@ -0,0 +1,119 @@
+/**
+ * Query-string and urlencoded-form parsing. Pure request-shaping helpers with no server internals:
+ * the fast scanner for `c.query`, the repeated-key -> `string[]` promotion shared by query + form,
+ * and the byte-capped HTML-form reader. Split out of the server kernel so the file stays one domain.
+ */
+import { readBoundedBytes } from "./body.ts"
+import { jsonError, urlPartsOf } from "./http.ts"
+import type { RequestSource } from "./server.ts"
+
+// The query string ("?a=1", or "" when absent) - for lazily building `c.query` only when read.
+// The fragment (after the first `#`) bounds the search: a `?` that appears only inside the fragment
+// is NOT a query (matches WHATWG). Fragments never reach the server in `req.url`, so this is purely
+// for provable equivalence with `new URL(req.url).search`.
+export function searchOf(url: string): string {
+  return urlPartsOf(url).search
+}
+
+/** A query value: a single occurrence is a string; a repeated key promotes to a string[] so an
+ * array query schema (`t.array(t.string())`) can validate `?tag=a&tag=b` - last-wins silently
+ * dropped values before (audit 2026-06). Single-occurrence keys stay plain strings, so existing
+ * `t.string()` schemas are untouched; a repeated key against a string schema now FAILS validation
+ * (an explicit 400 beats silently picking one). */
+export type QueryValue = string | string[]
+
+/** Accumulate into a NULL-PROTOTYPE record (every call site below creates one): with no inherited
+ * `constructor`/`toString`/`__proto__` accessors, a hostile key is just an own data key - the
+ * promotion logic can't collide with `Object.prototype` members, and `__proto__` needs no special
+ * case (direct assignment on a null-proto object creates an own property). */
+function setQueryValue(out: Record<string, QueryValue>, key: string, value: string): void {
+  const existing = out[key]
+  if (existing === undefined) {
+    out[key] = value
+  } else if (typeof existing === "string") {
+    out[key] = [existing, value]
+  } else {
+    existing.push(value)
+  }
+}
+
+function queryObjectFallback(search: string): Record<string, QueryValue> {
+  // Manual iteration instead of Object.fromEntries: repeated keys must promote to arrays
+  // (fromEntries is last-wins), and __proto__ needs the same own-property guard.
+  const out: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
+  for (const [key, value] of new URLSearchParams(search)) {
+    setQueryValue(out, key, value)
+  }
+  return out
+}
+
+/**
+ * Build the plain object passed to query schemas. Plain ASCII-ish queries avoid
+ * `URLSearchParams` + iterator allocations; encoded queries fall back to the Web API so `+`,
+ * percent-decoding, malformed escapes, and empty-key behavior stay exact. Repeated keys promote
+ * to `string[]` on BOTH paths (see {@link setQueryValue}).
+ */
+// Shared empty result for no-query requests: frozen + null-prototype (same shape contract as the
+// populated path), allocated once instead of per request.
+const EMPTY_QUERY = Object.freeze(Object.create(null)) as Record<string, QueryValue>
+
+export function queryObjectOf(search: string): Record<string, QueryValue> {
+  const start = search.charCodeAt(0) === 63 /* ? */ ? 1 : 0
+  if (start >= search.length) return EMPTY_QUERY
+
+  for (let i = start; i < search.length; i++) {
+    const c = search.charCodeAt(i)
+    if (c === 37 /* % */ || c === 43 /* + */) return queryObjectFallback(search)
+  }
+
+  const out: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
+  let pos = start
+  while (pos <= search.length) {
+    const amp = search.indexOf("&", pos)
+    const end = amp === -1 ? search.length : amp
+    if (end > pos) {
+      const eq = search.indexOf("=", pos)
+      const split = eq !== -1 && eq < end ? eq : end
+      const key = search.slice(pos, split)
+      const value = split === end ? "" : search.slice(split + 1, end)
+      setQueryValue(out, key, value)
+    }
+    if (amp === -1) break
+    pos = amp + 1
+  }
+  return out
+}
+
+/** `application/x-www-form-urlencoded`, with or without a charset suffix. */
+export function isUrlEncodedForm(contentType: string): boolean {
+  return (
+    contentType === "application/x-www-form-urlencoded" ||
+    contentType.startsWith("application/x-www-form-urlencoded;")
+  )
+}
+
+const FORM_DECODER = new TextDecoder()
+
+/**
+ * Read an HTML-form body (urlencoded) into the plain object a body schema validates - same byte
+ * cap as the JSON path (a lying/absent Content-Length can't force an oversized buffer), same
+ * repeated-key -> `string[]` promotion as query parsing, same `__proto__` guard.
+ */
+export async function readBoundedForm(
+  req: RequestSource,
+  maxBytes: number,
+): Promise<Record<string, QueryValue> | Response> {
+  const read = await readBoundedBytes(req, maxBytes)
+  if (!read.ok) {
+    return read.status === 413
+      ? jsonError(413, "payload_too_large")
+      : jsonError(400, "invalid_content_length")
+  }
+  const out: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
+  // URLSearchParams owns the format's quirks (`+` as space, percent-decoding, empty keys);
+  // it never throws on junk input, so no try/catch is needed here.
+  for (const [key, value] of new URLSearchParams(FORM_DECODER.decode(read.bytes))) {
+    setQueryValue(out, key, value)
+  }
+  return out
+}

package/src/server/registry.ts

@@ -1,4 +1,4 @@
-import type { InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
+import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import type { Params, RouteSchema } from "./context.ts"
 
 /**
@@ -16,12 +16,17 @@ export interface RouteInfo {
   readonly query: unknown
   readonly body: unknown
   readonly output: unknown
-  /** Union of the route's declared error-response body types (from `schema.errors`); `unknown` when the
-   * route declares none. Surfaced by the typed client as the failure `errorData`. */
+  /** The route's declared error bodies as a status-keyed record (from `schema.errors`, e.g.
+   * `{ 404: NotFound }`); `unknown` when the route declares none. The typed client turns this into
+   * a status-discriminated failure union. */
   readonly errors?: unknown
   /** The SSE event payload type (from `schema.sse`, declared via `app.sse()`); `never` for ordinary
    * routes. The typed client keys `.subscribe()` availability and its event type off this. */
   readonly sse?: unknown
+  /** The WebSocket message contract (from `app.ws()`'s `messageSchema`/`sendSchema`): `in` is what the
+   * client may send, `out` what the server pushes. Present only on WS entries (method key `"WS"`);
+   * the typed client keys `.ws()` availability and its frame types off this. */
+  readonly ws?: unknown
 }
 
 /** The accumulated, type-level map of every route on a Server: path → method → RouteInfo. */
@@ -46,12 +51,13 @@ type RegistryOutput<S extends RouteSchema, Output> = S extends {
   ? InferOutput<R>
   : Output
 
-/** The union of a route's declared error-response body types (`schema.errors` → `{status: schema}`), so the
- * typed client can surface the failure body. `unknown` when the route declares no `errors`. */
+/** A route's declared error-response body types as a STATUS-KEYED record (`schema.errors` →
+ * `{ 404: NotFound, 409: Conflict }`), so the typed client can discriminate the failure body by
+ * `status`, not just surface a union. `unknown` when the route declares no `errors`. */
 type RegistryErrors<S extends RouteSchema> = S extends {
   errors: infer E extends Record<number, StandardSchemaV1>
 }
-  ? { [K in keyof E]: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : never }[keyof E]
+  ? { [K in keyof E]: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : never }
   : unknown
 
 /** The SSE event payload type from a route's `sse` schema; `never` for ordinary routes. */
@@ -75,6 +81,30 @@ export type OutputOf<H extends (...args: never[]) => unknown> = Exclude<
   Response
 >
 
+/**
+ * The registry entry for a WebSocket route (stored under the pseudo-method key `"WS"`, so WS routes
+ * ride the same path → method map as HTTP routes - no extra Server generic). `in` is the client →
+ * server frame type: the `messageSchema`'s INPUT side, since that is what goes on the wire before
+ * validation transforms it. `out` is the server → client frame type from `sendSchema` (a type-level
+ * contract; the server's own sends are not runtime-validated). Either is `unknown` when undeclared.
+ */
+export type WsRouteInfoFor<
+  Path extends string,
+  In extends StandardSchemaV1 | undefined,
+  Out extends StandardSchemaV1 | undefined,
+> = {
+  readonly params: Params<Path>
+  readonly query: never
+  readonly body: never
+  readonly output: never
+  readonly errors: unknown
+  readonly sse: never
+  readonly ws: {
+    readonly in: In extends StandardSchemaV1 ? InferInput<In> : unknown
+    readonly out: Out extends StandardSchemaV1 ? InferOutput<Out> : unknown
+  }
+}
+
 /**
  * Merge a new route into the registry, combining methods that share a path.
  *