@nifrajs/client 1.12.0 → 2.0.0

package/src/treaty.ts

@@ -1,4 +1,4 @@
-import type { RouteInfo, Server } from "@nifrajs/core"
+import type { RouteInfo, Server } from "@nifrajs/core/server"
 import type { Jsonify } from "./jsonify.ts"
 import type { Result } from "./result.ts"
 
@@ -84,12 +84,60 @@ type SseMethods<MethodMap> = MethodMap extends { GET: infer G }
     : { subscribe: SubscribeCall<G & RouteInfo> }
   : unknown
 
+// --- typed WebSocket handles ---
+
+/** The WS frame contract of a route (from `app.ws()`'s schemas); `never` for ordinary routes. */
+type WsOf<I> = I extends { ws: infer W extends { in: unknown; out: unknown } } ? W : never
+
+export interface WsCallOptions {
+  query?: Record<string, string | number | boolean>
+  /** WebSocket subprotocols. A browser handshake cannot carry custom headers - authenticate via
+   * `upgrade()` reading cookies/query/subprotocol, not an Authorization header. */
+  protocols?: string | string[]
+  /** Abort to close the socket (same effect as calling `close()`). */
+  signal?: AbortSignal
+  /** Socket-level failures (connection refused, abnormal close). */
+  onError?: (error: unknown) => void
+}
+
+/**
+ * A live typed WebSocket connection to an `app.ws()` route. `send` accepts the route's
+ * `messageSchema` input type (validated server-side at the trust boundary); received frames are
+ * typed from its `sendSchema` and JSON-parsed. Binary frames are not part of the typed contract
+ * and are ignored by `messages()`/`onMessage` - use `raw` for them.
+ */
+export interface WsHandle<In, Out> {
+  /** Send one typed frame (JSON-encoded). Queued until the socket opens, so it never throws. */
+  send(message: In): void
+  /** Async-iterate incoming typed frames. Ends when the socket closes (or `signal` aborts). */
+  messages(options?: { signal?: AbortSignal }): AsyncIterableIterator<Out>
+  /** Callback form of {@link messages}; returns an unsubscribe. */
+  onMessage(callback: (message: Out) => void): () => void
+  /** Resolves when the socket is open (rejects on a connect failure). */
+  readonly opened: Promise<void>
+  close(code?: number, reason?: string): void
+  /** The underlying socket, for anything off the typed contract (binary frames, bufferedAmount…). */
+  readonly raw: WebSocket
+}
+
+type WsCall<I extends RouteInfo> = (
+  options?: WsCallOptions,
+) => WsHandle<WsOf<I>["in"], Jsonify<WsOf<I>["out"]>>
+
+/** Routes declared via `app.ws()` (pseudo-method `"WS"`) grow a `.ws()` handle. */
+type WsMethods<MethodMap> = MethodMap extends { WS: infer G }
+  ? [WsOf<G>] extends [never]
+    ? unknown
+    : { ws: WsCall<G & RouteInfo> }
+  : unknown
+
 type Methods<MethodMap> = {
-  [M in keyof MethodMap as Lowercase<M & string>]: MethodCall<
+  [M in Exclude<keyof MethodMap, "WS"> as Lowercase<M & string>]: MethodCall<
     MethodMap[M] & RouteInfo,
     IsBodyVerb<M & string>
   >
-} & SseMethods<MethodMap>
+} & SseMethods<MethodMap> &
+  WsMethods<MethodMap>
 
 // --- path-tree construction over the registry ---
 

package/src/validate-responses.ts

@@ -0,0 +1,121 @@
+/**
+ * Runtime response-contract assertion for the in-process test client
+ * (`testClient(app, { validateResponses: true })`).
+ *
+ * The `response` / `errors` schemas on a route are a compile-time contract on the handler; nothing
+ * re-checks the bytes that actually leave the app. This wrapper closes that gap in tests: every
+ * JSON response is validated against the route's declared schema for its status - `response` for
+ * 2xx, `errors[status]` for declared failures - and a mismatch THROWS (failing the test loudly)
+ * instead of letting a drifted payload pass. Responses with no declared schema for their status,
+ * non-JSON bodies (SSE, streams, HTML), and 204/205/HEAD are passed through untouched.
+ *
+ * Route lookup reuses the framework's own `Router` over `app.routes()`, so pattern matching can
+ * never drift from what the server itself does.
+ */
+
+import { type Method, Router } from "@nifrajs/core/router"
+import type { FetchFn } from "./client.ts"
+
+/** The slice of a Standard Schema this wrapper runs. */
+interface SchemaLike {
+  readonly "~standard": {
+    readonly validate: (value: unknown) =>
+      | { readonly issues?: ReadonlyArray<IssueLike> | undefined; readonly value?: unknown }
+      | Promise<{
+          readonly issues?: ReadonlyArray<IssueLike> | undefined
+          readonly value?: unknown
+        }>
+  }
+}
+
+interface IssueLike {
+  readonly message: string
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined
+}
+
+interface RouteSchemaLike {
+  readonly response?: SchemaLike
+  readonly errors?: Readonly<Record<number, SchemaLike>>
+}
+
+interface RouteDescriptorLike {
+  readonly method: string
+  readonly path: string
+  readonly schema: RouteSchemaLike | undefined
+}
+
+/** What `validateResponses` needs from the app beyond `fetch`: the route table. */
+export interface RouteIntrospectable {
+  routes(): ReadonlyArray<RouteDescriptorLike>
+}
+
+/**
+ * A response body that broke its route's declared contract. Thrown THROUGH the "never throws"
+ * client on purpose: this is a test assertion about the server's honesty, not a call outcome the
+ * caller should branch on - swallowing it into a `Result` would let the drift pass the test.
+ */
+export class ResponseContractViolation extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "ResponseContractViolation"
+  }
+}
+
+function formatIssues(issues: ReadonlyArray<IssueLike>): string {
+  return issues
+    .map((issue) => {
+      const path = (issue.path ?? [])
+        .map((seg) => String(typeof seg === "object" && seg !== null ? seg.key : seg))
+        .join(".")
+      return path === "" ? issue.message : `${path}: ${issue.message}`
+    })
+    .join("; ")
+}
+
+/**
+ * Wrap the in-process bridge so every response is checked against its route's declared contract.
+ * Throws at wrap time when the app cannot enumerate routes - a misconfiguration, not a soft skip.
+ */
+export function withResponseValidation(app: unknown, bridge: FetchFn): FetchFn {
+  const routesOf = (app as Partial<RouteIntrospectable>).routes
+  if (typeof routesOf !== "function") {
+    throw new Error(
+      "validateResponses needs an app that exposes .routes() (a nifra server); this app does not",
+    )
+  }
+  // One router per client, built once: match by the server's own engine, payload = the schema.
+  const router = new Router<RouteSchemaLike | undefined>()
+  for (const route of routesOf.call(app)) {
+    router.add(route.method as Method, route.path, route.schema)
+  }
+
+  return async (url, init) => {
+    const response = await bridge(url, init)
+    const method = (init?.method ?? "GET").toUpperCase()
+    const status = response.status
+    if (method === "HEAD" || status === 204 || status === 205) return response
+
+    const match = router.find(method, new URL(url).pathname)
+    if (!match.found) return response
+    const schema = match.payload
+    const declared = status >= 200 && status < 300 ? schema?.response : schema?.errors?.[status]
+    if (declared === undefined) return response
+
+    const contentType = response.headers.get("content-type") ?? ""
+    if (!contentType.includes("application/json")) return response
+    // Clone so the caller still gets an unconsumed body; unparseable JSON is the transport's problem.
+    let body: unknown
+    try {
+      body = await response.clone().json()
+    } catch {
+      return response
+    }
+    const result = await declared["~standard"].validate(body)
+    if (result.issues !== undefined) {
+      throw new ResponseContractViolation(
+        `response contract violation: ${method} ${new URL(url).pathname} → ${status}: ${formatIssues(result.issues)}`,
+      )
+    }
+    return response
+  }
+}

package/src/ws.ts

@@ -0,0 +1,154 @@
+/**
+ * The typed client's WebSocket transport - the runtime behind `api.chat.ws()` for routes declared
+ * with `app.ws()`. Uses the platform's global `WebSocket` (browser, Bun, Node 22+, Deno, workerd),
+ * mapping the client's `http(s)` base to `ws(s)`. Frames are JSON on the typed surface: `send`
+ * encodes, `messages()`/`onMessage` parse text frames (binary frames bypass the typed contract -
+ * read them off `raw`). Sends before the socket opens are queued, so the handle never throws.
+ */
+
+import type { WsCallOptions, WsHandle } from "./treaty.ts"
+
+/** Internal handshake between `inProcessClient` and the proxy: in-process apps have no socket. */
+export const NO_SOCKET = Symbol.for("@nifrajs/client/no-socket")
+
+interface WsRuntimeOptions extends WsCallOptions {
+  headers?: Record<string, string> | undefined
+}
+
+function toWsUrl(base: string, path: string, query: WsCallOptions["query"]): string {
+  const url = new URL(base + (path === "" ? "/" : path))
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:"
+  for (const [key, value] of Object.entries(query ?? {})) {
+    url.searchParams.set(key, String(value))
+  }
+  return url.toString()
+}
+
+export function openWebSocket(
+  base: string,
+  path: string,
+  callOptions: WsRuntimeOptions | undefined,
+  noSocket: boolean,
+): WsHandle<unknown, unknown> {
+  if (noSocket) {
+    throw new Error(
+      "the in-process client cannot open WebSockets (app.fetch has no socket) - listen() the app and connect with client(baseUrl)",
+    )
+  }
+  const WebSocketImpl = (globalThis as { WebSocket?: typeof WebSocket }).WebSocket
+  if (WebSocketImpl === undefined) {
+    throw new Error(
+      "no global WebSocket in this runtime - .ws() needs one (browser, Bun, Node 22+)",
+    )
+  }
+
+  const url = toWsUrl(base, path, callOptions?.query)
+  const socket =
+    callOptions?.protocols !== undefined
+      ? new WebSocketImpl(url, callOptions.protocols)
+      : new WebSocketImpl(url)
+
+  const sendQueue: string[] = []
+  const listeners = new Set<(message: unknown) => void>()
+
+  const opened = new Promise<void>((resolve, reject) => {
+    socket.addEventListener("open", () => resolve(), { once: true })
+    socket.addEventListener(
+      "error",
+      (event) => {
+        callOptions?.onError?.(event)
+        reject(new Error("websocket_connect_failed"))
+      },
+      { once: true },
+    )
+  })
+  // The rejection is surfaced via `opened` (and `onError`) only for those who look - an unconsumed
+  // `opened` on a failed connect must not crash the process with an unhandled rejection.
+  opened.catch(() => {})
+
+  socket.addEventListener("open", () => {
+    for (const frame of sendQueue) socket.send(frame)
+    sendQueue.length = 0
+  })
+  socket.addEventListener("message", (event: MessageEvent) => {
+    if (typeof event.data !== "string") return // binary frames live off the typed contract
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(event.data)
+    } catch {
+      return // a non-JSON text frame is outside the contract too
+    }
+    for (const listener of listeners) listener(parsed)
+  })
+
+  if (callOptions?.signal !== undefined) {
+    if (callOptions.signal.aborted) socket.close()
+    else callOptions.signal.addEventListener("abort", () => socket.close(), { once: true })
+  }
+
+  const onMessage = (callback: (message: unknown) => void): (() => void) => {
+    listeners.add(callback)
+    return () => listeners.delete(callback)
+  }
+
+  return {
+    raw: socket,
+    opened,
+    send(message: unknown): void {
+      const frame = JSON.stringify(message)
+      if (socket.readyState === WebSocketImpl.OPEN) socket.send(frame)
+      else sendQueue.push(frame)
+    },
+    close(code?: number, reason?: string): void {
+      socket.close(code, reason)
+    },
+    onMessage,
+    messages(options?: { signal?: AbortSignal }): AsyncIterableIterator<unknown> {
+      const buffered: unknown[] = []
+      let pending: ((result: IteratorResult<unknown>) => void) | undefined
+      let done = false
+
+      const push = (message: unknown): void => {
+        if (pending !== undefined) {
+          const resolve = pending
+          pending = undefined
+          resolve({ value: message, done: false })
+        } else {
+          buffered.push(message)
+        }
+      }
+      const end = (): void => {
+        if (done) return
+        done = true
+        unsubscribe()
+        pending?.({ value: undefined, done: true })
+        pending = undefined
+      }
+
+      const unsubscribe = onMessage(push)
+      socket.addEventListener("close", end, { once: true })
+      socket.addEventListener("error", end, { once: true })
+      options?.signal?.addEventListener("abort", end, { once: true })
+
+      const iterator: AsyncIterableIterator<unknown> = {
+        [Symbol.asyncIterator]() {
+          return this
+        },
+        next(): Promise<IteratorResult<unknown>> {
+          if (buffered.length > 0) {
+            return Promise.resolve({ value: buffered.shift(), done: false })
+          }
+          if (done) return Promise.resolve({ value: undefined, done: true })
+          return new Promise((resolve) => {
+            pending = resolve
+          })
+        },
+        return(): Promise<IteratorResult<unknown>> {
+          end()
+          return Promise.resolve({ value: undefined, done: true })
+        },
+      }
+      return iterator
+    },
+  }
+}