@openaddresses/batch-schema 10.24.1 → 10.26.0

package/lib/schema.ts

@@ -13,6 +13,7 @@ import { Ajv } from 'ajv'
 import type { ErrorObject } from 'ajv'
 import addFormatsModule from 'ajv-formats'
 import type { RequestValidation } from './types.js';
+import { normalizeBody, matchContentType } from './types.js';
 import type { OpenAPIDocumentInput } from './openapi.js'
 import SchemaAPI from './api.js';
 import Docs from './openapi.js';
@@ -53,6 +54,67 @@ export default class Schemas {
         return new Err(400, null, `Validation Error ${String(method).toUpperCase()} ${path}`);
     }
 
+    /**
+     * Compile body validators keyed by content-type. Returns null when no
+     * body validation is configured. Each entry is either `true` (any body
+     * accepted for this content-type) or a compiled ajv validator function.
+     */
+    compileBodyValidators(
+        body: RequestValidation<TSchema, TSchema, TSchema, TSchema>['body']
+    ): Map<string, true | ReturnType<typeof ajv.compile>> | null {
+        const normalized = normalizeBody(body);
+        if (!normalized) return null;
+
+        const map = new Map<string, true | ReturnType<typeof ajv.compile>>();
+        for (const ct of Object.keys(normalized)) {
+            const schema = normalized[ct].schema;
+            if (schema === true || schema === undefined) {
+                map.set(ct, true);
+            } else {
+                map.set(ct, ajv.compile(schema));
+            }
+        }
+        return map;
+    }
+
+    /**
+     * Validate the incoming request body against the compiled validator
+     * map for the route. Pushes a Body error onto `errors` if validation
+     * fails; returns an Err to respond with for an unsupported content-type.
+     *
+     * If `bodyRequired` is false and the request has no body / no
+     * content-type, validation is skipped.
+     */
+    validateBody(
+        req: Request,
+        validators: Map<string, true | ReturnType<typeof ajv.compile>>,
+        errors: Array<ErrorListItem>,
+        opts: { required?: boolean } = {}
+    ): Err | null {
+        const raw = (req.headers['content-type'] || '').split(';')[0].trim().toLowerCase();
+        const required = opts.required !== false;
+
+        if (!raw && !required) return null;
+
+        const normalizedMap: Record<string, { schema: true }> = {};
+        for (const key of validators.keys()) normalizedMap[key] = { schema: true };
+        const matched = matchContentType(raw, normalizedMap);
+        const validator = matched ? validators.get(matched) : undefined;
+
+        if (!validator) {
+            const supported = Array.from(validators.keys()).join(', ');
+            return new Err(400, null, `Content-Type ${raw || '(none)'} not supported. Supported: ${supported}`);
+        }
+
+        if (validator !== true) {
+            if (!validator(req.body)) {
+                errors.push({ type: 'Body', errors: validator.errors as ErrorObject[] });
+            }
+        }
+
+        return null;
+    }
+
     constructor(
         router: Router,
         opts: {
@@ -74,8 +136,16 @@ export default class Schemas {
             this.router.use(morgan('combined', morganOptions));
         }
 
-        this.router.use(bodyparser.urlencoded({ extended: true }));
+        this.router.use(bodyparser.urlencoded({ extended: true, limit: `${opts.limit || 50}mb` }));
         this.router.use(bodyparser.json({ limit: `${opts.limit || 50}mb` }));
+        this.router.use(bodyparser.text({
+            limit: `${opts.limit || 50}mb`,
+            type: ['text/*', 'application/xml', 'application/*+xml']
+        }));
+        this.router.use(bodyparser.raw({
+            limit: `${opts.limit || 50}mb`,
+            type: ['application/octet-stream']
+        }));
 
         if (opts.error) {
             this.error = opts.error;
@@ -91,6 +161,15 @@ export default class Schemas {
         this.schemas = new Map();
     }
 
+    normalizeValidation<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
+        opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {}
+    ): RequestValidation<TParams, TQuery, TBody, TResponse> {
+        return {
+            deprecated: false,
+            ...opts
+        };
+    }
+
     async api() {
         await SchemaAPI(this);
     }
@@ -147,13 +226,15 @@ export default class Schemas {
         handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
     ) {
         try {
-            this.docs.push({ method: Doc.HttpMethods.GET, path: path }, opts);
-            this.schemas.set(`GET ${path}`, opts);
+            const validation = this.normalizeValidation(opts);
+
+            this.docs.push({ method: Doc.HttpMethods.GET, path: path }, validation);
+            this.schemas.set(`GET ${path}`, validation);
 
-            const resValidation = opts.res && !(opts.res instanceof Type.Any) && !(opts.res instanceof Type.Unknown) && ajv.compile(opts.res);
-            const paramsValidation = opts.params && ajv.compile(opts.params);
-            const queryValidation = opts.query && ajv.compile(opts.query);
-            if (opts.body) throw new Error(`Body not allowed`);
+            const resValidation = validation.res && !(validation.res instanceof Type.Any) && !(validation.res instanceof Type.Unknown) && ajv.compile(validation.res);
+            const paramsValidation = validation.params && ajv.compile(validation.params);
+            const queryValidation = validation.query && ajv.compile(validation.query);
+            if (validation.body) throw new Error(`Body not allowed`);
 
             const _handler: RequestHandler = (req, res, next) => {
                 if (req.query) { // Ref: https://github.com/cdimascio/express-openapi-validator/issues/969
@@ -195,13 +276,15 @@ export default class Schemas {
         handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
     ) {
         try {
-            this.docs.push({ method: Doc.HttpMethods.DELETE, path: path }, opts);
-            this.schemas.set(`DELETE ${path}`, opts);
+            const validation = this.normalizeValidation(opts);
 
-            const resValidation = opts.res && !(opts.res instanceof Type.Any) && !(opts.res instanceof Type.Unknown) && ajv.compile(opts.res);
-            const paramsValidation = opts.params && ajv.compile(opts.params);
-            const queryValidation = opts.query && ajv.compile(opts.query);
-            if (opts.body) throw new Error(`Body not allowed`);
+            this.docs.push({ method: Doc.HttpMethods.DELETE, path: path }, validation);
+            this.schemas.set(`DELETE ${path}`, validation);
+
+            const resValidation = validation.res && !(validation.res instanceof Type.Any) && !(validation.res instanceof Type.Unknown) && ajv.compile(validation.res);
+            const paramsValidation = validation.params && ajv.compile(validation.params);
+            const queryValidation = validation.query && ajv.compile(validation.query);
+            if (validation.body) throw new Error(`Body not allowed`);
 
             const _handler: RequestHandler = (req, res, next) => {
                 if (req.query) { // Ref: https://github.com/cdimascio/express-openapi-validator/issues/969
@@ -243,13 +326,15 @@ export default class Schemas {
         handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
     ) {
         try {
-            this.docs.push({ method: Doc.HttpMethods.POST, path: path }, opts);
-            this.schemas.set(`POST ${path}`, opts);
+            const validation = this.normalizeValidation(opts);
+
+            this.docs.push({ method: Doc.HttpMethods.POST, path: path }, validation);
+            this.schemas.set(`POST ${path}`, validation);
 
-            const resValidation = opts.res && !(opts.res instanceof Type.Any) && !(opts.res instanceof Type.Unknown) && ajv.compile(opts.res);
-            const paramsValidation = opts.params && ajv.compile(opts.params);
-            const queryValidation = opts.query && ajv.compile(opts.query);
-            const bodyValidation = opts.body && ajv.compile(opts.body);
+            const resValidation = validation.res && !(validation.res instanceof Type.Any) && !(validation.res instanceof Type.Unknown) && ajv.compile(validation.res);
+            const paramsValidation = validation.params && ajv.compile(validation.params);
+            const queryValidation = validation.query && ajv.compile(validation.query);
+            const bodyValidators = this.compileBodyValidators(validation.body);
 
             const _handler: RequestHandler = (req, res, next) => {
                 if (req.query) { // Ref: https://github.com/cdimascio/express-openapi-validator/issues/969
@@ -262,7 +347,10 @@ export default class Schemas {
                 const errors: Array<ErrorListItem> = [];
                 if (paramsValidation && !paramsValidation(req.params)) errors.push({ type: 'Params', errors: paramsValidation.errors as ErrorObject[] });
                 if (queryValidation && !queryValidation(req.query)) errors.push({ type: 'Query', errors: queryValidation.errors as ErrorObject[] });
-                if (bodyValidation && !bodyValidation(req.body)) errors.push({ type: 'Body', errors: bodyValidation.errors as ErrorObject[] });
+                if (bodyValidators) {
+                    const ctErr = this.validateBody(req, bodyValidators, errors, { required: validation.bodyRequired });
+                    if (ctErr) return Err.respond(ctErr, res);
+                }
                 if (errors.length) return Err.respond(this.validationError(Doc.HttpMethods.POST, path), res, errors);
 
                 const json = res.json;
@@ -292,13 +380,15 @@ export default class Schemas {
         handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
     ) {
         try {
-            this.docs.push({ method: Doc.HttpMethods.PATCH, path: path }, opts);
-            this.schemas.set(`PATCH ${path}`, opts);
+            const validation = this.normalizeValidation(opts);
+
+            this.docs.push({ method: Doc.HttpMethods.PATCH, path: path }, validation);
+            this.schemas.set(`PATCH ${path}`, validation);
 
-            const resValidation = opts.res && !(opts.res instanceof Type.Any) && !(opts.res instanceof Type.Unknown) && ajv.compile(opts.res);
-            const paramsValidation = opts.params && ajv.compile(opts.params);
-            const queryValidation = opts.query && ajv.compile(opts.query);
-            const bodyValidation = opts.body && ajv.compile(opts.body);
+            const resValidation = validation.res && !(validation.res instanceof Type.Any) && !(validation.res instanceof Type.Unknown) && ajv.compile(validation.res);
+            const paramsValidation = validation.params && ajv.compile(validation.params);
+            const queryValidation = validation.query && ajv.compile(validation.query);
+            const bodyValidators = this.compileBodyValidators(validation.body);
 
             const _handler: RequestHandler = (req, res, next) => {
                 if (req.query) { // Ref: https://github.com/cdimascio/express-openapi-validator/issues/969
@@ -311,7 +401,10 @@ export default class Schemas {
                 const errors: Array<ErrorListItem> = [];
                 if (paramsValidation && !paramsValidation(req.params)) errors.push({ type: 'Params', errors: paramsValidation.errors as ErrorObject[] });
                 if (queryValidation && !queryValidation(req.query)) errors.push({ type: 'Query', errors: queryValidation.errors as ErrorObject[] });
-                if (bodyValidation && !bodyValidation(req.body)) errors.push({ type: 'Body', errors: bodyValidation.errors as ErrorObject[] });
+                if (bodyValidators) {
+                    const ctErr = this.validateBody(req, bodyValidators, errors, { required: validation.bodyRequired });
+                    if (ctErr) return Err.respond(ctErr, res);
+                }
                 if (errors.length) return Err.respond(this.validationError(Doc.HttpMethods.PATCH, path), res, errors);
 
                 const json = res.json;
@@ -341,13 +434,15 @@ export default class Schemas {
         handler: RequestHandler<Static<TParams>, Static<TResponse>, Static<TBody>, Static<TQuery>>
     ) {
         try {
-            this.docs.push({ method: Doc.HttpMethods.PUT, path: path }, opts);
-            this.schemas.set(`PUT ${path}`, opts);
+            const validation = this.normalizeValidation(opts);
+
+            this.docs.push({ method: Doc.HttpMethods.PUT, path: path }, validation);
+            this.schemas.set(`PUT ${path}`, validation);
 
-            const resValidation = opts.res && !(opts.res instanceof Type.Any) && !(opts.res instanceof Type.Unknown) && ajv.compile(opts.res);
-            const paramsValidation = opts.params && ajv.compile(opts.params);
-            const queryValidation = opts.query && ajv.compile(opts.query);
-            const bodyValidation = opts.body && ajv.compile(opts.body);
+            const resValidation = validation.res && !(validation.res instanceof Type.Any) && !(validation.res instanceof Type.Unknown) && ajv.compile(validation.res);
+            const paramsValidation = validation.params && ajv.compile(validation.params);
+            const queryValidation = validation.query && ajv.compile(validation.query);
+            const bodyValidators = this.compileBodyValidators(validation.body);
 
             const _handler: RequestHandler = (req, res, next) => {
                 if (req.query) { // Ref: https://github.com/cdimascio/express-openapi-validator/issues/969
@@ -360,7 +455,10 @@ export default class Schemas {
                 const errors: Array<ErrorListItem> = [];
                 if (paramsValidation && !paramsValidation(req.params)) errors.push({ type: 'Params', errors: paramsValidation.errors as ErrorObject[] });
                 if (queryValidation && !queryValidation(req.query)) errors.push({ type: 'Query', errors: queryValidation.errors as ErrorObject[] });
-                if (bodyValidation && !bodyValidation(req.body)) errors.push({ type: 'Body', errors: bodyValidation.errors as ErrorObject[] });
+                if (bodyValidators) {
+                    const ctErr = this.validateBody(req, bodyValidators, errors, { required: validation.bodyRequired });
+                    if (ctErr) return Err.respond(ctErr, res);
+                }
                 if (errors.length) return Err.respond(this.validationError(Doc.HttpMethods.PUT, path), res, errors);
 
                 const json = res.json;
@@ -396,6 +494,7 @@ export default class Schemas {
 
 
     query(method: Doc.HttpMethods, url: string): {
+        deprecated?: boolean;
         query?: object;
         body?: object;
         res?: object;
@@ -407,6 +506,7 @@ export default class Schemas {
         const schema = JSON.parse(JSON.stringify(this.schemas.get(`${method} ${url}`)));
 
         return {
+            deprecated: schema.deprecated,
             query: schema.query,
             body: schema.body,
             res: schema.res

package/lib/types.ts

@@ -1,5 +1,88 @@
+import { Kind } from '@sinclair/typebox';
 import type { TSchema } from '@sinclair/typebox';
 
+/**
+ * Per-content-type body entry. May be:
+ *   - a TypeBox schema (validated, no example)
+ *   - `true` (any body accepted, no validation)
+ *   - an object with optional `schema` (TSchema | true), `example`, `examples`
+ *     (forwarded to the OpenAPI media type object)
+ */
+export type BodyEntryConfig = {
+    schema?: TSchema | true;
+    example?: unknown;
+    examples?: Record<string, { summary?: string; description?: string; value: unknown }>;
+};
+
+export type BodyEntry = TSchema | true | BodyEntryConfig;
+
+/**
+ * Body validation can either be:
+ *   - a TypeBox schema (treated as `application/json` for backwards compatibility)
+ *   - a record mapping content-type strings to a `BodyEntry`. Content-type
+ *     keys may include wildcards: `text/*`, `application/*`, or `* / *`.
+ */
+export type BodyValidation<TBody extends TSchema> =
+    | TBody
+    | Record<string, BodyEntry>;
+
+/**
+ * Normalized internal representation: every entry has the expanded
+ * `BodyEntryConfig` shape with `schema` always set (defaulting to `true`).
+ */
+export type NormalizedBody = Record<string, Required<Pick<BodyEntryConfig, 'schema'>> & BodyEntryConfig>;
+
+/**
+ * Detect whether a given value is a TypeBox schema. TypeBox attaches a
+ * `[Kind]` symbol to every schema instance which is what we use to
+ * distinguish a schema from a content-type-keyed body record.
+ */
+export function isTSchema(value: unknown): value is TSchema {
+    return !!value && typeof value === 'object' && Kind in (value as object);
+}
+
+function normalizeEntry(entry: BodyEntry): NormalizedBody[string] {
+    if (entry === true) return { schema: true };
+    if (isTSchema(entry)) return { schema: entry };
+    return { schema: true, ...entry };
+}
+
+/**
+ * Normalize the body option into a `NormalizedBody` map. A bare TypeBox
+ * schema is mapped to `application/json` for backwards compatibility.
+ */
+export function normalizeBody(
+    body: TSchema | Record<string, BodyEntry> | undefined
+): NormalizedBody | undefined {
+    if (!body) return undefined;
+    if (isTSchema(body)) return { 'application/json': { schema: body } };
+
+    const out: NormalizedBody = {};
+    for (const ct of Object.keys(body)) {
+        out[ct.toLowerCase()] = normalizeEntry(body[ct]);
+    }
+    return out;
+}
+
+/**
+ * Match an incoming content-type against a normalized body map, honoring
+ * wildcard entries like `text/*` or `*\/*`. Exact matches always win.
+ */
+export function matchContentType(
+    incoming: string,
+    normalized: NormalizedBody
+): string | undefined {
+    if (!incoming) {
+        return normalized['*/*'] ? '*/*' : undefined;
+    }
+    if (normalized[incoming]) return incoming;
+
+    const [type] = incoming.split('/');
+    if (type && normalized[`${type}/*`]) return `${type}/*`;
+    if (normalized['*/*']) return '*/*';
+    return undefined;
+}
+
 export type RequestValidation<
     TParams extends TSchema,
     TQuery extends TSchema,
@@ -7,11 +90,14 @@ export type RequestValidation<
     TResponse extends TSchema
 > = {
   private?: boolean;
+  deprecated?: boolean;
   name?: string;
   group?: string;
   description?: string;
   params?: TParams;
   query?: TQuery;
-  body?: TBody;
+  body?: BodyValidation<TBody>;
+  /** Whether the request body is required. Defaults to true when `body` is set. */
+  bodyRequired?: boolean;
   res?: TResponse
 };

package/package.json

@@ -4,7 +4,7 @@
     "root": true,
     "main": "dist/index.js",
     "types": "index.ts",
-    "version": "10.24.1",
+    "version": "10.26.0",
     "description": "Strongly Validated JSON Schema support for address",
     "repository": {
         "type": "git",