@wirebench/engine 2.1.1

package/dist/wsdl/resolver.js

@@ -0,0 +1,276 @@
+import { WsdlParseError } from '../errors.js';
+import { NS } from '../xml/namespaces.js';
+import { getPosition, parseXml } from '../xml/parse.js';
+import { childElements, firstChildElement, optionalAttribute } from './dom-utils.js';
+import { MAX_IMPORT_DEPTH, MAX_IMPORT_DOCUMENTS, referencePolicyFor } from './ref-policy.js';
+/**
+ * Queues `ref`, resolved against `base` with the WHATWG `URL` class (which handles both
+ * `http(s):` and `file:`).
+ *
+ * A relative reference cannot be resolved against the pseudo-location of a pasted or dropped
+ * document (`inline:wsdl`, `dropped:service.wsdl`) — there is no directory to resolve it
+ * against — so that becomes an `unresolved-import` problem carrying the one action that fixes
+ * it, rather than an exception that loses the whole import.
+ */
+function queueRef(ref, base, importedBy, depth, queue, problems, chameleonNamespace) {
+    let requestedLocation;
+    try {
+        requestedLocation = new URL(ref, base).toString();
+    }
+    catch {
+        problems.push({
+            code: 'unresolved-import',
+            message: `Cannot resolve "${ref}" against "${base}". Use Browse… to import a WSDL whose imports live next to it`,
+            location: base,
+        });
+        return;
+    }
+    queue.push({
+        requestedLocation,
+        importedBy,
+        depth,
+        ...(chameleonNamespace !== undefined ? { chameleonNamespace } : {}),
+    });
+}
+/**
+ * Builds a {@link BundledDocument} from a fetched document, determining its
+ * `kind` from the root element and, for an `xs:schema` root, its effective
+ * namespace (its own `targetNamespace`, or the chameleon namespace adopted
+ * from its includer).
+ *
+ * @throws {Error} if the root element is neither a WSDL `definitions` nor an XSD `schema` and `isRoot` is `false`
+ *   (the caller turns this into a `not-xml` problem); a root with an unrecognized shape is tagged `kind: 'wsdl'`
+ *   so downstream `parseWsdlDocument` raises its own `not-a-wsdl` error.
+ */
+function buildBundledDocument(fetched, requestedLocation, importedBy, chameleonNamespace, isRoot) {
+    const document = parseXml(fetched.text, { location: fetched.location });
+    const root = document.documentElement;
+    let kind;
+    let namespace;
+    let chameleonFor;
+    if (root !== null && root.namespaceURI === NS.WSDL && root.localName === 'definitions') {
+        kind = 'wsdl';
+        namespace = optionalAttribute(root, 'targetNamespace');
+    }
+    else if (root !== null && root.namespaceURI === NS.XSD && root.localName === 'schema') {
+        kind = 'xsd';
+        const ownNamespace = optionalAttribute(root, 'targetNamespace');
+        if (ownNamespace !== undefined) {
+            namespace = ownNamespace;
+        }
+        else if (chameleonNamespace !== undefined) {
+            namespace = chameleonNamespace;
+            chameleonFor = importedBy;
+        }
+    }
+    else if (isRoot) {
+        // Leave shape validation of the root to parseWsdlDocument (via parseWsdl), which
+        // raises a proper 'not-a-wsdl' WsdlParseError with position details.
+        kind = 'wsdl';
+    }
+    else {
+        throw new Error(`Document at "${fetched.location}" is neither a WSDL <definitions> nor an XSD <schema> root`);
+    }
+    return {
+        location: fetched.location,
+        requestedLocation,
+        bytes: fetched.bytes,
+        text: fetched.text,
+        kind,
+        ...(importedBy !== undefined ? { importedBy } : {}),
+        ...(namespace !== undefined ? { namespace } : {}),
+        ...(chameleonFor !== undefined ? { chameleonFor } : {}),
+        document,
+    };
+}
+/** Walks one `xs:schema` element's `xs:import`/`xs:include`/`xs:redefine` children, queuing referenced documents. */
+function collectSchemaImports(schemaEl, baseLocation, importedBy, depth, queue, problems) {
+    const ownNamespace = optionalAttribute(schemaEl, 'targetNamespace');
+    for (const importEl of childElements(schemaEl, NS.XSD, 'import')) {
+        // A namespace-only xs:import (no schemaLocation) carries nothing to fetch: Task 7
+        // resolves types across the bundle by namespace instead.
+        const schemaLocation = optionalAttribute(importEl, 'schemaLocation');
+        if (schemaLocation === undefined) {
+            continue;
+        }
+        queueRef(schemaLocation, baseLocation, importedBy, depth, queue, problems);
+    }
+    for (const includeEl of childElements(schemaEl, NS.XSD, 'include')) {
+        const schemaLocation = optionalAttribute(includeEl, 'schemaLocation');
+        if (schemaLocation === undefined) {
+            continue;
+        }
+        queueRef(schemaLocation, baseLocation, importedBy, depth, queue, problems, ownNamespace);
+    }
+    for (const redefineEl of childElements(schemaEl, NS.XSD, 'redefine')) {
+        const schemaLocation = optionalAttribute(redefineEl, 'schemaLocation');
+        const pos = getPosition(redefineEl);
+        problems.push({
+            code: 'unsupported-redefine',
+            message: `xs:redefine is not supported${schemaLocation !== undefined ? ` (schemaLocation="${schemaLocation}")` : ''}`,
+            location: baseLocation,
+            ...(pos !== undefined ? pos : {}),
+        });
+        if (schemaLocation !== undefined) {
+            // Still fetch the referenced document, treating the redefine as a plain include.
+            queueRef(schemaLocation, baseLocation, importedBy, depth, queue, problems, ownNamespace);
+        }
+    }
+}
+/** Walks a {@link BundledDocument}'s imports/includes/redefines, queuing every referenced document. */
+function collectImports(doc, depth, queue, problems) {
+    const root = doc.document.documentElement;
+    if (root === null) {
+        return;
+    }
+    if (doc.kind === 'wsdl') {
+        for (const importEl of childElements(root, NS.WSDL, 'import')) {
+            const location = optionalAttribute(importEl, 'location');
+            if (location === undefined) {
+                continue;
+            }
+            queueRef(location, doc.location, doc.location, depth, queue, problems);
+        }
+        const typesEl = firstChildElement(root, NS.WSDL, 'types');
+        if (typesEl !== undefined) {
+            for (const schemaEl of childElements(typesEl, NS.XSD, 'schema')) {
+                collectSchemaImports(schemaEl, doc.location, doc.location, depth, queue, problems);
+            }
+        }
+    }
+    else {
+        collectSchemaImports(root, doc.location, doc.location, depth, queue, problems);
+    }
+}
+function abortError(signal) {
+    return signal.reason !== undefined ? signal.reason : new DOMException('Aborted', 'AbortError');
+}
+// Wrapped in a function (rather than inlining `signal?.aborted === true`) so TypeScript does not
+// carry a `false` narrowing of the readonly `aborted` property across loop iterations/awaits.
+function checkAborted(signal) {
+    if (signal !== undefined && signal.aborted) {
+        throw abortError(signal);
+    }
+}
+/**
+ * Resolves a WSDL/XSD document's full import graph (`wsdl:import`, `xs:import`,
+ * `xs:include`, `xs:redefine`) into a flat {@link DefinitionBundle}, fetching
+ * every referenced document exactly once (by canonical, post-redirect
+ * location) through the injected `fetchDocument`.
+ *
+ * Every nested reference is first judged against the root document's world (see
+ * `wsdl/ref-policy.ts`): a `file:` root may only reference `file:` documents inside its own
+ * folder, an `http(s):` root may only reference `http(s):` documents, and a pasted/dropped
+ * root may only reference `http(s):` documents. A refused reference becomes an
+ * `import-ref-refused` problem and the import continues with what did resolve — so a WSDL
+ * cannot be used to read arbitrary local files. The graph is additionally capped at
+ * {@link MAX_IMPORT_DEPTH} levels and {@link MAX_IMPORT_DOCUMENTS} documents (`import-limit`).
+ *
+ * A failed fetch of an imported/included document is recorded as a
+ * `fetch-failed` {@link ResolveProblem} and resolution continues with the
+ * rest of the graph; a failed fetch of the root document throws instead,
+ * since there is nothing to return without it.
+ *
+ * @throws {WsdlParseError} with code `fetch-failed` if the root document cannot be fetched
+ * @throws if `options.signal` is already aborted, or becomes aborted mid-resolution
+ */
+export async function resolveDefinition(source, options) {
+    const { fetchDocument, signal } = options;
+    checkAborted(signal);
+    const problems = [];
+    const canonicalDocs = new Map();
+    const requestedSeen = new Set([source.location]);
+    let rootFetched;
+    if (source.text !== undefined) {
+        rootFetched = { location: source.location, bytes: new TextEncoder().encode(source.text), text: source.text };
+    }
+    else {
+        try {
+            rootFetched = await fetchDocument(source.location, signal);
+        }
+        catch (cause) {
+            throw new WsdlParseError('fetch-failed', `Failed to fetch root document "${source.location}"`, {
+                cause,
+                details: { location: source.location },
+            });
+        }
+    }
+    requestedSeen.add(rootFetched.location);
+    const rootDoc = buildBundledDocument(rootFetched, source.location, undefined, undefined, true);
+    canonicalDocs.set(rootFetched.location, rootDoc);
+    const documents = [rootDoc];
+    // Every nested reference is judged against the *root* document's world; see `ref-policy.ts`.
+    const policy = referencePolicyFor(rootFetched.location);
+    const queue = [];
+    collectImports(rootDoc, 1, queue, problems);
+    let limitReported = false;
+    while (queue.length > 0) {
+        const job = queue.shift();
+        /* v8 ignore next 3 -- queue.length > 0 guarantees a defined element */
+        if (job === undefined) {
+            continue;
+        }
+        if (requestedSeen.has(job.requestedLocation)) {
+            continue;
+        }
+        requestedSeen.add(job.requestedLocation);
+        if (job.depth > MAX_IMPORT_DEPTH || documents.length >= MAX_IMPORT_DOCUMENTS) {
+            // One problem for the whole runaway graph: a cap hit usually trips on hundreds of
+            // references at once, and a problems list that long tells the user nothing extra.
+            if (!limitReported) {
+                limitReported = true;
+                problems.push({
+                    code: 'import-limit',
+                    message: job.depth > MAX_IMPORT_DEPTH
+                        ? `Import graph deeper than ${String(MAX_IMPORT_DEPTH)} levels; the rest was not fetched`
+                        : `Import graph larger than ${String(MAX_IMPORT_DOCUMENTS)} documents; the rest was not fetched`,
+                    location: job.importedBy,
+                });
+            }
+            continue;
+        }
+        const refused = await policy.allows(job.requestedLocation);
+        if (refused !== undefined) {
+            problems.push({
+                code: 'import-ref-refused',
+                message: `Refused to fetch "${job.requestedLocation}": ${refused.reason}`,
+                location: job.importedBy,
+            });
+            continue;
+        }
+        checkAborted(signal);
+        let fetched;
+        try {
+            fetched = await fetchDocument(job.requestedLocation, signal);
+        }
+        catch (cause) {
+            problems.push({
+                code: 'fetch-failed',
+                message: `Failed to fetch "${job.requestedLocation}": ${cause instanceof Error ? cause.message : String(cause)}`,
+                location: job.requestedLocation,
+            });
+            continue;
+        }
+        requestedSeen.add(fetched.location);
+        // A redirect may converge onto a location already fetched via a different request.
+        if (canonicalDocs.has(fetched.location)) {
+            continue;
+        }
+        let bundled;
+        try {
+            bundled = buildBundledDocument(fetched, job.requestedLocation, job.importedBy, job.chameleonNamespace, false);
+        }
+        catch (cause) {
+            problems.push({
+                code: 'not-xml',
+                message: cause instanceof Error ? cause.message : String(cause),
+                location: fetched.location,
+            });
+            continue;
+        }
+        canonicalDocs.set(fetched.location, bundled);
+        documents.push(bundled);
+        collectImports(bundled, job.depth + 1, queue, problems);
+    }
+    return { root: rootDoc, documents, problems };
+}

package/dist/wsdl/update-definition.d.ts

@@ -0,0 +1,106 @@
+/**
+ * "Update Definition": re-import a WSDL and reconcile an existing
+ * project against it.
+ *
+ * The two halves are deliberately separate. {@link planUpdate} is a pure diff of
+ * two {@link ImportResult}s — what a preview dialog shows before the user commits
+ * to anything. {@link applyUpdate} then rewrites the project model per the
+ * options the user ticked, and is equally pure: it returns the next `Project`
+ * plus the relative paths of the `.xml.bak` backups the save layer should write
+ * (see `project/save.ts`'s `backups` option), and never touches a file system
+ * itself.
+ *
+ * Nothing is ever deleted. Requests belonging to an operation the new definition
+ * no longer has are kept and flagged {@link RequestDef.orphaned} rather than
+ * removed — the user decides whether a vanished operation means "clean
+ * this up" or "the new WSDL is wrong".
+ */
+import type { IdGenerator, Project } from '../project/model.js';
+import type { OperationRef } from '../soap/request-builder.js';
+import type { ImportResult } from '../types.js';
+export type { OperationRef } from '../soap/request-builder.js';
+/** Why {@link planUpdate} considers an operation changed; the first applicable reason wins. */
+export type OperationChangeReason = 'input-schema' | 'output-schema' | 'soap-action' | 'style' | 'binding';
+/** One operation both definitions have, but not identically. */
+export interface ChangedOperation {
+    readonly ref: OperationRef;
+    readonly reason: OperationChangeReason;
+}
+/** The difference between the definition a project was built from and a freshly imported one. */
+export interface UpdatePlan {
+    /** Operations only the new definition has. */
+    readonly newOperations: readonly OperationRef[];
+    /** Operations only the old definition had; their saved requests become orphaned. */
+    readonly removedOperations: readonly OperationRef[];
+    /** Operations both have, whose generated request or transport metadata differs. */
+    readonly changedOperations: readonly ChangedOperation[];
+    /** `soap:address` locations the new definition adds. */
+    readonly endpointsAdded: readonly string[];
+    /** `soap:address` locations the new definition no longer declares. */
+    readonly endpointsRemoved: readonly string[];
+}
+/**
+ * Diffs two imports of the same interface: what the new definition adds, drops
+ * and changes. Operation identity is the binding's expanded name plus the
+ * operation name, so a renamed binding reads as "every operation removed, every
+ * operation added" — which is what it is.
+ *
+ * Pure and deterministic: the lists follow the new definition's document order
+ * (removed operations follow the old one's).
+ *
+ * @param oldImport the definition the project was built from
+ * @param newImport the freshly fetched definition
+ */
+export declare function planUpdate(oldImport: ImportResult, newImport: ImportResult): UpdatePlan;
+/**
+ * What {@link applyUpdate} is allowed to do, named after the checkboxes of
+ * the Update Definition dialog.
+ */
+export interface ApplyUpdateOptions {
+    /** "Create new requests": add a `Request 1` for every operation the new definition adds. */
+    readonly createNewRequests: boolean;
+    /** "Recreate requests": regenerate the envelopes of every changed operation's requests. */
+    readonly recreateRequests: boolean;
+    /** "Recreate optional elements": include `minOccurs="0"` content when regenerating. */
+    readonly recreateOptional: boolean;
+    /** "Keep existing values": copy matching leaf values across (Task 29's merge). */
+    readonly keepExisting: boolean;
+    /** "Keep SOAP headers": keep the current `soapenv:Header` verbatim. */
+    readonly keepSoapHeaders: boolean;
+    /** "Create backups": ask the save layer for a `<request>.xml.bak` of every rewritten envelope. */
+    readonly createBackups: boolean;
+    /** "Update TestRequests": not implemented in this phase; the dialog shows it disabled. */
+    readonly updateTestRequests: false;
+    /** Mints ids for created requests and endpoints; injected by tests for determinism. */
+    readonly newId?: IdGenerator;
+}
+/** What {@link applyUpdate} did, in ids the caller can select in the UI. */
+export interface ApplyUpdateResult {
+    readonly project: Project;
+    /** Ids of requests created for newly added operations. */
+    readonly requestsCreated: readonly string[];
+    /** Ids of requests whose envelope was regenerated. */
+    readonly requestsRecreated: readonly string[];
+    /** Ids of requests now flagged `orphaned` because their operation is gone. */
+    readonly requestsOrphaned: readonly string[];
+    /**
+     * Relative, `/`-separated project paths of the `.xml.bak` files the save layer
+     * should write before overwriting the corresponding envelope.
+     */
+    readonly backups: readonly string[];
+}
+/**
+ * Applies `plan` to one interface of `project`, per `options`.
+ *
+ * Never deletes anything: a removed operation's requests stay exactly where they
+ * are with `orphaned: true`, and an operation the new definition brought back has
+ * that flag cleared again.
+ *
+ * @param project the model to update; never mutated
+ * @param interfaceId the interface the plan belongs to
+ * @param plan the diff from {@link planUpdate}
+ * @param newImport the freshly imported definition the plan was built against
+ * @param options which of the update behaviours to perform
+ * @throws Error when `interfaceId` names no interface of `project`
+ */
+export declare function applyUpdate(project: Project, interfaceId: string, plan: UpdatePlan, newImport: ImportResult, options: ApplyUpdateOptions): ApplyUpdateResult;