@llm4ts/shell 2.11.0 → 2.13.0

package/kits/soap-ace/flows/lib/soap/Wsdl.js

@@ -0,0 +1,533 @@
+import { readFile } from "node:fs/promises";
+import { posix } from "node:path";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { CatalogVersion, Endpoint, FaultRef, OpenQuestion, Operation, qname, splitClark, WsdlCatalog, XsdNamespace } from "./Catalog.js";
+import { attribute, childrenNamed, firstChild, is, parseXmlBytes, resolveQName, textOf } from "./Xml.js";
+import { collectSchema, finishSchemas, makeSchemaCollector } from "./Xsd.js";
+// WSDL discovery: load the root document, follow `wsdl:import`,
+// `xsd:import`, and `xsd:include` through the `DocumentLoader`, and build the
+// typed `WsdlCatalog`. Only document/literal SOAP bindings become operations
+// (v1 scope). A WSDL whose every SOAP binding is RPC or encoded fails with
+// `WsdlError` naming the bindings; one that also offers a document/literal
+// binding keeps the usable one and records the others as open questions.
+export const Wsdl11Namespace = "http://schemas.xmlsoap.org/wsdl/";
+export const Wsdl20Namespace = "http://www.w3.org/ns/wsdl";
+const Soap11BindingNamespace = "http://schemas.xmlsoap.org/wsdl/soap/";
+const Soap12BindingNamespace = "http://schemas.xmlsoap.org/wsdl/soap12/";
+const Wsdl20SoapNamespace = "http://www.w3.org/ns/wsdl/soap";
+export class DocumentLoadError extends Schema.TaggedError()("DocumentLoadError", {
+    location: Schema.String,
+    detail: Schema.String
+}) {
+    get message() {
+        return `cannot load ${this.location}: ${this.detail}`;
+    }
+}
+export class WsdlError extends Schema.TaggedError()("WsdlError", {
+    reason: Schema.Literals(["not-wsdl", "unsupported-binding", "no-operations"]),
+    detail: Schema.String,
+    location: Schema.String
+}) {
+    get message() {
+        return `${this.location}: ${this.reason}: ${this.detail}`;
+    }
+}
+export class DocumentLoader extends Context.Service()("@llm4ts/kits/soap-ace/DocumentLoader") {
+}
+/** A loader over an in-memory map of location → text, for tests and fixtures. */
+export const makeMemoryDocumentLoader = (documents) => ({
+    load: (location) => {
+        const found = documents[location];
+        if (found === undefined) {
+            return Effect.fail(new DocumentLoadError({ location, detail: "not found" }));
+        }
+        return Effect.succeed(typeof found === "string" ? new TextEncoder().encode(found) : found);
+    }
+});
+/** A loader over local files; URLs are refused (they need a `SoapTransport`). */
+export const makeFileDocumentLoader = () => ({
+    load: (location) => isUrl(location)
+        ? Effect.fail(new DocumentLoadError({ location, detail: "URLs need the HTTP document loader" }))
+        : Effect.tryPromise({
+            try: async () => new Uint8Array(await readFile(location)),
+            catch: (cause) => new DocumentLoadError({
+                location,
+                detail: typeof cause === "object" && cause !== null && "code" in cause
+                    ? String(cause.code)
+                    : "unreadable"
+            })
+        })
+});
+/**
+ * A location as it may be recorded or shown: URL credentials removed and
+ * query parameters named like secrets redacted. The loader still gets the
+ * real location; catalogs, questions, and errors only ever see this one.
+ */
+export const safeLocation = (location) => {
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(location))
+        return location;
+    try {
+        const url = new URL(location);
+        url.username = "";
+        url.password = "";
+        const sensitive = [...url.searchParams.keys()].filter((name) => /token|key|secret|pass|auth|sig|session|code/i.test(name));
+        if (sensitive.length === 0)
+            return `${url.origin}${url.pathname}${url.search}${url.hash}`;
+        for (const name of sensitive)
+            url.searchParams.set(name, "REDACTED");
+        return url.toString();
+    }
+    catch {
+        return "(unreadable location)";
+    }
+};
+const isUrl = (location) => /^[a-z][a-z0-9+.-]*:\/\//i.test(location);
+/** Resolve a relative `location`/`schemaLocation` against the referring document. */
+export const resolveLocation = (base, relative) => {
+    if (isUrl(relative))
+        return relative;
+    if (isUrl(base))
+        return new URL(relative, base).toString();
+    if (relative.startsWith("/"))
+        return posix.normalize(relative);
+    return posix.normalize(posix.join(posix.dirname(base), relative));
+};
+const refOf = (element, name) => {
+    const value = attribute(element, name);
+    if (value === undefined)
+        return undefined;
+    const resolved = resolveQName(element, value);
+    return resolved === undefined ? `{?}${value}` : qname(resolved.namespace, resolved.local);
+};
+const wsdlDocumentation = (element, namespace) => {
+    const documentation = firstChild(element, namespace, "documentation");
+    const text = documentation === undefined ? "" : textOf(documentation).trim().replace(/\s+/g, " ");
+    return text === "" ? undefined : text;
+};
+class Discovery {
+    documents = [];
+    schemas = makeSchemaCollector();
+    questions = [];
+    wsdl11 = {
+        messages: new Map(),
+        portTypes: new Map(),
+        bindings: new Map(),
+        ports: []
+    };
+    wsdl20 = { interfaces: new Map(), bindings: new Map(), endpoints: [] };
+    visited = new Set();
+    loader;
+    constructor(loader) {
+        this.loader = loader;
+    }
+    question(code, location, subject, detail) {
+        this.questions.push(new OpenQuestion({ code, location, subject, detail }));
+    }
+    load(location) {
+        const shown = safeLocation(location);
+        this.documents.push(shown);
+        return this.loader.load(location).pipe(Effect.mapError((error) => new DocumentLoadError({ location: shown, detail: error.detail })), Effect.flatMap((bytes) => parseXmlBytes(bytes, { source: shown })));
+    }
+    /** Read a WSDL document (root or imported) and everything it pulls in. */
+    wsdl(location) {
+        this.visited.add(location);
+        return Effect.flatMap(this.load(location), (root) => this.wsdlFrom(root, location));
+    }
+    wsdlFrom(root, location) {
+        return Effect.gen({ self: this }, function* () {
+            const version = is(root, Wsdl11Namespace, "definitions")
+                ? "1.1"
+                : is(root, Wsdl20Namespace, "description")
+                    ? "2.0"
+                    : undefined;
+            if (version === undefined) {
+                return yield* new WsdlError({
+                    reason: "not-wsdl",
+                    detail: `root element {${root.name.namespace}}${root.name.local} is not a WSDL 1.1 definitions or WSDL 2.0 description`,
+                    location
+                });
+            }
+            const namespace = version === "1.1" ? Wsdl11Namespace : Wsdl20Namespace;
+            const targetNamespace = attribute(root, "targetNamespace") ?? "";
+            for (const imported of [
+                ...childrenNamed(root, namespace, "import"),
+                ...childrenNamed(root, namespace, "include")
+            ]) {
+                const target = attribute(imported, "location");
+                if (target === undefined)
+                    continue;
+                const resolved = resolveLocation(location, target);
+                if (this.visited.has(resolved))
+                    continue;
+                this.visited.add(resolved);
+                const next = yield* this.load(resolved);
+                if (is(next, XsdNamespace, "schema")) {
+                    yield* this.schema(next, resolved, undefined);
+                }
+                else {
+                    yield* this.wsdlFrom(next, resolved);
+                }
+            }
+            const types = firstChild(root, namespace, "types");
+            if (types !== undefined) {
+                for (const schema of childrenNamed(types, XsdNamespace, "schema")) {
+                    yield* this.schema(schema, location, undefined);
+                }
+            }
+            if (version === "1.1")
+                this.read11(root, location, targetNamespace);
+            else
+                this.read20(root, location, targetNamespace);
+            return { version, targetNamespace };
+        });
+    }
+    schema(schema, location, namespaceOverride) {
+        return Effect.gen({ self: this }, function* () {
+            const read = collectSchema(schema, safeLocation(location), this.schemas, namespaceOverride);
+            for (const reference of read.references) {
+                const resolved = resolveLocation(location, reference.location);
+                const key = reference.kind === "include" ? `${resolved}#${read.targetNamespace}` : resolved;
+                if (this.visited.has(key))
+                    continue;
+                this.visited.add(key);
+                const next = yield* this.load(resolved);
+                if (!is(next, XsdNamespace, "schema"))
+                    continue;
+                yield* this.schema(next, resolved, reference.kind === "include" ? read.targetNamespace : undefined);
+            }
+        });
+    }
+    read11(root, location, targetNamespace) {
+        const at = (element) => `${safeLocation(location)}:${element.line}`;
+        for (const message of childrenNamed(root, Wsdl11Namespace, "message")) {
+            const name = attribute(message, "name");
+            if (name === undefined)
+                continue;
+            this.wsdl11.messages.set(qname(targetNamespace, name), childrenNamed(message, Wsdl11Namespace, "part").map((part) => ({
+                name: attribute(part, "name") ?? "",
+                element: refOf(part, "element"),
+                type: refOf(part, "type")
+            })));
+        }
+        for (const portType of childrenNamed(root, Wsdl11Namespace, "portType")) {
+            const name = attribute(portType, "name");
+            if (name === undefined)
+                continue;
+            this.wsdl11.portTypes.set(qname(targetNamespace, name), childrenNamed(portType, Wsdl11Namespace, "operation").map((operation) => {
+                const input = firstChild(operation, Wsdl11Namespace, "input");
+                const output = firstChild(operation, Wsdl11Namespace, "output");
+                return {
+                    name: attribute(operation, "name") ?? "",
+                    input: input === undefined ? undefined : refOf(input, "message"),
+                    output: output === undefined ? undefined : refOf(output, "message"),
+                    faults: childrenNamed(operation, Wsdl11Namespace, "fault").map((fault) => ({
+                        name: attribute(fault, "name") ?? "",
+                        message: refOf(fault, "message")
+                    })),
+                    documentation: wsdlDocumentation(operation, Wsdl11Namespace)
+                };
+            }));
+        }
+        for (const binding of childrenNamed(root, Wsdl11Namespace, "binding")) {
+            const name = attribute(binding, "name");
+            if (name === undefined)
+                continue;
+            const soap11 = firstChild(binding, Soap11BindingNamespace, "binding");
+            const soap12 = firstChild(binding, Soap12BindingNamespace, "binding");
+            const soapNamespace = soap11 !== undefined ? Soap11BindingNamespace : Soap12BindingNamespace;
+            const soapBinding = soap11 ?? soap12;
+            const style = soapBinding === undefined ? "" : (attribute(soapBinding, "style") ?? "document");
+            this.wsdl11.bindings.set(qname(targetNamespace, name), {
+                name,
+                portType: refOf(binding, "type"),
+                soapVersion: soap11 !== undefined ? "1.1" : soap12 !== undefined ? "1.2" : undefined,
+                style,
+                location: at(binding),
+                operations: childrenNamed(binding, Wsdl11Namespace, "operation").map((operation) => {
+                    const soapOperation = firstChild(operation, soapNamespace, "operation");
+                    const input = firstChild(operation, Wsdl11Namespace, "input");
+                    const body = input === undefined ? undefined : firstChild(input, soapNamespace, "body");
+                    return {
+                        name: attribute(operation, "name") ?? "",
+                        soapAction: soapOperation === undefined ? "" : (attribute(soapOperation, "soapAction") ?? ""),
+                        style: (soapOperation === undefined ? undefined : attribute(soapOperation, "style")) ??
+                            style,
+                        use: body === undefined ? "literal" : (attribute(body, "use") ?? "literal"),
+                        bodyParts: body === undefined ? undefined : attribute(body, "parts")
+                    };
+                })
+            });
+        }
+        for (const service of childrenNamed(root, Wsdl11Namespace, "service")) {
+            const serviceName = attribute(service, "name") ?? "";
+            for (const port of childrenNamed(service, Wsdl11Namespace, "port")) {
+                const address = firstChild(port, Soap11BindingNamespace, "address") ??
+                    firstChild(port, Soap12BindingNamespace, "address");
+                this.wsdl11.ports.push({
+                    service: serviceName,
+                    name: attribute(port, "name") ?? "",
+                    binding: refOf(port, "binding"),
+                    address: address === undefined ? undefined : attribute(address, "location"),
+                    location: at(port)
+                });
+            }
+        }
+    }
+    read20(root, location, targetNamespace) {
+        for (const iface of childrenNamed(root, Wsdl20Namespace, "interface")) {
+            const name = attribute(iface, "name");
+            if (name === undefined)
+                continue;
+            const faults = new Map();
+            for (const fault of childrenNamed(iface, Wsdl20Namespace, "fault")) {
+                faults.set(attribute(fault, "name") ?? "", refOf(fault, "element"));
+            }
+            this.wsdl20.interfaces.set(qname(targetNamespace, name), {
+                faults,
+                operations: childrenNamed(iface, Wsdl20Namespace, "operation").map((operation) => {
+                    const input = firstChild(operation, Wsdl20Namespace, "input");
+                    const output = firstChild(operation, Wsdl20Namespace, "output");
+                    return {
+                        name: attribute(operation, "name") ?? "",
+                        input: input === undefined ? undefined : refOf(input, "element"),
+                        output: output === undefined ? undefined : refOf(output, "element"),
+                        faults: childrenNamed(operation, Wsdl20Namespace, "outfault").map((fault) => {
+                            const ref = refOf(fault, "ref");
+                            return ref === undefined ? "" : splitClark(ref).local;
+                        }),
+                        documentation: wsdlDocumentation(operation, Wsdl20Namespace)
+                    };
+                })
+            });
+        }
+        for (const binding of childrenNamed(root, Wsdl20Namespace, "binding")) {
+            const name = attribute(binding, "name");
+            if (name === undefined)
+                continue;
+            const actions = new Map();
+            for (const operation of childrenNamed(binding, Wsdl20Namespace, "operation")) {
+                const ref = refOf(operation, "ref");
+                if (ref !== undefined) {
+                    actions.set(splitClark(ref).local, attribute(operation, "action", Wsdl20SoapNamespace) ?? "");
+                }
+            }
+            this.wsdl20.bindings.set(qname(targetNamespace, name), {
+                name,
+                interfaceName: refOf(binding, "interface"),
+                soap: attribute(binding, "type") === Wsdl20SoapNamespace,
+                soapVersion: attribute(binding, "version", Wsdl20SoapNamespace) === "1.1" ? "1.1" : "1.2",
+                actions
+            });
+        }
+        for (const service of childrenNamed(root, Wsdl20Namespace, "service")) {
+            const serviceName = attribute(service, "name") ?? "";
+            for (const endpoint of childrenNamed(service, Wsdl20Namespace, "endpoint")) {
+                this.wsdl20.endpoints.push({
+                    service: serviceName,
+                    name: attribute(endpoint, "name") ?? "",
+                    binding: refOf(endpoint, "binding"),
+                    address: attribute(endpoint, "address"),
+                    location: `${safeLocation(location)}:${endpoint.line}`
+                });
+            }
+        }
+    }
+}
+const faultElement = (discovery, message) => {
+    if (message === undefined)
+        return undefined;
+    return discovery.wsdl11.messages.get(message)?.find((part) => part.element !== undefined)?.element;
+};
+const operations11 = (discovery, rootLocation) => {
+    const { bindings, portTypes, messages, ports } = discovery.wsdl11;
+    const operations = new Map();
+    const rejected = [];
+    // SOAP 1.1 bindings first: when a service offers both, the 1.1 binding
+    // names the operation's defaults, and the 1.2 one only adds an endpoint.
+    const ordered = [...bindings.values()].sort((left, right) => (left.soapVersion === "1.1" ? 0 : 1) - (right.soapVersion === "1.1" ? 0 : 1));
+    for (const binding of ordered) {
+        if (binding.soapVersion === undefined) {
+            discovery.question("unsupported-binding", binding.location, binding.name, `binding ${binding.name} is not a SOAP binding (HTTP or MIME bindings are out of scope)`);
+            continue;
+        }
+        const unsupported = binding.operations.filter((operation) => operation.style === "rpc" || operation.use === "encoded");
+        if (unsupported.length > 0) {
+            const styles = [...new Set(unsupported.map((op) => `${op.style}/${op.use}`))].join(", ");
+            rejected.push(`${binding.name} (${styles})`);
+            discovery.question("unsupported-binding", binding.location, binding.name, `binding ${binding.name} uses ${styles}; only document/literal is supported`);
+            continue;
+        }
+        const portType = binding.portType === undefined ? undefined : portTypes.get(binding.portType);
+        if (portType === undefined)
+            continue;
+        for (const bound of binding.operations) {
+            if (operations.has(bound.name))
+                continue;
+            const abstract = portType.find((operation) => operation.name === bound.name);
+            if (abstract === undefined)
+                continue;
+            const messageElement = (message, direction) => {
+                if (message === undefined)
+                    return undefined;
+                const parts = messages.get(message) ?? [];
+                const selected = bound.bodyParts === undefined
+                    ? parts
+                    : parts.filter((part) => bound.bodyParts?.split(/\s+/).includes(part.name));
+                if (selected.length > 1) {
+                    discovery.question("multi-part-message", binding.location, bound.name, `${direction} message ${splitClark(message).local} has ${selected.length} body parts; the first is used`);
+                }
+                const first = selected[0];
+                if (first !== undefined && first.element === undefined) {
+                    discovery.question("non-literal-part", binding.location, bound.name, `${direction} part ${first.name} uses type= instead of element=; not document/literal`);
+                    return undefined;
+                }
+                return first?.element;
+            };
+            const input = messageElement(abstract.input, "input");
+            if (input === undefined)
+                continue;
+            const output = messageElement(abstract.output, "output");
+            const inputType = discovery.schemas.elements.get(input)?.type;
+            const inputComplex = inputType === undefined ? undefined : discovery.schemas.complex.get(inputType);
+            operations.set(bound.name, new Operation({
+                name: bound.name,
+                soapAction: bound.soapAction,
+                soapVersion: binding.soapVersion,
+                binding: binding.name,
+                wrapped: splitClark(input).local === bound.name &&
+                    inputComplex !== undefined &&
+                    inputComplex.attributes.length === 0,
+                input,
+                ...(output === undefined ? {} : { output }),
+                faults: abstract.faults.flatMap((fault) => {
+                    const element = faultElement(discovery, fault.message);
+                    return element === undefined ? [] : [new FaultRef({ name: fault.name, element })];
+                }),
+                ...(abstract.documentation === undefined ? {} : { documentation: abstract.documentation })
+            }));
+        }
+    }
+    if (operations.size === 0) {
+        return Effect.fail(rejected.length > 0
+            ? new WsdlError({
+                reason: "unsupported-binding",
+                detail: `only document/literal bindings are supported; rejected: ${rejected.join("; ")}`,
+                location: safeLocation(rootLocation)
+            })
+            : new WsdlError({
+                reason: "no-operations",
+                detail: "no SOAP operation could be read from the WSDL",
+                location: safeLocation(rootLocation)
+            }));
+    }
+    const endpoints = ports.flatMap((port) => {
+        const binding = port.binding === undefined ? undefined : bindings.get(port.binding);
+        if (binding?.soapVersion === undefined)
+            return [];
+        if (port.address === undefined) {
+            discovery.question("missing-address", port.location, port.name, `port ${port.name} has no address`);
+            return [];
+        }
+        return [
+            new Endpoint({
+                service: port.service,
+                port: port.name,
+                binding: binding.name,
+                soapVersion: binding.soapVersion,
+                address: port.address
+            })
+        ];
+    });
+    return Effect.succeed({ operations: [...operations.values()], endpoints });
+};
+const operations20 = (discovery, rootLocation) => {
+    const { interfaces, bindings, endpoints } = discovery.wsdl20;
+    const operations = new Map();
+    for (const binding of bindings.values()) {
+        if (!binding.soap)
+            continue;
+        const iface = binding.interfaceName === undefined ? undefined : interfaces.get(binding.interfaceName);
+        if (iface === undefined)
+            continue;
+        for (const abstract of iface.operations) {
+            if (operations.has(abstract.name) || abstract.input === undefined)
+                continue;
+            const inputType = discovery.schemas.elements.get(abstract.input)?.type;
+            const inputComplex = inputType === undefined ? undefined : discovery.schemas.complex.get(inputType);
+            operations.set(abstract.name, new Operation({
+                name: abstract.name,
+                soapAction: binding.actions.get(abstract.name) ?? "",
+                soapVersion: binding.soapVersion,
+                binding: binding.name,
+                wrapped: splitClark(abstract.input).local === abstract.name &&
+                    inputComplex !== undefined &&
+                    inputComplex.attributes.length === 0,
+                input: abstract.input,
+                ...(abstract.output === undefined ? {} : { output: abstract.output }),
+                faults: abstract.faults.flatMap((name) => {
+                    const element = iface.faults.get(name);
+                    return element === undefined ? [] : [new FaultRef({ name, element })];
+                }),
+                ...(abstract.documentation === undefined ? {} : { documentation: abstract.documentation })
+            }));
+        }
+    }
+    if (operations.size === 0) {
+        return Effect.fail(new WsdlError({
+            reason: "no-operations",
+            detail: "no SOAP operation could be read from the WSDL 2.0 description",
+            location: safeLocation(rootLocation)
+        }));
+    }
+    return Effect.succeed({
+        operations: [...operations.values()],
+        endpoints: endpoints.flatMap((endpoint) => {
+            const binding = endpoint.binding === undefined ? undefined : bindings.get(endpoint.binding);
+            if (binding === undefined || !binding.soap || endpoint.address === undefined)
+                return [];
+            return [
+                new Endpoint({
+                    service: endpoint.service,
+                    port: endpoint.name,
+                    binding: binding.name,
+                    soapVersion: binding.soapVersion,
+                    address: endpoint.address
+                })
+            ];
+        })
+    });
+};
+/**
+ * Discover a SOAP service: read the WSDL at `location` (a path or URL) with
+ * every document it imports, and return its typed catalog.
+ */
+export const readCatalog = (location) => Effect.gen(function* () {
+    const loader = yield* DocumentLoader;
+    if (/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*@/i.test(location)) {
+        return yield* new DocumentLoadError({
+            location: safeLocation(location),
+            detail: "credentials in the URL are refused; put references in auth.json"
+        });
+    }
+    // Normalized so the root is recognized when an import cycles back to it.
+    const rootLocation = isUrl(location) ? location : posix.normalize(location);
+    const discovery = new Discovery(loader);
+    const root = yield* discovery.wsdl(rootLocation);
+    const schemas = finishSchemas(discovery.schemas);
+    const read = root.version === "1.1"
+        ? yield* operations11(discovery, rootLocation)
+        : yield* operations20(discovery, rootLocation);
+    return new WsdlCatalog({
+        version: CatalogVersion,
+        wsdlVersion: root.version,
+        targetNamespace: root.targetNamespace,
+        documents: discovery.documents,
+        endpoints: read.endpoints,
+        operations: read.operations,
+        elements: schemas.elements,
+        types: schemas.types,
+        openQuestions: [...schemas.questions, ...discovery.questions]
+    });
+});