@croutonian/with-openapi 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,451 @@
+import { FetchHandler, Middleware } from "@supabase/middleware";
+import { SchemaDraft } from "@cfworker/json-schema";
+import { OpenAPIObject, OperationObject, ParameterLocation, ParameterStyle, ReferenceObject, SchemaObject, SecurityRequirementObject } from "openapi3-ts/oas31";
+
+//#region src/document.d.ts
+/** The HTTP methods an OpenAPI Path Item Object may declare an operation for. */
+declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+/** One of the eight methods {@link HTTP_METHODS} lists. */
+type HttpMethod = (typeof HTTP_METHODS)[number];
+/** One segment of a path template: a literal, or a `{name}` placeholder. */
+type Segment = {
+  readonly kind: 'static';
+  readonly value: string;
+} | {
+  readonly kind: 'param';
+  readonly name: string;
+};
+/** A parameter, with its defaults filled in and its schema pre-resolved. */
+interface IndexedParameter {
+  readonly name: string;
+  readonly in: ParameterLocation;
+  /** The Parameter Object's own prose, surfaced on any violation about it. */
+  readonly description: string | undefined;
+  readonly required: boolean;
+  readonly style: ParameterStyle;
+  readonly explode: boolean;
+  readonly allowEmptyValue: boolean;
+  /** As written in the document — handed to the validator unresolved. */
+  readonly schema: SchemaObject | ReferenceObject | undefined;
+  /** `$ref` chain followed, so deserialization can read `type`. */
+  readonly resolved: SchemaObject | undefined;
+}
+/** One entry of a Request Body Object's `content` map. */
+interface IndexedContent {
+  readonly mediaType: string;
+  readonly schema: SchemaObject | ReferenceObject | undefined;
+  readonly resolved: SchemaObject | undefined;
+}
+/** A Request Body Object, flattened. */
+interface IndexedRequestBody {
+  readonly required: boolean;
+  /** The Request Body Object's own prose, surfaced on body-level violations. */
+  readonly description: string | undefined;
+  readonly contents: readonly IndexedContent[];
+}
+/** Everything the middleware needs about one operation, resolved up front. */
+interface IndexedOperation {
+  readonly method: HttpMethod;
+  readonly route: string;
+  readonly operation: OperationObject;
+  readonly operationId: string | undefined;
+  readonly security: SecurityRequirementObject[] | undefined;
+  readonly parameters: Readonly<Record<ParameterLocation, readonly IndexedParameter[]>>;
+  readonly requestBody: IndexedRequestBody | undefined;
+  /**
+   * Query string names the declared parameters may legitimately consume —
+   * a `form`/`explode` object contributes its property names, not its own.
+   * Only read when `additionalQuery: 'reject'`.
+   */
+  readonly knownQueryNames: ReadonlySet<string>;
+  /** `deepObject` parameters consume anything starting with `name[`. */
+  readonly knownQueryPrefixes: readonly string[];
+}
+/** A path template, its segments, and the operations declared under it. */
+interface IndexedRoute {
+  readonly template: string;
+  readonly segments: readonly Segment[];
+  readonly operations: ReadonlyMap<HttpMethod, IndexedOperation>;
+  /** Declared methods, upper-cased — the `Allow` header on a 405. */
+  readonly allow: readonly string[];
+}
+//#endregion
+//#region src/cors.d.ts
+/**
+ * Which origins may call the API.
+ *
+ * A literal `'*'` with `credentials` is forbidden by the Fetch standard, so in
+ * that combination the request's `Origin` is reflected instead.
+ */
+type CorsOrigin = '*' | string | readonly string[] | ((origin: string | null) => boolean);
+/** CORS configuration. Everything not listed here comes from the document. */
+interface OpenApiCorsOptions {
+  /**
+   * Allowed origins. **Required, and never derived** — a document describes
+   * where an API lives, not who may call it.
+   */
+  origin: CorsOrigin;
+  /** Send `Access-Control-Allow-Credentials: true`. @defaultValue `false` */
+  credentials?: boolean;
+  /** `Access-Control-Max-Age` in seconds, for preflight caching. */
+  maxAge?: number;
+  /**
+   * Request headers to allow **on top of** the ones derived from the document.
+   * Reach for this when a header is genuinely not describable in OpenAPI; a
+   * header the API actually reads belongs in the document instead.
+   */
+  allowedHeaders?: readonly string[];
+  /** Response headers to expose on top of the ones derived from the document. */
+  exposedHeaders?: readonly string[];
+  /** Status for a successful preflight. @defaultValue `204` */
+  optionsSuccessStatus?: number;
+}
+/** Built once at construction; answers preflights and stamps responses. */
+interface CorsPolicy {
+  /** A preflight is `OPTIONS` carrying `Access-Control-Request-Method`. */
+  isPreflight(req: Request): boolean;
+  /** The preflight response for a matched route. */
+  preflight(req: Request, route: IndexedRoute): Response;
+  /**
+   * Copy a response, adding the response-side CORS headers.
+   *
+   * The matched route is passed in rather than looked up, because it is what
+   * `Access-Control-Expose-Headers` is derived from and the caller already
+   * holds it. A side channel keyed on the request would be the alternative,
+   * and the authoring guide's rule 3 exists to prevent exactly that.
+   */
+  stamp(response: Response, req: Request, route: IndexedRoute | undefined): Response;
+}
+//#endregion
+//#region src/reference.d.ts
+/** Default CDN for Scalar's standalone browser build. */
+declare const SCALAR_CDN_URL = "https://cdn.jsdelivr.net/npm/@scalar/api-reference";
+/** Everything {@link ScalarReferenceOptions.html} is given to render a page. */
+interface ScalarHtmlInput {
+  /** Absolute path the document JSON is served from. */
+  readonly documentPath: string;
+  /** Page `<title>`. */
+  readonly title: string;
+  /** Script URL for Scalar's standalone build. */
+  readonly cdnUrl: string;
+  /** Config object passed to `Scalar.createApiReference`, `url` included. */
+  readonly configuration: Record<string, unknown>;
+}
+/** Configuration for the reference endpoint. */
+interface ScalarReferenceOptions {
+  /**
+   * Path the HTML page is served from. Matched exactly, and *before* the
+   * document's own routes, so it does not need to appear in the document.
+   *
+   * @defaultValue `'/reference'`
+   */
+  path?: string;
+  /**
+   * Path the document JSON is served from.
+   *
+   * @defaultValue `` `${path}/openapi.json` ``
+   */
+  documentPath?: string;
+  /** Page title. @defaultValue the document's `info.title`, or `'API Reference'` */
+  title?: string;
+  /** Script URL for Scalar's standalone build. @defaultValue {@link SCALAR_CDN_URL} */
+  cdnUrl?: string;
+  /**
+   * Extra options merged into the `Scalar.createApiReference` config — theme,
+   * `darkMode`, `proxyUrl`, and anything else Scalar accepts. `url` is set
+   * from {@link documentPath} and can be overridden here.
+   *
+   * @see https://scalar.com/products/api-references/configuration
+   */
+  configuration?: Record<string, unknown>;
+  /** `Cache-Control` on both responses. @defaultValue `'no-cache'` */
+  cacheControl?: string;
+  /** Render the page yourself, ignoring every option above except the paths. */
+  html?: (input: ScalarHtmlInput) => string;
+}
+//#endregion
+//#region src/types.d.ts
+/** Where a parameter was declared. */
+type ParameterIn = 'path' | 'query' | 'header' | 'cookie';
+/** Deserialized, coerced parameters, grouped by where they came from. */
+interface OpenApiParams {
+  readonly path: Readonly<Record<string, unknown>>;
+  readonly query: Readonly<Record<string, unknown>>;
+  readonly header: Readonly<Record<string, unknown>>;
+  readonly cookie: Readonly<Record<string, unknown>>;
+}
+/** One thing wrong with a request. */
+interface OpenApiViolation {
+  /** Which half of the request it is about. */
+  readonly in: ParameterIn | 'body';
+  /** Parameter name. Absent for a violation of the body as a whole. */
+  readonly name?: string;
+  /** JSON pointer into the offending value, from the schema validator. */
+  readonly location?: string;
+  /** The JSON Schema keyword that failed, when one did. */
+  readonly keyword?: string;
+  /** What the validator objected to, mechanically. */
+  readonly message: string;
+  /**
+   * The document's own prose for whatever failed — the Parameter Object's
+   * `description`, or the `description` on the schema the failing keyword
+   * belongs to.
+   *
+   * {@link message} says what is wrong; this says what the thing is *for*, and
+   * it is the half a caller can usually act on. Absent when the document does
+   * not describe that field, or when `validate.describe` is off.
+   */
+  readonly description?: string;
+}
+/** Why the middleware is refusing a request. */
+type OpenApiRejectionKind = 'route_not_found' | 'method_not_allowed' | 'unsupported_media_type' | 'validation_failed';
+/** Everything known about a refusal, handed to {@link WithOpenApiConfig.reject}. */
+interface OpenApiRejection {
+  readonly kind: OpenApiRejectionKind;
+  /** Status the default response would use. */
+  readonly status: number;
+  /** The request's method, as sent. */
+  readonly method: string;
+  /** The request's pathname, before `basePath` is stripped. */
+  readonly pathname: string;
+  /** Path template that matched, when one did. */
+  readonly route?: string;
+  /** Methods the route does declare. Set on `method_not_allowed`. */
+  readonly allow?: readonly string[];
+  /** Media types the operation accepts. Set on `unsupported_media_type`. */
+  readonly accepts?: readonly string[];
+  /** Empty for the routing kinds, which have nothing per-field to report. */
+  readonly violations: readonly OpenApiViolation[];
+}
+/** Which halves of a request to check, and how strictly. */
+interface OpenApiValidateOptions {
+  /** Check path parameters. @defaultValue `true` */
+  path?: boolean;
+  /** Check query parameters. @defaultValue `true` */
+  query?: boolean;
+  /** Check header parameters. @defaultValue `true` */
+  header?: boolean;
+  /** Check cookie parameters. @defaultValue `true` */
+  cookie?: boolean;
+  /**
+   * Check — and therefore read and parse — the request body. With this off,
+   * `ctx.openapi.body` is `undefined` and the handler reads the body itself.
+   *
+   * @defaultValue `true`
+   */
+  body?: boolean;
+  /**
+   * What to do with query parameters the operation does not declare.
+   * `'allow'` ignores them; `'reject'` treats each as a violation.
+   *
+   * @defaultValue `'allow'`
+   */
+  additionalQuery?: 'allow' | 'reject';
+  /** Status for a validation failure. @defaultValue `400` */
+  status?: number;
+  /**
+   * Include the document's `description` prose on each violation, so a caller
+   * is told what a field is for and not only that it is wrong.
+   *
+   * A document's descriptions are written for its consumers, which is who
+   * reads these errors — but turn this off if yours carries notes you would
+   * rather not return in a response body.
+   *
+   * @defaultValue `true`
+   */
+  describe?: boolean;
+  /**
+   * Most violations to report in one rejection. One bad array in a large body
+   * can fail thousands of times, and nobody reads past the first few.
+   *
+   * @defaultValue `20`
+   */
+  maxViolations?: number;
+}
+/** Per-instance configuration for `withOpenApi`. */
+interface WithOpenApiConfig {
+  /**
+   * The OpenAPI 3.1 document. Read once, at construction: `$ref`s are
+   * followed, parameters merged, and path templates compiled, so a request
+   * costs a segment walk rather than a document traversal.
+   *
+   * External `$ref`s are not fetched — bundle the document first.
+   */
+  document: OpenAPIObject;
+  /**
+   * Prefix stripped from the pathname before matching, for an API mounted
+   * under a sub-path. The reference endpoint's paths are **not** relative to
+   * it; they are matched against the full pathname.
+   */
+  basePath?: string;
+  /**
+   * Check requests against the document, and reject the ones that do not fit.
+   *
+   * `false` turns rejection off entirely: routes are still matched and
+   * parameters still deserialized onto `ctx.openapi.params`, but nothing is
+   * refused for being invalid. Pass an object to check some halves of the
+   * request and not others.
+   *
+   * @defaultValue `true`
+   */
+  validate?: boolean | OpenApiValidateOptions;
+  /**
+   * Convert parameter text into the JSON types the schemas describe, so
+   * `?limit=10` satisfies `type: integer`. Off, every non-string parameter in
+   * every document fails its own type check.
+   *
+   * @defaultValue `true`
+   */
+  coerce?: boolean;
+  /**
+   * What to do with a pathname no path template matches. `'reject'` answers
+   * `404`; `'pass'` falls through to the handler with
+   * `ctx.openapi.matched === false`.
+   *
+   * @defaultValue `'reject'`
+   */
+  onUnknownRoute?: 'reject' | 'pass';
+  /**
+   * What to do when the path matches but the operation is not declared for
+   * the request's method. `'reject'` answers `405` with an `Allow` header;
+   * `'pass'` falls through with `ctx.openapi.matched === false`.
+   *
+   * @defaultValue `'reject'`
+   */
+  onUnknownMethod?: 'reject' | 'pass';
+  /**
+   * Serve a Scalar API reference and the document JSON. `true` takes every
+   * default — the page at `/reference`, the document at
+   * `/reference/openapi.json`.
+   *
+   * @defaultValue off
+   */
+  reference?: boolean | ScalarReferenceOptions;
+  /**
+   * Answer CORS preflights and stamp `Access-Control-*` headers, with the
+   * policy derived from the document: a path's declared operations are its
+   * allowed methods, its `in: header` parameters and security schemes are its
+   * allowed request headers, its Response Objects' `headers` are what it
+   * exposes.
+   *
+   * `origin` is the one field that is never derived and so is required — a
+   * document says where an API lives, not who may call it.
+   *
+   * Rejections are stamped too. An unstamped `400` reaches a browser as an
+   * opaque CORS error rather than the violations it is carrying.
+   *
+   * @defaultValue off
+   */
+  cors?: OpenApiCorsOptions;
+  /**
+   * JSON Schema draft the document's schemas are written against. Inferred
+   * from the document's `openapi` version, which is almost always right.
+   */
+  schemaDraft?: SchemaDraft;
+  /**
+   * Leave a request alone entirely — no matching, no reference endpoint, no
+   * rejection. The handler still sees `ctx.openapi`, with
+   * `matched === false`.
+   */
+  skip?: (req: Request) => boolean;
+  /**
+   * Answer a refusal yourself. Return `undefined` to fall back to the default
+   * response for that {@link OpenApiRejection}.
+   */
+  reject?: (rejection: OpenApiRejection, req: Request) => Response | undefined | Promise<Response | undefined>;
+}
+/** `ctx.openapi` when an operation in the document describes the request. */
+interface OpenApiMatched {
+  readonly matched: true;
+  /** The document, as passed to `withOpenApi`. */
+  readonly document: OpenAPIObject;
+  /** Path template that matched, e.g. `'/users/{id}'`. */
+  readonly route: string;
+  /** Lowercase method the operation was declared under. */
+  readonly method: HttpMethod;
+  /** The Operation Object, with its own `$ref` (if any) already followed. */
+  readonly operation: OperationObject;
+  readonly operationId: string | undefined;
+  /**
+   * Security requirements in force — the operation's, falling back to the
+   * document's. Contributed for a downstream auth middleware to act on; this
+   * middleware never enforces them.
+   */
+  readonly security: SecurityRequirementObject[] | undefined;
+  /** Deserialized and (unless turned off) coerced parameters. */
+  readonly params: OpenApiParams;
+  /**
+   * The parsed request body. `undefined` when the operation declares none,
+   * when none was sent, when body validation is off, or when the media type
+   * is binary and was deliberately left unread.
+   */
+  readonly body: unknown;
+  /** The `content` key that matched the request's content type. */
+  readonly mediaType: string | undefined;
+  /** `false` when `validate: false` — the request was matched, not checked. */
+  readonly validated: boolean;
+}
+/** `ctx.openapi` when the document does not describe the request. */
+interface OpenApiUnmatched {
+  readonly matched: false;
+  /** Why nothing matched. */
+  readonly reason: 'skipped' | 'no_route' | 'no_operation';
+  readonly document: OpenAPIObject;
+  /** Set when the path matched but the method was not declared under it. */
+  readonly route: string | undefined;
+  /** The request's method, as sent. */
+  readonly method: string;
+  readonly operation: undefined;
+  readonly operationId: undefined;
+  readonly security: undefined;
+  readonly params: OpenApiParams;
+  readonly body: undefined;
+  readonly mediaType: undefined;
+  readonly validated: false;
+}
+/**
+ * What lands at `ctx.openapi`.
+ *
+ * With the default `onUnknownRoute`/`onUnknownMethod` of `'reject'` and no
+ * `skip`, the handler only ever sees {@link OpenApiMatched} — anything else was
+ * already answered with a `404` or a `405`. Narrow with
+ * `if (!ctx.openapi.matched)` where those are set to `'pass'`.
+ */
+type OpenApiContribution = OpenApiMatched | OpenApiUnmatched;
+//#endregion
+//#region src/with-openapi.d.ts
+/**
+ * Middleware that holds an API to its own description.
+ *
+ * @example Reject anything the document does not describe, and serve the docs.
+ * ```ts
+ * import { pipeline } from '@supabase/middleware'
+ * import { withOpenApi } from '@croutonian/with-openapi'
+ * import document from './openapi.json' with { type: 'json' }
+ *
+ * export default {
+ *   fetch: pipeline(
+ *     [withOpenApi({ document, reference: true })],
+ *     async (_req, ctx) => {
+ *       if (!ctx.openapi.matched) return new Response(null, { status: 404 })
+ *       return Response.json({ op: ctx.openapi.operationId })
+ *     },
+ *   ),
+ * }
+ * ```
+ *
+ * @example Describe and document, but do not enforce.
+ * ```ts
+ * withOpenApi({
+ *   document,
+ *   validate: false,
+ *   onUnknownRoute: 'pass',
+ *   reference: { path: '/docs' },
+ * })
+ * ```
+ *
+ * @category Middleware
+ */
+declare const withOpenApi: Middleware<'openapi', WithOpenApiConfig, Record<never, never>, OpenApiContribution>;
+//#endregion
+export { type CorsOrigin, type CorsPolicy, type FetchHandler, type HttpMethod, type OpenApiContribution, type OpenApiCorsOptions, type OpenApiMatched, type OpenApiParams, type OpenApiRejection, type OpenApiRejectionKind, type OpenApiUnmatched, type OpenApiValidateOptions, type OpenApiViolation, type ParameterIn, SCALAR_CDN_URL, type ScalarHtmlInput, type ScalarReferenceOptions, type SchemaDraft, type WithOpenApiConfig, withOpenApi };