@nifrajs/core 1.13.0 → 2.0.0

package/src/server/sse-hook.ts

@@ -0,0 +1,14 @@
+/**
+ * The `SseRuntime` contract - the streaming implementation that `.use(streaming())` installs (from
+ * `@nifrajs/core/sse`). `server.ts` type-imports only this, so the ReadableStream framing code stays
+ * out of a bare server bundle until a route opts in.
+ */
+import type { SSEContext, SSEInit, TypedSSEStream } from "./sse.ts"
+
+export interface SseRuntime {
+  response<Event>(
+    context: SSEContext,
+    run: (stream: TypedSSEStream<Event>) => void | Promise<void>,
+    init?: SSEInit,
+  ): Response
+}

package/src/server/sse.ts

@@ -21,6 +21,10 @@
  *       stream.signal.addEventListener("abort", () => { off(); resolve() }, { once: true }))
  *   }, { keepAlive: 15_000 }))
  */
+import { INSTALL_SSE } from "./install.ts"
+import type { IdentityPlugin } from "./plugin.ts"
+import type { AnyServer } from "./server.ts"
+import type { SseRuntime } from "./sse-hook.ts"
 
 /** One SSE frame. Every field is optional; `data` may be multi-line (emitted as multiple `data:` lines). */
 export interface SSEMessage {
@@ -188,3 +192,25 @@ export function sse(
   if (!headers.has("x-accel-buffering")) headers.set("x-accel-buffering", "no") // defeat proxy buffering
   return new Response(body, { status: init.status ?? 200, headers })
 }
+
+/** The install seam a server exposes so the `streaming()` plugin can hand it the runtime. */
+interface SseInstallable {
+  [INSTALL_SSE](runtime: SseRuntime): void
+}
+
+/**
+ * Enable `.sse()` streaming routes: `.use(streaming())` installs the SSE runtime. Without it, an
+ * `.sse()` route is a registration error, so the ReadableStream framing stays out of non-SSE bundles.
+ * The `sse()` / `typedSSEStream()` helpers ship from this same subpath for use inside handlers.
+ */
+export function streaming(): IdentityPlugin {
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as SseInstallable)[INSTALL_SSE]({
+      response(context, run, init) {
+        return sse(context, (stream) => run(typedSSEStream(stream)), init)
+      },
+    })
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:streaming" }) as IdentityPlugin
+}

package/src/server/websocket.ts

@@ -130,6 +130,7 @@ export interface WebSocketHandler<
   Data = unknown,
   Env = unknown,
   Schema extends StandardSchemaV1 | undefined = undefined,
+  Send extends StandardSchemaV1 | undefined = undefined,
 > {
   /**
    * Cross-site WebSocket hijacking (CSWSH) guard — checked BEFORE `upgrade()`. A browser does not
@@ -159,6 +160,13 @@ export interface WebSocketHandler<
    * non-JSON or schema-invalid frame is routed to `onInvalidMessage` (or dropped if that's omitted).
    */
   messageSchema?: Schema
+  /**
+   * The **outbound** frame contract (server → client), a Standard Schema. Purely type-level: it types
+   * the frames the typed client's `.ws()` handle receives, and documents what this route pushes. The
+   * server does NOT runtime-validate its own sends - the inbound `messageSchema` guards the trust
+   * boundary; outbound honesty is the handler author's code, checked by tests.
+   */
+  sendSchema?: Send
   open?(ws: NifraWebSocket<Data>): MaybePromise<void>
   message?(ws: NifraWebSocket<Data>, data: WsMessageInput<Schema>): MaybePromise<void>
   /** Inbound frame that failed JSON parse or `messageSchema` validation (only fires when a schema is
@@ -189,8 +197,20 @@ export type WebSocketUpgradeOutcome =
       readonly data: unknown
       /** The app's pub/sub registry — the adapter wires `ws.subscribe` + close-cleanup to it. */
       readonly pubsub: TopicRegistry
+      /** The installed runtime's {@link attachWebSocket}, carried on the outcome so an adapter can wire
+       * a standard socket without a static import of the WS implementation (which would defeat the
+       * `.use(websocket())` tree-shaking). `@nifrajs/workers` may import `attachWebSocket` directly instead. */
+      readonly attach: WsAttach
     }
 
+/** The socket-wiring signature the upgrade outcome carries (the installed runtime's `attach`). */
+export type WsAttach = (
+  socket: StandardWebSocket,
+  handler: WebSocketHandler,
+  data: unknown,
+  options: { openNow: boolean; pubsub: TopicRegistry },
+) => NifraWebSocket
+
 /**
  * A standard server-side `WebSocket` — the half returned by Deno's `Deno.upgradeWebSocket` and the
  * Workers `WebSocketPair`. {@link attachWebSocket} wires one to a nifra handler, so the Deno and Workers

package/src/server/ws-hook.ts

@@ -1,10 +1,11 @@
 /**
- * Lazy WebSocket runtime seam. `server.ts` never imports the WS implementation statically — the
- * `@nifrajs/core/ws` subpath entry registers it here on import. That keeps the WS dispatcher, pub/sub
- * registry, Bun socket plumbing, and message-schema validation out of the base server bundle for
- * apps that never call `app.ws()` (~1.5 KB gzipped on the minimal-app benchmark).
+ * WebSocket runtime contract. `server.ts` type-imports only this; the `.use(websocket())` plugin
+ * (from `@nifrajs/core/ws`) installs the implementation on a server instance via the `INSTALL_WS`
+ * symbol seam. That keeps the WS dispatcher, pub/sub registry, Bun socket plumbing, and
+ * message-schema validation out of the base server bundle for apps that never call `app.ws()`
+ * (~1.5 KB gzipped on the minimal-app benchmark).
  *
- * Only type imports below — this module must stay weightless, it is always in the base bundle.
+ * Only type declarations below - this module must stay weightless, it is always in the base bundle.
  */
 
 import type {
@@ -25,13 +26,13 @@ export interface BunWsHandlers {
 
 /** What `@nifrajs/core/ws` registers: everything `server.ts` and `toFetchHandler` need at runtime. */
 export interface WsRuntime {
-  /** `wrapWebSocketMessageValidation` — applied once at `app.ws()` registration. */
+  /** `wrapWebSocketMessageValidation` - applied once at `app.ws()` registration. */
   wrapHandler(handler: WebSocketHandler): WebSocketHandler
   /** One in-process pub/sub registry per app (backs `ws.subscribe` + `app.publish`). */
   createTopics(): TopicRegistry
   /** The Bun `websocket` config for `listen()` when the app has WS routes. */
   bunHandlers(topics: TopicRegistry): BunWsHandlers
-  /** `attachWebSocket` — wires a standard server socket (Workers `WebSocketPair`) to a handler. */
+  /** `attachWebSocket` - wires a standard server socket (Workers `WebSocketPair`) to a handler. */
   attach(
     socket: StandardWebSocket,
     handler: WebSocketHandler,
@@ -39,15 +40,3 @@ export interface WsRuntime {
     options: { openNow: boolean; pubsub: TopicRegistry },
   ): NifraWebSocket
 }
-
-let runtime: WsRuntime | undefined
-
-/** Called by `@nifrajs/core/ws` on import. Last registration wins (idempotent in practice — there is
- * one implementation; double-import is a no-op re-set of the same functions). */
-export function setWsRuntime(impl: WsRuntime): void {
-  runtime = impl
-}
-
-export function getWsRuntime(): WsRuntime | undefined {
-  return runtime
-}

package/src/server.ts

@@ -0,0 +1,92 @@
+/**
+ * Lean server entry for the common Nifra runtime.
+ *
+ * Use `@nifrajs/core/server` or the equivalent lean package root when building an HTTP app.
+ * Optional systems such as
+ * causality, invariants, manifests, reflection, and capability tooling live at
+ * their dedicated subpaths. Keeping this entry curated is intentional: do not
+ * export an opt-in module here unless the Server implementation already loads it.
+ */
+
+export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
+export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
+export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"
+export type {
+  InferInput,
+  InferOutput,
+  StandardIssue,
+  StandardResult,
+  StandardSchemaV1,
+  StandardTypes,
+  ValidationOutcome,
+} from "./schema/standard.ts"
+export type {
+  Context,
+  Params,
+  Platform,
+  Prettify,
+  ResponseControls,
+  RouteSchema,
+} from "./server/context.ts"
+export {
+  type CookieOptions,
+  parseCookies,
+  serializeCookie,
+  signValue,
+  unsignValue,
+} from "./server/cookies.ts"
+export {
+  commonSecretPatterns,
+  jsonLogger,
+  type LogFields,
+  type Logger,
+  type RedactOptions,
+  redactLogFields,
+  silentLogger,
+} from "./server/logger.ts"
+export type { Registry, RouteInfo } from "./server/registry.ts"
+export {
+  type AdmissionController,
+  type AdmissionDecision,
+  type AnyServer,
+  type DurableObjectNamespaceLike,
+  defineIdentityPlugin,
+  definePlugin,
+  defineRouterPlugin,
+  type ExecutionContext,
+  type Handler,
+  type IdentityPlugin,
+  type McpPromptDescriptor,
+  type McpResourceDescriptor,
+  type Middleware,
+  type NifraPlugin,
+  type NodeServeOutcome,
+  type OnRequestResult,
+  type PromptArgument,
+  type PromptMessage,
+  type ResponseFinalization,
+  type RouteDescriptor,
+  type RunningServer,
+  type ScheduledController,
+  type ScheduledHandler,
+  Server,
+  type ServerOptions,
+  server,
+  type ToolAnnotations,
+  toFetchHandler,
+} from "./server/server.ts"
+export type {
+  SSEContext,
+  SSEInit,
+  SSEMessage,
+  SSEStream,
+  TypedSSEStream,
+} from "./server/sse.ts"
+export type {
+  NifraWebSocket,
+  StandardWebSocket,
+  WebSocketContext,
+  WebSocketData,
+  WebSocketHandler,
+  WebSocketUpgradeOutcome,
+} from "./server/websocket.ts"

package/src/ws.ts

@@ -1,33 +1,56 @@
 /**
- * WebSocket runtime for `@nifrajs/core` — import once at your server entry to enable `app.ws()`:
+ * The opt-in WebSocket runtime plugin.
  *
- *   import "@nifrajs/core/ws"
+ * `.use(websocket())` enables `app.ws()`:
  *
- *   const app = server().ws("/chat", { message: (ws, data) => ws.send(data) })
+ *   import { websocket } from "@nifrajs/core/ws"
  *
- * Why a subpath: an app that never uses WebSockets shouldn't ship the WS dispatcher, pub/sub
- * registry, and Bun socket plumbing in its server bundle (~1.5 KB gzipped on the minimal-app size
- * benchmark). Importing this module registers the runtime with the core server (idempotent);
- * calling `app.ws()` without it fails loud at boot with a `WS_RUNTIME_MISSING` error pointing here.
+ *   const app = server().use(websocket()).ws("/chat", { message: (ws, data) => ws.send(data) })
+ *
+ * Without it, `app.ws()` throws at registration (fail-closed), so an app that never uses WebSockets
+ * never evaluates or bundles the WS dispatcher, pub/sub registry, and Bun socket plumbing (~1.5 KB
+ * gzipped on the minimal-app size benchmark). The runtime installs on that server instance only -
+ * the same `.use()` install seam as `mcp()` / `streaming()` / `idempotency()`, not a process-global
+ * or a side-effect import.
  *
  * Serving adapters that wire standard sockets themselves (`@nifrajs/workers`) import
  * `attachWebSocket` / `TopicRegistry` from here too.
  */
 
+import { INSTALL_WS } from "./server/install.ts"
+import type { IdentityPlugin } from "./server/plugin.ts"
+import type { AnyServer } from "./server/server.ts"
 import {
   attachWebSocket,
   TopicRegistry,
   wrapWebSocketMessageValidation,
 } from "./server/websocket.ts"
 import { createBunWsHandlers } from "./server/ws-bun.ts"
-import { setWsRuntime } from "./server/ws-hook.ts"
+import type { WsRuntime } from "./server/ws-hook.ts"
 
-setWsRuntime({
+const WS_RUNTIME: WsRuntime = {
   wrapHandler: wrapWebSocketMessageValidation,
   createTopics: () => new TopicRegistry(),
   bunHandlers: createBunWsHandlers,
   attach: attachWebSocket,
-})
+}
+
+/** The install seam a server exposes so the `websocket()` plugin can hand it the runtime. */
+interface WsInstallable {
+  [INSTALL_WS](runtime: WsRuntime): void
+}
+
+/**
+ * Enable WebSocket routes on a server: `.use(websocket())` turns on `app.ws()`. Applying it twice is
+ * a no-op (named plugin dedupe).
+ */
+export function websocket(): IdentityPlugin {
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as WsInstallable)[INSTALL_WS](WS_RUNTIME)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:websocket" }) as IdentityPlugin
+}
 
 export type {
   NifraWebSocket,

package/dist/invariants.d.ts

@@ -1,70 +0,0 @@
-/**
- * Contract-generated invariant tests: the declared contract *is* the test suite.
- *
- * `runContractInvariants(app)` reads each route's reflected contract (schemas, classification) and
- * verifies, with deterministic seeded fuzzing, the properties the contract already promises:
- *
- *  1. **Classification consistency** (static) — a route whose response fields are tagged more
- *     sensitive than its declared route-level classification is understating what it emits.
- *  2. **Valid input never crashes** (dynamic) — schema-generated valid requests must not produce 5xx.
- *  3. **Response conformance** (dynamic) — a 2xx response body must validate against the declared
- *     response schema; an undeclared response shape is exactly where sensitive data leaks.
- *  4. **Validation fails closed** (dynamic) — schema-violating bodies must be rejected (4xx), never
- *     accepted (2xx) and never crash (5xx).
- *
- * Everything is deterministic: a seeded PRNG (no ambient randomness, no wall clock), so a failing
- * case reproduces from its seed. Routes whose inputs cannot be generated from their JSON Schema are
- * reported in `skipped` — never silently dropped.
- */
-export type InvariantFindingCode = "classification-understated" | "server-error-on-valid-input" | "response-schema-violation" | "validation-bypass" | "server-error-on-invalid-input";
-export interface InvariantFinding {
-    readonly code: InvariantFindingCode;
-    readonly method: string;
-    readonly path: string;
-    /** The case's deterministic seed — rerun with it to reproduce the exact request. */
-    readonly seed?: number;
-    readonly message: string;
-}
-export interface SkippedRoute {
-    readonly method: string;
-    readonly path: string;
-    readonly reason: string;
-}
-export interface InvariantReport {
-    readonly ok: boolean;
-    /** Routes exercised dynamically. */
-    readonly tested: readonly {
-        readonly method: string;
-        readonly path: string;
-    }[];
-    /** Routes that could not be exercised, with the reason — reported, never silently dropped. */
-    readonly skipped: readonly SkippedRoute[];
-    readonly findings: readonly InvariantFinding[];
-}
-export interface RunInvariantsOptions {
-    /** Deterministic seed for the fuzzer. Default 1. */
-    readonly seed?: number;
-    /** Valid-input cases per route. Default 8. */
-    readonly casesPerRoute?: number;
-    /** Invalid-input (mutated) cases per route with a body schema. Default 4. */
-    readonly invalidCasesPerRoute?: number;
-    /**
-     * Explicit isolated executor for dynamic cases. It must point at a disposable test app, sandbox,
-     * or transaction that is rolled back. The runner never calls `source.fetch()` implicitly: doing so
-     * could charge cards, send mail, or mutate production state merely by running a verification tool.
-     */
-    readonly executor?: InvariantExecutor;
-}
-export type InvariantExecutor = (request: Request) => Response | Promise<Response>;
-/** Opaque route-reflection source. The runner never invokes an app's live fetch method implicitly. */
-type ReflectableApp = object;
-/** Deterministic PRNG (mulberry32). Ambient randomness would make failures unreproducible. */
-export declare function createSeededRandom(seed: number): () => number;
-/** Run the contract-derived invariant suite against a reflectable app. Pure; no ambient state. */
-/**
- * @deprecated Use `runAdversarialContract` from `@nifrajs/testing`. The testing package is the
- * authoritative deep contract laboratory and powers CLI L4; this export remains for compatibility.
- */
-export declare function runContractInvariants(app: ReflectableApp, options?: RunInvariantsOptions): Promise<InvariantReport>;
-export {};
-//# sourceMappingURL=invariants.d.ts.map

package/dist/invariants.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"invariants.d.ts","sourceRoot":"","sources":["../src/invariants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,MAAM,MAAM,oBAAoB,GAC5B,4BAA4B,GAC5B,6BAA6B,GAC7B,2BAA2B,GAC3B,mBAAmB,GACnB,+BAA+B,CAAA;AAEnC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC9E,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC/C;AAED,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;IACtC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAA;CACtC;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAElF,sGAAsG;AACtG,KAAK,cAAc,GAAG,MAAM,CAAA;AA0B5B,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM,CAS7D;AA8ND,kGAAkG;AAClG;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,cAAc,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,eAAe,CAAC,CAmG1B"}