@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/ws/session.js

@@ -1,8 +1,10 @@
 /**
- * One WebSocket connection from handshake to close, and the only file that touches undici's
- * WebSocket. It knows nothing about projects or containers: a saved WebSocket request opens one
- * through `call.ts`, and anything else that needs a socket — a subscription protocol layered on a
- * subprotocol, a contract check wrapped around `onFrame` — opens one the same way.
+ * One WebSocket connection from handshake to close, recorded frame by frame. It is one of the two
+ * files that touch undici's WebSocket: the other, `connect.ts`, hands a bare socket to a caller with
+ * its own protocol, and both build their dispatcher with `wsDispatcher`. It knows nothing about
+ * projects or containers: a saved WebSocket request opens one through `call.ts`, and anything else
+ * that needs a recorded socket (a subscription protocol layered on a subprotocol, a contract check
+ * wrapped around `onFrame`) opens one the same way.
  *
  * Whatever the server does is a result. `done` never rejects: a refused handshake, a dropped
  * socket and a clean close all resolve with the exchange that records them. A bad *option* is
@@ -10,13 +12,23 @@
  * whatever it had already built (subscriptions, an owned dispatcher) before doing so.
  */
 import diagnosticsChannel from 'node:diagnostics_channel';
-import { ProxyAgent, WebSocket } from 'undici';
+import { WebSocket } from 'undici';
 import { WsError } from '../errors.js';
-import { createDispatcher, proxyAgentOptionsFor } from '../http/client.js';
 import { sslInfoForSocket } from '../http/tls.js';
+import { wsDispatcher } from './connect.js';
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 30_000;
-/** RFC 6455 §7.4, as the WHATWG API enforces it: 1000, or the 3000–4999 range. */
-function assertCloseCode(code) {
+/**
+ * How a handshake that timed out begins its `error`: the one failure a caller tells apart from a
+ * refusal (the run facet fails a run's send with `timeout` for it). Not part of the public surface.
+ */
+export const HANDSHAKE_TIMEOUT_ERROR = 'The server did not answer the handshake within';
+/**
+ * RFC 6455 §7.4, as the WHATWG API enforces it: 1000, or the 3000–4999 range. Exported for the run
+ * facet, which refuses a bad code when it is asked to close rather than when the close goes out.
+ *
+ * @throws WsError `ws-bad-close`
+ */
+export function assertCloseCode(code) {
     if (code !== 1000 && !(code >= 3000 && code <= 4999)) {
         throw new WsError('ws-bad-close', `${code} is not a close code an application may send (1000, or 3000–4999)`, {
             details: { code },
@@ -76,12 +88,9 @@ export function openWsSession(options, hooks = {}) {
             details: { url: options.url },
         });
     }
-    // `createDispatcher({ proxy })` does not CONNECT-tunnel a WebSocket handshake: undici rewrites
-    // `ws:`/`wss:` to `http:`/`https:` before dispatching, and `ProxyAgent` only tunnels `http:`
-    // when built with `proxyTunnel: true`. So a proxied session always owns its own `ProxyAgent`;
-    // an unproxied one owns a dispatcher only when it asked for TLS/bind-address options that
-    // `createDispatcher` would otherwise hand back the shared keep-alive agent for.
-    const ownsDispatcher = options.proxy !== undefined || options.tls !== undefined || options.localAddress !== undefined;
+    // Which dispatcher the handshake gets, and whether this session must close it, is `wsDispatcher`'s
+    // rule (`connect.ts`). It is assigned in the try block that builds the socket, below.
+    let ownsDispatcher = false;
     const httpOrigin = `${target.protocol === 'wss:' ? 'https:' : 'http:'}//${target.host}`;
     const frames = [];
     const counts = { sent: 0, received: 0, bytesSent: 0, bytesReceived: 0 };
@@ -91,6 +100,9 @@ export function openWsSession(options, hooks = {}) {
     let closedBy;
     let failure;
     let settled = false;
+    /** The upgrade's socket, which a close the server never answers tears down after `closeGraceMs`. */
+    let connection;
+    let closeTimer;
     const record = (direction, opcode, payload, close) => {
         const bytes = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : Buffer.from(payload);
         const binaryish = opcode === 'binary' || ((opcode === 'ping' || opcode === 'pong') && bytes.length > 0);
@@ -139,6 +151,7 @@ export function openWsSession(options, hooks = {}) {
         if (!isUpgradeHeadFor(message, httpOrigin, `${target.pathname}${target.search}`))
             return;
         rawRequestHead = message.headers;
+        connection = message.socket;
         if (message.socket?.encrypted === true)
             tls = sslInfoForSocket(message.socket);
     };
@@ -190,16 +203,7 @@ export function openWsSession(options, hooks = {}) {
     // owned dispatcher if one got built, then report `ws-bad-options` instead of leaking either.
     let dispatcher;
     try {
-        dispatcher =
-            options.proxy !== undefined
-                ? new ProxyAgent(proxyAgentOptionsFor(options.proxy, {
-                    ...(options.tls !== undefined ? { tls: options.tls } : {}),
-                    ...(options.localAddress !== undefined ? { localAddress: options.localAddress } : {}),
-                }, false, { proxyTunnel: true }))
-                : createDispatcher({
-                    ...(options.tls !== undefined ? { tls: options.tls } : {}),
-                    ...(options.localAddress !== undefined ? { localAddress: options.localAddress } : {}),
-                });
+        ({ dispatcher, owned: ownsDispatcher } = wsDispatcher(options));
         diagnosticsChannel.subscribe('undici:client:sendHeaders', onSendHeaders);
         diagnosticsChannel.subscribe('undici:websocket:open', onOpenChannel);
         diagnosticsChannel.subscribe('undici:websocket:ping', onPing);
@@ -236,6 +240,7 @@ export function openWsSession(options, hooks = {}) {
             return;
         settled = true;
         clearTimeout(timer);
+        clearTimeout(closeTimer);
         options.signal?.removeEventListener('abort', onAbort);
         unsubscribeAll();
         const clean = wasClean && handshake !== undefined;
@@ -262,16 +267,37 @@ export function openWsSession(options, hooks = {}) {
         hooks.onClosed?.(exchange);
         resolveDone(exchange);
     };
+    /**
+     * Lets go of a connection whose close the server never answered: the socket is destroyed, and the
+     * session settles with 1006 on the next macrotask if undici reports nothing of it.
+     */
+    const tearDown = () => {
+        if (settled)
+            return;
+        connection?.destroy?.();
+        setTimeout(() => settle(1006, '', false), 0);
+    };
+    /** Gives a close from this side `closeGraceMs` to be answered, when the options bound it. */
+    const boundClose = () => {
+        if (options.closeGraceMs === undefined || closeTimer !== undefined)
+            return;
+        closeTimer = setTimeout(tearDown, options.closeGraceMs);
+    };
     /** Ends a session the server never ended: a timeout, or an abort. */
     const fail = (message) => {
         failure ??= message;
         closedBy ??= 'error';
+        // A cancel while the close waits for its answer, when the wait is bounded, waits no more.
+        if (ws.readyState === WebSocket.CLOSING && options.closeGraceMs !== undefined) {
+            tearDown();
+            return;
+        }
         // There is no abort for a connecting socket; close() on one fails the handshake, which is the point.
         ws.close();
     };
     const timer = setTimeout(() => {
         if (handshake === undefined)
-            fail(`The server did not answer the handshake within ${timeoutMs} ms`);
+            fail(`${HANDSHAKE_TIMEOUT_ERROR} ${timeoutMs} ms`);
     }, timeoutMs);
     const onAbort = () => fail('The connection was cancelled');
     if (options.signal?.aborted === true)
@@ -328,6 +354,7 @@ export function openWsSession(options, hooks = {}) {
             if (ws.readyState === WebSocket.OPEN)
                 record('sent', 'close', reason, { code, reason });
             ws.close(code, reason);
+            boundClose();
         },
     };
 }

package/dist/ws/storage.d.ts

@@ -0,0 +1,9 @@
+/**
+ * How WebSocket APIs are stored in a project folder (spec §3.2): `apis/<slug>/api.yaml` with
+ * `kind: websocket`, and a tree of folders and `*.request.yaml` files under `requests/`, each saved
+ * message in a sibling `<slug>.msg-<message slug>.<ext>`.
+ */
+import type { ProtocolStorage } from '../protocol/module.js';
+import type { WsApi } from './model.js';
+/** WebSocket's storage facet. */
+export declare const wsStorage: ProtocolStorage<WsApi>;

package/dist/ws/storage.js

@@ -0,0 +1,176 @@
+/**
+ * How WebSocket APIs are stored in a project folder (spec §3.2): `apis/<slug>/api.yaml` with
+ * `kind: websocket`, and a tree of folders and `*.request.yaml` files under `requests/`, each saved
+ * message in a sibling `<slug>.msg-<message slug>.<ext>`.
+ */
+import { toCallbackAssertion } from '../assert/schema.js';
+import { ProjectError } from '../errors.js';
+import { readFileIfExists } from '../project/fs.js';
+import { abs, authConfig, definitionAuth, exact, keyValueEntries, loadFolderContents, optional, readYaml, } from '../project/load-helpers.js';
+import { apiManagedFiles } from '../project/managed-files.js';
+import { API_FILE, APIS_DIR, assertPathSegment, REQUEST_SUFFIX, REQUESTS_DIR } from '../project/paths.js';
+import { assertSupportedKind, parseFile } from '../project/schema-parts.js';
+import { addFolderFiles, authDocument, definitionDocument, keyValueDocuments } from '../project/serialize-helpers.js';
+import { compact, stringifyYaml } from '../project/yaml.js';
+import { wsApiFileSchema, wsRequestFileSchema } from './files.js';
+import { wsMessageFileName } from './model.js';
+/**
+ * Reads a WebSocket request and its saved messages, each in its own sibling file. A message whose
+ * file is gone loads with empty content and a `missing-body` problem, exactly as a gRPC message
+ * does; its slug is recovered from the file name between the `.msg-` marker and the extension.
+ */
+function wsRequestReader(fs, root, problems) {
+    return async (dir, fileName, unclaimed) => {
+        const relative = `${dir}/${fileName}`;
+        const document = await readYaml(fs, root, relative);
+        assertSupportedKind(document, relative);
+        const parsed = parseFile(wsRequestFileSchema, document, relative);
+        unclaimed.delete(fileName);
+        const requestSlug = fileName.slice(0, -REQUEST_SUFFIX.length);
+        const messages = [];
+        for (const entry of parsed.messages) {
+            assertPathSegment(entry.file);
+            unclaimed.delete(entry.file);
+            const messageRelative = `${dir}/${entry.file}`;
+            const text = await readFileIfExists(fs, abs(root, messageRelative));
+            if (text === undefined) {
+                problems.push({
+                    code: 'missing-body',
+                    message: `Request "${parsed.name}" has no message file; loaded with an empty message`,
+                    file: messageRelative,
+                });
+            }
+            const slug = entry.file.slice(`${requestSlug}.msg-`.length, entry.file.lastIndexOf('.'));
+            messages.push({
+                id: entry.id,
+                name: entry.name,
+                slug,
+                format: entry.format,
+                content: text === undefined ? '' : text.toString('utf8'),
+                ...(entry.contract !== undefined
+                    ? { contract: { message: entry.contract.message, generated: entry.contract.generated } }
+                    : {}),
+            });
+        }
+        return {
+            kind: 'websocket',
+            id: parsed.id,
+            name: parsed.name,
+            slug: requestSlug,
+            order: parsed.order,
+            ...optional('description', parsed.description),
+            url: parsed.url,
+            query: keyValueEntries(parsed.query),
+            headers: keyValueEntries(parsed.headers),
+            subprotocols: parsed.subprotocols,
+            auth: authConfig(parsed.auth),
+            settings: exact(parsed.settings),
+            messages,
+            assertions: parsed.assertions.map((a) => (a.type === 'callback' ? toCallbackAssertion(a) : exact(a))),
+            ...(parsed.contract !== undefined ? { contract: { channel: parsed.contract.channel } } : {}),
+            ...(parsed.orphaned === true ? { orphaned: true } : {}),
+        };
+    };
+}
+/**
+ * A WebSocket request as written: each saved message goes to a sibling file, so a JSON message is a
+ * JSON file in git. Siblings rather than a directory, because every directory here loads as a folder.
+ *
+ * @throws ProjectError `duplicate-slug` when two of the request's messages share a slug.
+ */
+const writeWsRequest = (files, dir, request) => {
+    const messages = request.messages.map((message) => {
+        const file = wsMessageFileName(request.slug, message);
+        assertPathSegment(file);
+        if (files.has(`${dir}/${file}`)) {
+            throw new ProjectError('duplicate-slug', `Request "${request.name}" has two messages named "${message.slug}"`, {
+                details: { file: `${dir}/${file}` },
+            });
+        }
+        files.set(`${dir}/${file}`, message.content);
+        return compact({
+            id: message.id,
+            name: message.name,
+            format: message.format === 'binary' ? 'binary' : undefined,
+            file,
+            contract: message.contract === undefined
+                ? undefined
+                : { message: message.contract.message, generated: message.contract.generated },
+        });
+    });
+    files.set(`${dir}/${request.slug}${REQUEST_SUFFIX}`, stringifyYaml(compact({
+        kind: request.kind,
+        id: request.id,
+        name: request.name,
+        order: request.order,
+        description: request.description,
+        url: request.url,
+        query: request.query.length > 0 ? keyValueDocuments(request.query) : undefined,
+        headers: request.headers.length > 0 ? keyValueDocuments(request.headers) : undefined,
+        subprotocols: request.subprotocols.length > 0 ? [...request.subprotocols] : undefined,
+        auth: authDocument(request.auth),
+        settings: Object.keys(request.settings).length > 0 ? compact({ ...request.settings }) : undefined,
+        messages: messages.length > 0 ? messages : undefined,
+        assertions: request.assertions.length > 0 ? request.assertions.map((a) => compact({ ...a })) : undefined,
+        contract: request.contract === undefined ? undefined : { channel: request.contract.channel },
+        orphaned: request.orphaned === true ? true : undefined,
+    })));
+};
+/** Every file one WebSocket API occupies. It shares `apis/` with the others; its `kind` says which it is. */
+function addWsApiFiles(files, api) {
+    assertPathSegment(api.slug);
+    const base = `${APIS_DIR}/${api.slug}`;
+    files.set(`${base}/${API_FILE}`, stringifyYaml(compact({
+        kind: api.kind,
+        id: api.id,
+        name: api.name,
+        order: api.order,
+        description: api.description,
+        url: api.url,
+        headers: api.headers.length > 0 ? keyValueDocuments(api.headers) : undefined,
+        auth: api.auth === undefined ? undefined : authDocument(api.auth),
+        definition: api.definition === undefined ? undefined : definitionDocument(api.definition),
+    })));
+    addFolderFiles(files, `${base}/${REQUESTS_DIR}`, api, 0, writeWsRequest);
+}
+/** WebSocket's storage facet. */
+export const wsStorage = {
+    dir: APIS_DIR,
+    async load(ctx, slug, document) {
+        const { fs, root, problems } = ctx;
+        const parsed = parseFile(wsApiFileSchema, document, `${APIS_DIR}/${slug}/${API_FILE}`);
+        const contents = await loadFolderContents(fs, root, `${APIS_DIR}/${slug}/${REQUESTS_DIR}`, 0, problems, wsRequestReader(fs, root, problems));
+        return {
+            kind: 'websocket',
+            id: parsed.id,
+            name: parsed.name,
+            slug,
+            order: parsed.order,
+            ...optional('description', parsed.description),
+            url: parsed.url,
+            headers: keyValueEntries(parsed.headers),
+            ...(parsed.auth !== undefined ? { auth: authConfig(parsed.auth) } : {}),
+            ...(parsed.definition !== undefined
+                ? {
+                    definition: {
+                        kind: parsed.definition.kind,
+                        source: parsed.definition.source,
+                        cache: parsed.definition.cache,
+                        ...optional('server', parsed.definition.server),
+                        ...optional('auth', definitionAuth(parsed.definition.auth)),
+                    },
+                }
+                : {}),
+            folders: contents.folders,
+            requests: contents.requests,
+        };
+    },
+    files(api) {
+        const files = new Map();
+        addWsApiFiles(files, api);
+        return files;
+    },
+    managed: (fs, root, slug) => apiManagedFiles(fs, root, slug),
+    containers: (project) => project.wsApis,
+    withContainers: (project, wsApis) => ({ ...project, wsApis }),
+};

package/dist/ws/transcript.d.ts

@@ -2,13 +2,12 @@
  * What History keeps of a session. Both ends, because the end — the last messages before an
  * unexpected close — is what a person comes back for, and a first-N cap loses exactly that.
  */
+import { WS_HISTORY_HEAD, WS_HISTORY_MAX_BYTES, WS_HISTORY_TAIL } from '../http/transcript-cap.js';
 import type { WsFrame } from './model.js';
-export declare const WS_HISTORY_HEAD = 400;
-export declare const WS_HISTORY_TAIL = 100;
-export declare const WS_HISTORY_MAX_BYTES = 1048576;
+export { WS_HISTORY_HEAD, WS_HISTORY_MAX_BYTES, WS_HISTORY_TAIL };
 export interface WsTranscript {
     readonly frames: readonly WsFrame[];
     readonly truncated: boolean;
     readonly omittedFrames: number;
 }
-export declare function capFrames(frames: readonly WsFrame[]): WsTranscript;
+export declare function capFrames(input: readonly WsFrame[]): WsTranscript;

package/dist/ws/transcript.js

@@ -1,20 +1,28 @@
-export const WS_HISTORY_HEAD = 400;
-export const WS_HISTORY_TAIL = 100;
-export const WS_HISTORY_MAX_BYTES = 1_048_576;
-export function capFrames(frames) {
-    const limit = WS_HISTORY_HEAD + WS_HISTORY_TAIL;
-    const kept = frames.length <= limit ? [...frames] : [...frames.slice(0, WS_HISTORY_HEAD), ...frames.slice(-WS_HISTORY_TAIL)];
-    const omittedFrames = frames.length - kept.length;
-    let budget = WS_HISTORY_MAX_BYTES;
-    let stripped = false;
-    const capped = kept.map((frame) => {
-        if (frame.size <= budget) {
-            budget -= frame.size;
-            return frame;
-        }
+/**
+ * What History keeps of a session. Both ends, because the end — the last messages before an
+ * unexpected close — is what a person comes back for, and a first-N cap loses exactly that.
+ */
+import { capByEnds, WS_HISTORY_HEAD, WS_HISTORY_MAX_BYTES, WS_HISTORY_TAIL } from '../http/transcript-cap.js';
+export { WS_HISTORY_HEAD, WS_HISTORY_MAX_BYTES, WS_HISTORY_TAIL };
+/** History keeps a frame's contract verdict but not its problem list: the list is for the live
+ *  view, and re-checking a saved frame recomputes it. */
+function withoutProblems(frame) {
+    if (frame.contract?.problems === undefined)
+        return frame;
+    const { status, message, reason } = frame.contract;
+    const contract = {
+        status,
+        ...(message !== undefined ? { message } : {}),
+        ...(reason !== undefined ? { reason } : {}),
+    };
+    return { ...frame, contract };
+}
+export function capFrames(input) {
+    const frames = input.map(withoutProblems);
+    const limits = { head: WS_HISTORY_HEAD, tail: WS_HISTORY_TAIL, maxBytes: WS_HISTORY_MAX_BYTES };
+    const r = capByEnds(frames, limits, (frame) => frame.size, (frame) => {
         if (frame.text === undefined && frame.base64 === undefined)
-            return frame;
-        stripped = true;
+            return undefined;
         return {
             index: frame.index,
             direction: frame.direction,
@@ -22,8 +30,9 @@ export function capFrames(frames) {
             at: frame.at,
             size: frame.size,
             ...(frame.close !== undefined ? { close: frame.close } : {}),
+            ...(frame.contract !== undefined ? { contract: frame.contract } : {}),
             payloadTruncated: true,
         };
     });
-    return { frames: capped, truncated: omittedFrames > 0 || stripped, omittedFrames };
+    return { frames: r.items, truncated: r.truncated, omittedFrames: r.omitted };
 }

package/dist/ws/url.d.ts

@@ -1,3 +1,3 @@
-import type { KeyValueEntry } from '../rest/model.js';
+import type { KeyValueEntry } from '../http/entries.js';
 /** The URL a session dials: the request's own when absolute, else its path under the server URL. */
 export declare function resolveWsUrl(serverUrl: string, requestUrl: string, query: readonly KeyValueEntry[]): string;

package/dist/wsdl/cache.js

@@ -13,7 +13,7 @@ import { definitionCacheManifestSchema, parseFile } from '../project/schema.js';
 import { nodeFs, readFileIfExists, readdirIfExists, writeFileAtomic } from '../project/fs.js';
 import { parseYaml, stringifyYaml } from '../project/yaml.js';
 import { parseXml } from '../xml/parse.js';
-import { assignFileNames } from './cache-naming.js';
+import { assignFileNames } from '../project/cache-naming.js';
 const MANIFEST_FILE = 'manifest.yaml';
 /** Hex-encoded SHA-256 digest of `bytes`, used to verify cached documents haven't been tampered with or corrupted. */
 function sha256Hex(bytes) {

package/dist/wsdl/docs-generator.d.ts

@@ -3,12 +3,12 @@
  * single self-contained document — HTML (inline CSS, no scripts, everything
  * escaped) or Markdown (with a table of contents).
  *
- * Pure and deterministic: the same {@link ImportResult} always produces
+ * Pure and deterministic: the same {@link WsdlImportResult} always produces
  * byte-identical output, so the golden tests are meaningful and a regenerated
  * document is a clean diff. Nothing is fetched; every byte comes from the
  * bundle the import already resolved.
  */
-import type { ImportResult } from '../types.js';
+import type { WsdlImportResult } from '../soap/types.js';
 /** Options accepted by {@link generateDocs}. */
 export interface GenerateDocsOptions {
     readonly format: 'html' | 'markdown';
@@ -44,4 +44,4 @@ export declare function sourceSnippet(text: string, line: number, maxLines?: num
  * @param options output format and an optional title
  * @returns the whole document as a string; the caller decides where it lands
  */
-export declare function generateDocs(result: ImportResult, options: GenerateDocsOptions): string;
+export declare function generateDocs(result: WsdlImportResult, options: GenerateDocsOptions): string;

package/dist/wsdl/docs-generator.js

@@ -3,7 +3,7 @@
  * single self-contained document — HTML (inline CSS, no scripts, everything
  * escaped) or Markdown (with a table of contents).
  *
- * Pure and deterministic: the same {@link ImportResult} always produces
+ * Pure and deterministic: the same {@link WsdlImportResult} always produces
  * byte-identical output, so the golden tests are meaningful and a regenerated
  * document is a clean diff. Nothing is fetched; every byte comes from the
  * bundle the import already resolved.

package/dist/wsdl/export-definition.js

@@ -13,7 +13,7 @@ import { writeFileAtomic } from '../project/fs.js';
 import { NS } from '../xml/namespaces.js';
 import { parseXml } from '../xml/parse.js';
 import { serializeXml } from '../xml/serialize.js';
-import { assignFileNames } from './cache-naming.js';
+import { assignFileNames } from '../project/cache-naming.js';
 import { childElements, firstChildElement, optionalAttribute } from './dom-utils.js';
 /** Resolves `ref` (an import/include/redefine location) against `base` using the WHATWG `URL` class. */
 function resolveUrl(ref, base) {

package/dist/wsdl/qname.d.ts

@@ -1,9 +1,6 @@
 import type { Element } from '@xmldom/xmldom';
-/** A namespace-qualified name: an expanded `{namespaceUri}localName` pair. */
-export interface QName {
-    readonly namespaceUri: string;
-    readonly localName: string;
-}
+import type { QName } from '../xml/qname.js';
+export type { QName };
 /**
  * Resolves a (possibly prefixed) QName string against the namespaces in
  * scope at `contextElement`, walking ancestors via `lookupNamespaceURI`.

package/dist/wsdl/resolver.d.ts

@@ -1,4 +1,5 @@
 import type { Document } from '@xmldom/xmldom';
+import type { FetchDocument, FetchedDocument } from '../http/fetch-document.js';
 /** The root document to resolve, plus an optional pre-fetched body (avoids a redundant fetch of the root). */
 export interface DefinitionSource {
     /** Absolute URL (`http(s)://` or `file://`) identifying the root document. */
@@ -6,15 +7,7 @@ export interface DefinitionSource {
     /** Pre-fetched root document text, when the caller already has it in hand. */
     readonly text?: string;
 }
-/** A fetched document's canonical location (post-redirect) and raw content. */
-export interface FetchedDocument {
-    /** The final absolute location after following any redirects. */
-    readonly location: string;
-    readonly bytes: Uint8Array;
-    readonly text: string;
-}
-/** Fetches a single document by absolute location, honouring an optional abort signal. */
-export type FetchDocument = (location: string, signal?: AbortSignal) => Promise<FetchedDocument>;
+export type { FetchDocument, FetchedDocument };
 /** Options for {@link resolveDefinition}. */
 export interface ResolveOptions {
     readonly fetchDocument: FetchDocument;
@@ -40,7 +33,7 @@ export interface BundledDocument {
 /** A non-fatal problem encountered while resolving an import graph. */
 export interface ResolveProblem {
     readonly code: 'unsupported-redefine' | 'fetch-failed' | 'unresolved-import' | 'not-xml'
-    /** A reference the {@link ReferencePolicy} refused; see `wsdl/ref-policy.ts`. */
+    /** A reference the {@link ReferencePolicy} refused; see `http/ref-policy.ts`. */
      | 'import-ref-refused'
     /** The graph hit the depth or document cap; everything resolved so far is still returned. */
      | 'import-limit';
@@ -63,7 +56,7 @@ export interface DefinitionBundle {
  * 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
+ * `http/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

package/dist/wsdl/resolver.js

@@ -2,7 +2,7 @@ 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';
+import { MAX_IMPORT_DEPTH, MAX_IMPORT_DOCUMENTS, referencePolicyFor } from '../http/ref-policy.js';
 /**
  * Queues `ref`, resolved against `base` with the WHATWG `URL` class (which handles both
  * `http(s):` and `file:`).
@@ -159,7 +159,7 @@ function checkAborted(signal) {
  * 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
+ * `http/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
@@ -199,7 +199,7 @@ export async function resolveDefinition(source, options) {
     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`.
+    // Every nested reference is judged against the *root* document's world; see `http/ref-policy.ts`.
     const policy = referencePolicyFor(rootFetched.location);
     const queue = [];
     collectImports(rootDoc, 1, queue, problems);

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

@@ -3,7 +3,7 @@
  * 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
+ * two {@link WsdlImportResult}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
@@ -11,13 +11,13 @@
  * 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
+ * no longer has are kept and flagged {@link SoapRequestDef.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';
+import type { WsdlImportResult } from '../soap/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';
@@ -51,7 +51,7 @@ export interface UpdatePlan {
  * @param oldImport the definition the project was built from
  * @param newImport the freshly fetched definition
  */
-export declare function planUpdate(oldImport: ImportResult, newImport: ImportResult): UpdatePlan;
+export declare function planUpdate(oldImport: WsdlImportResult, newImport: WsdlImportResult): UpdatePlan;
 /**
  * What {@link applyUpdate} is allowed to do, named after the checkboxes of
  * the Update Definition dialog.
@@ -103,4 +103,4 @@ export interface ApplyUpdateResult {
  * @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;
+export declare function applyUpdate(project: Project, interfaceId: string, plan: UpdatePlan, newImport: WsdlImportResult, options: ApplyUpdateOptions): ApplyUpdateResult;

package/dist/wsdl/update-definition.js

@@ -3,7 +3,7 @@
  * 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
+ * two {@link WsdlImportResult}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
@@ -11,11 +11,11 @@
  * 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
+ * no longer has are kept and flagged {@link SoapRequestDef.orphaned} rather than
  * removed — the user decides whether a vanished operation means "clean
  * this up" or "the new WSDL is wrong".
  */
-import { generateRequest } from '../generate.js';
+import { generateSoapRequest } from '../soap/generate.js';
 import { createRequest, generateId } from '../project/model.js';
 import { INTERFACES_DIR, OPERATIONS_DIR, uniqueSlug } from '../project/paths.js';
 import { recreateRequest } from '../soap/recreate.js';
@@ -51,7 +51,7 @@ function addressesOf(summary) {
 /** The generated sample envelope for one operation, or `undefined` when it cannot be built. */
 function envelopeOf(result, ref) {
     try {
-        return generateRequest(result, ref, DIFF_GENERATE_OPTIONS).envelopeXml;
+        return generateSoapRequest(result, ref, DIFF_GENERATE_OPTIONS).envelopeXml;
     }
     catch {
         return undefined;
@@ -236,7 +236,7 @@ export function applyUpdate(project, interfaceId, plan, newImport, options) {
             if (recreate) {
                 const summary = summaryFor(newImport, key);
                 if (summary !== undefined) {
-                    const generated = generateRequest(newImport, refOf(summary), generateOptions);
+                    const generated = generateSoapRequest(newImport, refOf(summary), generateOptions);
                     const merged = recreateRequest(next.envelopeXml, generated.envelopeXml, {
                         keepValues: options.keepExisting,
                         keepHeaders: options.keepSoapHeaders,
@@ -274,7 +274,7 @@ export function applyUpdate(project, interfaceId, plan, newImport, options) {
                 order: iface.operations.length,
                 requests: [],
             };
-            const generated = generateRequest(newImport, ref, generateOptions);
+            const generated = generateSoapRequest(newImport, ref, generateOptions);
             const name = 'Request 1';
             const request = createRequest(name, {
                 id: newId(),