@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/rest/openapi/runtime-expression.js

@@ -0,0 +1,213 @@
+/**
+ * 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.
+ */
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+function parseSource(text, request) {
+    if (text === 'body')
+        return { kind: 'body', pointer: '' };
+    if (text.startsWith('body#')) {
+        const pointer = text.slice('body#'.length);
+        return pointer === '' || pointer.startsWith('/') ? { kind: 'body', pointer } : undefined;
+    }
+    const dot = text.indexOf('.');
+    if (dot < 0)
+        return undefined;
+    const where = text.slice(0, dot);
+    const name = text.slice(dot + 1);
+    if (name === '')
+        return undefined;
+    if (where === 'header')
+        return TOKEN.test(name) ? { kind: 'header', name } : undefined;
+    if (request && (where === 'query' || where === 'path'))
+        return { kind: where, name };
+    return undefined;
+}
+/** Parses one expression without its braces: `$url`, `$request.body#/a`… */
+export function parseRuntimeExpression(text) {
+    if (text === '$url')
+        return { kind: 'url' };
+    if (text === '$method')
+        return { kind: 'method' };
+    if (text === '$statusCode')
+        return { kind: 'statusCode' };
+    for (const kind of ['request', 'response']) {
+        const prefix = `$${kind}.`;
+        if (text.startsWith(prefix)) {
+            const source = parseSource(text.slice(prefix.length), kind === 'request');
+            return source === undefined ? undefined : { kind, source };
+        }
+    }
+    return undefined;
+}
+/** Splits a callback key into literal text and `{expression}` parts; `undefined` when it does not parse. */
+export function parseRuntimeTemplate(key) {
+    const parts = [];
+    let index = 0;
+    while (index < key.length) {
+        const open = key.indexOf('{', index);
+        if (open < 0) {
+            parts.push({ kind: 'text', text: key.slice(index) });
+            break;
+        }
+        if (open > index)
+            parts.push({ kind: 'text', text: key.slice(index, open) });
+        const close = key.indexOf('}', open);
+        if (close < 0)
+            return undefined;
+        const source = key.slice(open + 1, close);
+        const expression = parseRuntimeExpression(source);
+        if (expression === undefined)
+            return undefined;
+        parts.push({ kind: 'expression', source, expression });
+        index = close + 1;
+    }
+    return parts;
+}
+/** RFC 6901: `''` is the whole value; `~1` is `/`, `~0` is `~`. `undefined` when there is nothing there. */
+export function resolveJsonPointer(value, pointer) {
+    if (pointer === '')
+        return value;
+    let current = value;
+    for (const raw of pointer.slice(1).split('/')) {
+        const key = raw.replaceAll('~1', '/').replaceAll('~0', '~');
+        if (Array.isArray(current)) {
+            if (!/^(0|[1-9][0-9]*)$/.test(key))
+                return undefined;
+            current = current[Number(key)];
+        }
+        else if (typeof current === 'object' && current !== null && Object.hasOwn(current, key)) {
+            current = current[key];
+        }
+        else {
+            return undefined;
+        }
+        if (current === undefined)
+            return undefined;
+    }
+    return current;
+}
+function headerOf(headers, name) {
+    const lower = name.toLowerCase();
+    return headers.find(([candidate]) => candidate.toLowerCase() === lower)?.[1];
+}
+function pathParam(url, template, name) {
+    if (template === undefined)
+        return undefined;
+    let path;
+    try {
+        path = new URL(url).pathname;
+    }
+    catch {
+        return undefined;
+    }
+    // Segment by segment, aligned from the end so a server base path in front still matches. No
+    // regular expression: the template comes from a document and must not be able to stall a send.
+    const templateSegments = template.split('/');
+    const pathSegments = path.split('/');
+    const offset = pathSegments.length - templateSegments.length;
+    if (offset < 0)
+        return undefined;
+    let found;
+    for (let index = 0; index < templateSegments.length; index += 1) {
+        const expected = templateSegments[index];
+        const actual = pathSegments[offset + index];
+        if (index === 0 && expected === '')
+            continue;
+        const open = expected.indexOf('{');
+        if (open < 0) {
+            if (expected !== actual)
+                return undefined;
+            continue;
+        }
+        const close = expected.indexOf('}', open);
+        // One parameter per segment, with optional literal text around it (`{name}.json`).
+        if (close < 0 || expected.includes('{', close))
+            return undefined;
+        const prefix = expected.slice(0, open);
+        const suffix = expected.slice(close + 1);
+        if (actual.length <= prefix.length + suffix.length || !actual.startsWith(prefix) || !actual.endsWith(suffix)) {
+            return undefined;
+        }
+        if (expected.slice(open + 1, close) === name) {
+            found = actual.slice(prefix.length, actual.length - suffix.length);
+        }
+    }
+    if (found === undefined)
+        return undefined;
+    try {
+        return decodeURIComponent(found);
+    }
+    catch {
+        // A stray `%` that is not an escape: the parameter has no value rather than the send failing.
+        return undefined;
+    }
+}
+function bodyValue(body, pointer) {
+    if (body === undefined)
+        return undefined;
+    if (pointer === '')
+        return body;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    const found = resolveJsonPointer(parsed, pointer);
+    if (found === undefined || found === null)
+        return undefined;
+    return typeof found === 'string' ? found : JSON.stringify(found);
+}
+function evaluate(expression, exchange) {
+    switch (expression.kind) {
+        case 'url':
+            return exchange.url;
+        case 'method':
+            return exchange.method;
+        case 'statusCode':
+            return exchange.response === undefined ? undefined : String(exchange.response.status);
+        case 'request':
+        case 'response': {
+            const side = expression.kind === 'request' ? exchange.request : exchange.response;
+            if (side === undefined)
+                return undefined;
+            const source = expression.source;
+            switch (source.kind) {
+                case 'header':
+                    return headerOf(side.headers, source.name);
+                case 'body':
+                    return bodyValue(side.body, source.pointer);
+                case 'query':
+                    try {
+                        return new URL(exchange.url).searchParams.get(source.name) ?? undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                case 'path':
+                    return pathParam(exchange.url, exchange.pathTemplate, source.name);
+            }
+        }
+    }
+}
+/** Fills a callback key from `exchange`. */
+export function evaluateRuntimeTemplate(key, exchange) {
+    const parts = parseRuntimeTemplate(key);
+    if (parts === undefined)
+        return { ok: false, reason: 'not a runtime expression' };
+    let value = '';
+    for (const part of parts) {
+        if (part.kind === 'text') {
+            value += part.text;
+            continue;
+        }
+        const found = evaluate(part.expression, exchange);
+        if (found === undefined)
+            return { ok: false, reason: `${part.source} has no value` };
+        value += found;
+    }
+    return { ok: true, value };
+}

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

@@ -0,0 +1,116 @@
+/**
+ * Update Definition for an OpenAPI-imported REST API: a per-operation report of what a new version of
+ * the document changes.
+ *
+ * An operation is identified by its lower-cased method and its path exactly as the document writes
+ * it, the same key a request's contract link uses — so a renamed path is a removal plus an addition,
+ * never a guess by `operationId`.
+ *
+ * Schemas arrive `$ref`-resolved, which means shared and even cyclic object graphs, so nothing here
+ * serialises them: {@link sameStructure} walks both sides together and remembers the pairs it is
+ * already comparing.
+ *
+ * Applying one follows the AsyncAPI rule: both documents are re-mapped with the importer's own
+ * {@link apiFromDocument}, and a generated value follows the new document only while it still equals
+ * what the old document generated. Nothing is ever deleted: a request whose operation is gone is
+ * flagged `orphaned`, and one whose operation came back has the flag cleared.
+ *
+ * Pure: it reads two parsed documents and writes nothing.
+ */
+import type { IdGenerator } from '../../project/model.js';
+import type { WebhookFolder } from '../../webhooks/model.js';
+import type { RestApi } from '../model.js';
+import type { WebhookItemRef } from './map.js';
+import type { OpenApiDocument } from './model.js';
+export type RestChangeReason = 'parameters' | 'request-body' | 'responses' | 'security' | 'servers';
+export type RestApiChangeReason = 'servers' | 'security' | 'version';
+export interface RestOpRef {
+    readonly method: string;
+    readonly path: string;
+    readonly summary?: string;
+}
+/** What moving from one document to the next would do to its webhooks and callbacks. */
+export interface WebhookUpdatePlan {
+    readonly added: readonly WebhookItemRef[];
+    readonly removed: readonly WebhookItemRef[];
+    readonly changed: readonly {
+        readonly item: WebhookItemRef;
+        readonly reasons: readonly RestChangeReason[];
+    }[];
+}
+export interface RestUpdatePlan {
+    readonly added: readonly RestOpRef[];
+    readonly removed: readonly RestOpRef[];
+    readonly changed: readonly {
+        readonly op: RestOpRef;
+        readonly reasons: readonly RestChangeReason[];
+    }[];
+    readonly api: readonly RestApiChangeReason[];
+    readonly webhooks: WebhookUpdatePlan;
+}
+/**
+ * Structural equality that terminates on cycles: a pair already under comparison is assumed equal,
+ * which is sound because any real difference is found along some other finite path.
+ */
+export declare function sameStructure(a: unknown, b: unknown): boolean;
+/**
+ * What moving from `old` to `next` would change: added and changed operations in `next`'s document
+ * order, removed ones in `old`'s, and the API-level differences.
+ */
+export declare function planRestUpdate(old: OpenApiDocument, next: OpenApiDocument): RestUpdatePlan;
+/**
+ * What moving from `old` to `next` would change among webhooks and callbacks: added and changed
+ * items keyed as {@link hookKey} matches them, removed ones the same way. Mirrors
+ * {@link planRestUpdate}'s per-operation comparison, over {@link webhookSourcesOf} instead of
+ * `document.operations`.
+ */
+export declare function planWebhookUpdate(old: OpenApiDocument, next: OpenApiDocument): WebhookUpdatePlan;
+/** What {@link applyRestUpdate} changed, counted for the toast. */
+export interface RestApplyResult {
+    readonly api: RestApi;
+    readonly requestsAdded: number;
+    /**
+     * Operations the plan lists under Added that a request already claims by contract, so no request
+     * was made for them. The plan compares documents alone and cannot see them; this is the difference.
+     */
+    readonly requestsAlreadyPresent: number;
+    readonly requestsOrphaned: number;
+    readonly requestsRestored: number;
+    /** Requests where at least one generated field followed the new document. */
+    readonly requestsRewritten: number;
+    readonly rowsAdded: number;
+    readonly rowsRemoved: number;
+}
+export interface ApplyRestUpdateOptions {
+    readonly newId?: IdGenerator;
+    /** Passed to the sampler for a body a generated field follows into, as the importer would. */
+    readonly includeOptional?: boolean;
+    /** Passed to the sampler for a body a generated field follows into, as the importer would. */
+    readonly sampleValues?: boolean;
+}
+/**
+ * Applies `next` to an API imported from `old`: the request of every operation still in `next`
+ * follows it where untouched, the request of every operation gone is orphaned, and every new
+ * operation gets a request in the folder the importer would have put it in. Never deletes a request
+ * or a folder.
+ */
+export declare function applyRestUpdate(api: RestApi, old: OpenApiDocument, next: OpenApiDocument, options?: ApplyRestUpdateOptions): RestApplyResult;
+/** What {@link applyWebhookUpdate} changed, counted for the toast. */
+export interface WebhookApplyResult {
+    readonly folder: WebhookFolder;
+    readonly added: number;
+    readonly orphaned: number;
+    readonly restored: number;
+    readonly rewritten: number;
+}
+/**
+ * Applies `next` to a webhook group imported from `old`: the same follow rule as
+ * {@link applyRestUpdate}, matched by {@link hookKey} across the group's whole tree instead of by
+ * contract. A request with no `hook` (added by hand) is left untouched; an item's `hook` — including
+ * a callback's `expression` — follows the new document, since a renamed expression is not a new
+ * item. A new webhook or callback method is appended to the group root with a unique slug and an
+ * increasing `order` — but only one truly new to `next`: an item `old` already offered and the group
+ * never held (an import that used `only` to leave it unticked) stays absent rather than coming back.
+ * Never deletes a request or a folder.
+ */
+export declare function applyWebhookUpdate(folder: WebhookFolder, old: OpenApiDocument, next: OpenApiDocument, options?: ApplyRestUpdateOptions): WebhookApplyResult;