@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/asyncapi/import.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Import = parse + map, with the fetched documents handed back for the definition cache and the
+ * references that could not be followed added to the summary.
+ */
+import type { OpenApiSource } from '../json/schema/source.js';
+import type { ResolvedDocument } from '../json/schema/refs.js';
+import { type MapAsyncApiOptions, type MappedAsyncApi } from './map.js';
+import type { AsyncApiDocument } from './model.js';
+import { type ParseAsyncApiOptions } from './parse.js';
+export interface ImportAsyncApiOptions extends ParseAsyncApiOptions, MapAsyncApiOptions {
+}
+export interface ImportedAsyncApi extends MappedAsyncApi {
+    /** Every file fetched, root first — what the definition cache stores. */
+    readonly documents: readonly ResolvedDocument[];
+    readonly declaredVersion: string;
+    /** The parsed document, for a caller that wants to map again with another server. */
+    readonly document: AsyncApiDocument;
+}
+/**
+ * Fetches, resolves, parses and maps one AsyncAPI document into a WebSocket API.
+ *
+ * @throws AsyncApiError the codes `parseAsyncApi` and `mapAsyncApi` throw; an `AbortError` when the
+ * signal fires
+ */
+export declare function importAsyncApi(source: OpenApiSource, options: ImportAsyncApiOptions): Promise<ImportedAsyncApi>;

package/dist/asyncapi/import.js

@@ -0,0 +1,34 @@
+/**
+ * Import = parse + map, with the fetched documents handed back for the definition cache and the
+ * references that could not be followed added to the summary.
+ */
+import { mapAsyncApi } from './map.js';
+import { parseAsyncApi } from './parse.js';
+function sourceOf(source) {
+    if (source.kind === 'url')
+        return source.url;
+    if (source.kind === 'file')
+        return source.path;
+    return source.location ?? 'inline:asyncapi';
+}
+/**
+ * Fetches, resolves, parses and maps one AsyncAPI document into a WebSocket API.
+ *
+ * @throws AsyncApiError the codes `parseAsyncApi` and `mapAsyncApi` throw; an `AbortError` when the
+ * signal fires
+ */
+export async function importAsyncApi(source, options) {
+    const parsed = await parseAsyncApi(source, options);
+    const mapped = mapAsyncApi(parsed.document, options);
+    const skipped = [
+        ...mapped.summary.skipped,
+        ...parsed.problems.map((problem) => ({ where: problem.at, reason: `${problem.ref}: ${problem.reason}` })),
+    ];
+    return {
+        api: { ...mapped.api, definition: { kind: 'asyncapi', source: sourceOf(source), cache: true } },
+        summary: { ...mapped.summary, skipped },
+        documents: parsed.documents,
+        declaredVersion: parsed.document.declaredVersion,
+        document: parsed.document,
+    };
+}

package/dist/asyncapi/map.d.ts

@@ -0,0 +1,40 @@
+/**
+ * An AsyncAPI document as a WebSocket API: one request per WebSocket channel, a saved sample per
+ * message Wirebench sends on it, and the server's first mappable security scheme as the API's auth.
+ *
+ * Pure: the same document and ids give the same API. Everything the mapping cannot carry over is a
+ * line in the summary, never an error — except asking for a server the document does not have.
+ */
+import type { IdGenerator } from '../project/model.js';
+import { type WsApi } from '../ws/model.js';
+import type { AsyncApiDocument, AsyncApiSkip } from './model.js';
+export interface MapAsyncApiOptions {
+    /** The server key to dial; defaults to the first `ws`/`wss` server. */
+    readonly server?: string;
+    readonly newId?: IdGenerator;
+}
+export interface AsyncApiImportSummary {
+    readonly declaredVersion: string;
+    readonly title: string;
+    /** The server the API's URL came from, when there was a WebSocket one. */
+    readonly server?: string;
+    /** Every server key the document lists, WebSocket or not. */
+    readonly servers: readonly string[];
+    readonly requests: number;
+    readonly messages: number;
+    readonly skipped: readonly AsyncApiSkip[];
+    /** Parameters and server variables left as `${name}` for the user to define. */
+    readonly unresolved: readonly string[];
+    /** JSON Schema keywords the contract check will not assert. */
+    readonly unsupportedKeywords: readonly string[];
+}
+export interface MappedAsyncApi {
+    readonly api: WsApi;
+    readonly summary: AsyncApiImportSummary;
+}
+/**
+ * Maps a parsed document to a WebSocket API.
+ *
+ * @throws AsyncApiError `asyncapi-server-unknown` when `options.server` names no WebSocket server
+ */
+export declare function mapAsyncApi(document: AsyncApiDocument, options?: MapAsyncApiOptions): MappedAsyncApi;

package/dist/asyncapi/map.js

@@ -0,0 +1,230 @@
+/**
+ * An AsyncAPI document as a WebSocket API: one request per WebSocket channel, a saved sample per
+ * message Wirebench sends on it, and the server's first mappable security scheme as the API's auth.
+ *
+ * Pure: the same document and ids give the same API. Everything the mapping cannot carry over is a
+ * line in the summary, never an error — except asking for a server the document does not have.
+ */
+import { AsyncApiError } from '../errors.js';
+import { unsupportedKeywordsIn } from '../json/schema-validate.js';
+import { uniqueSlug } from '../project/paths.js';
+import { entry } from '../http/entries.js';
+import { sampleFromSchema } from '../json/schema/sample.js';
+import { createWsApi, createWsFolder, createWsRequest, createWsSavedMessage, } from '../ws/model.js';
+import { isJsonSchemaFormat, isRecord, record, str } from './read.js';
+import { authFromScheme, isSkip } from './security.js';
+const WS_PROTOCOLS = new Set(['ws', 'wss']);
+const SUBPROTOCOL_HEADER = 'sec-websocket-protocol';
+function isWsServer(server) {
+    return WS_PROTOCOLS.has(server.protocol.toLowerCase());
+}
+/** `{name}` placeholders as Wirebench properties, the names collected. */
+function asProperties(text, unresolved) {
+    return text.replace(/\{([^{}]+)\}/g, (_whole, name) => {
+        unresolved.add(name);
+        return `\${${name}}`;
+    });
+}
+function channelUrl(channel, unresolved) {
+    if (channel.address === null)
+        return '';
+    return channel.address.replace(/\{([^{}]+)\}/g, (_whole, name) => {
+        const p = channel.parameters[name];
+        const chosen = p?.default ?? p?.enum?.[0] ?? p?.examples?.[0];
+        if (chosen !== undefined)
+            return chosen;
+        unresolved.add(name);
+        return `\${${name}}`;
+    });
+}
+function sampleText(value) {
+    if (typeof value === 'string')
+        return value;
+    return JSON.stringify(value) ?? '';
+}
+function sampleOf(schema) {
+    return isRecord(schema) ? sampleFromSchema(schema, { includeOptional: false, sampleValues: true }) : '';
+}
+/** `bindings.ws`: query and header properties as entries, `Sec-WebSocket-Protocol` as subprotocols. */
+function wsBinding(channel, skipped) {
+    const binding = record(channel.bindings['ws']);
+    const where = `channel ${channel.key}`;
+    const method = str(binding['method']);
+    if (method !== undefined && method.toUpperCase() !== 'GET') {
+        skipped.push({ where, reason: `ws binding method ${method} is ignored: a handshake is always GET` });
+    }
+    const propertiesOf = (schema) => Object.entries(record(record(schema)['properties']));
+    const query = propertiesOf(binding['query']).map(([name, schema]) => entry(name, sampleText(sampleOf(schema))));
+    const headers = [];
+    const subprotocols = [];
+    for (const [name, schema] of propertiesOf(binding['headers'])) {
+        if (name.toLowerCase() !== SUBPROTOCOL_HEADER) {
+            headers.push(entry(name, sampleText(sampleOf(schema))));
+            continue;
+        }
+        const s = record(schema);
+        const offered = typeof s['const'] === 'string' ? [s['const']] : Array.isArray(s['enum']) ? s['enum'] : [];
+        const names = offered.filter((v) => typeof v === 'string');
+        if (names.length === 0) {
+            skipped.push({ where, reason: 'Sec-WebSocket-Protocol has no const or enum to take a subprotocol from' });
+        }
+        subprotocols.push(...names);
+    }
+    return { query, headers, subprotocols };
+}
+/** Why a channel is not a WebSocket one, or undefined when it is. */
+function notWebSocket(channel, servers) {
+    if (isRecord(channel.bindings['ws']))
+        return undefined;
+    const on = channel.servers === 'all' ? servers : servers.filter((s) => channel.servers.includes(s.key));
+    if (on.some(isWsServer))
+        return undefined;
+    const bindings = Object.keys(channel.bindings);
+    if (bindings.length > 0)
+        return `${bindings.join(', ')} binding: only WebSocket is imported`;
+    const protocols = [...new Set(on.map((s) => s.protocol))];
+    return protocols.length > 0
+        ? `served over ${protocols.join(', ')}: only WebSocket is imported`
+        : 'no WebSocket server carries it';
+}
+/** The saved-message text for one outgoing message, or undefined when it gets no sample. */
+function messageText(m) {
+    if (!isJsonSchemaFormat(m.schemaFormat))
+        return undefined;
+    const value = m.example !== undefined ? m.example : sampleOf(m.payload);
+    if (typeof value === 'string' && record(m.payload)['type'] === 'string')
+        return value;
+    return JSON.stringify(value, null, 2) ?? '';
+}
+function chooseServer(document, wanted) {
+    if (wanted === undefined)
+        return document.servers.find(isWsServer);
+    const server = document.servers.find((s) => s.key === wanted);
+    if (server === undefined || !isWsServer(server)) {
+        throw new AsyncApiError('asyncapi-server-unknown', `The document has no WebSocket server named ${wanted}`, {
+            details: { server: wanted },
+        });
+    }
+    return server;
+}
+/**
+ * Maps a parsed document to a WebSocket API.
+ *
+ * @throws AsyncApiError `asyncapi-server-unknown` when `options.server` names no WebSocket server
+ */
+export function mapAsyncApi(document, options = {}) {
+    const newId = options.newId;
+    const ids = newId !== undefined ? { newId } : {};
+    const skipped = [...document.notes];
+    const unresolved = new Set();
+    const unsupported = new Set();
+    const server = chooseServer(document, options.server);
+    for (const s of document.servers) {
+        if (!isWsServer(s))
+            skipped.push({ where: `server ${s.key}`, reason: `${s.protocol} server: only WebSocket is imported` });
+    }
+    if (server === undefined)
+        skipped.push({ where: 'servers', reason: 'no ws or wss server: the API has no URL' });
+    const url = server !== undefined ? asProperties(server.url, unresolved) : '';
+    let auth;
+    for (const scheme of server?.security ?? []) {
+        const mapped = authFromScheme(scheme);
+        if (isSkip(mapped)) {
+            skipped.push(mapped);
+        }
+        else if (auth === undefined) {
+            auth = mapped;
+        }
+        else {
+            skipped.push({ where: `security ${scheme.key}`, reason: `only the first scheme becomes the API's auth` });
+        }
+    }
+    const rootRequests = [];
+    const folders = new Map();
+    const requestSlugs = new Map();
+    let messageCount = 0;
+    let order = 0;
+    for (const channel of document.channels) {
+        const where = `channel ${channel.key}`;
+        const why = notWebSocket(channel, document.servers);
+        if (why !== undefined) {
+            skipped.push({ where, reason: why });
+            continue;
+        }
+        for (const key of Object.keys(channel.bindings)) {
+            if (key !== 'ws')
+                skipped.push({ where, reason: `${key} binding is ignored on a WebSocket channel` });
+        }
+        const binding = wsBinding(channel, skipped);
+        const operations = document.operations.filter((o) => o.channel === channel.key);
+        const messages = [];
+        const messageSlugs = new Set();
+        const seen = new Set();
+        for (const op of operations) {
+            for (const m of op.messages) {
+                if (isJsonSchemaFormat(m.schemaFormat))
+                    for (const k of unsupportedKeywordsIn(m.payload))
+                        unsupported.add(k);
+                if (op.direction !== 'sent' || seen.has(m.key))
+                    continue;
+                seen.add(m.key);
+                const content = messageText(m);
+                if (content === undefined)
+                    continue;
+                const slug = uniqueSlug(m.name, messageSlugs);
+                messageSlugs.add(slug);
+                messages.push(createWsSavedMessage(m.name, { ...ids, slug, content, contract: { message: m.key, generated: content } }));
+            }
+        }
+        messageCount += messages.length;
+        const tag = channel.tags[0];
+        const bucket = tag ?? '';
+        const slugs = requestSlugs.get(bucket) ?? new Set();
+        requestSlugs.set(bucket, slugs);
+        const slug = uniqueSlug(channel.key, slugs);
+        slugs.add(slug);
+        const request = createWsRequest(channel.key, {
+            ...ids,
+            slug,
+            order: order++,
+            url: channelUrl(channel, unresolved),
+            query: binding.query,
+            headers: binding.headers,
+            subprotocols: binding.subprotocols,
+            messages,
+            contract: { channel: channel.key },
+        });
+        if (tag === undefined)
+            rootRequests.push(request);
+        else
+            folders.set(tag, [...(folders.get(tag) ?? []), request]);
+    }
+    const folderSlugs = new Set();
+    const folderList = [...folders].map(([name, requests], index) => {
+        const slug = uniqueSlug(name, folderSlugs);
+        folderSlugs.add(slug);
+        return createWsFolder(name, { ...ids, slug, order: index, requests });
+    });
+    const requestCount = rootRequests.length + folderList.reduce((n, f) => n + f.requests.length, 0);
+    const api = createWsApi(document.title, {
+        ...ids,
+        url,
+        ...(auth !== undefined ? { auth } : {}),
+        folders: folderList,
+        requests: rootRequests,
+    });
+    return {
+        api,
+        summary: {
+            declaredVersion: document.declaredVersion,
+            title: document.title,
+            ...(server !== undefined ? { server: server.key } : {}),
+            servers: document.servers.map((s) => s.key),
+            requests: requestCount,
+            messages: messageCount,
+            skipped,
+            unresolved: [...unresolved],
+            unsupportedKeywords: [...unsupported].sort(),
+        },
+    };
+}

package/dist/asyncapi/model.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The version-neutral view of an AsyncAPI document that both normalisers (2.x and 3.0) produce.
+ *
+ * Directions are Wirebench's side of the conversation: the document describes an application, and
+ * Wirebench is its peer, so what the application receives is what Wirebench sends.
+ */
+export type AsyncApiVersion = '2' | '3';
+/** One security scheme a server asks for, as the document states it. */
+export interface AsyncApiSecurityScheme {
+    /** The name the document files it under (`components.securitySchemes` key). */
+    readonly key: string;
+    /** `http`, `httpApiKey`, `apiKey`, `userPassword`, `oauth2`, … — as written. */
+    readonly type: string;
+    readonly description?: string;
+    /** `http`: `basic`, `bearer`, …, lower-cased. */
+    readonly scheme?: string;
+    readonly bearerFormat?: string;
+    /** `httpApiKey` / `apiKey`: where the key travels (`query`, `header`, `cookie`, `user`, `password`). */
+    readonly in?: string;
+    /** `httpApiKey`: the parameter's name. */
+    readonly name?: string;
+    /** `oauth2` / `openIdConnect`: the first flow's endpoints and scope names. */
+    readonly grant?: 'client-credentials' | 'authorization-code' | 'implicit' | 'password';
+    readonly tokenUrl?: string;
+    readonly authorizationUrl?: string;
+    readonly scopes?: readonly string[];
+    /** `openIdConnect`: the discovery document. */
+    readonly openIdConnectUrl?: string;
+}
+export interface AsyncApiServer {
+    readonly key: string;
+    /** The full URL, variables substituted by `default` (else the first `enum` value). */
+    readonly url: string;
+    readonly protocol: string;
+    readonly security: readonly AsyncApiSecurityScheme[];
+    /** Variables left as `{name}` in {@link url}: no default and no enum to take one from. */
+    readonly unresolvedVariables: readonly string[];
+}
+export interface AsyncApiMessage {
+    readonly key: string;
+    /** `name`, else `title`, else {@link key}. */
+    readonly name: string;
+    readonly title?: string;
+    readonly contentType: string;
+    readonly schemaFormat?: string;
+    readonly payload?: unknown;
+    readonly example?: unknown;
+}
+export interface AsyncApiOperation {
+    readonly key: string;
+    /** The key of the channel it runs on. */
+    readonly channel: string;
+    /** Wirebench's side: what the described application receives, Wirebench sends. */
+    readonly direction: 'sent' | 'received';
+    readonly messages: readonly AsyncApiMessage[];
+}
+export interface AsyncApiChannelParameter {
+    readonly default?: string;
+    readonly enum?: readonly string[];
+    readonly examples?: readonly string[];
+}
+export interface AsyncApiChannel {
+    readonly key: string;
+    readonly address: string | null;
+    /** The server keys it is available on, or every server. */
+    readonly servers: readonly string[] | 'all';
+    readonly parameters: Readonly<Record<string, AsyncApiChannelParameter>>;
+    readonly bindings: Readonly<Record<string, unknown>>;
+    readonly tags: readonly string[];
+}
+/** Something in the document that could not be mapped, and why. Never fatal. */
+export interface AsyncApiSkip {
+    readonly where: string;
+    readonly reason: string;
+}
+export interface AsyncApiDocument {
+    readonly version: AsyncApiVersion;
+    readonly declaredVersion: string;
+    readonly title: string;
+    readonly servers: readonly AsyncApiServer[];
+    readonly channels: readonly AsyncApiChannel[];
+    readonly operations: readonly AsyncApiOperation[];
+    readonly notes: readonly AsyncApiSkip[];
+}

package/dist/asyncapi/model.js

@@ -0,0 +1,7 @@
+/**
+ * The version-neutral view of an AsyncAPI document that both normalisers (2.x and 3.0) produce.
+ *
+ * Directions are Wirebench's side of the conversation: the document describes an application, and
+ * Wirebench is its peer, so what the application receives is what Wirebench sends.
+ */
+export {};

package/dist/asyncapi/normalise-2.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AsyncAPI 2.x into the version-neutral view.
+ *
+ * In 2.x a channel's `publish` is what the described application accepts — so Wirebench, its peer,
+ * sends it — and `subscribe` is what the application emits, which Wirebench receives.
+ */
+import type { AsyncApiDocument } from './model.js';
+import { type Json } from './read.js';
+/**
+ * @param raw the parsed document before `$ref` inlining, where the keys references name still are
+ * @param resolved the same document with references inlined
+ */
+export declare function normaliseAsyncApi2(raw: Json, resolved: Json, declaredVersion: string): AsyncApiDocument;

package/dist/asyncapi/normalise-2.js

@@ -0,0 +1,113 @@
+/**
+ * AsyncAPI 2.x into the version-neutral view.
+ *
+ * In 2.x a channel's `publish` is what the described application accepts — so Wirebench, its peer,
+ * sends it — and `subscribe` is what the application emits, which Wirebench receives.
+ */
+import { channelParameter, deref, entries, isJsonSchemaFormat, isRecord, message, record, refKey, securityScheme, str, substitute, tagNames, } from './read.js';
+const DIRECTIONS = [
+    ['publish', 'sent'],
+    ['subscribe', 'received'],
+];
+function payloadOf(node) {
+    const schemaFormat = str(node['schemaFormat']);
+    return {
+        ...('payload' in node ? { payload: node['payload'] } : {}),
+        ...(schemaFormat !== undefined ? { schemaFormat } : {}),
+    };
+}
+/**
+ * @param raw the parsed document before `$ref` inlining, where the keys references name still are
+ * @param resolved the same document with references inlined
+ */
+export function normaliseAsyncApi2(raw, resolved, declaredVersion) {
+    const notes = [];
+    const defaultContentType = str(resolved['defaultContentType']) ?? 'application/json';
+    const schemes = record(record(resolved['components'])['securitySchemes']);
+    const servers = entries(resolved['servers']).map(([key, server]) => {
+        const protocol = str(server['protocol']) ?? '';
+        const written = str(server['url']) ?? '';
+        const { value, unresolved } = substitute(written, server['variables']);
+        const url = value.includes('://') || protocol === '' ? value : `${protocol}://${value}`;
+        const security = Array.isArray(server['security']) ? server['security'] : [];
+        return {
+            key,
+            url,
+            protocol,
+            security: security.flatMap((requirement) => Object.keys(record(requirement)).flatMap((name) => {
+                const scheme = schemes[name];
+                if (!isRecord(scheme)) {
+                    notes.push({ where: `servers/${key}/security`, reason: `no security scheme named ${name}` });
+                    return [];
+                }
+                return [securityScheme(name, scheme)];
+            })),
+            unresolvedVariables: unresolved,
+        };
+    });
+    const channels = [];
+    const operations = [];
+    const rawChannels = record(raw['channels']);
+    for (const [key, channel] of entries(resolved['channels'])) {
+        const listed = channel['servers'];
+        channels.push({
+            key,
+            address: key,
+            servers: Array.isArray(listed) && listed.length > 0 ? listed.filter((s) => typeof s === 'string') : 'all',
+            parameters: Object.fromEntries(entries(channel['parameters']).map(([name, parameter]) => [
+                name,
+                channelParameter(record(parameter['schema'])),
+            ])),
+            bindings: record(channel['bindings']),
+            tags: tagNames(channel['tags']),
+        });
+        const rawChannel = record(deref(raw, rawChannels[key]));
+        for (const [verb, direction] of DIRECTIONS) {
+            const operation = channel[verb];
+            if (operation === undefined)
+                continue;
+            const where = `channels/${key}/${verb}`;
+            if (!isRecord(operation)) {
+                notes.push({ where, reason: 'the operation is not an object' });
+                continue;
+            }
+            const opKey = str(operation['operationId']) ?? `${key}#${verb}`;
+            const rawMessage = record(deref(raw, rawChannel[verb]))['message'];
+            const messages = messagesOf(raw, rawMessage, operation['message'], opKey, defaultContentType);
+            for (const m of messages) {
+                if (!isJsonSchemaFormat(m.schemaFormat)) {
+                    notes.push({ where, reason: `message ${m.key} uses ${String(m.schemaFormat)}, which is not JSON Schema` });
+                }
+            }
+            if (messages.length === 0) {
+                notes.push({ where, reason: 'the operation names no message' });
+            }
+            operations.push({ key: opKey, channel: key, direction, messages });
+        }
+    }
+    return {
+        version: '2',
+        declaredVersion,
+        title: str(record(resolved['info'])['title']) ?? '',
+        servers,
+        channels,
+        operations,
+        notes,
+    };
+}
+function messagesOf(raw, rawNode, node, opKey, defaultContentType) {
+    if (!isRecord(node))
+        return [];
+    const one = (rawOne, value, index) => {
+        if (!isRecord(value))
+            return [];
+        const key = refKey(rawOne) ?? str(value['messageId']) ?? str(value['name']) ?? `${opKey}#message${String(index)}`;
+        return [message(key, value, defaultContentType, payloadOf, true)];
+    };
+    const oneOf = node['oneOf'];
+    if (Array.isArray(oneOf)) {
+        const rawOneOf = record(deref(raw, rawNode))['oneOf'];
+        return oneOf.flatMap((value, index) => one(Array.isArray(rawOneOf) ? rawOneOf[index] : undefined, value, index));
+    }
+    return one(rawNode, node, 0);
+}

package/dist/asyncapi/normalise-3.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AsyncAPI 3.0 into the version-neutral view.
+ *
+ * A 3.0 operation's `action` is the described application's: `receive` is what it accepts, so
+ * Wirebench — its peer — sends it, and `send` is what it emits, which Wirebench receives. A `reply`
+ * travels the other way from its operation.
+ */
+import type { AsyncApiDocument } from './model.js';
+import { type Json } from './read.js';
+/**
+ * @param raw the parsed document before `$ref` inlining, where the keys references name still are
+ * @param resolved the same document with references inlined
+ */
+export declare function normaliseAsyncApi3(raw: Json, resolved: Json, declaredVersion: string): AsyncApiDocument;