@znight/openapi 0.0.0-stage → 0.1.0

package/src/shared.ts

@@ -0,0 +1,154 @@
+/**
+ * Import-free helpers shared by the compiler extension and the runtime (the compiler entry may
+ * only reach modules of the package that import nothing at runtime).
+ */
+
+/** Grammar of operation ids. */
+export const OPERATION_ID: RegExp = /^[A-Za-z_][\w.-]*$/
+
+/** Grammar of HTTP header names (RFC 9110 token). */
+export const HEADER_NAME: RegExp = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/
+
+/** A media type or a range (`application/json`, `image/*`, `*\/*`), parameters allowed. */
+export const MEDIA_TYPE: RegExp =
+  /^(?:\*\/\*|[\w!#$&^.+-]+\/(?:\*|[\w!#$&^.+-]+))(?:\s*;\s*[\w!#$&^.+-]+=(?:[\w!#$&^.+-]+|"[^"]*"))*$/
+
+/** OpenAPI methods, in document order. */
+export const METHOD_ORDER: readonly string[] = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch']
+
+/** Reserved names of the standard error components. */
+export const ERROR_COMPONENTS: { readonly body: 'HttpErrorBody'; readonly validation: 'ValidationErrorBody' } =
+  Object.freeze({ body: 'HttpErrorBody', validation: 'ValidationErrorBody' })
+
+/** Standard responses referenced by operations (`#/components/responses/<name>`). */
+export const ERROR_RESPONSES: {
+  readonly badRequest: 'BadRequest'
+  readonly payloadTooLarge: 'PayloadTooLarge'
+  readonly unsupportedMediaType: 'UnsupportedMediaType'
+} = Object.freeze({
+  badRequest: 'BadRequest',
+  payloadTooLarge: 'PayloadTooLarge',
+  unsupportedMediaType: 'UnsupportedMediaType',
+})
+
+/** The OpenAPI version of the documents. */
+export const OPENAPI_VERSION = '3.1.1'
+
+/** A component name: `[A-Za-z0-9._-]`, other characters replaced with `_`. */
+export function componentName(name: string): string {
+  const cleaned = name.replace(/[^A-Za-z0-9._-]/g, '_')
+  return cleaned === '' ? '_' : cleaned
+}
+
+/** `#/components/schemas/<name>`. */
+export function schemaRef(name: string): string {
+  return `#/components/schemas/${name}`
+}
+
+/** Code-point comparison of strings (deterministic across runtimes and locales). */
+export function compareStrings(a: string, b: string): number {
+  if (a === b) return 0
+  return a < b ? -1 : 1
+}
+
+/** Deep equality of JSON-like values (key order ignored). */
+export function jsonEquals(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, index) => jsonEquals(item, b[index]))
+  }
+  const keysA = Object.keys(a).filter(key => (a as Record<string, unknown>)[key] !== undefined)
+  const keysB = Object.keys(b).filter(key => (b as Record<string, unknown>)[key] !== undefined)
+  if (keysA.length !== keysB.length) return false
+  return keysA.every(key => jsonEquals((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]))
+}
+
+/** JSON text with sorted object keys (fingerprints). */
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(sortKeys(value))
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys)
+  if (typeof value !== 'object' || value === null) return value
+  const sorted: Record<string, unknown> = {}
+  for (const key of Object.keys(value).sort(compareStrings)) {
+    const item = (value as Record<string, unknown>)[key]
+    if (item !== undefined) sorted[key] = sortKeys(item)
+  }
+  return sorted
+}
+
+/** Reason phrases of the statuses documented by default (`description` of responses). */
+const REASONS: Readonly<Record<number, string>> = {
+  100: 'Continue',
+  101: 'Switching Protocols',
+  200: 'OK',
+  201: 'Created',
+  202: 'Accepted',
+  203: 'Non-Authoritative Information',
+  204: 'No Content',
+  205: 'Reset Content',
+  206: 'Partial Content',
+  207: 'Multi-Status',
+  300: 'Multiple Choices',
+  301: 'Moved Permanently',
+  302: 'Found',
+  303: 'See Other',
+  304: 'Not Modified',
+  307: 'Temporary Redirect',
+  308: 'Permanent Redirect',
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  402: 'Payment Required',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  406: 'Not Acceptable',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  410: 'Gone',
+  411: 'Length Required',
+  412: 'Precondition Failed',
+  413: 'Content Too Large',
+  414: 'URI Too Long',
+  415: 'Unsupported Media Type',
+  416: 'Range Not Satisfiable',
+  417: 'Expectation Failed',
+  418: "I'm a teapot",
+  421: 'Misdirected Request',
+  422: 'Unprocessable Content',
+  423: 'Locked',
+  424: 'Failed Dependency',
+  425: 'Too Early',
+  426: 'Upgrade Required',
+  428: 'Precondition Required',
+  429: 'Too Many Requests',
+  431: 'Request Header Fields Too Large',
+  451: 'Unavailable For Legal Reasons',
+  500: 'Internal Server Error',
+  501: 'Not Implemented',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+  505: 'HTTP Version Not Supported',
+}
+
+/** Description of a response without one: its reason phrase (`'2XX'` → `Success`). */
+export function reasonPhrase(status: string): string {
+  if (status === 'default') return 'Unexpected response'
+  const range = /^([1-5])XX$/.exec(status)
+  if (range) {
+    return { '1': 'Informational', '2': 'Success', '3': 'Redirection', '4': 'Client error', '5': 'Server error' }[
+      range[1] as '1' | '2' | '3' | '4' | '5'
+    ]
+  }
+  return REASONS[Number(status)] ?? `Status ${status}`
+}
+
+/** `200`-`599` codes, `1XX`-`5XX` ranges, or `default`. */
+export function isResponseStatus(status: string): boolean {
+  return status === 'default' || /^[1-5]XX$/.test(status) || (/^[1-5]\d\d$/.test(status) && Number(status) >= 100)
+}

package/src/testing.ts

@@ -0,0 +1,224 @@
+/**
+ * `@znight/openapi/testing`: checks that a response matches its documentation (status, media type,
+ * documented headers, JSON body against the resolved schema). JSON Schema 2020-12 validation uses
+ * the optional peer `@cfworker/json-schema` (no code generation: Bun, Node.js and edge runtimes).
+ */
+import type { JsonSchema, OpenApiObject, ReferenceObject, ResponseObject } from './types.ts'
+
+import { createRequire } from 'node:module'
+
+/** A problem found by {@link validateResponse}. */
+export interface ResponseIssue {
+  /** `status`, `headers.location`, `body.items[0].id`... */
+  readonly path: string
+  readonly message: string
+  /** `operation`, `status`, `media-type`, `header`, `json`, or the failing JSON Schema keyword (`type`, `required`...). */
+  readonly keyword: string
+}
+
+/** A response: an `InjectResponse` of `@znight/http` / `@znight/testing`, or a plain object. */
+export interface ResponseLike {
+  readonly status: number
+  readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>
+  readonly body: string
+}
+
+/** What to check. */
+export interface ValidateResponseInput {
+  /** HTTP method (`'GET'`). */
+  readonly method: string
+  /** Path template of the document (`/books/{id}`). */
+  readonly path: string
+  readonly response: ResponseLike
+}
+
+interface CfValidator {
+  validate(instance: unknown): {
+    valid: boolean
+    errors: { keyword: string; instanceLocation: string; error: string }[]
+  }
+}
+type CfValidatorClass = new (schema: object, draft?: string, shortCircuit?: boolean) => CfValidator
+
+let validatorClass: CfValidatorClass | undefined
+
+function loadValidator(): CfValidatorClass {
+  if (validatorClass !== undefined) return validatorClass
+  try {
+    const module = createRequire(import.meta.url)('@cfworker/json-schema') as { Validator?: CfValidatorClass }
+    if (typeof module.Validator !== 'function') throw new Error('no Validator export')
+    validatorClass = module.Validator
+    return validatorClass
+  } catch (error) {
+    throw new Error(
+      'validateResponse() needs the optional peer dependency @cfworker/json-schema (npm install -D @cfworker/json-schema)',
+      {
+        cause: error,
+      },
+    )
+  }
+}
+
+const COMPOSITE = new Set([
+  'properties',
+  'items',
+  'prefixItems',
+  '$ref',
+  'allOf',
+  'patternProperties',
+  'dependentSchemas',
+  '$dynamicRef',
+])
+
+/**
+ * Checks `response` against the documentation of `method path` in `document`. Returns `[]` when it
+ * matches.
+ *
+ * ```ts
+ * const response = await app.inject({ method: 'GET', url: '/books/1' })
+ * expect(validateResponse(document, { method: 'GET', path: '/books/{id}', response })).toEqual([])
+ * ```
+ *
+ * The status is looked up as an exact code, then its range (`4XX`), then `default`; the media type
+ * against the documented ones (ranges such as `image/*` included); documented headers marked
+ * `required` must be present; a JSON body is validated against its schema (`$ref`s to the
+ * components followed).
+ */
+export function validateResponse(document: OpenApiObject, input: ValidateResponseInput): ResponseIssue[] {
+  const issues: ResponseIssue[] = []
+  const method = input.method.toLowerCase() as 'get'
+  const operation = document.paths?.[input.path]?.[method]
+  if (operation === undefined) {
+    return [
+      {
+        path: 'operation',
+        keyword: 'operation',
+        message: `${input.method.toUpperCase()} ${input.path} is not documented`,
+      },
+    ]
+  }
+  const status = String(input.response.status)
+  const responses = operation.responses ?? {}
+  const entry = responses[status] ?? responses[`${status.charAt(0)}XX`] ?? responses['default']
+  if (entry === undefined) {
+    return [
+      {
+        path: 'status',
+        keyword: 'status',
+        message: `The status ${status} is not documented (documented: ${Object.keys(responses).join(', ') || 'none'})`,
+      },
+    ]
+  }
+  const documented = resolveResponse(document, entry)
+  if (documented === undefined) {
+    return [
+      {
+        path: 'status',
+        keyword: '$ref',
+        message: `Cannot resolve the response ${JSON.stringify((entry as ReferenceObject).$ref)}`,
+      },
+    ]
+  }
+  // headers
+  const headers = lowerCase(input.response.headers)
+  for (const [name, header] of Object.entries(documented.headers ?? {})) {
+    if ((header as { required?: boolean }).required === true && headers[name.toLowerCase()] === undefined) {
+      issues.push({
+        path: `headers.${name.toLowerCase()}`,
+        keyword: 'header',
+        message: `The documented header "${name}" is missing`,
+      })
+    }
+  }
+  // media type
+  const content = documented.content
+  const body = input.response.body
+  const contentType = headers['content-type']
+  const mediaType = (Array.isArray(contentType) ? contentType[0] : contentType)?.split(';')[0]?.trim().toLowerCase()
+  if (content === undefined || Object.keys(content).length === 0) {
+    if (body !== '')
+      issues.push({
+        path: 'body',
+        keyword: 'content',
+        message: `The ${status} response is documented without body, but it has one`,
+      })
+    return issues
+  }
+  if (mediaType === undefined) {
+    if (body !== '')
+      issues.push({
+        path: 'headers.content-type',
+        keyword: 'media-type',
+        message: 'The response has a body but no content-type',
+      })
+    return issues
+  }
+  const key = Object.keys(content).find(candidate => mediaMatches(candidate, mediaType))
+  if (key === undefined) {
+    issues.push({
+      path: 'headers.content-type',
+      keyword: 'media-type',
+      message: `The media type ${mediaType} is not documented (documented: ${Object.keys(content).join(', ')})`,
+    })
+    return issues
+  }
+  const schema = content[key]?.schema
+  if (schema === undefined || !isJsonMediaType(mediaType)) return issues
+  let value: unknown
+  try {
+    value = JSON.parse(body)
+  } catch {
+    issues.push({ path: 'body', keyword: 'json', message: 'The body is not valid JSON' })
+    return issues
+  }
+  const Validator = loadValidator()
+  // the validator annotates the schemas it reads: work on a copy of the (frozen) document parts
+  const root = structuredClone({ ...(schema as JsonSchema), components: document.components ?? {} })
+  const result = new Validator(root, '2020-12', false).validate(value)
+  if (result.valid) return issues
+  const leaves = result.errors.filter(error => !COMPOSITE.has(error.keyword))
+  for (const error of leaves.length > 0 ? leaves : result.errors) {
+    issues.push({ path: readablePath(error.instanceLocation), keyword: error.keyword, message: error.error })
+  }
+  return issues
+}
+
+function resolveResponse(document: OpenApiObject, entry: ResponseObject | ReferenceObject): ResponseObject | undefined {
+  let current: ResponseObject | ReferenceObject | undefined = entry
+  for (let depth = 0; depth < 8 && current !== undefined && '$ref' in current; depth++) {
+    const name: string = current.$ref.replace(/^#\/components\/responses\//, '')
+    current = document.components?.responses?.[name]
+  }
+  return current === undefined || '$ref' in current ? undefined : current
+}
+
+function lowerCase(headers: ResponseLike['headers']): Record<string, string | readonly string[] | undefined> {
+  const result: Record<string, string | readonly string[] | undefined> = {}
+  for (const [name, value] of Object.entries(headers)) result[name.toLowerCase()] = value
+  return result
+}
+
+function mediaMatches(documented: string, actual: string): boolean {
+  const pattern = documented.split(';')[0]?.trim().toLowerCase() ?? ''
+  if (pattern === '*/*' || pattern === actual) return true
+  return pattern.endsWith('/*') && actual.startsWith(pattern.slice(0, -1))
+}
+
+function isJsonMediaType(mediaType: string): boolean {
+  return mediaType === 'application/json' || mediaType.endsWith('+json')
+}
+
+/** `#/items/0/id` → `body.items[0].id`. */
+function readablePath(pointer: string): string {
+  const segments = pointer
+    .replace(/^#\/?/, '')
+    .split('/')
+    .filter(segment => segment !== '')
+    .map(segment => segment.replaceAll('~1', '/').replaceAll('~0', '~'))
+  let path = 'body'
+  for (const segment of segments)
+    if (/^\d+$/.test(segment)) path += `[${segment}]`
+    else if (/^[A-Za-z_$][\w$]*$/.test(segment)) path += `.${segment}`
+    else path += `[${JSON.stringify(segment)}]`
+  return path
+}

package/src/types.ts

@@ -0,0 +1,240 @@
+/**
+ * OpenAPI 3.1 types (our own, no `openapi-types` dependency). They describe the documents produced
+ * by `buildOpenApiDocument`: every object is read-only, optional fields are omitted when absent and
+ * `x-*` specification extensions are allowed where OpenAPI allows them.
+ *
+ * Schemas are JSON Schema 2020-12 ({@link JsonSchema}), the dialect of OpenAPI 3.1.
+ */
+
+/** A JSON value. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | { readonly [key: string]: JsonValue }
+
+/** A JSON Schema 2020-12 object (keywords are not modelled one by one). */
+export interface JsonSchema {
+  readonly [keyword: string]: JsonValue | undefined
+}
+
+/** `x-*` fields. */
+export interface SpecificationExtensions {
+  readonly [extension: `x-${string}`]: JsonValue | undefined
+}
+
+/** `{ $ref }` to a component (`#/components/schemas/Book`). */
+export interface ReferenceObject {
+  readonly $ref: string
+  readonly summary?: string
+  readonly description?: string
+}
+
+export interface ContactObject extends SpecificationExtensions {
+  readonly name?: string
+  readonly url?: string
+  readonly email?: string
+}
+
+export interface LicenseObject extends SpecificationExtensions {
+  readonly name: string
+  /** SPDX expression (exclusive with `url`). */
+  readonly identifier?: string
+  readonly url?: string
+}
+
+export interface InfoObject extends SpecificationExtensions {
+  readonly title: string
+  readonly version: string
+  readonly summary?: string
+  readonly description?: string
+  readonly termsOfService?: string
+  readonly contact?: ContactObject
+  readonly license?: LicenseObject
+}
+
+export interface ServerVariableObject extends SpecificationExtensions {
+  readonly enum?: readonly string[]
+  readonly default: string
+  readonly description?: string
+}
+
+export interface ServerObject extends SpecificationExtensions {
+  readonly url: string
+  readonly description?: string
+  readonly variables?: Readonly<Record<string, ServerVariableObject>>
+}
+
+export interface ExternalDocumentationObject extends SpecificationExtensions {
+  readonly url: string
+  readonly description?: string
+}
+
+export interface TagObject extends SpecificationExtensions {
+  readonly name: string
+  readonly description?: string
+  readonly externalDocs?: ExternalDocumentationObject
+}
+
+/** Parameter locations. */
+export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie'
+
+export interface ExampleObject extends SpecificationExtensions {
+  readonly summary?: string
+  readonly description?: string
+  readonly value?: JsonValue
+  readonly externalValue?: string
+}
+
+export interface ParameterObjectOf<S> extends SpecificationExtensions {
+  readonly name: string
+  readonly in: ParameterLocation
+  readonly description?: string
+  readonly required?: boolean
+  readonly deprecated?: boolean
+  readonly allowEmptyValue?: boolean
+  readonly style?: string
+  readonly explode?: boolean
+  readonly schema?: S
+  readonly example?: JsonValue
+  readonly examples?: Readonly<Record<string, ExampleObject | ReferenceObject>>
+}
+
+export interface HeaderObjectOf<S> extends SpecificationExtensions {
+  readonly description?: string
+  readonly required?: boolean
+  readonly deprecated?: boolean
+  readonly schema?: S
+  readonly example?: JsonValue
+}
+
+export interface EncodingObjectOf<S> extends SpecificationExtensions {
+  readonly contentType?: string
+  readonly headers?: Readonly<Record<string, HeaderObjectOf<S> | ReferenceObject>>
+  readonly style?: string
+  readonly explode?: boolean
+}
+
+export interface MediaTypeObjectOf<S> extends SpecificationExtensions {
+  readonly schema?: S
+  readonly example?: JsonValue
+  readonly examples?: Readonly<Record<string, ExampleObject | ReferenceObject>>
+  readonly encoding?: Readonly<Record<string, EncodingObjectOf<S>>>
+}
+
+export interface RequestBodyObjectOf<S> extends SpecificationExtensions {
+  readonly description?: string
+  readonly content: Readonly<Record<string, MediaTypeObjectOf<S>>>
+  readonly required?: boolean
+}
+
+export interface ResponseObjectOf<S> extends SpecificationExtensions {
+  readonly description: string
+  readonly headers?: Readonly<Record<string, HeaderObjectOf<S> | ReferenceObject>>
+  readonly content?: Readonly<Record<string, MediaTypeObjectOf<S>>>
+}
+
+/** `{ schemeName: scopes }`: every scheme of one requirement applies (AND). */
+export interface SecurityRequirementObject {
+  readonly [scheme: string]: readonly string[]
+}
+
+/** An OpenAPI Operation Object whose schemas are `S` and whose parameters may also be `P`. */
+export interface OperationObjectOf<S, P = never> extends SpecificationExtensions {
+  readonly tags?: readonly string[]
+  readonly summary?: string
+  readonly description?: string
+  readonly externalDocs?: ExternalDocumentationObject
+  readonly operationId?: string
+  readonly parameters?: readonly (ParameterObjectOf<S> | ReferenceObject | P)[]
+  readonly requestBody?: RequestBodyObjectOf<S> | ReferenceObject
+  readonly responses?: Readonly<Record<string, ResponseObjectOf<S> | ReferenceObject>>
+  readonly deprecated?: boolean
+  readonly security?: readonly SecurityRequirementObject[]
+  readonly servers?: readonly ServerObject[]
+}
+
+export type ParameterObject = ParameterObjectOf<JsonSchema>
+export type HeaderObject = HeaderObjectOf<JsonSchema>
+export type MediaTypeObject = MediaTypeObjectOf<JsonSchema>
+export type RequestBodyObject = RequestBodyObjectOf<JsonSchema>
+export type ResponseObject = ResponseObjectOf<JsonSchema>
+export type OperationObject = OperationObjectOf<JsonSchema>
+
+/** HTTP methods of a path item, in OpenAPI order. */
+export type OpenApiMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch'
+
+export interface PathItemObject extends SpecificationExtensions {
+  readonly summary?: string
+  readonly description?: string
+  readonly get?: OperationObject
+  readonly put?: OperationObject
+  readonly post?: OperationObject
+  readonly delete?: OperationObject
+  readonly options?: OperationObject
+  readonly head?: OperationObject
+  readonly patch?: OperationObject
+  readonly trace?: OperationObject
+  readonly servers?: readonly ServerObject[]
+  readonly parameters?: readonly (ParameterObject | ReferenceObject)[]
+}
+
+export interface OAuthFlowObject extends SpecificationExtensions {
+  readonly authorizationUrl?: string
+  readonly tokenUrl?: string
+  readonly refreshUrl?: string
+  readonly scopes: Readonly<Record<string, string>>
+}
+
+export interface OAuthFlowsObject extends SpecificationExtensions {
+  readonly implicit?: OAuthFlowObject
+  readonly password?: OAuthFlowObject
+  readonly clientCredentials?: OAuthFlowObject
+  readonly authorizationCode?: OAuthFlowObject
+}
+
+/** An OpenAPI Security Scheme Object. */
+export type SecuritySchemeObject =
+  | ({
+      readonly type: 'apiKey'
+      readonly name: string
+      readonly in: 'query' | 'header' | 'cookie'
+      readonly description?: string
+    } & SpecificationExtensions)
+  | ({
+      readonly type: 'http'
+      /** `bearer`, `basic`... (RFC 7235 scheme name). */
+      readonly scheme: string
+      readonly bearerFormat?: string
+      readonly description?: string
+    } & SpecificationExtensions)
+  | ({
+      readonly type: 'oauth2'
+      readonly flows: OAuthFlowsObject
+      readonly description?: string
+    } & SpecificationExtensions)
+  | ({
+      readonly type: 'openIdConnect'
+      readonly openIdConnectUrl: string
+      readonly description?: string
+    } & SpecificationExtensions)
+  | ({ readonly type: 'mutualTLS'; readonly description?: string } & SpecificationExtensions)
+
+export interface ComponentsObject extends SpecificationExtensions {
+  readonly schemas?: Readonly<Record<string, JsonSchema>>
+  readonly responses?: Readonly<Record<string, ResponseObject | ReferenceObject>>
+  readonly parameters?: Readonly<Record<string, ParameterObject | ReferenceObject>>
+  readonly examples?: Readonly<Record<string, ExampleObject | ReferenceObject>>
+  readonly requestBodies?: Readonly<Record<string, RequestBodyObject | ReferenceObject>>
+  readonly headers?: Readonly<Record<string, HeaderObject | ReferenceObject>>
+  readonly securitySchemes?: Readonly<Record<string, SecuritySchemeObject>>
+}
+
+/** An OpenAPI 3.1 document. */
+export interface OpenApiObject extends SpecificationExtensions {
+  readonly openapi: string
+  readonly info: InfoObject
+  readonly jsonSchemaDialect?: string
+  readonly servers?: readonly ServerObject[]
+  readonly paths?: Readonly<Record<string, PathItemObject>>
+  readonly components?: ComponentsObject
+  readonly security?: readonly SecurityRequirementObject[]
+  readonly tags?: readonly TagObject[]
+  readonly externalDocs?: ExternalDocumentationObject
+}