@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/rest/openapi/parse.js

@@ -8,10 +8,9 @@
  * YAML, and a document that does not declare a supported OpenAPI or Swagger version. Swagger 1.x
  * and 2.0 documents are converted into the intermediate OpenAPI representation.
  *
- * The parser reads a document that is already resolved: `refs.ts` inlines every `$ref` first, so
+ * The parser reads a document that is already resolved: `json/schema/refs.ts` inlines every `$ref` first, so
  * nothing here has to fetch anything.
  */
-import { parse as parseYamlDocument } from 'yaml';
 import { OpenApiError } from '../../errors.js';
 import { HTTP_METHODS } from './model.js';
 import { trimTrailingSlashes } from '../url.js';
@@ -37,34 +36,7 @@ function asStringArray(value) {
 function asJson(value) {
     return value === undefined ? undefined : value;
 }
-/**
- * Parses text as JSON when it looks like JSON, and as YAML otherwise.
- *
- * JSON is a subset of YAML, so one parser would do — but a JSON document with a syntax error gets a
- * far better message from `JSON.parse`, and that message is what the user has to act on.
- *
- * @throws OpenApiError `openapi-malformed` when the text parses as neither.
- */
-export function parseDocumentText(text, where = 'the document') {
-    const trimmed = text.replace(/^/, '').trimStart();
-    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
-        try {
-            return JSON.parse(trimmed);
-        }
-        catch (error) {
-            throw new OpenApiError('openapi-malformed', `${where} is not valid JSON: ${messageOf(error)}`, { cause: error });
-        }
-    }
-    try {
-        return parseYamlDocument(trimmed);
-    }
-    catch (error) {
-        throw new OpenApiError('openapi-malformed', `${where} is not valid YAML: ${messageOf(error)}`, { cause: error });
-    }
-}
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}
+export { parseDocumentText } from '../../json/schema/parse-text.js';
 function asVersionString(v) {
     if (typeof v === 'string')
         return v;
@@ -132,14 +104,13 @@ export function versionOf(root) {
 }
 /** The keys a document may carry that this client knowingly does not read, with what to call them. */
 const IGNORED_ROOT_KEYS = {
-    webhooks: 'webhook',
     callbacks: 'callback',
     links: 'link',
 };
 /**
  * Reads a resolved OpenAPI document.
  *
- * @param root the parsed document, with every `$ref` already inlined (see `refs.ts`)
+ * @param root the parsed document, with every `$ref` already inlined (see `json/schema/refs.ts`)
  * @throws OpenApiError `openapi-not-a-document` / `openapi-unsupported-version` as {@link versionOf} does
  */
 export function parseOpenApiDocument(root) {
@@ -159,6 +130,7 @@ export function parseOpenApiDocument(root) {
     }
     const info = isRecord(document['info']) ? document['info'] : {};
     const title = asString(info['title']) ?? 'Imported API';
+    const webhooks = parseWebhooks(document['webhooks'], version, skipped);
     for (const [key, kind] of Object.entries(IGNORED_ROOT_KEYS)) {
         const value = document[key];
         if (isRecord(value)) {
@@ -187,9 +159,32 @@ export function parseOpenApiDocument(root) {
             ? { security: parseSecurityRequirements(document['security']) }
             : {}),
         tags: parseTags(document['tags']),
+        ...(webhooks.length > 0 ? { webhooks } : {}),
         skipped,
     };
 }
+/** Root `webhooks` (OpenAPI 3.1+): one {@link OpenApiHook} per name, each a path item of operations. */
+function parseWebhooks(value, version, skipped) {
+    if (!isRecord(value))
+        return [];
+    const hooks = [];
+    for (const [name, item] of Object.entries(value)) {
+        if (name.startsWith('x-')) {
+            skipped.push({ kind: 'extension', where: `/webhooks/${name}`, reason: 'vendor extensions are not imported' });
+            continue;
+        }
+        if (version === '3.0') {
+            skipped.push({ kind: 'webhook', where: `/webhooks/${name}`, reason: 'webhooks need OpenAPI 3.1' });
+            continue;
+        }
+        if (!isRecord(item)) {
+            skipped.push({ kind: 'webhook', where: `/webhooks/${name}`, reason: 'not a path item' });
+            continue;
+        }
+        hooks.push({ name, operations: parsePathItemOperations(name, item, skipped) });
+    }
+    return hooks;
+}
 function parseServers(value, skipped) {
     if (!Array.isArray(value)) {
         return [];
@@ -254,37 +249,43 @@ function parseOperations(value, skipped) {
             skipped.push({ kind: 'path', where: `/paths/${path}`, reason: 'not a path item' });
             continue;
         }
-        const shared = parseParameters(item['parameters'], `${path} (path level)`, skipped);
-        for (const [key, operation] of Object.entries(item)) {
-            if (!HTTP_METHODS.includes(key.toLowerCase())) {
+        operations.push(...parsePathItemOperations(path, item, skipped));
+    }
+    return operations;
+}
+/** One path item's operations: the fixed HTTP-method fields plus 3.2's `additionalOperations`. */
+function parsePathItemOperations(key, item, skipped) {
+    const operations = [];
+    const shared = parseParameters(item['parameters'], `${key} (path level)`, skipped);
+    for (const [method, operation] of Object.entries(item)) {
+        if (!HTTP_METHODS.includes(method.toLowerCase())) {
+            continue;
+        }
+        if (!isRecord(operation)) {
+            skipped.push({ kind: 'operation', where: `${method.toUpperCase()} ${key}`, reason: 'not an object' });
+            continue;
+        }
+        operations.push(parseOperation(method.toLowerCase(), key, operation, shared, skipped));
+    }
+    if (isRecord(item['additionalOperations'])) {
+        for (const [method, operation] of Object.entries(item['additionalOperations'])) {
+            if (method.startsWith('x-')) {
+                skipped.push({ kind: 'extension', where: `${method} ${key}`, reason: 'vendor extensions are not imported' });
                 continue;
             }
-            if (!isRecord(operation)) {
-                skipped.push({ kind: 'operation', where: `${key.toUpperCase()} ${path}`, reason: 'not an object' });
+            if (FIXED_PATH_ITEM_METHODS.has(method.toLowerCase())) {
+                skipped.push({ kind: 'operation', where: `${method} ${key}`, reason: 'use the fixed field' });
                 continue;
             }
-            operations.push(parseOperation(key.toLowerCase(), path, operation, shared, skipped));
-        }
-        if (isRecord(item['additionalOperations'])) {
-            for (const [key, operation] of Object.entries(item['additionalOperations'])) {
-                if (key.startsWith('x-')) {
-                    skipped.push({ kind: 'extension', where: `${key} ${path}`, reason: 'vendor extensions are not imported' });
-                    continue;
-                }
-                if (FIXED_PATH_ITEM_METHODS.has(key.toLowerCase())) {
-                    skipped.push({ kind: 'operation', where: `${key} ${path}`, reason: 'use the fixed field' });
-                    continue;
-                }
-                if (!RFC_9110_METHOD_TOKEN.test(key)) {
-                    skipped.push({ kind: 'operation', where: `${key} ${path}`, reason: 'invalid HTTP method name' });
-                    continue;
-                }
-                if (!isRecord(operation)) {
-                    skipped.push({ kind: 'operation', where: `${key} ${path}`, reason: 'not an object' });
-                    continue;
-                }
-                operations.push(parseOperation(key, path, operation, shared, skipped));
+            if (!RFC_9110_METHOD_TOKEN.test(method)) {
+                skipped.push({ kind: 'operation', where: `${method} ${key}`, reason: 'invalid HTTP method name' });
+                continue;
+            }
+            if (!isRecord(operation)) {
+                skipped.push({ kind: 'operation', where: `${method} ${key}`, reason: 'not an object' });
+                continue;
             }
+            operations.push(parseOperation(method, key, operation, shared, skipped));
         }
     }
     return operations;
@@ -299,8 +300,8 @@ function parseOperation(method, path, operation, shared, skipped) {
         merged.set(`${parameter.in}:${parameter.name}`, parameter);
     }
     for (const key of Object.keys(operation)) {
-        if (key === 'callbacks' || key === 'links') {
-            skipped.push({ kind: key.replace(/s$/, ''), where, reason: `${key} are not imported` });
+        if (key === 'links') {
+            skipped.push({ kind: 'link', where, reason: 'links are not imported' });
         }
         if (key.startsWith('x-')) {
             skipped.push({ kind: 'extension', where: `${where} ${key}`, reason: 'vendor extensions are not imported' });
@@ -308,6 +309,8 @@ function parseOperation(method, path, operation, shared, skipped) {
     }
     const requestBody = parseRequestBody(operation['requestBody'], where, skipped);
     const security = parseSecurityRequirements(operation['security']);
+    const responses = parseResponses(operation['responses'], false);
+    const callbacks = parseCallbacks(operation['callbacks'], where, skipped);
     return {
         method,
         path,
@@ -323,8 +326,68 @@ function parseOperation(method, path, operation, shared, skipped) {
         ...(asBoolean(operation['deprecated']) === true ? { deprecated: true } : {}),
         ...(requestBody !== undefined ? { requestBody } : {}),
         ...(security !== undefined ? { security } : {}),
+        ...(responses !== undefined ? { responses } : {}),
+        ...(callbacks.length > 0 ? { callbacks } : {}),
     };
 }
+/** One operation's `callbacks`: each name to its path-item key (an expression) and that item's operations. */
+function parseCallbacks(value, where, skipped) {
+    if (!isRecord(value))
+        return [];
+    const callbacks = [];
+    for (const [name, entry] of Object.entries(value)) {
+        if (name.startsWith('x-') || !isRecord(entry))
+            continue;
+        for (const [expression, item] of Object.entries(entry)) {
+            if (expression.startsWith('x-'))
+                continue;
+            if (!isRecord(item)) {
+                skipped.push({ kind: 'callback', where: `${where} ${name}`, reason: 'not a path item' });
+                continue;
+            }
+            callbacks.push({ name, expression, operations: parsePathItemOperations(expression, item, skipped) });
+        }
+    }
+    return callbacks;
+}
+/**
+ * Reads an operation's `responses`, schemas kept as the resolved nodes (response validation needs every
+ * keyword, not the sample generator's subset). Swagger 2.0 declares one `schema` per response and no
+ * media types; it becomes `application/json` content, which is what those documents describe.
+ */
+function parseResponses(value, swagger2) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const responses = nullRecord();
+    for (const [key, entry] of Object.entries(value)) {
+        if (key.startsWith('x-') || !isRecord(entry)) {
+            continue;
+        }
+        const description = asString(entry['description']);
+        let content;
+        if (swagger2) {
+            if (entry['schema'] !== undefined) {
+                content = nullRecord();
+                content['application/json'] = { schema: entry['schema'] };
+            }
+        }
+        else if (isRecord(entry['content'])) {
+            content = nullRecord();
+            for (const [mediaType, media] of Object.entries(entry['content'])) {
+                if (!isRecord(media)) {
+                    continue;
+                }
+                content[mediaType] = media['schema'] !== undefined ? { schema: media['schema'] } : {};
+            }
+        }
+        responses[key] = {
+            ...(description !== undefined ? { description } : {}),
+            ...(content !== undefined ? { content } : {}),
+        };
+    }
+    return responses;
+}
 function parseParameters(value, where, skipped) {
     if (!Array.isArray(value)) {
         return [];
@@ -434,7 +497,7 @@ function parseRequestBody(value, where, skipped) {
 /**
  * One parsed schema per resolved node, keyed by the node itself.
  *
- * A `$ref`-resolved description is a *graph*: `refs.ts` hands back one object per reference target,
+ * A `$ref`-resolved description is a *graph*: `json/schema/refs.ts` hands back one object per reference target,
  * shared by every place that referenced it. Rebuilding that graph as a tree — which is what a plain
  * recursive parse does — revisits a shared node once per path to it, so a document whose schemas
  * reference each other costs `breadth ^ depth`. Keyed on identity because that is exactly the
@@ -495,6 +558,9 @@ function parseSchemaFields(value) {
         ...(branches('allOf') !== undefined ? { allOf: branches('allOf') } : {}),
         ...(branches('oneOf') !== undefined ? { oneOf: branches('oneOf') } : {}),
         ...(branches('anyOf') !== undefined ? { anyOf: branches('anyOf') } : {}),
+        ...(isRecord(value['discriminator']) && asString(value['discriminator']['propertyName']) !== undefined
+            ? { discriminator: parseDiscriminator(value['discriminator']) }
+            : {}),
         ...(asBoolean(value['nullable']) !== undefined ? { nullable: asBoolean(value['nullable']) } : {}),
         ...(asBoolean(value['deprecated']) === true ? { deprecated: true } : {}),
         ...(asBoolean(value['readOnly']) === true ? { readOnly: true } : {}),
@@ -505,6 +571,15 @@ function parseSchemaFields(value) {
         ...(asString(value['$ref']) !== undefined ? { $ref: asString(value['$ref']) } : {}),
     };
 }
+function parseDiscriminator(value) {
+    const mapping = isRecord(value['mapping'])
+        ? Object.fromEntries(Object.entries(value['mapping']).filter((entry) => typeof entry[1] === 'string'))
+        : undefined;
+    return {
+        propertyName: asString(value['propertyName']),
+        ...(mapping !== undefined ? { mapping } : {}),
+    };
+}
 function parseXml(value) {
     return {
         ...(asString(value['name']) !== undefined ? { name: asString(value['name']) } : {}),
@@ -644,9 +719,6 @@ function parseSwagger2Document(document, declared) {
     if (document['produces'] !== undefined) {
         skipped.push({ kind: 'produces', where: '/produces', reason: 'produces are not imported' });
     }
-    if (document['responses'] !== undefined) {
-        skipped.push({ kind: 'responses', where: '/responses', reason: 'responses are not imported' });
-    }
     return {
         version: '2.0',
         declaredVersion: declared,
@@ -1013,14 +1085,12 @@ function parseSwagger2Operations(document, skipped) {
                 else if (opKey === 'produces') {
                     skipped.push({ kind: 'produces', where: `${where} produces`, reason: 'produces are not imported' });
                 }
-                else if (opKey === 'responses') {
-                    skipped.push({ kind: 'responses', where: `${where} responses`, reason: 'responses are not imported' });
-                }
                 else if (opKey === 'example') {
                     skipped.push({ kind: 'example', where: `${where} example`, reason: 'examples are not imported' });
                 }
             }
             const security = parseSecurityRequirements(operation['security']);
+            const responses = parseResponses(operation['responses'], true);
             operations.push({
                 method: key.toLowerCase(),
                 path,
@@ -1038,6 +1108,7 @@ function parseSwagger2Operations(document, skipped) {
                 ...(asBoolean(operation['deprecated']) === true ? { deprecated: true } : {}),
                 ...(requestBody !== undefined ? { requestBody } : {}),
                 ...(security !== undefined ? { security } : {}),
+                ...(responses !== undefined ? { responses } : {}),
             });
         }
     }

package/dist/rest/openapi/responses.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Choosing the declared response a received one is checked against.
+ *
+ * Status first: the exact code, then its range (`4XX`, any case), then `default`. Then the media type,
+ * parameters ignored: the exact type, then `application/json` for a `+json` suffix, then
+ * `application/*`, then `*\/*`. Pure, so the worker and the tests share it.
+ */
+import type { OpenApiResponses } from './model.js';
+export type ResponseSelection = {
+    readonly kind: 'schema';
+    readonly responseKey: string;
+    readonly mediaType: string;
+    readonly schema: unknown;
+} | {
+    readonly kind: 'no-body';
+    readonly responseKey: string;
+} | {
+    readonly kind: 'no-schema';
+    readonly responseKey: string;
+} | {
+    readonly kind: 'unmatched';
+};
+export declare function selectResponse(responses: OpenApiResponses, status: number, contentType: string | undefined): ResponseSelection;

package/dist/rest/openapi/responses.js

@@ -0,0 +1,59 @@
+function own(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+function findStatus(responses, status) {
+    const exact = String(status);
+    if (own(responses, exact)) {
+        return [exact, responses[exact]];
+    }
+    const range = `${Math.floor(status / 100)}xx`;
+    for (const key of Object.keys(responses)) {
+        if (key.toLowerCase() === range) {
+            return [key, responses[key]];
+        }
+    }
+    if (own(responses, 'default')) {
+        return ['default', responses['default']];
+    }
+    return undefined;
+}
+function essence(mediaType) {
+    return (mediaType.split(';')[0] ?? '').trim().toLowerCase();
+}
+export function selectResponse(responses, status, contentType) {
+    const found = findStatus(responses, status);
+    if (found === undefined) {
+        return { kind: 'unmatched' };
+    }
+    const [responseKey, response] = found;
+    const content = response.content;
+    if (content === undefined || Object.keys(content).length === 0) {
+        return { kind: 'no-body', responseKey };
+    }
+    const declared = new Map();
+    for (const key of Object.keys(content)) {
+        const normal = essence(key);
+        if (!declared.has(normal)) {
+            declared.set(normal, key);
+        }
+    }
+    const received = contentType === undefined ? '' : essence(contentType);
+    const candidates = [
+        received,
+        received.endsWith('+json') ? 'application/json' : '',
+        received.startsWith('application/') ? 'application/*' : '',
+        '*/*',
+    ];
+    for (const candidate of candidates) {
+        const key = candidate === '' ? undefined : declared.get(candidate);
+        if (key === undefined) {
+            continue;
+        }
+        const schema = content[key]?.schema;
+        if (schema === undefined) {
+            return { kind: 'no-schema', responseKey };
+        }
+        return { kind: 'schema', responseKey, mediaType: key, schema };
+    }
+    return { kind: 'no-schema', responseKey };
+}

package/dist/rest/openapi/runtime-expression.d.ts

@@ -0,0 +1,69 @@
+/**
+ * OpenAPI runtime expressions: the `{$request.body#/callbackUrl}` in a callback's key. Parsed once,
+ * evaluated against one recorded exchange of the parent operation. Anything the grammar does not
+ * allow is "not a runtime expression" — never an exception.
+ */
+export type RuntimeSource = {
+    readonly kind: 'header';
+    readonly name: string;
+} | {
+    readonly kind: 'query';
+    readonly name: string;
+} | {
+    readonly kind: 'path';
+    readonly name: string;
+} | {
+    readonly kind: 'body';
+    readonly pointer: string;
+};
+export type RuntimeExpression = {
+    readonly kind: 'url';
+} | {
+    readonly kind: 'method';
+} | {
+    readonly kind: 'statusCode';
+} | {
+    readonly kind: 'request';
+    readonly source: RuntimeSource;
+} | {
+    readonly kind: 'response';
+    readonly source: RuntimeSource;
+};
+export type TemplatePart = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'expression';
+    readonly source: string;
+    readonly expression: RuntimeExpression;
+};
+/** The exchange an expression is evaluated against: the parent operation's last request and reply. */
+export interface RuntimeExchange {
+    readonly url: string;
+    readonly method: string;
+    /** The parent's templated path (`/subscriptions/{id}`), for `$request.path.<name>`. */
+    readonly pathTemplate?: string;
+    readonly request: {
+        readonly headers: readonly (readonly [string, string])[];
+        readonly body?: string;
+    };
+    readonly response?: {
+        readonly status: number;
+        readonly headers: readonly (readonly [string, string])[];
+        readonly body?: string;
+    } | undefined;
+}
+/** Parses one expression without its braces: `$url`, `$request.body#/a`… */
+export declare function parseRuntimeExpression(text: string): RuntimeExpression | undefined;
+/** Splits a callback key into literal text and `{expression}` parts; `undefined` when it does not parse. */
+export declare function parseRuntimeTemplate(key: string): readonly TemplatePart[] | undefined;
+/** RFC 6901: `''` is the whole value; `~1` is `/`, `~0` is `~`. `undefined` when there is nothing there. */
+export declare function resolveJsonPointer(value: unknown, pointer: string): unknown;
+/** Fills a callback key from `exchange`. */
+export declare function evaluateRuntimeTemplate(key: string, exchange: RuntimeExchange): {
+    readonly ok: true;
+    readonly value: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};