@decohere/http 0.0.1-dev.116

package/types/src/hosting/hosted-service-host.d.ts

@@ -0,0 +1,37 @@
+import type { IContainer } from "@decohere/crucible";
+import type { Constructable } from "@decohere/core/reflection";
+import type { IReadinessCheck } from "../health/readiness.types.js";
+import type { HostedService } from "./hosted-service.js";
+/**
+ * Starts and stops the app's {@link HostedService}s. One per app; `Builder.withHostedService`
+ * adds the types and `App` drives it.
+ */
+export declare class HostedServiceHost {
+    private readonly logger;
+    private readonly types;
+    private readonly controller;
+    /** In start order; stopped in reverse. */
+    private readonly started;
+    private starting;
+    private stopping;
+    add(...types: Constructable<HostedService>[]): void;
+    get isEmpty(): boolean;
+    /**
+     * Start every service in registration order. If one throws, the ones already started are
+     * stopped and the error is rethrown. Stops launching more once {@link stop} has begun.
+     */
+    start(container: IContainer): Promise<void>;
+    /** Abort the services' signal: background work should wind down. {@link stop} does this too. */
+    abort(): void;
+    /**
+     * Abort the signal, wait for a start still in progress, then stop the started services in
+     * reverse order. Every `stop()` runs even if one throws; the failures are rethrown after.
+     */
+    stop(): Promise<void>;
+    /** The started services that report readiness, for `GET /ready`. */
+    readinessChecks(): IReadinessCheck[];
+    private startAll;
+    private stopAll;
+    /** Stop what is started, newest first. Takes each service off the list, so it runs once. */
+    private stopStarted;
+}

package/types/src/hosting/hosted-service.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Work that runs for the life of the app outside a request: a feed, a poller, a queue consumer.
+ * Register it with `builder.withHostedService(Type)`; it is a singleton, so other services can
+ * inject it by its class.
+ *
+ * The app starts hosted services in registration order before the HTTP server listens, and stops
+ * them in reverse order when it stops (`app.dispose()`, SIGTERM or SIGINT, a Flux reboot).
+ */
+export interface HostedService {
+    /**
+     * Called once when the app starts, and awaited: a throw fails `app.start()`. Do what must be
+     * ready before traffic, then start long work (a first load that takes minutes, a timer) in
+     * the background and return. Waiting for it here keeps the HTTP server dark.
+     *
+     * `signal` is aborted as soon as the app starts stopping, before `stop()` is called, also
+     * while `start()` itself is still running. Stop background work and clear timers on it.
+     */
+    start(signal: AbortSignal): Promise<void> | void;
+    /**
+     * Called once when the app stops, after the HTTP server has drained and before the container
+     * is disposed, so the services it uses (a DataSource) are still open. Wait here for the
+     * background work to finish. Optional: a service with nothing to wait for can rely on the
+     * signal, or on `Symbol.asyncDispose`, which the container calls later.
+     */
+    stop?(): Promise<void> | void;
+    /**
+     * Readiness while the service is started but still warming up: throw until it can serve, and
+     * `GET /ready` answers 503 (`withHealth()`). Optional.
+     */
+    check?(): Promise<void>;
+}

package/types/src/hosting/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./hosted-service.js";
+export * from "./hosted-service-host.js";

package/types/src/http/http.compression.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Response compression (`builder.withCompression`). Provider-neutral options and defaults;
+ * the HTTP provider hands them to its compression plugin and the plugin owns the policy
+ * (which responses are compressed, `Vary`, `HEAD`, streams). See ADR 0008.
+ */
+/** A content coding the HTTP package can offer. */
+export type CompressionEncoding = "br" | "gzip" | "deflate";
+/** Bodies smaller than this many bytes are sent as they are (not applied to streams, such as files). */
+export declare const DEFAULT_COMPRESSION_THRESHOLD = 1024;
+/** The codings offered by default, in order of preference. `deflate` is left out on purpose. */
+export declare const DEFAULT_COMPRESSION_ENCODINGS: readonly CompressionEncoding[];
+/** Options for {@link Builder.withCompression}. `false` turns compression off. */
+export type CompressionOptions = false | {
+    /** Smallest body, in bytes, that is compressed. Defaults to 1024. Not applied to streamed bodies. */
+    threshold?: number;
+    /** The codings to offer, in order of preference. Defaults to `["br", "gzip"]`. */
+    encodings?: CompressionEncoding[];
+    /**
+     * Content types to compress, tested against the `Content-Type` header. Passed to the
+     * plugin as `customTypes`: it replaces the plugin's default pattern (text, JSON, XML,
+     * `octet-stream`; never `text/event-stream`) and anything the MIME database marks
+     * compressible is still compressed. Use it to add a type; do not match
+     * `text/event-stream` unless you want streams buffered.
+     */
+    types?: RegExp | ((contentType: string) => boolean);
+    /**
+     * Fastify-specific. Any other `@fastify/compress` option (`brotliOptions`, `zlibOptions`,
+     * `onUnsupportedEncoding`, `inflateIfDeflated`, ...), merged last so it overrides the
+     * values above. Not portable to another HTTP provider.
+     */
+    providerOptions?: Record<string, unknown>;
+};

package/types/src/http/http.extensions.d.ts

@@ -0,0 +1,79 @@
+import type { Constructable } from "@decohere/core/reflection";
+import { Builder } from "../builder/builder.js";
+import type { OpenApiOptions } from "../openapi/openapi.types.js";
+import type { CorsOptions, HttpProvider } from "../routing/anvil.types.js";
+import type { ExceptionFilter } from "../routing/filters/exception-filter.js";
+import type { Middleware } from "../routing/middleware/middleware.js";
+import type { WithHttpOptions } from "./http.options.js";
+import type { CompressionOptions } from "./http.compression.js";
+import type { HelmetOptions, RateLimitOptions } from "./http.security.js";
+import { type StaticOptions } from "./http.static.js";
+declare module "@decohere/http" {
+    interface Builder {
+        withHttpProvider<Thttp extends Constructable<HttpProvider>>(type: Thttp): Builder;
+        /**
+         * HTTP provider plus scaffold defaults (request id + Scribe access log).
+         * Prefer this over {@link Builder.withHttpProvider} for application entrypoints.
+         */
+        withHttp<Thttp extends Constructable<HttpProvider>>(type: Thttp, options?: WithHttpOptions): Builder;
+        withControllers(...controllers: Constructable[]): Builder;
+        /**
+         * Prefix every controller route (`/api` makes `/lp/portfolio` into `/api/lp/portfolio`).
+         * It covers controller routes only: not static mounts (`withStatic`), not the OpenAPI
+         * document, and not a controller declared with `@Controller({ globalPrefix: false })`,
+         * such as the `withHealth()` probes, which platforms expect at the root. With a prefix
+         * set, the static fallback treats everything under it as the API.
+         */
+        withGlobalPrefix(prefix: string): Builder;
+        withCors(options: CorsOptions): Builder;
+        /**
+         * Override or disable default `@fastify/helmet` headers.
+         * Defaults are on with `withHttpProvider`; pass `false` to disable.
+         */
+        withHelmet(options?: HelmetOptions): Builder;
+        /**
+         * Override or disable default `@fastify/rate-limit` (100 req / 1 minute).
+         * Pass `false` to disable.
+         */
+        withRateLimit(options?: RateLimitOptions): Builder;
+        /**
+         * Compress responses with `br` or `gzip` when the client accepts it, using `@fastify/compress`
+         * with best-practice defaults (on by default, 1 KB threshold, no `deflate`). Pass `false` to
+         * turn it off, or `{ threshold, encodings, types, providerOptions }` to override. The plugin
+         * does not compress `text/event-stream` by default. Compressing a response that mixes a secret
+         * with input an attacker controls can leak the secret over HTTPS (BREACH); see ADR 0008.
+         */
+        withCompression(options?: CompressionOptions): Builder;
+        /**
+         * Override the default request body size limit (1 MiB).
+         */
+        withBodyLimit(bytes: number): Builder;
+        withMiddleware(...middlewares: Constructable<Middleware>[]): Builder;
+        withExceptionFilters(...filters: Constructable<ExceptionFilter>[]): Builder;
+        withOpenApi(options: OpenApiOptions): Builder;
+        /**
+         * Serve a built UI (a folder of static files) from this API, for example
+         * `.withStatic("/ui/", "ui")`. The directory is resolved from the process working
+         * directory, like `./config`. The files are public: they are served before auth,
+         * validation and middleware, and outside the rate limit. An unknown path under the prefix
+         * serves `index.html` to a browser (`Accept: text/html`) so client routes survive a reload. `"/"` mounts it at the root. Hashed assets are cached for a
+         * year, `index.html` is not cached. See {@link StaticOptions}.
+         */
+        withStatic(prefix: string, directory: string, options?: StaticOptions): Builder;
+    }
+}
+export declare class BuilderExtensions {
+    static withHttpProvider<Thttp extends Constructable<HttpProvider>>(builder: Builder, type: Thttp): Builder<import("@decohere/http").App>;
+    static withHttp<Thttp extends Constructable<HttpProvider>>(builder: Builder, type: Thttp, options?: WithHttpOptions): Builder<import("@decohere/http").App>;
+    static withControllers(builder: Builder, ...controllers: Constructable[]): Builder<import("@decohere/http").App>;
+    static withGlobalPrefix(builder: Builder, prefix: string): Builder<import("@decohere/http").App>;
+    static withCors(builder: Builder, options: CorsOptions): Builder<import("@decohere/http").App>;
+    static withHelmet(builder: Builder, options?: HelmetOptions): Builder<import("@decohere/http").App>;
+    static withRateLimit(builder: Builder, options?: RateLimitOptions): Builder<import("@decohere/http").App>;
+    static withCompression(builder: Builder, options?: CompressionOptions): Builder<import("@decohere/http").App>;
+    static withBodyLimit(builder: Builder, bytes: number): Builder<import("@decohere/http").App>;
+    static withMiddleware(builder: Builder, ...middlewares: Constructable<Middleware>[]): Builder<import("@decohere/http").App>;
+    static withExceptionFilters(builder: Builder, ...filters: Constructable<ExceptionFilter>[]): Builder<import("@decohere/http").App>;
+    static withOpenApi(builder: Builder, options: OpenApiOptions): Builder<import("@decohere/http").App>;
+    static withStatic(builder: Builder, prefix: string, directory: string, options?: StaticOptions): Builder<import("@decohere/http").App>;
+}

package/types/src/http/http.options.d.ts

@@ -0,0 +1,39 @@
+import type { Constructable } from "@decohere/core/reflection";
+import type { OpenApiOptions } from "../openapi/openapi.types.js";
+import type { CorsOptions } from "../routing/anvil.types.js";
+import type { ExceptionFilter } from "../routing/filters/exception-filter.js";
+import type { Middleware } from "../routing/middleware/middleware.js";
+import type { CompressionOptions } from "./http.compression.js";
+import type { StaticMount } from "./http.static.js";
+import type { HelmetOptions, RateLimitOptions } from "./http.security.js";
+/** Options for {@link Builder.withHttp} (request-id / access-log defaults, etc.). */
+export type WithHttpOptions = {
+    /**
+     * Register {@link HttpAccessLogMiddleware} (request id echo + Scribe access log).
+     * Defaults to `true`.
+     */
+    accessLog?: boolean;
+};
+/** App-level HTTP options set via builder extensions (`withCors`, `withGlobalPrefix`, …). */
+export declare class HttpOptions {
+    globalPrefix: string;
+    /**
+     * Controllers put under the global prefix although they declare `globalPrefix: false`
+     * (`withHealth({ underGlobalPrefix: true })`).
+     */
+    readonly underGlobalPrefix: Set<Constructable>;
+    cors?: CorsOptions;
+    openapi?: OpenApiOptions;
+    /** `undefined` = helmet on with defaults; `false` = off; object = plugin options. */
+    helmet?: HelmetOptions;
+    /** `undefined` = rate-limit on with defaults; `false` = off; object = plugin options. */
+    rateLimit?: RateLimitOptions;
+    /** `undefined` = compression on with defaults; `false` = off; object = options. See `withCompression`. */
+    compression?: CompressionOptions;
+    /** Request body size limit in bytes; `undefined` uses the 1 MiB default. */
+    bodyLimit?: number;
+    /** Built UIs served from this API, see `withStatic`. */
+    statics: StaticMount[];
+    middlewareTypes: Constructable<Middleware>[];
+    filterTypes: Constructable<ExceptionFilter>[];
+}

package/types/src/http/http.options.store.d.ts

@@ -0,0 +1,7 @@
+import type { Builder } from "../builder/builder.js";
+import { HttpOptions } from "./http.options.js";
+/**
+ * The {@link HttpOptions} a builder collects through its extensions. Internal: lets extensions
+ * outside `http.extensions.ts` (`withHealth`) set an option without a public builder method.
+ */
+export declare function getOrCreateHttpOptions(builder: Builder): HttpOptions;

package/types/src/http/http.security.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Default HTTP security settings applied by {@link FastifyProvider} when
+ * `withHttpProvider` is used. Override via `withHelmet` / `withRateLimit` /
+ * `withBodyLimit` (pass `false` to disable helmet or rate-limit).
+ */
+/** Fastify body size limit (bytes). Matches Fastify's built-in default, made explicit and overridable. */
+export declare const DEFAULT_HTTP_BODY_LIMIT = 1048576;
+/** Global request rate limit applied unless disabled or customized. */
+export declare const DEFAULT_HTTP_RATE_LIMIT: {
+    readonly max: 100;
+    readonly timeWindow: "1 minute";
+};
+/** `false` disables the plugin; an object customizes `@fastify/helmet`. */
+export type HelmetOptions = false | Record<string, unknown>;
+/** `false` disables the plugin; an object customizes `@fastify/rate-limit`. */
+export type RateLimitOptions = false | {
+    max?: number;
+    timeWindow?: number | string;
+    [key: string]: unknown;
+};

package/types/src/http/http.static.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Serving a module's built UI from its API (`builder.withStatic`). Everything here is
+ * provider-neutral: the options, the caching rules and the missing-directory policy.
+ * Only the HTTP provider knows how to put files on the wire. See ADR 0007.
+ */
+/** Cache header for files whose name carries a content hash. The name changes when the content does. */
+export declare const STATIC_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/** Cache header for files that must be revalidated on every use (the entry points of a UI). */
+export declare const STATIC_NO_CACHE_CONTROL = "no-cache";
+/** Cache header for every other file: cacheable, but always revalidated (ETag / Last-Modified). */
+export declare const STATIC_DEFAULT_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+/**
+ * The entry points of a UI. `index.html` names the hashed bundles, and a module-federation host
+ * loads `remoteEntry.js` by a fixed name to find the current remote, so neither can be cached.
+ */
+export declare const STATIC_DEFAULT_NO_CACHE: readonly string[];
+/**
+ * A build tool's hashed file name: `index-DiwrgTda.js`, `chunk.3f9a8c1b.css`, `app-abc123de.js.map`.
+ * The hash is 8 or more letters, digits or `_` after a `-` or `.`, and holds a digit or a lowercase
+ * letter followed by an uppercase one. Plain words (`logo-background.png`) are not hashes.
+ */
+export declare const STATIC_DEFAULT_IMMUTABLE: RegExp;
+export type StaticOptions = {
+    /**
+     * Serve `index.html` for an unknown path under the prefix, so a client-side route survives a
+     * reload. Only for GET and HEAD, and never for a path that looks like a file (has an
+     * extension), so a missing asset stays a 404. Defaults to `true`.
+     */
+    spaFallback?: boolean;
+    /**
+     * Path patterns this mount never answers, neither a file nor the fallback: the request gets the
+     * normal JSON 404. Globs on the full request path (not relative to the prefix), for example
+     * `["/api/**", "/docs/**"]`: `*` is any run of characters inside one segment, `**` crosses
+     * segments, `?` is one character. `/api/**` also covers `/api` itself. Rarely needed: a path
+     * that starts with the first segment of a registered controller route is already never
+     * answered with the fallback (see `staticFiles.isUnderRoute`).
+     */
+    exclude?: string[];
+    /** The file served for the prefix itself and for the fallback. Defaults to `index.html`. */
+    index?: string;
+    /**
+     * Files sent with `Cache-Control: no-cache`, by file name (`index.html`) or by path relative to
+     * the directory (`remote/remoteEntry.js`). Replaces the default `["index.html", "remoteEntry.js"]`,
+     * so list `index.html` again if you override it.
+     */
+    noCache?: string[];
+    /**
+     * Files whose name holds a content hash get `public, max-age=31536000, immutable`. Replace the
+     * pattern if your build names files differently (it is tested against the path relative to the
+     * directory), or pass `false` to give no file the immutable header.
+     */
+    immutable?: RegExp | false;
+    /** `Cache-Control` for every other file. Defaults to `public, max-age=0, must-revalidate`. */
+    cacheControl?: string;
+    /**
+     * What to do when the directory does not exist at start. `"fail"` stops the app with an error;
+     * `"warn"` logs a warning and serves nothing, so the API still boots before the UI is built.
+     * Defaults to `"warn"` when NODE_ENV is `development` or `dev`, and to `"fail"` otherwise.
+     */
+    onMissingDirectory?: "fail" | "warn";
+};
+/** A `withStatic` call, as the builder keeps it. */
+export type StaticMount = {
+    /** Normalised: starts and ends with `/`, for example `/ui/`. */
+    prefix: string;
+    /** As given by the caller, resolved from the process working directory when the app starts. */
+    directory: string;
+    options: StaticOptions;
+};
+/** A mount the provider can register: the directory exists and every option has its value. */
+export type ResolvedStaticMount = {
+    prefix: string;
+    /** Absolute path of the directory. */
+    root: string;
+    spaFallback: boolean;
+    index: string;
+    noCache: readonly string[];
+    immutable: RegExp | false;
+    cacheControl: string;
+    exclude: readonly string[];
+};
+declare function toMount(prefix: string, directory: string, options?: StaticOptions): StaticMount;
+type DirectoryProbe = (absolutePath: string) => Promise<boolean>;
+export type ResolveStaticOptions = {
+    /** Where relative directories are resolved from. Defaults to the process working directory. */
+    cwd?: string;
+    nodeEnv?: string;
+    directoryExists: DirectoryProbe;
+    warn: (message: string) => void;
+};
+/**
+ * Checks every mount at start. Returns the ones that can be served; a missing directory fails or
+ * warns according to the mount's `onMissingDirectory`. Two mounts on one prefix always fail.
+ */
+declare function resolve(mounts: readonly StaticMount[], env: ResolveStaticOptions): Promise<ResolvedStaticMount[]>;
+/** `Cache-Control` for a file, given its path relative to the mount's directory. */
+declare function cacheControlFor(mount: ResolvedStaticMount, relativePath: string): string;
+/**
+ * Does this path look like a file: an extension on the last segment, or a dotfile anywhere?
+ * Then a miss is a real 404, not a client-side route.
+ */
+declare function looksLikeFile(pathname: string): boolean;
+/** The request path as the mount sees it: no query, decoded, repeated slashes collapsed. */
+declare function normalizePathname(url: string): string;
+/** Builds the test for a mount's `exclude` patterns. Matches on the normalised path. */
+declare function excluder(patterns: readonly string[]): (pathname: string) => boolean;
+/**
+ * The first path segment of every registered route, for {@link isUnderRoute}. A segment that is a
+ * parameter or wildcard (`:id`, `*`) says nothing about the path and is skipped.
+ */
+declare function routeSegments(routePaths: Iterable<string>): Set<string>;
+/**
+ * Is this path under one of the app's own routes? True when its first segment is the first
+ * segment of a registered route: with a controller route `/lp/portfolio`, `/lp/portfolo` and
+ * `/lp/anything/else` belong to the API and keep the JSON 404, while `/lpx` does not.
+ */
+declare function isUnderRoute(pathname: string, segments: ReadonlySet<string>): boolean;
+/**
+ * What the fallback treats as the API, as a test on the normalised path. With a global prefix it
+ * is the prefix, the OpenAPI path and every route left outside the prefix
+ * (`@Controller({ globalPrefix: false })`, such as `/health`), each with the paths below it, so a
+ * client route may share a first segment with a controller. Without a prefix it is
+ * {@link isUnderRoute} (the first segment of every registered route), the safe guess when nothing
+ * says where the API lives.
+ */
+declare function apiBoundary(boundary: {
+    /** Normalised global prefix (`/api`), or `""` when there is none. */
+    globalPrefix: string;
+    openApiPath?: string;
+    /** Every registered route path, global prefix included. */
+    routePaths: Iterable<string>;
+}): (pathname: string) => boolean;
+/** Does the `Accept` header ask for HTML (a browser navigation)? `text/html;q=0` does not. */
+declare function acceptsHtml(accept: string | undefined): boolean;
+export type FallbackRequest = {
+    method: string;
+    /** Normalised, see `normalizePathname`. */
+    pathname: string;
+    accept: string | undefined;
+};
+/**
+ * Should an unknown path get the app's `index.html`? Only a browser navigation: GET or HEAD, no
+ * file extension and no dotfile in the path, an `Accept` that includes `text/html`, and not under
+ * the API (see {@link apiBoundary}). Everything else keeps the normal JSON 404.
+ */
+declare function shouldFallBack(request: FallbackRequest, belongsToApi: (pathname: string) => boolean): boolean;
+export declare const staticFiles: {
+    toMount: typeof toMount;
+    resolve: typeof resolve;
+    cacheControlFor: typeof cacheControlFor;
+    looksLikeFile: typeof looksLikeFile;
+    normalizePathname: typeof normalizePathname;
+    excluder: typeof excluder;
+    routeSegments: typeof routeSegments;
+    isUnderRoute: typeof isUnderRoute;
+    apiBoundary: typeof apiBoundary;
+    acceptsHtml: typeof acceptsHtml;
+    shouldFallBack: typeof shouldFallBack;
+};
+export {};

package/types/src/http/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./http.compression.js";
+export * from "./http.extensions.js";
+export * from "./http.options.js";
+export * from "./http.security.js";
+export * from "./http.static.js";

package/types/src/index.d.ts

@@ -0,0 +1,10 @@
+export type { StartOptions } from "./app/index.js";
+export * from "./app/index.js";
+export * from "./auth/index.js";
+export * from "./builder/index.js";
+export * from "./const.js";
+export * from "./health/index.js";
+export * from "./hosting/index.js";
+export * from "./openapi/index.js";
+export * from "./routing/index.js";
+export * from "./sse/index.js";

package/types/src/openapi/index.d.ts

@@ -0,0 +1,6 @@
+export type { ValidationIssue } from "../routing/anvil.types.js";
+export { generateOpenApiDocument, resolveOpenApiPath, toOpenApiPath, } from "./openapi.generator.js";
+export type { JsonSchema, OpenApiDocument, OpenApiOperation, OpenApiOptions, OpenApiParameter, } from "./openapi.types.js";
+export type { RouteRequestSchemas } from "./request-schema.js";
+export { buildRouteRequestSchemas, mergeObjectSchemas, objectArgToParts, pathParamsToSchema, typeToSchema, } from "./request-schema.js";
+export { ValidationError, validateRequest } from "./request-validator.js";

package/types/src/openapi/openapi.generator.d.ts

@@ -0,0 +1,6 @@
+import type { RouteRegistry } from "../routing/services/route-registry.js";
+import type { OpenApiDocument, OpenApiOptions } from "./openapi.types.js";
+export declare function resolveOpenApiPath(options: OpenApiOptions): string;
+/** Convert Fastify-style `:id` path params to OpenAPI `{id}`. */
+export declare function toOpenApiPath(fastifyPath: string): string;
+export declare function generateOpenApiDocument(registry: RouteRegistry, options: OpenApiOptions): OpenApiDocument;

package/types/src/openapi/openapi.types.d.ts

@@ -0,0 +1,58 @@
+export type OpenApiInfo = {
+    title: string;
+    version: string;
+    description?: string;
+};
+export type OpenApiServer = {
+    url: string;
+    description?: string;
+};
+export type OpenApiOptions = {
+    /** Defaults to `/openapi.json`. Absolute Fastify path (not affected by globalPrefix). */
+    path?: string;
+    info: OpenApiInfo;
+    servers?: OpenApiServer[];
+    /** When true (default), validate request params/query/body before the handler. */
+    validateRequests?: boolean;
+};
+export type JsonSchema = {
+    type?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    additionalProperties?: boolean | JsonSchema;
+    format?: string;
+    description?: string;
+    minLength?: number;
+    maxLength?: number;
+};
+export type OpenApiParameter = {
+    name: string;
+    in: "query" | "path" | "header" | "cookie";
+    required?: boolean;
+    schema?: JsonSchema;
+};
+export type OpenApiOperation = {
+    operationId?: string;
+    summary?: string;
+    tags?: string[];
+    parameters?: OpenApiParameter[];
+    requestBody?: {
+        required?: boolean;
+        content: Record<string, {
+            schema: JsonSchema;
+        }>;
+    };
+    responses: Record<string, {
+        description: string;
+        content?: Record<string, {
+            schema: JsonSchema;
+        }>;
+    }>;
+};
+export type OpenApiDocument = {
+    openapi: "3.0.3";
+    info: OpenApiInfo;
+    servers?: OpenApiServer[];
+    paths: Record<string, Partial<Record<string, OpenApiOperation>>>;
+};

package/types/src/openapi/request-schema.d.ts

@@ -0,0 +1,21 @@
+import { type MappedRoute, type RouteArg } from "../routing/anvil.types.js";
+import type { JsonSchema, OpenApiParameter } from "./openapi.types.js";
+/**
+ * Request shapes derived from route / `@Field` metadata (same source as OpenAPI).
+ * Used by the document generator and the AJV request validator.
+ */
+export type RouteRequestSchemas = {
+    queryParams: OpenApiParameter[];
+    pathParams: OpenApiParameter[];
+    body?: JsonSchema;
+};
+export declare function buildRouteRequestSchemas(route: MappedRoute): RouteRequestSchemas;
+export declare function objectArgToParts(routeArg: RouteArg): {
+    queryParams: OpenApiParameter[];
+    pathParams: OpenApiParameter[];
+    body?: JsonSchema;
+};
+export declare function mergeObjectSchemas(a: JsonSchema | undefined, b: JsonSchema): JsonSchema;
+export declare function typeToSchema(typeName?: string): JsonSchema;
+/** JSON Schema object for required path params (HTTP path values are always strings). */
+export declare function pathParamsToSchema(params: OpenApiParameter[]): JsonSchema | undefined;

package/types/src/openapi/request-validator.d.ts

@@ -0,0 +1,9 @@
+import type { HttpRequest, MappedRoute, ValidationIssue } from "../routing/anvil.types.js";
+import { ValidationError } from "../routing/anvil.types.js";
+export type { ValidationIssue };
+export { ValidationError };
+/**
+ * Fail-closed request validation from route / OpenAPI / `@Field` metadata.
+ * Uses AJV against the same schemas as the OpenAPI generator (no type coercion).
+ */
+export declare function validateRequest(route: MappedRoute, request: HttpRequest): void;

package/types/src/providers/fastify.provider.d.ts

@@ -0,0 +1,56 @@
+import { type FastifyInstance } from "fastify";
+import type { HttpOptions } from "../http/http.options.js";
+import { type HttpProvider, type StartOptions, type StartResponse, type StopResponse } from "../routing/anvil.types.js";
+import { type ExceptionFilterHost } from "../routing/filters/exception-filter-host.js";
+import type { RouteRegistry } from "../routing/services/route-registry.js";
+import type { Router } from "../routing/services/router.js";
+export declare class FastifyProvider implements HttpProvider {
+    readonly provider: FastifyInstance;
+    readonly router: Router;
+    private readonly routeRegistry;
+    private readonly httpOptions?;
+    private readonly exceptionFilterHost?;
+    private closing;
+    private readonly logger;
+    /** One per live `@Sse()` request, so stopping the app can end the streams. */
+    private readonly openStreams;
+    constructor(routeRegistry?: RouteRegistry, router?: Router, httpOptions?: HttpOptions, exceptionFilterHost?: ExceptionFilterHost);
+    start<T extends StartOptions>(options?: T): Promise<StartResponse>;
+    stop(): Promise<StopResponse>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Once stopping, tell clients to drop the connection after their response. Otherwise
+     * a request that was in flight leaves a kept-alive socket that holds `close()` open
+     * until Node's keep-alive timeout (5s).
+     */
+    private closeConnectionsWhileStopping;
+    get addresses(): string[];
+    private registerHelmet;
+    private registerRateLimit;
+    private resolveStatics;
+    /**
+     * One encapsulated context per mount: its not-found handler (the SPA fallback) applies to
+     * paths under the prefix and nowhere else, so an API 404 is never answered with the UI.
+     */
+    private registerStatic;
+    /** What the static fallback leaves to the API: the global prefix, else the registered routes. ADR 0007. */
+    private apiBoundary;
+    /**
+     * `@fastify/compress` with best-practice defaults; the plugin owns the policy. Registered
+     * before any route so every response goes through it, errors and static files included.
+     * `providerOptions` is merged last, so a user can override any plugin option.
+     */
+    private registerCompression;
+    private registerCors;
+    private registerOpenApi;
+    private registerAllRoutes;
+    private routeRequest;
+    /**
+     * Gives the handler a signal that aborts when the client goes away before the response
+     * finished. Streams are also tracked so that stopping the app can abort them.
+     */
+    private abortOnDisconnect;
+    private sendEventStream;
+    private applyResponseHeaders;
+    private fastifyToRequest;
+}

package/types/src/providers/index.d.ts

@@ -0,0 +1 @@
+export * from "./fastify.provider.js";