@databehave/openapi 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [Unreleased]
+
+Upcoming package version: **0.1.0**. This section describes planned release contents, not a published release.
+
+### Runtime requirements
+
+- Require Node.js 24 or 26; support and test majors 24 and 26. Node.js 18, 20 and 22 are unsupported.
+
+### Added
+
+- Explicit operation catalog, selectable response-generator providers, request validation and mock-status plugins.
+- Separate `/schema` adapter receiving builders and a runtime explicitly; the default entry does not import schema.
+- Selected declared success statuses, bodyless status handling and shared response generation for fault injection.
+- Incremental request-body limits, required-body checks and problem-response documentation.
+
+See [migration](../../MIGRATION.md) and [release procedures](../../docs/releasing.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ochairo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @databehave/openapi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Requires Node.js 24 or 26; supported majors are 24 and 26. See the
+[plugin author guide](../../docs/plugins.md) and [migration guide](../../MIGRATION.md).
+
+Explicit OpenAPI catalog, generation, request validation and mock-status plugins for Databehave.
+The default entry point never imports the schema package at runtime or in its public declarations.
+
+```ts
+import { readFile } from 'node:fs/promises'
+import { createHost } from '@databehave/core'
+import { httpPlugin, nodeHttpPlugin } from '@databehave/server'
+import {
+  openapiPlugin, placeholderGeneratorPlugin, requestValidationPlugin, mockModePlugin,
+} from '@databehave/openapi'
+
+const host = createHost({ plugins: [
+  httpPlugin(),
+  placeholderGeneratorPlugin(),
+  openapiPlugin({ document: await readFile('./openapi.json', 'utf8') }),
+  requestValidationPlugin({ maxBodyBytes: 102400 }),
+  mockModePlugin({ allowHeaderOverride: true }),
+  nodeHttpPlugin({ port: 3000 }),
+] })
+await host.start()
+// await host.close() when the application shuts down.
+```
+
+`document` is raw JSON text. Filesystem/network loading belongs to the application; YAML must be converted before
+composition. Parsing and generator compilation happen during preparation, before HTTP materializes routes or opens
+listeners. The operation catalog owns method/path matching and response status selection. Exact paths precede
+parameterized paths; parameterized ties retain document declaration order. HTTP explicit routes replace generated
+routes with the same key.
+
+`openapiCapability` provides the parsed document, operations, `find(method, path)` and
+`body(operation, status, request)`. Responses use 200 when declared, otherwise the lowest declared 2xx, defaulting
+to 200 if none is declared. Only exact numeric status keys and `application/json` response schemas generate bodies.
+204, 205 and 304 have no generated body. Unsupported nonnumeric/default/range statuses do not select a schema.
+GET/HEAD without a schema use `{}`; other methods use `{ success: true, message: null }`.
+
+Placeholder generation uses deterministic structural values such as `"string"`, `0` and `false`.
+Unsupported placeholder schemas report `onWalkError` and fall back to a stub. Permissive success schemas report
+`onEmptySchema`. A response is compiled once per operation/status; injection and ordinary routes share its generator.
+
+For schema generation, replace `placeholderGeneratorPlugin()` with the optional adapter:
+
+```ts
+import * as builders from '@databehave/schema'
+import { createSchemaRuntime, standardKinds, standardBehaviors } from '@databehave/schema'
+import { schemaGeneratorPlugin } from '@databehave/openapi/schema'
+
+const runtime = createSchemaRuntime({ kinds: standardKinds, behaviors: standardBehaviors })
+const provider = schemaGeneratorPlugin({ builders, runtime, seed: 'stable' })
+```
+
+The adapter receives builders and a runtime explicitly. It never resolves another schema implementation internally.
+`seed` accepts a number, `'stable'` (default: operation, sorted query and path parameters), or `'random'` (per request).
+Schema generation rejects unsupported response schemas during startup, including schemas for injected error statuses.
+The translator retains bounds, formats, nullable/optional fields, object/array/union/discriminator shapes, local
+references and examples. Request conformance remains separate: generation is not a validator. Exclusive numeric
+bounds retain the existing inclusive approximation in generation; conformance enforces exclusive bounds exactly.
+
+An external provider can provide `openapiGeneratorCapability` using the public core `Plugin` protocol, or a different
+`Capability<OpenApiGenerator>` selected with `openapiPlugin({ document, generator: token })`.
+Its `compile(schema, { document, operation, status })` returns a request body function, optionally asynchronously.
+`failureMode: 'throw'` rejects startup; `'fallback'` emits diagnostics and preserves stub behavior.
+Do not also include a second provider for the same capability.
+
+Request validation is opt-in through `requestValidationPlugin()`. It retains body/parameter conformance, parameter
+coercion, local references, size checks and presence checks for declared security schemes. HEAD fallback validates the
+GET contract. Failures produce problem JSON with 400/401/413/415/422; HTTP applies decorators and observes the outcome.
+Security checks establish declared credential presence, not token authenticity.
+
+Problem response references: [400](../../docs/errors/malformed-body.md),
+[401](../../docs/errors/unauthorized.md), [413](../../docs/errors/payload-too-large.md),
+[415](../../docs/errors/unsupported-media-type.md), [422](../../docs/errors/request-validation.md).
+
+Declared request bodies are read incrementally with a UTF-8 byte limit before JSON parsing. `maxBodyBytes` defaults
+to 102400 and must be a nonnegative safe integer; zero permits no body bytes. Overflow returns 413 before EOF and
+cancels both validation and original request streams; read failures or aborts return 400. Successful validation leaves
+the original body readable by the handler. Required-body presence is checked even without a schema, including declared
+OPTIONS bodies. JSON media declarations still require valid JSON without a schema; non-JSON bodies retain presence
+and size checks. A `pattern` requires a finite nonnegative integer `maxLength` on the same schema node; oversized
+strings report a length violation without executing that regex.
+
+`mockModePlugin()` enables status selection by method/path override, path override, then default status. Incoming
+status headers require `allowHeaderOverride: true`. Health paths bypass injection/tagging. A selected numeric status
+uses the same catalog and generator as normal responses; a missing body schema uses `{ error: true, status }`.
+
+Migration changes: import these features from `@databehave/openapi`, compose an explicit provider, and pass JSON text
+through `document`. Generated routes now return their selected declared success status (201 stays 201; 204/205 are
+empty), root operations are registered, HEAD/OPTIONS operations are supported, malformed non-object documents are
+rejected early, and error-status generation follows the selected provider. Removed JSONC `enabled`, `locale` and
+`arrayCount` schema knobs are not part of this API; the latter two had no generation effect.

package/dist/catalog.d.ts

@@ -0,0 +1,51 @@
+import type { Method, MockRequest, RouteKey } from '@databehave/server';
+import type { OasDoc, OasNode } from './openapi/walker.js';
+/** One declared numeric response; permissive or absent schemas have no generator. */
+export interface OpenApiResponse {
+    readonly status: number;
+    readonly schema?: OasNode;
+}
+/** One parsed operation shared by routes, request conformance and status injection. */
+export interface OpenApiOperation {
+    readonly key: RouteKey;
+    readonly method: Method;
+    readonly path: string;
+    readonly sourcePath: string;
+    readonly definition: Readonly<Record<string, unknown>>;
+    readonly pathParameters: readonly unknown[];
+    readonly responses: readonly OpenApiResponse[];
+    /** Preferred success schema source: 200, then the smallest declared 2xx. */
+    readonly successStatus: number;
+}
+/** Per-request body generator prepared once for a declared operation and status. */
+export type OpenApiBodyGenerator = (request: MockRequest) => unknown;
+/** Compilation input owned by the catalog; providers must not enumerate operations themselves. */
+export interface OpenApiGenerationContext {
+    readonly document: OasDoc;
+    readonly operation: OpenApiOperation;
+    readonly status: number;
+}
+/** Replaceable response generation policy. Schema generation fails startup; placeholders allow stubs. */
+export interface OpenApiGenerator {
+    readonly failureMode: 'throw' | 'fallback';
+    compile(schema: OasNode, context: OpenApiGenerationContext): OpenApiBodyGenerator | Promise<OpenApiBodyGenerator>;
+}
+/** Parsed catalog and prepared generators, available after the preparation barrier. */
+export interface OpenApiCatalog {
+    readonly document: OasDoc;
+    readonly operations: readonly OpenApiOperation[];
+    find(method: string, path: string): OpenApiOperation | undefined;
+    body(operation: OpenApiOperation, status: number, request: MockRequest): unknown;
+}
+export declare const openapiCapability: import("@databehave/core").Capability<OpenApiCatalog>;
+export declare const openapiGeneratorCapability: import("@databehave/core").Capability<OpenApiGenerator>;
+/** Diagnostics for fallback placeholder generation and permissive success schemas. */
+export interface OpenApiDiagnostics {
+    readonly onWalkError?: (method: Method, path: string, error: unknown) => void;
+    readonly onEmptySchema?: (method: Method, path: string, status: number) => void;
+}
+/** Parse operation identities and status selection exactly once per document. */
+export declare const readOperations: (document: OasDoc) => readonly OpenApiOperation[];
+/** Prepare one immutable catalog, compiling each operation/status only once. */
+export declare const prepareCatalog: (document: OasDoc, generator: OpenApiGenerator, diagnostics?: OpenApiDiagnostics) => Promise<OpenApiCatalog>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAEvE,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE1D,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACtD,QAAQ,CAAC,cAAc,EAAE,SAAS,OAAO,EAAE,CAAA;IAC3C,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAA;IAC9C,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAA;AAEpE,kGAAkG;AAClG,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,yGAAyG;AACzG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,OAAO,GAAG,UAAU,CAAA;IAC1C,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,GAAG,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;CAClH;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAChD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAA;IAChE,IAAI,CAAC,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAA;CACjF;AAED,eAAO,MAAM,iBAAiB,uDAAsD,CAAA;AACpF,eAAO,MAAM,0BAA0B,yDAAkE,CAAA;AAEzG,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CAChF;AAWD,iFAAiF;AACjF,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,KAAG,SAAS,gBAAgB,EAiC1E,CAAA;AAED,gFAAgF;AAChF,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,EAChB,WAAW,gBAAgB,EAC3B,cAAa,kBAAuB,KACnC,OAAO,CAAC,cAAc,CAkCxB,CAAA"}

package/dist/catalog.js

@@ -0,0 +1,90 @@
+import { capability } from '@databehave/core';
+import { matchPattern, parseRoutePattern } from '@databehave/server';
+export const openapiCapability = capability('databehave.openapi', 1);
+export const openapiGeneratorCapability = capability('databehave.openapi.generator', 1);
+const METHODS = ['get', 'post', 'put', 'delete', 'patch', 'head', 'options'];
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const hasShape = (node) => Boolean(node.$ref || node.type || node.enum || node.const !== undefined || node.example !== undefined || node.examples || node.properties ||
+    node.items || node.allOf || node.oneOf || node.anyOf);
+/** Parse operation identities and status selection exactly once per document. */
+export const readOperations = (document) => {
+    const operations = [];
+    for (const [sourcePath, item] of Object.entries(document.paths ?? {})) {
+        if (!isObject(item))
+            throw new Error(`OpenAPI path item must be an object: ${sourcePath}`);
+        const path = sourcePath.split('/').map(segment => /^\{[^{}]+\}$/.test(segment) ? `:${segment.slice(1, -1)}` : segment).join('/');
+        if (!path.startsWith('/'))
+            throw new Error(`OpenAPI path must start with '/': ${path}`);
+        parseRoutePattern(path);
+        for (const [methodName, definition] of Object.entries(item)) {
+            if (!METHODS.includes(methodName))
+                continue;
+            if (!isObject(definition))
+                throw new Error(`OpenAPI operation must be an object: ${methodName} ${path}`);
+            const method = methodName;
+            const responses = [];
+            const rawResponses = definition.responses;
+            if (isObject(rawResponses)) {
+                for (const [code, response] of Object.entries(rawResponses)) {
+                    if (!/^[1-5]\d\d$/.test(code))
+                        continue;
+                    const status = Number(code);
+                    const content = isObject(response) && isObject(response.content) ? response.content : undefined;
+                    const media = content?.['application/json'];
+                    const schema = isObject(media) && isObject(media.schema) ? media.schema : undefined;
+                    responses.push(Object.freeze({ status, ...(schema ? { schema } : {}) }));
+                }
+            }
+            const successStatus = responses.map(r => r.status).filter(status => status >= 200 && status < 300).sort((a, b) => a - b)[0] ?? 200;
+            operations.push(Object.freeze({
+                key: `${method.toUpperCase()} ${path}`, method, path, sourcePath,
+                definition, pathParameters: Array.isArray(item.parameters) ? item.parameters : [],
+                responses: Object.freeze(responses), successStatus,
+            }));
+        }
+    }
+    // HTTP resolves exact paths before parameterized paths; ties retain declaration order.
+    return Object.freeze(operations.sort((a, b) => Number(!parseRoutePattern(a.path).isStatic) - Number(!parseRoutePattern(b.path).isStatic)));
+};
+/** Prepare one immutable catalog, compiling each operation/status only once. */
+export const prepareCatalog = async (document, generator, diagnostics = {}) => {
+    const operations = readOperations(document);
+    const patterns = new Map(operations.map(operation => [operation, parseRoutePattern(operation.path)]));
+    const generators = new Map();
+    for (const operation of operations) {
+        const responses = new Map();
+        for (const { status, schema } of operation.responses) {
+            if (!schema || status === 204 || status === 205 || status === 304)
+                continue;
+            if (!hasShape(schema)) {
+                if (status === operation.successStatus)
+                    diagnostics.onEmptySchema?.(operation.method, operation.path, status);
+                if (generator.failureMode === 'fallback')
+                    continue;
+            }
+            try {
+                responses.set(status, await generator.compile(schema, { document, operation, status }));
+            }
+            catch (error) {
+                if (generator.failureMode === 'throw')
+                    throw error;
+                diagnostics.onWalkError?.(operation.method, operation.path, error);
+            }
+        }
+        generators.set(operation, responses);
+    }
+    return Object.freeze({
+        document,
+        operations,
+        find(method, path) {
+            return operations.find(operation => {
+                const pattern = patterns.get(operation);
+                return operation.method === method.toLowerCase() && pattern !== undefined && matchPattern(pattern, path) !== null;
+            });
+        },
+        body(operation, status, request) {
+            return generators.get(operation)?.get(status)?.(request);
+        },
+    });
+};
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { openapiPlugin, type OpenApiOptions } from './plugin.js';
+export { placeholderGeneratorPlugin, placeholderGenerator } from './placeholder.js';
+export { requestValidationPlugin, type RequestValidationOptions } from './request-validation-plugin.js';
+export { mockModePlugin, type MockModeOptions } from './mock-mode-plugin.js';
+export { openapiCapability, openapiGeneratorCapability } from './catalog.js';
+export type { OpenApiCatalog, OpenApiOperation, OpenApiResponse, OpenApiGenerator, OpenApiGenerationContext, OpenApiBodyGenerator, OpenApiDiagnostics } from './catalog.js';
+export type { OasDoc, OasNode } from './openapi/walker.js';
+export { parseOpenApi } from './openapi/loader.js';
+export { seedFor, type SeedInput } from './openapi/seed.js';
+export { resolveStatus, type MockModeLogger } from './mock-mode.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACnF,OAAO,EAAE,uBAAuB,EAAE,KAAK,wBAAwB,EAAE,MAAM,gCAAgC,CAAA;AACvG,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5E,OAAO,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAC5E,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAC3K,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { openapiPlugin } from './plugin.js';
+export { placeholderGeneratorPlugin, placeholderGenerator } from './placeholder.js';
+export { requestValidationPlugin } from './request-validation-plugin.js';
+export { mockModePlugin } from './mock-mode-plugin.js';
+export { openapiCapability, openapiGeneratorCapability } from './catalog.js';
+export { parseOpenApi } from './openapi/loader.js';
+export { seedFor } from './openapi/seed.js';
+export { resolveStatus } from './mock-mode.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAuB,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACnF,OAAO,EAAE,uBAAuB,EAAiC,MAAM,gCAAgC,CAAA;AACvG,OAAO,EAAE,cAAc,EAAwB,MAAM,uBAAuB,CAAA;AAC5E,OAAO,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAG5E,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,OAAO,EAAkB,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAuB,MAAM,gBAAgB,CAAA"}

package/dist/middleware/request-validation.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Inbound request-validation middleware (opt-in, zero-runtime-dep).
+ *
+ * Builds per-route validator descriptors from the OpenAPI document at
+ * server-start (build-time errors propagate up through the server
+ * boot). Per-request, validates body / path / query / header
+ * parameters and security against the schema and emits an RFC 7807
+ * `application/problem+json` envelope on violation.
+ *
+ * Status mapping:
+ *   400 — malformed JSON body or interrupted/failed body read
+ *   401 — required security scheme not satisfied
+ *   413 — request body exceeds the byte limit
+ *   415 — request body content-type not declared by the spec
+ *   422 — semantic validation failure (one or more `violations`)
+ *
+ * Body coercion: body validation is strict (no coercion) — mirroring
+ * how a real client/server pair speaks JSON. Path / query / header
+ * parameters arrive as strings on the wire, so they are coerced
+ * (integer / number / boolean) before validation.
+ */
+import type { OpenApiCatalog } from '../catalog.js';
+import { type RoutePattern } from '@databehave/server';
+import { type Validator } from '../validation/validate.js';
+/** Prepared OpenAPI ParamSpec metadata. */
+interface ParamSpec {
+    readonly name: string;
+    readonly in: 'query' | 'path' | 'header';
+    readonly required: boolean;
+    readonly type: string | null;
+    readonly validator: Validator;
+}
+/** Prepared OpenAPI RouteValidator metadata. */
+interface RouteValidator {
+    readonly key: string;
+    readonly pattern: RoutePattern;
+    readonly hasBody: boolean;
+    readonly hasJsonBody: boolean;
+    readonly bodyOnlyJson: boolean;
+    readonly bodyRequired: boolean;
+    readonly bodyValidator: Validator | null;
+    readonly params: readonly ParamSpec[];
+    readonly security: readonly Readonly<Record<string, readonly string[]>>[];
+}
+/** Prepared OpenAPI SecurityScheme metadata. */
+interface SecurityScheme {
+    readonly type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect';
+    readonly scheme?: string;
+    readonly in?: 'header' | 'query' | 'cookie';
+    readonly name?: string;
+}
+/** Prepared conformance checks attached to the authoritative operation catalog. */
+export interface RequestValidationContext {
+    readonly catalog: OpenApiCatalog;
+    readonly routes: readonly RouteValidator[];
+    readonly schemes: ReadonlyMap<string, SecurityScheme>;
+    /** Hard cap on declared body size in bytes (UTF-8). Default 100 KB. */
+    readonly maxBodyBytes: number;
+}
+export declare const createRequestValidationContext: (catalog: OpenApiCatalog, options?: {
+    readonly maxBodyBytes?: number;
+}) => RequestValidationContext;
+export declare const validateRequest: (req: Request, ctx: RequestValidationContext, effectiveMethod?: string) => Promise<Response | null>;
+export {};
+//# sourceMappingURL=request-validation.d.ts.map

package/dist/middleware/request-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-validation.d.ts","sourceRoot":"","sources":["../../src/middleware/request-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,OAAO,EAAmC,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACvF,OAAO,EAAoB,KAAK,SAAS,EAAkB,MAAM,2BAA2B,CAAA;AA8B5F,2CAA2C;AAC3C,UAAU,SAAS;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;CAC9B;AAED,gDAAgD;AAChD,UAAU,cAAc;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,aAAa,EAAE,SAAS,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,EAAE,CAAA;CAC1E;AAED,gDAAgD;AAChD,UAAU,cAAc;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,CAAA;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,mFAAmF;AACnF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;IAC1C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IACrD,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAiCD,eAAO,MAAM,8BAA8B,GACzC,SAAS,cAAc,EACvB,UAAS;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,KAC/C,wBAgFF,CAAA;AA6ID,eAAO,MAAM,eAAe,GAC1B,KAAK,OAAO,EACZ,KAAK,wBAAwB,EAC7B,wBAA4B,KAC3B,OAAO,CAAC,QAAQ,GAAG,IAAI,CA2HzB,CAAA"}