@nifrajs/core 1.13.0 → 2.1.0

package/dist/server/server-types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Public API-surface types for the server: construction options, the capacity-admission contract,
+ * route/tool/MCP descriptors, and the middleware bundle shape. Pure types (no runtime), split out of
+ * the server kernel so the descriptor/option vocabulary is one file, distinct from the engine.
+ */
+import type { CapabilityUseEvent } from "../internal/capability-runtime.js";
+import type { AssuranceEvidence } from "../internal/route-assurance.js";
+import type { Method } from "../router/router.js";
+import type { ClientIpTrust } from "./client-ip.js";
+import type { Context, Platform, RouteSchema } from "./context.js";
+import type { Logger } from "./logger.js";
+import type { MaybePromise, OnRequestResult } from "./server.js";
+/**
+ * The outcome of a capacity-admission decision. `admitted` requests carry a `release` the server calls
+ * exactly once when the response is finalized; a shed request carries a ready `429` Response.
+ */
+export type AdmissionDecision = {
+    readonly admitted: true;
+    release(): void;
+} | {
+    readonly admitted: false;
+    readonly response: Response;
+};
+/**
+ * A capacity-admission gate. Decides, per request, whether the instance has capacity to run it now -
+ * bounding *concurrency*, which rate limits (frequency) and deadlines (duration) do not. Provide an
+ * implementation (see `@nifrajs/middleware`'s `createAdmissionController`) as {@link ServerOptions.admission}.
+ *
+ * Enabling it trades the fused native-route lane for native matching + this gate (the gate cannot be a
+ * per-request `onRequest` hook without disabling native routes entirely); when unset, the request path
+ * is untouched.
+ */
+export interface AdmissionController {
+    admit(req: Request): AdmissionDecision | Promise<AdmissionDecision>;
+}
+export interface ServerOptions {
+    /**
+     * Max request body size (bytes), enforced **only when a route declares a body schema** - the cap
+     * lives in the schema-validated read path. Default 1_000_000.
+     *
+     * A route WITHOUT a body schema (raw body, file upload, BYO-validation) that reads `c.req` directly
+     * is not auto-bounded - use **`c.boundedBody(maxBytes?)`** / **`c.boundedJson(maxBytes?)`**, which
+     * apply this same cap (override per route by passing `maxBytes` - larger for an upload endpoint,
+     * smaller to tighten one).
+     */
+    readonly maxBodyBytes?: number;
+    /** Max inbound WebSocket message size (bytes) when `listen()`ing on Bun - frames over this are rejected
+     * by the runtime before reaching your handler (so a huge frame can't be JSON-parsed into memory).
+     * Default: `maxBodyBytes` (1 MB). */
+    readonly wsMaxPayloadBytes?: number;
+    /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */
+    readonly requestTimeoutMs?: number;
+    /**
+     * How to derive `c.clientIp` behind a reverse proxy or CDN. Omit (default) to trust only the raw
+     * socket peer and never believe a forwarded header. Set `{ trustedHops: n }` when the app sits
+     * behind `n` proxies you operate (the caller is read from `X-Forwarded-For` past those hops), or
+     * `{ header: name }` to trust one edge-set header's first value. Declaring trust the app can't
+     * actually enforce lets clients forge their IP, so leave it unset unless a proxy really fronts you.
+     */
+    readonly clientIp?: ClientIpTrust;
+    /**
+     * Admit the public `x-nifra-deadline` header and let it shorten local work. Disabled by default:
+     * services that participate in trusted cross-service deadline propagation opt in explicitly,
+     * while ordinary/public HTTP routes pay no header-admission tax and ignore hostile client values.
+     */
+    readonly acceptInboundDeadlines?: boolean;
+    /**
+     * Maximum time accepted from an inbound `x-nifra-deadline`, in milliseconds. An incoming absolute
+     * deadline may shorten this cap (and `requestTimeoutMs`, when configured), never extend it.
+     * Default 30_000; applies only when `acceptInboundDeadlines` is enabled and the header is present.
+     */
+    readonly maxInboundDeadlineMs?: number;
+    /** When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false. */
+    readonly gracefulSignals?: boolean;
+    /**
+     * Capacity-admission gate (see {@link AdmissionController}). Bounds concurrent in-flight work so a
+     * healthy instance sheds load (`429` + `Retry-After`) instead of accepting more than it can finish.
+     * Off by default. Enabling it disables the fused native-route fast path (requests route through the
+     * shared matched lane where the gate runs); when unset, the request path pays nothing.
+     */
+    readonly admission?: AdmissionController;
+    /**
+     * Optional token-only observation hook called by `useCapability(c, id)`. It receives no request,
+     * parameters, body, tenant, or values. Routes without capability declarations keep the old hot path.
+     */
+    readonly onCapabilityUse?: (event: CapabilityUseEvent) => void;
+    /** Structured logger for framework events (redacts secrets). Default: JSON to stderr. */
+    readonly logger?: Logger;
+    /**
+     * App-wide fallback fired when a route **without its own `onValidationError`** fails body/query
+     * validation. Same contract as the per-route hook (`(issues, ctx, kind) => Response | repaired-value |
+     * undefined`): a route's own hook takes precedence, and a route can fall through to the plain `422` by
+     * returning `undefined`. Use it for one app-wide error envelope (like tRPC's `errorFormatter` /
+     * Fastify's `setErrorHandler`) instead of repeating a formatter per route.
+     */
+    readonly onValidationError?: RouteSchema["onValidationError"];
+}
+/**
+ * MCP tool safety hints, surfaced in `tools/list`, that tell an agent how risky a `.tool()` call is - so it
+ * can decide whether to auto-invoke or confirm first. All optional; an omitted hint means "unknown". Mirrors
+ * the MCP spec's tool `annotations`.
+ */
+export interface ToolAnnotations {
+    /** Human-readable display title for the tool, distinct from the machine `name`. */
+    readonly title?: string;
+    /** The tool does not modify its environment (a pure read). */
+    readonly readOnlyHint?: boolean;
+    /** The tool may perform destructive updates - only meaningful when `readOnlyHint` is not `true`. */
+    readonly destructiveHint?: boolean;
+    /** Repeated calls with the same arguments have no additional effect beyond the first. */
+    readonly idempotentHint?: boolean;
+    /** The tool interacts with external entities (an "open world" beyond this server). */
+    readonly openWorldHint?: boolean;
+}
+/**
+ * A registered route's public descriptor - method, path, and input schemas. The
+ * router trie discards the original patterns, so this flat list is what lets tools
+ * (e.g. `toOpenAPI`) enumerate routes after registration.
+ */
+export interface RouteDescriptor {
+    readonly method: Method;
+    readonly path: string;
+    readonly schema: RouteSchema | undefined;
+    /** Effective enforcement evidence, populated only during reflection/introspection. */
+    readonly assurance?: readonly AssuranceEvidence[];
+    /** Normalized declared effect tokens, populated only when the route declares any. */
+    readonly capabilities?: readonly string[];
+    /** Set when the route is a declared dynamic route family (`schema.family`). */
+    readonly family?: boolean;
+    readonly tool?: {
+        readonly name: string;
+        readonly description: string;
+        readonly annotations?: ToolAnnotations;
+    };
+}
+/** A message in an MCP prompt's rendered output (see {@link Server.prompt}). */
+export interface PromptMessage {
+    readonly role: "user" | "assistant";
+    readonly content: {
+        readonly type: "text";
+        readonly text: string;
+    };
+}
+/** One declared argument of an MCP prompt, surfaced in `prompts/list`. */
+export interface PromptArgument {
+    readonly name: string;
+    readonly description?: string;
+    readonly required?: boolean;
+}
+/** An app-declared MCP resource - read-only data an agent can fetch through `nifra mcp`. */
+export interface McpResourceDescriptor {
+    readonly uri: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly mimeType?: string;
+    readonly read: () => MaybePromise<string | {
+        readonly text: string;
+        readonly mimeType?: string;
+    }>;
+}
+/** An app-declared MCP prompt - a reusable prompt template an agent can fetch through `nifra mcp`. */
+export interface McpPromptDescriptor {
+    readonly name: string;
+    readonly description: string;
+    readonly arguments?: readonly PromptArgument[];
+    readonly handler: (args: Record<string, string>) => MaybePromise<readonly PromptMessage[]>;
+}
+/**
+ * The handle `listen()` returns - the slice of Bun's server nifra holds and exposes.
+ * Declared explicitly (rather than `ReturnType<typeof Bun.serve>`) so the public type
+ * surface doesn't leak the ambient `Bun` global into consumers' `.d.ts` resolution.
+ */
+export interface RunningServer {
+    readonly port: number;
+    readonly hostname: string;
+    readonly pendingRequests: number;
+    stop(closeActiveConnections?: boolean): void;
+}
+/**
+ * A bundle of lifecycle hooks applied together via {@link Server.use} - the unit
+ * `@nifrajs/middleware` ships (cors, security headers, rate-limit). Every hook is
+ * optional and wired to its lifecycle point. Middleware is context-agnostic (sees
+ * the base `Context`); `use` does no context-type merging - the full type-merging
+ * plugin system is deferred, and `.use` is reserved as its future entry point.
+ */
+export interface Middleware {
+    readonly name?: string;
+    readonly onRequest?: (req: Request, platform?: Platform) => MaybePromise<OnRequestResult>;
+    readonly around?: <T>(context: Context, next: () => MaybePromise<T>) => MaybePromise<T>;
+    readonly beforeHandle?: (context: Context) => MaybePromise<unknown>;
+    readonly afterHandle?: (result: unknown, context: Context) => MaybePromise<unknown>;
+    readonly onResponse?: (response: Response, req: Request) => MaybePromise<Response>;
+    readonly onResponseFinalized?: (outcome: ResponseFinalization, req: Request) => MaybePromise<void>;
+    readonly onError?: (error: unknown, context: Context) => MaybePromise<unknown>;
+}
+/** The terminal response-pipeline outcome observed after every transforming `onResponse` hook. */
+export interface ResponseFinalization {
+    /** The final response, or the last response available when a transformation failed. */
+    readonly response: Response;
+    /** A response-hook failure. Terminal observers run fail-open before the error is rethrown. */
+    readonly error?: unknown;
+}
+//# sourceMappingURL=server-types.d.ts.map

package/dist/server/server-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-types.d.ts","sourceRoot":"","sources":["../../src/server/server-types.ts"],"names":[],"mappings":"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"}

package/dist/server/server-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server-types.js.map

package/dist/server/server-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-types.js","sourceRoot":"","sources":["../../src/server/server-types.ts"],"names":[],"mappings":""}