@usearazzo/runner 0.0.0-stage → 1.0.1-alpha.9

package/src/executor/OpenAPIOperationExecutor.cjs

@@ -0,0 +1,457 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
+var _ramdaAdjunct = require("ramda-adjunct");
+var _swaggerClient = require("../vendor/swagger-client.cjs");
+var _ParameterDelivery = _interopRequireDefault(require("../client/ParameterDelivery.cjs"));
+var _HTTPClientFetch = _interopRequireDefault(require("../client/HTTPClientFetch.cjs"));
+var _OpenAPIOperationResponseNormalizer = _interopRequireDefault(require("../client/OpenAPIOperationResponseNormalizer.cjs"));
+var _OpenAPIOperationExtractor = _interopRequireDefault(require("../extractor/OpenAPIOperationExtractor.cjs"));
+var _OpenAPIOperationNormalizer = _interopRequireDefault(require("../normalizer/OpenAPIOperationNormalizer.cjs"));
+var _OpenAPIDocumentAssembler = _interopRequireDefault(require("../assembler/OpenAPIDocumentAssembler.cjs"));
+var _ClientError = _interopRequireDefault(require("../errors/ClientError.cjs"));
+// @ts-expect-error vendored swagger-client bundle has no type declarations
+
+/**
+ * Decorates the built request before it is handed to the {@link HTTPClient}.
+ *
+ * Receives the finalized {@link OpenAPIOperationRequest} and may mutate it in
+ * place or return a replacement; returning nothing keeps the received request.
+ * May be synchronous or asynchronous.
+ * @public
+ */
+
+/**
+ * Options for executing an OpenAPI operation.
+ *
+ * All fields are forwarded to the vendored swagger-client `buildRequest`
+ * (which owns parameter serialization, security application, and server URL
+ * resolution), except `requestInterceptor`, which the executor runs between
+ * building the request and sending it.
+ *
+ * Typed here are the options the runner itself drives and the ones callers
+ * routinely reach for. The rest of `buildRequest`'s surface (`securities`,
+ * `scheme`, `parameterBuilders`, `attachContentTypeForEmptyPayload`, …) is
+ * deliberately left untyped and passes through the bag's open tail unchanged —
+ * see {@link OpenAPIOperationExecuteOptionsBag}. Authentication in particular
+ * is not modeled: Arazzo is auth-agnostic, so credentials are applied with a
+ * {@link RequestInterceptor}.
+ * @public
+ */
+
+/**
+ * The execute options forwarded to {@link OpenAPIOperationExecutor.execute}.
+ *
+ * The {@link OpenAPIOperationExecuteOptions} fields are surfaced for
+ * type-checked callers, while the open `Record` tail keeps the bag opaque so
+ * the rest of `buildRequest`'s surface (`scheme`, `parameterBuilders`,
+ * `attachContentTypeForEmptyPayload`, …) passes through untouched.
+ *
+ * Nothing routine belongs in the tail. Credentials go through a
+ * {@link RequestInterceptor} and `server` covers every case that once needed a
+ * `contextUrl`, so reaching for either of those here means an edge case: tests
+ * standing in for a document fetched over HTTP, or credentials applied from the
+ * document's own security schemes.
+ *
+ * Two kinds of entry are inert rather than honored, since the executor owns
+ * what they used to control. The operation target always comes from the
+ * locator, so `operationId`/`operationPath` have no effect; and the options
+ * only swagger-client's `execute()` ever read — `userFetch` and
+ * `responseInterceptor`, which the runner replaces with `httpClient` and
+ * `responseNormalizer` — reach `buildRequest` but nothing acts on them.
+ * @public
+ */
+
+/**
+ * Options for the OpenAPIOperationExecutor.
+ * @public
+ */
+
+/**
+ * Executes a single OpenAPI operation named by a canonical
+ * {@link OpenAPIOperationLocator}.
+ *
+ * The pipeline extracts the operation from its owning document, normalizes it,
+ * assembles a minimal standalone OpenAPI document containing just that
+ * operation, builds the HTTP request with the vendored swagger-client
+ * `buildRequest` (parameter serialization, securities, server resolution),
+ * sends it through the pluggable {@link HTTPClient}, and normalizes the raw
+ * `Response` into the runner's response model. A non-2xx status is a valid
+ * outcome (judged by a step's `successCriteria`) and is returned, never
+ * thrown; a transport failure is wrapped as a {@link ClientError}.
+ *
+ * The executor is Arazzo-agnostic: it neither locates the operation (that is
+ * the operation locator normalizer's concern) nor resolves parameters or
+ * request bodies from runtime expressions (the step executor's concern). It
+ * receives an already-resolved locator and an opaque bag of execute options,
+ * and returns the normalized operation response carrying the request that was
+ * actually sent, so `$url` / `$method` / `$request.*` can be evaluated after
+ * execution.
+ * @public
+ */
+class OpenAPIOperationExecutor {
+  #httpClient;
+  #requestInterceptor;
+  #responseNormalizer;
+  #operationExtractor;
+  #operationNormalizer;
+  #documentAssembler;
+  constructor(options = {}) {
+    this.#httpClient = options.httpClient ?? _HTTPClientFetch.default;
+    this.#requestInterceptor = options.requestInterceptor;
+    this.#responseNormalizer = options.responseNormalizer ?? new _OpenAPIOperationResponseNormalizer.default();
+    this.#operationExtractor = options.operationExtractor ?? new _OpenAPIOperationExtractor.default();
+    this.#operationNormalizer = options.operationNormalizer ?? new _OpenAPIOperationNormalizer.default();
+    this.#documentAssembler = options.documentAssembler ?? new _OpenAPIDocumentAssembler.default();
+  }
+
+  /**
+   * Executes the located operation, returning the normalized operation
+   * response.
+   *
+   * `executeOptions` is an opaque bag of `buildRequest` options (e.g. resolved
+   * `parameters`, a `requestBody` and its `requestContentType`, or a `server`).
+   * The operation target always takes precedence over it: the
+   * locator's JSON Pointer selects the operation in the assembled document, so
+   * `operationId`/`operationPath` entries in the bag cannot hijack the
+   * operation.
+   */
+  async execute(locator, executeOptions = {}) {
+    // extraction validates the locator first: a pointer naming anything but an
+    // operation would otherwise crash inside normalization
+    const operation = this.#operationExtractor.extractByPointer(locator.document, locator.jsonPointer);
+    // the legacy id (`{method}-{path}`) matches regardless of an explicit
+    // `operationId` in the assembled document
+    const operationId = (0, _swaggerClient.idFromPathMethodLegacy)((0, _apidomCore.toValue)(operation.meta.get('path')), (0, _apidomCore.toValue)(operation.meta.get('http-method')));
+    const normalizedOperation = await this.#operationNormalizer.normalize(operation, locator.document);
+    const assembled = this.#documentAssembler.assemble(normalizedOperation, locator.document);
+
+    // the interceptor is consumed here, and the target always comes from the
+    // locator, so both operation keys are dropped rather than rest
+    const {
+      requestInterceptor,
+      operationId: _,
+      operationPath: __,
+      ...rest
+    } = executeOptions;
+
+    // each step derives the next options rather than editing in place
+    const withServer = this.#applyServerOptions(rest, normalizedOperation, locator.document);
+    const withBody = this.#adaptRequestBody(withServer, normalizedOperation, locator.document, locator.jsonPointer);
+    const buildOptions = this.#adaptRequestContentType(withBody, normalizedOperation, locator.document, locator.jsonPointer);
+    let request;
+    try {
+      const spec = assembled.toJSON();
+      request = (0, _swaggerClient.buildRequest)({
+        ...buildOptions,
+        spec,
+        operationId
+      });
+    } catch (error) {
+      throw new _ClientError.default('Failed to build request for OpenAPI operation', {
+        operationPath: locator.jsonPointer,
+        cause: error
+      });
+    }
+
+    // a differing value means #adaptRequestContentType swapped the authored
+    // media type for the declared one so the body would attach; the header
+    // still goes out as authored, parameters and all
+    const authoredContentType = executeOptions.requestContentType;
+    if (typeof authoredContentType === 'string' && buildOptions.requestContentType !== authoredContentType) {
+      request.headers['Content-Type'] = authoredContentType;
+    }
+    request = await this.#finalizeRequest(request, requestInterceptor);
+
+    // capture the request as sent, so `$url` / `$method` / `$request.*` can be
+    // evaluated after execution; headers are copied so a transport-side
+    // mutation cannot rewrite the record
+    const requestInfo = {
+      url: request.url,
+      method: request.method,
+      headers: {
+        ...request.headers
+      },
+      body: request.body
+    };
+    let rawResponse;
+    try {
+      rawResponse = await this.#httpClient(request);
+    } catch (error) {
+      throw new _ClientError.default('OpenAPI operation request failed', {
+        operationPath: locator.jsonPointer,
+        cause: error
+      });
+    }
+    return this.#responseNormalizer.normalize(rawResponse, requestInfo);
+  }
+
+  /**
+   * Derives where the request is sent, returning the options to build with.
+   *
+   * swagger-client already selects a declared server, substitutes its variables
+   * and resolves relative URLs — the one thing it gets wrong is what to do with
+   * a `server` matching nothing it declared, which it silently swaps for the
+   * first declared server. Here that value becomes an override instead: the URL
+   * you name is the URL that is called, whatever the document declares. Passing
+   * it as `baseURL` bypasses swagger-client's own server resolution, which also
+   * makes `server` work on Swagger 2.0, where it is otherwise ignored.
+   *
+   * A relative server resolves against the URL the document was loaded from,
+   * which is what `contextUrl` means, so it is derived rather than asked for.
+   * Only an HTTP(S) document URL qualifies. Swagger 2.0 falls back to the
+   * context URL's protocol when the document declares no `schemes`, so a `file:`
+   * URL would yield `file://host/basePath` instead of `http://…`. The registry
+   * normalizes `file:` URIs to bare filesystem paths, which carry no protocol
+   * and are harmless, so this is a guard on the invariant rather than on a
+   * reachable state today. A caller-supplied `contextUrl` still wins, for
+   * resolving against somewhere the document did not come from.
+   */
+  #applyServerOptions(buildOptions, operation, document) {
+    const resolved = buildOptions.contextUrl === undefined && _empty.url.isHttpUrl(document.uri) ? {
+      ...buildOptions,
+      contextUrl: document.uri
+    } : buildOptions;
+    const {
+      server,
+      ...withoutServer
+    } = resolved;
+    if (typeof server !== 'string') return resolved;
+
+    // the operation normalizer has already inherited servers down from the
+    // document root, including the spec's default `[{ url: '/' }]`. spread into
+    // a real array rather than using ArrayElement's own find(), which returns an
+    // empty ArrayElement on a miss — truthy, so every server would look declared.
+    // the members are Server elements, but isObjectElement keeps this one code
+    // path valid for every version: isServerElement is per-namespace, and the
+    // 3.1 one rejects 3.0 servers
+    const servers = operation.get('servers');
+    const declared = (0, _apidomDatamodel.isArrayElement)(servers) ? [...servers] : [];
+    const isDeclared = declared.some(candidate => (0, _apidomDatamodel.isObjectElement)(candidate) && (0, _apidomCore.toValue)(candidate.get('url')) === server);
+    if (isDeclared) return resolved;
+    const baseURL = _empty.url.hasProtocol(server) ? server : _empty.url.resolve(resolved.contextUrl ?? '', server);
+
+    // buildRequest concatenates the base and the path verbatim, so a trailing
+    // slash would double up. swagger-client trims one in its own resolution too
+    return {
+      ...withoutServer,
+      baseURL: baseURL.replace(/\/$/, '')
+    };
+  }
+
+  /**
+   * Reconciles the requested body media type with the ones the operation
+   * declares, returning the options to build with. A rewritten
+   * `requestContentType` is what tells `execute` to restore the authored value
+   * onto the header afterwards.
+   *
+   * swagger-client attaches the body only when `requestContentType` is an exact
+   * key of `requestBody.content`, and otherwise drops the body *and* the header
+   * without a word. Media types are richer than that: they carry optional
+   * parameters and their names are case-insensitive, so the Arazzo
+   * `application/json; charset=utf-8` and `Application/JSON` both name a
+   * declared `application/json`. Both are matched here, the request is built
+   * under the declared spelling, and the authored value is restored onto the
+   * header afterwards. A type naming nothing declared is an authoring error and
+   * is raised rather than turned into an empty request.
+   *
+   * Only OpenAPI 3.x declares media types this way. A Swagger 2.0 operation has
+   * no `requestBody` to check against, so its content type passes through for
+   * `consumes` to govern.
+   */
+  #adaptRequestContentType(buildOptions, operation, document, jsonPointer) {
+    const requested = buildOptions.requestContentType;
+    if (typeof requested !== 'string' || buildOptions.requestBody === undefined) {
+      return buildOptions;
+    }
+    if ((0, _apidomNsOpenapi.isSwaggerElement)(document.parseResult.api)) return buildOptions;
+    const requestBody = operation.get('requestBody');
+    const content = (0, _apidomDatamodel.isObjectElement)(requestBody) ? requestBody.get('content') : undefined;
+    if (!(0, _apidomDatamodel.isObjectElement)(content)) {
+      throw new _ClientError.default(`Request body media type "${requested}" cannot be sent: the operation declares ` + 'no request body content. Omit the content type to send the payload as-is', {
+        operationPath: jsonPointer
+      });
+    }
+    const declared = content.keys();
+    if (declared.includes(requested)) return buildOptions;
+
+    // media type names are case-insensitive and their parameters are not part of
+    // the name, so both are normalized away before matching
+    const baseType = requested.split(';')[0].trim().toLowerCase();
+    const [type] = baseType.split('/');
+    const covers = (mediaType, by) => {
+      const candidate = mediaType.toLowerCase();
+      if (by === 'exact') return candidate === baseType;
+      if (by === 'subtype') return candidate === `${type}/*`;
+      return candidate === '*/*';
+    };
+
+    // a form media type decides how the body is encoded, and buildRequest applies
+    // that encoding only for an exactly declared type. matching one against a
+    // range would put a JSON body behind a form Content-Type
+    const isFormEncoded = baseType === 'application/x-www-form-urlencoded' || baseType === 'multipart/form-data';
+
+    // otherwise a declared range covers a concrete type, so `*/*` (what several
+    // generators emit by default) accepts anything; the most specific wins
+    const exact = declared.find(mediaType => covers(mediaType, 'exact'));
+    const match = exact ?? (isFormEncoded ? undefined : declared.find(mediaType => covers(mediaType, 'subtype')) ?? declared.find(mediaType => covers(mediaType, 'any')));
+    if (match === undefined) {
+      throw new _ClientError.default(isFormEncoded ? `Request body media type "${requested}" must be declared by the operation exactly, ` + `since it decides how the body is encoded (declared: [${declared.join(', ')}])` : `Request body media type "${requested}" is not declared by the operation ` + `(declared: [${declared.join(', ')}])`, {
+        operationPath: jsonPointer
+      });
+    }
+    return {
+      ...buildOptions,
+      requestContentType: match
+    };
+  }
+
+  /**
+   * Routes a request body through the convention the target OpenAPI version
+   * uses, leaving OpenAPI 3.x calls untouched.
+   *
+   * Swagger 2.0 has no request body concept — the payload is an ordinary
+   * parameter declared `in: body`, or a set of `in: formData` ones — so it must
+   * travel through `parameters` under the names the operation declares. Arazzo
+   * cannot express that itself (its parameter `in` allows only `path`, `query`,
+   * `querystring`, `header`, and `cookie`), which is why the translation lives
+   * here, where the assembled document has those parameters dereferenced and
+   * inherited.
+   *
+   * The payload travels under {@link ParameterDelivery} keys
+   * (`body.{name}`, `formData.{name}`), never bare names: a bare key would
+   * capture a same-named parameter in another location — 2.0 legally declares
+   * e.g. `petId` in `path` and in `formData` at once — per the lookup order
+   * documented on {@link ParameterDelivery}.
+   *
+   * A *bare* `parameters` entry bearing a payload target's name is rejected
+   * with {@link ClientError} rather than resolved either way: before the
+   * qualified keys the payload silently overwrote it, after them the bare key
+   * would silently outrank the payload at the client's bare-first lookup —
+   * both wrong for somebody, so the ambiguity is reported instead. Such an
+   * entry can come from a direct caller mixing bare parameters with a request
+   * body, or from the runner's own pipeline: the parameter resolver keeps a
+   * `querystring` parameter under its bare name.
+   */
+  #adaptRequestBody(buildOptions, operation, document, jsonPointer) {
+    if (!(0, _apidomNsOpenapi.isSwaggerElement)(document.parseResult.api) || buildOptions.requestBody === undefined) {
+      return buildOptions;
+    }
+    const {
+      requestBody,
+      parameters: given,
+      ...rest
+    } = buildOptions;
+    const callerParameters = given;
+    // an operation declaring none leaves `parameters` absent rather than empty,
+    // and that case still has to reach the throw below
+    const declared = operation.parameters;
+    const parameters = (0, _apidomDatamodel.isArrayElement)(declared) ? [...declared.filter(_apidomNsOpenapi.isParameterElement)] : [];
+
+    // the body parameter's name is arbitrary, so the payload wins over a
+    // same-keyed entry the caller supplied
+    const body = parameters.find(parameter => (0, _apidomCore.toValue)(parameter.in) === 'body');
+    if (body !== undefined) {
+      const name = (0, _apidomCore.toValue)(body.name);
+      this.#rejectBarePayloadConflicts(callerParameters, [name], jsonPointer);
+      return {
+        ...rest,
+        parameters: {
+          ...callerParameters,
+          [_ParameterDelivery.default.keyFor('body', name)]: requestBody
+        }
+      };
+    }
+
+    // formData models each field as its own parameter, so the payload's keys
+    // are the parameter names; buildRequest reports any that do not match
+    const hasForm = parameters.some(parameter => (0, _apidomCore.toValue)(parameter.in) === 'formData');
+    if (hasForm) {
+      if (!(0, _ramdaAdjunct.isPlainObject)(requestBody)) {
+        throw new _ClientError.default('Request body cannot be sent: the OpenAPI 2.0 operation carries it in "formData" ' + 'parameters, so the payload must be an object keyed by their names', {
+          operationPath: jsonPointer
+        });
+      }
+      const payload = requestBody;
+      this.#rejectBarePayloadConflicts(callerParameters, Object.keys(payload), jsonPointer);
+      const merged = {
+        ...callerParameters
+      };
+      for (const [field, value] of Object.entries(payload)) {
+        merged[_ParameterDelivery.default.keyFor('formData', field)] = value;
+      }
+      return {
+        ...rest,
+        parameters: merged
+      };
+    }
+    throw new _ClientError.default('Request body cannot be sent: the OpenAPI 2.0 operation declares no "body" or ' + '"formData" parameter to carry it', {
+      operationPath: jsonPointer
+    });
+  }
+
+  /**
+   * Rejects bare `parameters` entries bearing the names the payload is about
+   * to be delivered under — the client consults bare names before qualified
+   * keys, so such an entry would silently displace the request body (see
+   * {@link OpenAPIOperationExecutor.#adaptRequestBody}).
+   */
+  #rejectBarePayloadConflicts(callerParameters, payloadNames, jsonPointer) {
+    if (callerParameters === undefined) return;
+    const conflicts = payloadNames.filter(name => Object.hasOwn(callerParameters, name));
+    if (conflicts.length === 0) return;
+    throw new _ClientError.default(`Request body cannot be sent: bare parameter ${conflicts.length === 1 ? 'entry' : 'entries'} ` + `[${conflicts.join(', ')}] would displace the payload at delivery. Supply the ` + `parameter under its "{in}.{name}" key, or drop the duplicate`, {
+      operationPath: jsonPointer
+    });
+  }
+
+  /**
+   * Applies the wire-level fixups swagger-client performs between building a
+   * request and fetching it, and runs the request interceptors: the
+   * executor-level one first, the per-call one from the options bag second.
+   *
+   * Ported rather than imported: upstream keeps them inline in `execute()` and
+   * `http()`, which also fetch and throw on a non-2xx. Diff against those two
+   * when bumping swagger-client.
+   */
+  async #finalizeRequest(request, perCallInterceptor) {
+    let finalized = request;
+
+    // JSON-encode plain-object and array bodies, exactly as swagger-client's
+    // execute() does before handing the request to its transport
+    if (finalized.body && ((0, _ramdaAdjunct.isPlainObject)(finalized.body) || Array.isArray(finalized.body))) {
+      finalized.body = JSON.stringify(finalized.body);
+    }
+
+    // an embedded newline makes a header value invalid per the Fetch standard,
+    // so fetch throws a TypeError before sending anything. squashing repairs it,
+    // and since the request is captured after this, the record shows the value
+    // that actually went out
+    Object.keys(finalized.headers).forEach(headerName => {
+      const value = finalized.headers[headerName];
+      if (typeof value === 'string') {
+        finalized.headers[headerName] = value.replace(/\n+/g, ' ');
+      }
+    });
+    finalized = (await this.#requestInterceptor?.(finalized)) ?? finalized;
+    finalized = (await perCallInterceptor?.(finalized)) ?? finalized;
+
+    // for multipart/form-data, remove the built content-type so the transport
+    // sets one carrying the correct boundary
+    const contentType = finalized.headers['content-type'] ?? finalized.headers['Content-Type'];
+    if (typeof contentType === 'string' && /multipart\/form-data/i.test(contentType)) {
+      delete finalized.headers['content-type'];
+      delete finalized.headers['Content-Type'];
+    }
+    return finalized;
+  }
+}
+var _default = exports.default = OpenAPIOperationExecutor;