@wirebench/engine 2.1.1

package/dist/soap/legacy-project/import.js

@@ -0,0 +1,46 @@
+/**
+ * Reading a legacy single-XML SOAP project from a file or text. Mapping it onto a Wirebench project
+ * is `map.ts`'s job, once each interface's definition has been resolved.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { LegacyProjectError } from '../../errors.js';
+import { parseLegacyProject } from './parse.js';
+/** Largest project accepted, in bytes (file) or UTF-16 code units (text). */
+export const MAX_LEGACY_PROJECT_BYTES = 50 * 1024 * 1024;
+function tooLarge() {
+    return new LegacyProjectError('legacy-too-large', `The project file is larger than ${String(MAX_LEGACY_PROJECT_BYTES / (1024 * 1024))} MB`);
+}
+/**
+ * Reads and parses a legacy SOAP project.
+ *
+ * @throws LegacyProjectError when the file cannot be read, is too large, or is not a readable project.
+ */
+export async function readLegacySoapProject(source) {
+    if (source.kind === 'text') {
+        if (source.text.length > MAX_LEGACY_PROJECT_BYTES) {
+            throw tooLarge();
+        }
+        return parseLegacyProject(source.text);
+    }
+    let size;
+    try {
+        size = (await stat(source.path)).size;
+    }
+    catch {
+        size = undefined; // reported by readFile below
+    }
+    if (size !== undefined && size > MAX_LEGACY_PROJECT_BYTES) {
+        throw tooLarge();
+    }
+    let text;
+    try {
+        text = await readFile(source.path, 'utf8');
+    }
+    catch (cause) {
+        throw new LegacyProjectError('legacy-read-failed', `Could not read "${source.path}"`, {
+            cause,
+            details: { path: source.path },
+        });
+    }
+    return parseLegacyProject(text, source.path);
+}

package/dist/soap/legacy-project/index.d.ts

@@ -0,0 +1,9 @@
+export { looksLikeLegacyProject } from './format.js';
+export { MAX_LEGACY_PROJECT_BYTES, readLegacySoapProject } from './import.js';
+export type { LegacyProjectSource } from './import.js';
+export type * from './model.js';
+export { parseLegacyProject } from './parse.js';
+export { definitionRootOf, fetchDocumentFromCache } from './definition-fetcher.js';
+export type { CacheFetchOptions } from './definition-fetcher.js';
+export { formatLegacyImportReport, IMPORTED_SCRIPTS_DIR, mapLegacyProject, resolvedOperationsOf } from './map.js';
+export type { LegacyImportReport, LegacyImportReportItem, LegacyMapContext, LegacyScriptFile, MappedLegacyProject, ResolvedLegacyInterface, ResolvedOperation, } from './map.js';

package/dist/soap/legacy-project/index.js

@@ -0,0 +1,5 @@
+export { looksLikeLegacyProject } from './format.js';
+export { MAX_LEGACY_PROJECT_BYTES, readLegacySoapProject } from './import.js';
+export { parseLegacyProject } from './parse.js';
+export { definitionRootOf, fetchDocumentFromCache } from './definition-fetcher.js';
+export { formatLegacyImportReport, IMPORTED_SCRIPTS_DIR, mapLegacyProject, resolvedOperationsOf } from './map.js';

package/dist/soap/legacy-project/map.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Maps a parsed legacy SOAP project onto Wirebench project entities.
+ *
+ * Pure: resolving each interface's definition (which needs the network or the definition cache) is
+ * the caller's job, and it hands the result in as a {@link ResolvedLegacyInterface}. What comes back
+ * is ready to be added to a project, plus the report of everything that did not come across.
+ */
+import type { Environment, IdGenerator, Interface } from '../../project/model.js';
+import type { OperationSummary } from '../../types.js';
+import type { LegacyInterface, LegacyProject } from './model.js';
+/** One operation of a resolved definition, as the mapper needs it. */
+export interface ResolvedOperation {
+    /** The owning binding as `{namespace}localName`. */
+    readonly bindingName: string;
+    readonly name: string;
+    readonly soapVersion: '1.1' | '1.2' | 'none';
+    readonly soapAction?: string;
+}
+/** The engine's operation summaries, as {@link ResolvedOperation}s. */
+export declare function resolvedOperationsOf(summaries: readonly OperationSummary[]): ResolvedOperation[];
+/** A legacy interface after the caller tried to resolve its definition. */
+export type ResolvedLegacyInterface = {
+    readonly legacy: LegacyInterface;
+    /** The id and slug the caller chose (the slug names the definition-cache folder it wrote). */
+    readonly id: string;
+    readonly slug: string;
+} & ({
+    readonly resolved: true;
+    readonly definitionUrl: string;
+    readonly targetNamespace?: string;
+    readonly operations: readonly ResolvedOperation[];
+    /** Locations that were not in the file's cache and came from the network. */
+    readonly fetchedFromNetwork: readonly string[];
+} | {
+    readonly resolved: false;
+    readonly problem: string;
+});
+/** What the target project already holds, so nothing imported collides with it. */
+export interface LegacyMapContext {
+    readonly environmentNames: ReadonlySet<string>;
+    readonly environmentSlugs: ReadonlySet<string>;
+    readonly propertyNames: ReadonlySet<string>;
+    /** The `order` the first imported interface gets; interfaces and APIs share one sequence. */
+    readonly firstInterfaceOrder: number;
+    readonly firstEnvironmentOrder: number;
+    readonly newId?: IdGenerator;
+}
+/** One line of the import report. */
+export interface LegacyImportReportItem {
+    readonly severity: 'info' | 'warning';
+    /** Owner names from the project down, joined with ` › `; empty for the project itself. */
+    readonly path: string;
+    readonly message: string;
+}
+/** What came across, and what did not. */
+export interface LegacyImportReport {
+    readonly projectName: string;
+    readonly counts: {
+        readonly interfaces: number;
+        readonly operations: number;
+        readonly requests: number;
+        readonly environments: number;
+        readonly properties: number;
+        readonly scripts: number;
+    };
+    readonly items: readonly LegacyImportReportItem[];
+}
+/** A script to write, as is, under the project folder. */
+export interface LegacyScriptFile {
+    /** Relative to the project root, `/`-separated, always under {@link IMPORTED_SCRIPTS_DIR}. */
+    readonly path: string;
+    readonly source: string;
+}
+/** The mapped entities, ready to add to a project. */
+export interface MappedLegacyProject {
+    readonly interfaces: readonly Interface[];
+    readonly environments: readonly Environment[];
+    /** Only the properties the project did not already have. */
+    readonly properties: Readonly<Record<string, string>>;
+    readonly scripts: readonly LegacyScriptFile[];
+    readonly report: LegacyImportReport;
+}
+/** The folder imported scripts are written to. Nothing in Wirebench reads it. */
+export declare const IMPORTED_SCRIPTS_DIR = "imported-scripts";
+/**
+ * Maps `project` onto Wirebench entities. `resolved` holds one entry per `project.interfaces`
+ * element, in the same order.
+ */
+export declare function mapLegacyProject(project: LegacyProject, resolved: readonly ResolvedLegacyInterface[], context: LegacyMapContext): MappedLegacyProject;
+/** The report as plain text, one line per item, for copying out of the dialog. */
+export declare function formatLegacyImportReport(report: LegacyImportReport): string;

package/dist/soap/legacy-project/map.js

@@ -0,0 +1,290 @@
+/**
+ * Maps a parsed legacy SOAP project onto Wirebench project entities.
+ *
+ * Pure: resolving each interface's definition (which needs the network or the definition cache) is
+ * the caller's job, and it hands the result in as a {@link ResolvedLegacyInterface}. What comes back
+ * is ready to be added to a project, plus the report of everything that did not come across.
+ */
+import { createInterface, createRequest, generateId } from '../../project/model.js';
+import { slugify, uniqueSlug } from '../../project/paths.js';
+import { DEFAULT_WSA_CONFIG } from '../../wsa/model.js';
+import { qnameToString } from '../../wsdl/qname.js';
+/** The engine's operation summaries, as {@link ResolvedOperation}s. */
+export function resolvedOperationsOf(summaries) {
+    return summaries.map((summary) => ({
+        bindingName: qnameToString(summary.bindingName),
+        name: summary.operationName,
+        soapVersion: summary.soapVersion,
+        ...(summary.soapAction !== undefined ? { soapAction: summary.soapAction } : {}),
+    }));
+}
+/** The folder imported scripts are written to. Nothing in Wirebench reads it. */
+export const IMPORTED_SCRIPTS_DIR = 'imported-scripts';
+const PATH_SEPARATOR = ' › ';
+/** Auth types the file can name that a username alone cannot stand in for. */
+const UNSUPPORTED_AUTH = new Set(['SPNEGO/Kerberos', 'OAuth 2.0', 'OAuth 1.0']);
+function joinPath(...segments) {
+    return segments.filter((segment) => segment !== '').join(PATH_SEPARATOR);
+}
+/** A name not in `taken`, numbered from 2 when it is: `Staging`, `Staging 2`, ... */
+function uniqueName(name, taken) {
+    const lower = new Set([...taken].map((entry) => entry.toLowerCase()));
+    if (!lower.has(name.toLowerCase())) {
+        return name;
+    }
+    for (let n = 2;; n += 1) {
+        const candidate = `${name} ${String(n)}`;
+        if (!lower.has(candidate.toLowerCase())) {
+            return candidate;
+        }
+    }
+}
+/** The credentials a call carried, as Wirebench auth: a username kept, the password never. */
+function authOf(call) {
+    const { username, domain, authType } = call.credentials;
+    if (username === undefined || (authType !== undefined && UNSUPPORTED_AUTH.has(authType))) {
+        return undefined;
+    }
+    if (domain !== undefined || authType === 'NTLM') {
+        return { type: 'ntlm', username, ...(domain !== undefined ? { domain } : {}) };
+    }
+    return { type: 'basic', username, ...(authType === 'Preemptive' ? { preemptive: true } : {}) };
+}
+class ReportBuilder {
+    items = [];
+    info(path, message) {
+        this.items.push({ severity: 'info', path, message });
+    }
+    warning(path, message) {
+        this.items.push({ severity: 'warning', path, message });
+    }
+}
+/** Everything a call carried that the request cannot, reported against `path`. */
+function reportCallLosses(call, path, report) {
+    if (call.credentials.hadPassword) {
+        report.warning(path, 'The password was not imported. Enter it again under Auth.');
+    }
+    const { authType, username } = call.credentials;
+    if (username !== undefined && authType !== undefined && UNSUPPORTED_AUTH.has(authType)) {
+        report.warning(path, `${authType} authentication is not imported. Set up auth for this request again.`);
+    }
+    if (call.assertions > 0) {
+        report.warning(path, `${String(call.assertions)} assertion${call.assertions === 1 ? ' was' : 's were'} not imported.`);
+    }
+    if (call.attachments > 0) {
+        report.warning(path, `${String(call.attachments)} attachment${call.attachments === 1 ? ' was' : 's were'} not imported. Add the files again.`);
+    }
+    for (const ref of call.wssRefs) {
+        report.warning(path, `The WS-Security configuration "${ref}" was not imported.`);
+    }
+}
+/**
+ * The interface's operations: every operation of the legacy binding in definition order, then any
+ * legacy operation the definition no longer has (its requests marked orphaned).
+ */
+function mapOperations(entry, endpoints, newId, report) {
+    const { legacy } = entry;
+    const ownBinding = entry.operations.filter((operation) => legacy.bindingName === undefined || operation.bindingName === legacy.bindingName);
+    const byName = new Map();
+    for (const operation of legacy.operations) {
+        byName.set(operation.bindingOperationName, operation);
+    }
+    const taken = new Set();
+    const operations = [];
+    let requests = 0;
+    const build = (name, bindingName, source, resolved) => {
+        const slug = uniqueSlug(name, taken);
+        taken.add(slug);
+        const requestSlugs = new Set();
+        const defs = [];
+        for (const call of source?.calls ?? []) {
+            const path = joinPath(legacy.name, name, call.name);
+            if (call.envelope === undefined) {
+                report.warning(path, `The request was skipped: ${call.envelopeProblem ?? 'its body could not be read'}.`);
+                continue;
+            }
+            const requestSlug = uniqueSlug(call.name, requestSlugs);
+            requestSlugs.add(requestSlug);
+            const endpoint = call.endpoint === undefined ? undefined : endpoints.find((candidate) => candidate.url === call.endpoint);
+            const soapVersion = resolved !== undefined && resolved.soapVersion !== 'none' ? resolved.soapVersion : legacy.soapVersion;
+            const soapAction = resolved?.soapAction ?? source?.action;
+            const auth = authOf(call);
+            const request = createRequest(call.name, {
+                newId,
+                slug: requestSlug,
+                order: defs.length,
+                envelopeXml: call.envelope,
+                soapVersion,
+                ...(soapAction !== undefined ? { soapAction } : {}),
+                ...(endpoint !== undefined ? { endpointId: endpoint.id } : {}),
+                properties: {
+                    ...(call.encoding !== undefined ? { encoding: call.encoding } : {}),
+                    ...(call.timeoutMs !== undefined ? { timeoutMs: call.timeoutMs } : {}),
+                },
+            });
+            defs.push({
+                ...request,
+                ...(endpoint === undefined && call.endpoint !== undefined ? { endpointUrl: call.endpoint } : {}),
+                ...(auth !== undefined ? { auth } : {}),
+                ...(call.useWsAddressing ? { wsa: { ...DEFAULT_WSA_CONFIG, enabled: true } } : {}),
+                ...(resolved === undefined ? { orphaned: true } : {}),
+            });
+            reportCallLosses(call, path, report);
+        }
+        requests += defs.length;
+        operations.push({ name, bindingName, slug, order: operations.length, requests: defs });
+    };
+    const matched = new Set();
+    for (const resolved of ownBinding) {
+        const source = byName.get(resolved.name);
+        if (source !== undefined) {
+            matched.add(source);
+        }
+        build(resolved.name, resolved.bindingName, source, resolved);
+    }
+    const fallbackBinding = legacy.bindingName ?? ownBinding[0]?.bindingName ?? '';
+    for (const source of legacy.operations) {
+        if (matched.has(source)) {
+            continue;
+        }
+        if (source.calls.length > 0) {
+            report.info(joinPath(legacy.name, source.name), 'The definition no longer has this operation; its requests were kept and marked as orphaned.');
+        }
+        build(source.bindingOperationName, fallbackBinding, source, undefined);
+    }
+    return { operations, requests };
+}
+/** Where a script lands: `imported-scripts/<owners...>/<element>.<ext>`, unique within `taken`. */
+function scriptPath(script, taken) {
+    const extension = script.language?.toLowerCase() === 'javascript' ? 'js' : 'groovy';
+    const folder = [IMPORTED_SCRIPTS_DIR, ...script.ownerPath.map(slugify)].join('/');
+    let candidate = `${folder}/${script.element}.${extension}`;
+    for (let n = 2; taken.has(candidate.toLowerCase()); n += 1) {
+        candidate = `${folder}/${script.element}-${String(n)}.${extension}`;
+    }
+    taken.add(candidate.toLowerCase());
+    return candidate;
+}
+/**
+ * Maps `project` onto Wirebench entities. `resolved` holds one entry per `project.interfaces`
+ * element, in the same order.
+ */
+export function mapLegacyProject(project, resolved, context) {
+    const newId = context.newId ?? generateId;
+    const report = new ReportBuilder();
+    const interfaces = [];
+    const slugByLegacyName = new Map();
+    let operationCount = 0;
+    let requestCount = 0;
+    for (const entry of resolved) {
+        const { legacy } = entry;
+        if (!entry.resolved) {
+            report.warning(legacy.name, `The interface was not imported: ${entry.problem}`);
+            continue;
+        }
+        for (const location of entry.fetchedFromNetwork) {
+            report.info(legacy.name, `The project file held no copy of ${location}, so it was fetched from the network.`);
+        }
+        const endpoints = legacy.endpoints.map((url) => ({
+            id: newId(),
+            name: url,
+            url,
+            authMode: 'complement',
+        }));
+        const { operations, requests } = mapOperations(entry, endpoints, newId, report);
+        operationCount += operations.length;
+        requestCount += requests;
+        interfaces.push(createInterface(legacy.name, {
+            id: entry.id,
+            slug: entry.slug,
+            order: context.firstInterfaceOrder + interfaces.length,
+            definitionUrl: entry.definitionUrl,
+            ...(entry.targetNamespace !== undefined ? { targetNamespace: entry.targetNamespace } : {}),
+            endpoints,
+            operations,
+        }));
+        slugByLegacyName.set(legacy.name, entry.slug);
+    }
+    const properties = {};
+    for (const property of project.properties) {
+        if (context.propertyNames.has(property.name) || property.name in properties) {
+            report.info('', `The project property "${property.name}" already exists and kept its current value.`);
+            continue;
+        }
+        properties[property.name] = property.value;
+    }
+    const environmentNames = new Set(context.environmentNames);
+    const environmentSlugs = new Set(context.environmentSlugs);
+    const environments = [];
+    for (const legacy of project.environments) {
+        const name = uniqueName(legacy.name, environmentNames);
+        environmentNames.add(name);
+        if (name !== legacy.name) {
+            report.info(legacy.name, `An environment with this name already exists, so it was imported as "${name}".`);
+        }
+        const slug = uniqueSlug(name, environmentSlugs);
+        environmentSlugs.add(slug);
+        const endpoints = {};
+        for (const override of legacy.endpoints) {
+            const interfaceSlug = slugByLegacyName.get(override.interfaceName);
+            if (interfaceSlug === undefined) {
+                report.warning(joinPath(name, override.interfaceName), 'The endpoint override was not imported: its interface was not imported.');
+                continue;
+            }
+            endpoints[interfaceSlug] = override.url;
+        }
+        const values = {};
+        for (const property of legacy.properties) {
+            values[property.name] = property.value;
+        }
+        environments.push({
+            id: newId(),
+            name,
+            slug,
+            order: context.firstEnvironmentOrder + environments.length,
+            endpoints,
+            properties: values,
+            disabledProperties: [],
+        });
+    }
+    const scriptPaths = new Set();
+    const scripts = project.scripts.map((script) => {
+        const path = scriptPath(script, scriptPaths);
+        report.info(joinPath(...script.ownerPath), `A script (${script.element}) was saved to ${path}. It is not run.`);
+        return { path, source: script.source };
+    });
+    for (const unmapped of project.unmapped) {
+        report.warning(joinPath(...unmapped.ownerPath), unmapped.message);
+    }
+    return {
+        interfaces,
+        environments,
+        properties,
+        scripts,
+        report: {
+            projectName: project.name,
+            counts: {
+                interfaces: interfaces.length,
+                operations: operationCount,
+                requests: requestCount,
+                environments: environments.length,
+                properties: Object.keys(properties).length,
+                scripts: scripts.length,
+            },
+            items: report.items,
+        },
+    };
+}
+/** The report as plain text, one line per item, for copying out of the dialog. */
+export function formatLegacyImportReport(report) {
+    const { counts } = report;
+    const lines = [
+        `Imported "${report.projectName}": ${String(counts.interfaces)} interfaces, ${String(counts.operations)} operations, ` +
+            `${String(counts.requests)} requests, ${String(counts.environments)} environments, ` +
+            `${String(counts.properties)} properties, ${String(counts.scripts)} scripts.`,
+    ];
+    for (const item of report.items) {
+        lines.push(`${item.severity === 'warning' ? 'Warning' : 'Note'}: ${item.path === '' ? '' : `${item.path}: `}${item.message}`);
+    }
+    return lines.join('\n');
+}

package/dist/soap/legacy-project/model.d.ts

@@ -0,0 +1,98 @@
+/**
+ * A legacy single-XML SOAP project file as the import reads it: only what v1 maps, plus enough about
+ * everything else to say in the import report what was left behind.
+ */
+/** A name/value pair from a `properties` list or an environment. */
+export interface LegacyProperty {
+    readonly name: string;
+    readonly value: string;
+}
+/** One document of an interface's cached definition, keyed by the URL it was fetched from. */
+export interface LegacyDefinitionPart {
+    readonly url: string;
+    readonly content: string;
+}
+/** The definition an interface carried, so it can be resolved without the network. */
+export interface LegacyDefinitionCache {
+    /** The URL of the root WSDL among {@link parts}, when the file names one. */
+    readonly rootPart?: string;
+    readonly parts: readonly LegacyDefinitionPart[];
+}
+/** The credentials of a saved request. The password itself is never kept. */
+export interface LegacyCredentials {
+    readonly username?: string;
+    readonly domain?: string;
+    /** True when the file had a non-empty password, so the report can ask for it to be re-entered. */
+    readonly hadPassword: boolean;
+    readonly authType?: string;
+}
+/** A saved request (`call`) under an operation. */
+export interface LegacyCall {
+    readonly name: string;
+    readonly endpoint?: string;
+    /** The envelope as text, decompressed when it was stored compressed. Absent when it could not be read. */
+    readonly envelope?: string;
+    /** Why {@link envelope} is absent. */
+    readonly envelopeProblem?: string;
+    readonly encoding?: string;
+    readonly timeoutMs?: number;
+    readonly credentials: LegacyCredentials;
+    readonly useWsAddressing: boolean;
+    readonly assertions: number;
+    readonly attachments: number;
+    /** Names of the outgoing and incoming WS-Security configurations the request referenced. */
+    readonly wssRefs: readonly string[];
+}
+/** A binding operation and its saved requests. */
+export interface LegacyOperation {
+    readonly name: string;
+    /** The operation's name in the binding; falls back to {@link name}. */
+    readonly bindingOperationName: string;
+    readonly action?: string;
+    readonly calls: readonly LegacyCall[];
+}
+/** A SOAP interface (one WSDL binding). */
+export interface LegacyInterface {
+    readonly name: string;
+    readonly definitionUrl?: string;
+    /** The binding as `{namespace}localName`. */
+    readonly bindingName?: string;
+    readonly soapVersion: '1.1' | '1.2';
+    readonly cache?: LegacyDefinitionCache;
+    readonly endpoints: readonly string[];
+    readonly operations: readonly LegacyOperation[];
+}
+/** A named set of property values and per-interface endpoint overrides. */
+export interface LegacyEnvironment {
+    readonly name: string;
+    readonly properties: readonly LegacyProperty[];
+    /** The endpoint URL this environment sends each named interface to. */
+    readonly endpoints: readonly {
+        readonly interfaceName: string;
+        readonly url: string;
+    }[];
+}
+/** A script found anywhere in the file, never run. */
+export interface LegacyScript {
+    /** Names of the owning items from the project down, e.g. `['Smoke', 'Echo once']`. Empty at project level. */
+    readonly ownerPath: readonly string[];
+    /** The element that held it, e.g. `afterLoadScript`, or `script` for a script test step. */
+    readonly element: string;
+    readonly language?: string;
+    readonly source: string;
+}
+/** Something in the file that holds user work v1 does not map. */
+export interface LegacyUnmapped {
+    readonly ownerPath: readonly string[];
+    readonly message: string;
+}
+/** The whole file as read. */
+export interface LegacyProject {
+    readonly name: string;
+    readonly description?: string;
+    readonly properties: readonly LegacyProperty[];
+    readonly interfaces: readonly LegacyInterface[];
+    readonly environments: readonly LegacyEnvironment[];
+    readonly scripts: readonly LegacyScript[];
+    readonly unmapped: readonly LegacyUnmapped[];
+}

package/dist/soap/legacy-project/model.js

@@ -0,0 +1,5 @@
+/**
+ * A legacy single-XML SOAP project file as the import reads it: only what v1 maps, plus enough about
+ * everything else to say in the import report what was left behind.
+ */
+export {};

package/dist/soap/legacy-project/parse.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reads the text of a legacy single-XML SOAP project file into a {@link LegacyProject}.
+ *
+ * Tolerant by design: every optional element may be missing, and anything unexpected is skipped
+ * rather than fatal. Only a document that is not well-formed, is not this format, or is encrypted
+ * is rejected, with a {@link LegacyProjectError}.
+ */
+import type { LegacyProject } from './model.js';
+/**
+ * Parses `text` as a legacy single-XML SOAP project.
+ *
+ * @throws LegacyProjectError `legacy-malformed` when the XML is not well-formed or declares a DTD,
+ *   `legacy-not-a-project` when it is some other document, and `legacy-encrypted` when the project
+ *   was saved encrypted.
+ */
+export declare function parseLegacyProject(text: string, location?: string): LegacyProject;