@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

package/src/runtime/checkedGatewayHost.tpl.txt

@@ -0,0 +1,157 @@
+import Fastify from 'fastify';
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {types} from 'node:util';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import gateway, {expectedOpenApiJson} from __GATEWAY_IMPORT__;
+import {selection, type Options} from __CLIENT_IMPORT__;
+
+export interface CheckedGatewayConfig {
+  readonly localSource?: string;
+  readonly fileRoots?: readonly string[];
+  readonly endpoint?: string;
+  readonly allowedEndpoints?: readonly string[];
+  readonly capsuleFiles?: Readonly<Record<string, string>>;
+  readonly sourceResources?: Options['sourceResources'];
+  readonly sourceOrigins?: Options['sourceOrigins'];
+  readonly sourceUri?: string;
+  readonly namespaceLocations?: Options['namespaceLocations'];
+  readonly standardLibraries?: Options['standardLibraries'];
+  readonly recordSources?: Options['recordSources'];
+  readonly caFile?: string;
+  readonly host?: string;
+  readonly port?: number;
+  readonly timeoutMs?: number;
+  readonly limits?: Options['soap']['limits'];
+  readonly capabilities?: Options['soap']['capabilities'];
+  readonly signal?: AbortSignal;
+}
+type SourceConfig = CheckedGatewayConfig & Required<Pick<CheckedGatewayConfig,
+  'localSource' | 'fileRoots' | 'sourceResources' | 'sourceOrigins'>>;
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = fs.existsSync(path.join(moduleDir, 'package.json')) ? moduleDir : path.resolve(moduleDir, '..');
+const defaultCapsules = __CAPSULE_FILES__;
+
+function generatedSources(): SourceConfig {
+  const recordFile = path.resolve(projectRoot, __SOURCE_RECORD__);
+  const owner = fs.realpathSync(path.dirname(recordFile));
+  const record = JSON.parse(fs.readFileSync(recordFile, 'utf8')) as {
+    version?: unknown; resources?: readonly {file: string; digest: string}[]; runtime?: SourceConfig;
+  };
+  if (record.version !== 'checked-source-resources-v2' || !Array.isArray(record.resources) || !record.runtime)
+    throw new Error('incompatible-artifact: regenerate the host and source records together, or supply complete explicit source configuration');
+  const ownedFile = (value: string): string => {
+    if (typeof value !== 'string' || !value || path.isAbsolute(value)) throw new Error('Generated source path must be relative to its owner');
+    const file = fs.realpathSync(path.resolve(owner, value));
+    const relative = path.relative(owner, file);
+    if (relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative))
+      throw new Error('Generated source path escapes its owner');
+    return file;
+  };
+  const resources = new Set<string>();
+  for (const resource of record.resources) {
+    const file = ownedFile(resource.file);
+    if (resources.has(file) || createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== resource.digest)
+      throw new Error('incompatible-artifact: stale or mixed generated source records');
+    resources.add(file);
+  }
+  const sourceFile = (value: string): string => {
+    const file = ownedFile(value);
+    if (!resources.has(file)) throw new Error('Generated source is absent from its owned snapshot inventory');
+    return file;
+  };
+  const logical = (value: string): string => /^[A-Za-z][A-Za-z0-9+.-]*:/.test(value)
+    ? value : pathToFileURL(sourceFile(value)).href;
+  const supplied = record.runtime;
+  const sourceKeys = ['localSource', 'fileRoots', 'capsuleFiles', 'sourceResources', 'sourceOrigins', 'sourceUri', 'namespaceLocations', 'recordSources', 'standardLibraries'];
+  if (Object.keys(supplied).some(key => !sourceKeys.includes(key))) throw new Error('Generated bookkeeping may contain only source and artifact records');
+  if (JSON.stringify(supplied.fileRoots) !== '["."]' || !Array.isArray(supplied.sourceResources) || !Array.isArray(supplied.sourceOrigins))
+    throw new Error('Generated source permissions require the owned closed snapshots');
+  return {...supplied, localSource: sourceFile(supplied.localSource), fileRoots: [owner],
+    capsuleFiles: Object.fromEntries(Object.entries(supplied.capsuleFiles ?? {}).map(([name, file]) => [name, ownedFile(file)])),
+    sourceResources: supplied.sourceResources.map(resource => ({uri: logical(resource.uri), file: sourceFile(resource.file),
+      ...(resource.canonicalUri === undefined ? {} : {canonicalUri: logical(resource.canonicalUri)})})),
+    ...(supplied.namespaceLocations ? {namespaceLocations: supplied.namespaceLocations.map(location => ({...location, location: logical(location.location)}))} : {}),
+    ...(supplied.recordSources ? {recordSources: supplied.recordSources.map(record => ({...record, source: sourceFile(record.source)}))} : {}),
+  };
+}
+
+/** Builds the host without listening or dispatching SOAP.
+ * @param supplied Optional overrides, restrictions, or complete advanced source configuration.
+ * @returns A ready Fastify host; physical native qualification remains an invocation duty.
+ * @throws For unknown controls, conflicting/incomplete source configuration or mismatched artifacts.
+ */
+export async function buildServer(supplied: CheckedGatewayConfig = {}) {
+  const supported = ['localSource', 'fileRoots', 'endpoint', 'allowedEndpoints', 'capsuleFiles', 'sourceResources', 'sourceOrigins',
+    'sourceUri', 'namespaceLocations', 'standardLibraries', 'recordSources', 'caFile', 'host', 'port', 'timeoutMs', 'limits', 'capabilities', 'signal'];
+  if (!supplied || typeof supplied !== 'object' || types.isProxy(supplied)
+    || ![null, Object.prototype].includes(Object.getPrototypeOf(supplied) as object | null)
+    || Reflect.ownKeys(supplied).some(key => typeof key !== 'string' || !supported.includes(key)
+      || !Object.hasOwn(Object.getOwnPropertyDescriptor(supplied, key)!, 'value')))
+    throw new Error('Unsupported checked gateway configuration field');
+  const advanced = ['localSource', 'sourceUri', 'namespaceLocations', 'recordSources', 'capsuleFiles'].some(key => Object.hasOwn(supplied, key));
+  if (advanced && ['localSource', 'fileRoots', 'sourceResources', 'sourceOrigins'].some(key => !Object.hasOwn(supplied, key)))
+    throw new Error('Conflicting or incomplete advanced source configuration; supply localSource, fileRoots, sourceResources and sourceOrigins together');
+  const config = (advanced ? {...supplied} : {...generatedSources(), ...supplied}) as SourceConfig;
+  if (typeof config.localSource !== 'string' || !Array.isArray(config.fileRoots) || !config.fileRoots.length
+    || !config.fileRoots.every(root => typeof root === 'string') || !Array.isArray(config.sourceResources) || !Array.isArray(config.sourceOrigins)
+    || config.endpoint !== undefined && typeof config.endpoint !== 'string'
+    || config.allowedEndpoints !== undefined && (!Array.isArray(config.allowedEndpoints) || !config.allowedEndpoints.every(endpoint => typeof endpoint === 'string')))
+    throw new Error('Explicit source configuration and valid endpoint restrictions are required');
+  const allowed = config.allowedEndpoints === undefined ? undefined : new Set(config.allowedEndpoints.map(endpoint => new URL(endpoint).href));
+  const capsules = Object.fromEntries(Object.entries(config.capsuleFiles ?? defaultCapsules)
+    .map(([name, file]) => [name, fs.readFileSync(path.resolve(projectRoot, file))]));
+  const selected = JSON.parse(selection) as {service: {namespace: string; local: string}; port: string};
+  const clientOptions: Options = {
+    localSource: config.localSource, fileRoots: config.fileRoots, sourceResources: config.sourceResources, sourceOrigins: config.sourceOrigins,
+    ...(config.sourceUri === undefined ? {} : {sourceUri: config.sourceUri}),
+    ...(config.namespaceLocations ? {namespaceLocations: config.namespaceLocations} : {}),
+    ...(config.standardLibraries ? {standardLibraries: config.standardLibraries} : {}),
+    ...(config.recordSources ? {recordSources: config.recordSources} : {}),
+    soap: {service: selected.service, port: selected.port,
+      ...(config.endpoint === undefined ? {} : {endpoint: config.endpoint}),
+      ...(allowed === undefined ? {} : {allowEndpoint: (endpoint: URL) => allowed.has(endpoint.href)}),
+      ...(config.signal ? {signal: config.signal} : {}), ...(config.timeoutMs === undefined ? {} : {timeoutMs: config.timeoutMs}),
+      ...(config.limits === undefined ? {} : {limits: config.limits}), ...(config.capabilities === undefined ? {} : {capabilities: config.capabilities}),
+      ...(config.caFile === undefined ? {} : {ca: fs.readFileSync(config.caFile, 'utf8')}),
+    },
+  };
+  const app = Fastify({logger: false});
+  try {
+    const openapi: unknown = JSON.parse(fs.readFileSync(path.resolve(projectRoot, __OPENAPI_FILE__), 'utf8'));
+    if (JSON.stringify(openapi) !== expectedOpenApiJson) throw new Error('incompatible-artifact: mixed checked OpenAPI and gateway; regenerate together');
+    app.get('/health', async () => ({status: 'ok'}));
+    app.get('/openapi.json', async () => openapi);
+    await app.register(gateway, {clientOptions, capsules});
+    await app.ready(); return app;
+  } catch (error) {await app.close(); throw error;}
+}
+
+async function start(): Promise<void> {
+  const file = process.env.CHECKED_GATEWAY_CONFIG;
+  const absolute = file === undefined ? undefined : path.resolve(file);
+  const supplied = absolute === undefined ? {} : JSON.parse(fs.readFileSync(absolute, 'utf8')) as CheckedGatewayConfig;
+  const base = absolute === undefined ? projectRoot : path.dirname(absolute);
+  const uri = (value: string) => /^[A-Za-z][A-Za-z0-9+.-]*:/.test(value) ? value : pathToFileURL(path.resolve(base, value)).href;
+  const config: CheckedGatewayConfig = {...supplied,
+    ...(supplied.localSource === undefined ? {} : {localSource: path.resolve(base, supplied.localSource)}),
+    ...(supplied.fileRoots === undefined ? {} : {fileRoots: supplied.fileRoots.map(root => path.resolve(base, root))}),
+    ...(supplied.sourceResources === undefined ? {} : {sourceResources: supplied.sourceResources.map(resource => ({uri: uri(resource.uri),
+      file: path.resolve(base, resource.file), ...(resource.canonicalUri === undefined ? {} : {canonicalUri: uri(resource.canonicalUri)})}))}),
+    ...(supplied.namespaceLocations ? {namespaceLocations: supplied.namespaceLocations.map(location => ({...location, location: uri(location.location)}))} : {}),
+    ...(supplied.recordSources ? {recordSources: supplied.recordSources.map(record => ({...record, source: path.resolve(base, record.source)}))} : {}),
+    ...(supplied.caFile ? {caFile: path.resolve(base, supplied.caFile)} : {}),
+    ...(supplied.capsuleFiles ? {capsuleFiles: Object.fromEntries(Object.entries(supplied.capsuleFiles).map(([name, file]) => [name, path.resolve(base, file)]))} : {}),
+  };
+  const app = await buildServer(config);
+  process.once('SIGINT', () => {void app.close();});
+  process.once('SIGTERM', () => {void app.close();});
+  const address = await app.listen({host: config.host ?? __DEFAULT_HOST__, port: config.port ?? __DEFAULT_PORT__});
+  console.log('CHECKED_GATEWAY_LISTENING ' + address);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  start().catch(error => {console.error(error); process.exitCode = 1;});
+}

package/src/runtime/clientStreamMethods.tpl.txt

@@ -1,11 +1,18 @@
 
   /**
-   * Streaming transport for operations flagged with a stream configuration.
-   *
-   * node-soap buffers the full response before invoking the operation callback
-   * (verified empirically in ADR-002 / phase-0 research), so this method
-   * bypasses node-soap and POSTs a hand-built SOAP envelope directly, then
-   * pipes the response body through the SAX-driven record parser.
+   * Stream complete SOAP records through the legacy DTO mapper.
+   * @param args - Flat request DTO, serialized using the generated metadata.
+   * @param operation - SOAP operation name for diagnostics.
+   * @param requestType - Request metadata key.
+   * @param recordTypeName - Record metadata key, including companion catalog types.
+   * @param inputElementLocal - SOAP body element local name.
+   * @param inputElementNs - SOAP body element namespace.
+   * @param soapAction - SOAP 1.1 action.
+   * @param recordPath - Local-name path to repeated records.
+   * @param callOptions - Cancellation and total response deadline.
+   * @returns Single-pass records; callers must exhaust or return their iterator to release the connection.
+   * @throws Error for unsupported transport settings, HTTP errors, XML faults, or invalid mapped values.
+   * @constraints Streaming supports SOAP 1.1 document/literal requests, static SOAP headers, and ISecurity hooks.
    */
   protected async callStream<RequestType, RecordType, HeadersType>(
     args: RequestType,
@@ -15,169 +22,170 @@
     inputElementLocal: string,
     inputElementNs: string,
     soapAction: string,
-    recordPath: string[]
+    recordPath: string[],
+    callOptions?: StreamCallOptions
   ): Promise<StreamOperationResponse<RecordType, HeadersType>> {
+    callOptions?.signal?.throwIfAborted();
     const client = await this.soapClient();
-    const endpoint = this.resolveStreamEndpoint(client);
-    const envelope = this.buildSoapEnvelope(args, operation, requestType, inputElementLocal, inputElementNs);
-    const res = await fetch(endpoint, {
-      method: "POST",
-      headers: {
-        "content-type": "text/xml; charset=utf-8",
-        "soapaction": '"' + soapAction + '"',
-      },
-      body: envelope,
-    });
-    if (!res.ok) {
-      throw new Error(
-        operation + " stream request failed: " + res.status + " " + res.statusText
-      );
+    const soapOptions = client.wsdl.options;
+    if (soapOptions.forceSoap12Headers || soapOptions.envelopeSoapUrl && soapOptions.envelopeSoapUrl !== "http://schemas.xmlsoap.org/soap/envelope/") {
+      throw new Error("Streaming supports SOAP 1.1 only");
     }
-    if (!res.body) {
-      throw new Error(operation + " stream request returned an empty response body");
+    const envelopeKey = soapOptions.envelopeKey ?? "soap";
+    if (!/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(envelopeKey) || envelopeKey === "xml" || envelopeKey === "xmlns") {
+      throw new Error("Streaming requires a supported XML envelope prefix");
     }
-    const headers: Record<string, string> = {};
-    res.headers.forEach((value, key) => { headers[key] = value; });
-    const spec: RecordParseSpec = {
-      recordPath,
-      recordTypeName,
-      attributesKey: this.attributesKeyOut,
-      childType: this.dataTypes?.ChildrenTypes,
+    const soapHeaders = client.getSoapHeaders() ?? [];
+    if (soapHeaders.some(header => typeof header !== "string")) {
+      throw new Error("Streaming requires static XML SOAP headers");
+    }
+    if (client.getBodyAttributes()?.length) {
+      throw new Error("Streaming does not support SOAP body attributes");
+    }
+    const transport = this.options?.httpClient ?? new __SOAP_HTTP_CLIENT__(this.options);
+    if (!transport.requestStream) throw new Error("Configured SOAP HTTP client does not support requestStream");
+    const security = (client as unknown as {security?: __SOAP_SECURITY__}).security ?? this.security;
+    const {endpoint, input} = this.resolveStreamBinding(client, operation, soapAction, inputElementLocal, inputElementNs);
+    const headers: Record<string, string> = {
+      "Content-Type": "text/xml; charset=utf-8",
+      SOAPAction: '"' + soapAction + '"',
     };
-    const records = parseRecords<RecordType>(
-      this.webStreamToAsyncIterable(res.body),
-      spec
-    );
-    return {
-      records,
-      headers: headers as unknown as HeadersType,
-      requestRaw: envelope,
+    const requestOptions: __SOAP_EX_OPTIONS__ = {...this.streamRequestOptions};
+    security?.addHeaders?.(headers);
+    security?.addOptions?.(requestOptions);
+    Object.assign(headers, client.getHttpHeaders());
+    if (requestOptions.forceMTOM || requestOptions.attachments?.length || requestOptions.ntlm) {
+      throw new Error("Streaming does not support MTOM attachments or NTLM transport");
+    }
+    // @why node-soap's schema serializer retains element qualification and foreign references that DTO type metadata omits.
+    const soapArgs = this.toSoapArgs(args, requestType);
+    const message = client.wsdl.objectToDocumentXML(input.$name, soapArgs, input.targetNSAlias, input.targetNamespace, input.$type || input.$lookupType, requestOptions);
+    let envelope = this.buildSoapEnvelope(message, envelopeKey, client);
+    const headerXml = soapHeaders.join(" ") + (security?.postProcess ? "" : security?.toXML?.() ?? "");
+    if (headerXml || security?.postProcess) {
+      const body = "<" + envelopeKey + ":Body>";
+      const headerNamespaces = client.wsdl.xmlnsInHeader ? " " + client.wsdl.xmlnsInHeader : "";
+      envelope = envelope.replace(body, "<" + envelopeKey + ":Header" + headerNamespaces + ">" + headerXml + "</" + envelopeKey + ":Header>" + body);
+    }
+    if (security?.postProcess) envelope = security.postProcess(envelope, envelopeKey);
+    if (typeof requestOptions.postProcess === "function") envelope = requestOptions.postProcess(envelope);
+    const controller = new AbortController();
+    const signals = [controller.signal, callOptions?.signal, requestOptions.signal].filter((signal): signal is AbortSignal => !!signal);
+    requestOptions.signal = AbortSignal.any(signals);
+    const timeoutMs = callOptions?.timeoutMs;
+    if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)) {
+      throw new RangeError("Stream timeoutMs must be a positive safe timer duration");
+    }
+    const timer = timeoutMs === undefined ? undefined : setTimeout(() => controller.abort(new Error("Stream request timed out")), timeoutMs);
+    timer?.unref();
+    let body: (AsyncIterable<string | Uint8Array> & {destroy(): void}) | undefined;
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      if (typeof body?.destroy === "function") body.destroy();
+      controller.abort();
     };
+    try {
+      const res = await transport.requestStream(endpoint, envelope, headers, requestOptions, client);
+      body = res.data as unknown as typeof body;
+      if (!body || typeof body[Symbol.asyncIterator] !== "function" || typeof body.destroy !== "function") {
+        throw new Error(operation + " stream request returned an invalid response body");
+      }
+      if (res.status < 200 || res.status >= 300) {
+        throw new Error(operation + " stream request failed: " + res.status + " " + res.statusText);
+      }
+      const spec: RecordParseSpec = {
+        recordPath,
+        recordTypeName,
+        attributesKey: this.attributesKeyOut,
+        childType: this.dataTypes?.ChildrenTypes,
+        repeatedElements: this.dataTypes?.RepeatedElements,
+      };
+      const source = parseRecords(body, spec);
+      const self = this;
+      async function* mapped(): AsyncGenerator<RecordType> {
+        try {
+          for await (const record of source) yield self.fromSoapResult(record, recordTypeName) as RecordType;
+        } finally { cleanup(); }
+      }
+      const iterator = mapped();
+      // @constraints return() must close transport even before the generator's first next().
+      const records: AsyncIterable<RecordType> = {
+        [Symbol.asyncIterator]() {
+          return {
+            next: () => iterator.next(),
+            return: async () => { cleanup(); return iterator.return(undefined); },
+            throw: async error => { cleanup(); return iterator.throw(error); },
+          };
+        },
+      };
+      return {records, headers: res.headers as unknown as HeadersType, requestRaw: envelope};
+    } catch (error) {
+      cleanup();
+      throw error;
+    }
   }
 
   /**
-   * Walk the node-soap WSDL descriptor to locate the first service port's
-   * SOAP address. Falls back to the \`source\` URL when the descriptor is
-   * unavailable (e.g., \`source\` was given as a direct endpoint URL).
+   * Select one compatible live document/literal operation binding and endpoint.
+   * @param client - Initialized node-soap client.
+   * @param operation - Compiled operation name.
+   * @param soapAction - Compiled SOAP action, used to disambiguate live methods.
+   * @param inputElementLocal - Expected input element local name.
+   * @param inputElementNs - Expected input namespace.
+   * @returns Matched input descriptor and current override or owning port address.
+   * @throws Error for missing, ambiguous, or incompatible live operation bindings.
+   * @constraints Distinct bindings cannot be assumed equivalent after node-soap has processed shared port-type metadata.
    */
-  protected resolveStreamEndpoint(client: __SOAP_CLIENT_TYPE__): string {
+  protected resolveStreamBinding(
+    client: __SOAP_CLIENT_TYPE__,
+    operation: string,
+    soapAction: string,
+    inputElementLocal: string,
+    inputElementNs: string
+  ): {endpoint: string; input: {$name: string; targetNSAlias: string; targetNamespace: string; $type?: string; $lookupType?: string}} {
+    const override = (client as unknown as {endpoint?: string}).endpoint ?? this.options?.endpoint;
+    const candidates: Array<{endpoint: string; binding: unknown; method: any}> = [];
     const services = (client as any)?.wsdl?.definitions?.services ?? {};
     for (const svc of Object.values(services)) {
       const ports = (svc as any)?.ports ?? {};
       for (const port of Object.values(ports)) {
-        const location = (port as any)?.location;
-        if (typeof location === "string" && location) return location;
+        const binding = (port as any)?.binding;
+        const method = binding?.methods?.[operation];
+        if (!method || method.$name !== operation || (method.soapAction ?? "") !== soapAction) continue;
+        const endpoint = override || (port as any)?.location;
+        if (typeof endpoint !== "string" || !endpoint) throw new Error("No SOAP endpoint configured for stream request");
+        candidates.push({endpoint, binding, method});
       }
     }
-    return this.source;
+    if (candidates.length === 0) throw new Error("No matching SOAP operation binding for stream request: " + operation);
+    const selected = candidates[0];
+    if (candidates.some(candidate => candidate.binding !== selected.binding || candidate.method !== selected.method || candidate.endpoint !== selected.endpoint)) {
+      throw new Error("Ambiguous or incompatible SOAP operation bindings for stream request: " + operation);
+    }
+    const method = selected.method;
+    const input = method.input;
+    if (method.style && method.style !== "document" || method.inputSoap?.use && method.inputSoap.use !== "literal" ||
+      !input || input.parts || input.$name !== inputElementLocal || input.targetNamespace !== inputElementNs) {
+      throw new Error("Incompatible SOAP document/literal input binding for stream request: " + operation);
+    }
+    return {endpoint: selected.endpoint, input};
   }
 
   /**
-   * Build a SOAP 1.1 envelope around the operation's input element. Uses the
-   * existing attributes / children metadata so attribute bags render as XML
-   * attributes and child properties render as nested elements.
+   * Wrap the schema-serialized request using the initialized client's envelope namespace context.
+   * @param body - Document/literal XML from node-soap's public WSDL serializer.
+   * @param envelopeKey - Validated SOAP envelope prefix, also passed to security processing.
+   * @param client - Initialized client supplying the WSDL namespace declarations.
+   * @returns A SOAP 1.1 envelope ready for static headers and security hooks.
    */
   protected buildSoapEnvelope(
-    args: unknown,
-    operation: string,
-    requestType: string | undefined,
-    inputElementLocal: string,
-    inputElementNs: string
+    body: string,
+    envelopeKey: string,
+    client: __SOAP_CLIENT_TYPE__
   ): string {
-    const body = this.toXmlElement(args, requestType, inputElementLocal, inputElementNs);
     return '<?xml version="1.0" encoding="utf-8"?>' +
-      '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">' +
-      '<soap:Body>' + body + '</soap:Body>' +
-      '</soap:Envelope>';
-  }
-
-  /**
-   * Serialize a value as a single XML element. The element namespace is only
-   * emitted when \`namespace\` is provided (i.e., the envelope's top-level body
-   * element). Nested elements inherit the namespace via XML scoping.
-   */
-  protected toXmlElement(
-    value: unknown,
-    typeName: string | undefined,
-    elementName: string,
-    namespace?: string
-  ): string {
-    const nsAttr = namespace ? ' xmlns="' + this.escapeXml(namespace) + '"' : "";
-    if (value === null || value === undefined) {
-      return '<' + elementName + nsAttr +
-        ' xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>';
-    }
-    if (typeof value !== "object") {
-      return '<' + elementName + nsAttr + '>' + this.escapeXml(String(value)) + '</' + elementName + '>';
-    }
-    if (Array.isArray(value)) {
-      return value.map((v) => this.toXmlElement(v, typeName, elementName, namespace)).join("");
-    }
-    const obj = value as Record<string, unknown>;
-    const attributesList = (typeName && this.dataTypes?.Attributes?.[typeName]) || [];
-    const childrenTypes = (typeName && this.dataTypes?.ChildrenTypes?.[typeName]) || {};
-    const attrPairs: Array<[string, string]> = [];
-    const bagIn = (obj as any)[this.attributesKeyIn] ?? (obj as any)["attributes"];
-    if (bagIn && typeof bagIn === "object") {
-      for (const [k, v] of Object.entries(bagIn)) attrPairs.push([k, this.normalizeAttr(v)]);
-    }
-    const childParts: string[] = [];
-    let textContent: string | undefined;
-    if ("$value" in obj) textContent = String(obj.$value ?? "");
-    for (const [k, v] of Object.entries(obj)) {
-      if (k === "$value" || k === this.attributesKeyIn || k === "attributes") continue;
-      if ((attributesList as readonly string[]).includes(k)) {
-        attrPairs.push([k, this.normalizeAttr(v)]);
-        continue;
-      }
-      const childTypeRaw = (childrenTypes as Record<string, string>)[k];
-      const childType = childTypeRaw?.endsWith("[]") ? childTypeRaw.slice(0, -2) : childTypeRaw;
-      if (Array.isArray(v)) {
-        for (const item of v) childParts.push(this.toXmlElement(item, childType, k));
-      } else {
-        childParts.push(this.toXmlElement(v, childType, k));
-      }
-    }
-    const attrStr = attrPairs.map(([k, val]) => ' ' + k + '="' + this.escapeXml(val) + '"').join("");
-    if (childParts.length === 0 && textContent === undefined) {
-      return '<' + elementName + nsAttr + attrStr + '/>';
-    }
-    const inner = childParts.join("") + (textContent !== undefined ? this.escapeXml(textContent) : "");
-    return '<' + elementName + nsAttr + attrStr + '>' + inner + '</' + elementName + '>';
-  }
-
-  protected normalizeAttr(v: unknown): string {
-    if (v === null || v === undefined) return "";
-    if (typeof v === "boolean") return v ? "true" : "false";
-    if (typeof v === "number") return Number.isFinite(v) ? String(v) : "";
-    return String(v);
-  }
-
-  protected escapeXml(s: string): string {
-    return s
-      .replace(/&/g, "&amp;")
-      .replace(/</g, "&lt;")
-      .replace(/>/g, "&gt;")
-      .replace(/"/g, "&quot;")
-      .replace(/'/g, "&apos;");
-  }
-
-  /**
-   * Iterate an uploaded web ReadableStream as Uint8Array chunks. Node 24+
-   * ReadableStream implements Symbol.asyncIterator natively; this helper
-   * normalizes the types so TypeScript can drive it through \`for await\`.
-   */
-  protected async *webStreamToAsyncIterable(
-    body: ReadableStream<Uint8Array>
-  ): AsyncIterable<Uint8Array> {
-    const reader = body.getReader();
-    try {
-      while (true) {
-        const {value, done} = await reader.read();
-        if (done) return;
-        if (value) yield value;
-      }
-    } finally {
-      try { reader.releaseLock(); } catch { /* noop */ }
-    }
+      '<' + envelopeKey + ':Envelope xmlns:' + envelopeKey + '="http://schemas.xmlsoap.org/soap/envelope/" ' +
+      'xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ' + client.wsdl.xmlnsInEnvelope + '>' +
+      '<' + envelopeKey + ':Body>' + body + '</' + envelopeKey + ':Body>' +
+      '</' + envelopeKey + ':Envelope>';
   }

package/src/runtime/operationsStreamHelper.tpl.txt

@@ -1,11 +1,11 @@
 /**
- * Response shape for streaming __CLIENT_NAME__ operations. `records` is a
- * single-pass async iterable of parsed record objects; iteration pulls bytes
- * from the upstream SOAP response on demand. `headers` is the HTTP response
- * header map captured before the first record is parsed. `requestRaw`, when
- * populated, contains the serialized SOAP envelope that was sent upstream.
+ * Represents a streamed __CLIENT_NAME__ response.
+ * @typeParam RecordType Parsed record DTO yielded by the single-pass upstream iterator.
+ * @typeParam HeadersType HTTP headers captured before the first record is parsed.
+ * @constraints The structural default permits WSDL DTOs named Record without shadowing a utility type.
+ * @remarks requestRaw contains the serialized SOAP request when populated.
  */
-export type StreamOperationResponse<RecordType, HeadersType = Record<string, unknown>> = {
+export type StreamOperationResponse<RecordType, HeadersType = {[key: string]: unknown}> = {
   records: AsyncIterable<RecordType>;
   headers: HeadersType;
   requestRaw?: string;