@usearazzo/runner 1.0.1-alpha.11 → 1.0.1-alpha.13

package/src/executor/OpenAPIOperationExecutor.mjs

@@ -2,6 +2,7 @@ import { toValue } from '@speclynx/apidom-core';
 import { isArrayElement, isObjectElement } from '@speclynx/apidom-datamodel';
 import { url as urlUtils } from '@speclynx/apidom-reference/configuration/empty';
 import { isSwaggerElement, isParameterElement } from '@speclynx/apidom-ns-openapi-2';
+import { serializeCookie, cookieNameLenientValidator, cookieValueStrictPercentEncoder } from '@swaggerexpert/cookie';
 import { identify, matches, selectBestMatch } from '@swaggerexpert/media-types';
 import { isPlainObject } from 'ramda-adjunct';
 
@@ -22,6 +23,19 @@ import ClientError from "../errors/ClientError.mjs";
  * May be synchronous or asynchronous.
  * @public
  */
+/**
+ * The plain-JSON shape of the assembled document, as far as declaring a
+ * parameter on its one operation needs it.
+ */
+/**
+ * A caller-supplied parameter the operation does not declare, in a location
+ * it can still be delivered to.
+ */
+const UNDECLARED_LOCATIONS = new Set(['header', 'query', 'cookie', 'path']);
+
+// the header parameters OpenAPI 3 says SHALL be ignored, which buildRequest drops
+const IGNORED_HEADERS = new Set(['accept', 'authorization', 'content-type']);
+
 /**
  * Options for executing an OpenAPI operation.
  *
@@ -39,6 +53,7 @@ import ClientError from "../errors/ClientError.mjs";
  * {@link RequestInterceptor}.
  * @public
  */
+
 /**
  * The execute options forwarded to {@link OpenAPIOperationExecutor.execute}.
  *
@@ -61,10 +76,12 @@ import ClientError from "../errors/ClientError.mjs";
  * `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}.
@@ -137,9 +154,11 @@ class OpenAPIOperationExecutor {
     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);
+    const undeclared = this.#undeclaredParameters(buildOptions.parameters, normalizedOperation);
+    const spec = assembled.toJSON();
+    this.#declareQueryAndPathParameters(spec, undeclared, toValue(operation.meta.get('path')), toValue(operation.meta.get('http-method')), locator);
     let request;
     try {
-      const spec = assembled.toJSON();
       request = buildRequest({
         ...buildOptions,
         spec,
@@ -159,6 +178,7 @@ class OpenAPIOperationExecutor {
     if (typeof authoredContentType === 'string' && buildOptions.requestContentType !== authoredContentType) {
       request.headers['Content-Type'] = authoredContentType;
     }
+    this.#deliverHeadersAndCookies(request, undeclared);
     request = await this.#finalizeRequest(request, requestInterceptor);
 
     // capture the request as sent, so `$url` / `$method` / `$request.*` can be
@@ -184,6 +204,130 @@ class OpenAPIOperationExecutor {
     return this.#responseNormalizer.normalize(rawResponse, requestInfo);
   }
 
+  /**
+   * The `{in}.{name}`-keyed parameters (see {@link ParameterDelivery}) in a
+   * header, query, cookie or path location that the operation does not
+   * declare. `buildRequest` delivers only what the operation declares, yet a
+   * step's parameters are what its author asked to send — an `Authorization`
+   * header carrying a token from an earlier step most of all, which OpenAPI 3
+   * cannot even declare. A declared `Accept`, `Authorization` or
+   * `Content-Type` header parameter counts as undeclared too: `buildRequest`
+   * drops it for OpenAPI 3, as that specification requires, and for 2.0
+   * delivering it here sends the same value. Bare keys are left to
+   * `buildRequest`: they name no location to deliver to.
+   */
+  #undeclaredParameters(parameters, operation) {
+    if (!isPlainObject(parameters)) return [];
+    const declared = new Set((isArrayElement(operation.parameters) ? [...operation.parameters] : []).filter(isObjectElement).map(parameter => `${toValue(parameter.get('in'))}.${toValue(parameter.get('name'))}`));
+    return Object.entries(parameters).flatMap(([key, value]) => {
+      const separator = key.indexOf('.');
+      const location = key.slice(0, separator);
+      const name = key.slice(separator + 1);
+      // an unresolved expression or a null delivers nothing, as buildRequest
+      // does for a declared parameter
+      if (separator === -1 || !UNDECLARED_LOCATIONS.has(location) || value === undefined || value === null) {
+        return [];
+      }
+      const ignored = location === 'header' && IGNORED_HEADERS.has(name.toLowerCase());
+      return declared.has(key) && !ignored ? [] : [{
+        location,
+        name,
+        value
+      }];
+    });
+  }
+
+  /**
+   * Declares the undeclared query and path parameters on the assembled
+   * operation, so `buildRequest` serializes and encodes them as it does
+   * declared ones. A path parameter is declared only when the path has its
+   * `{name}` template expression; otherwise there is nowhere to put it, and
+   * that authoring error throws {@link ClientError} rather than sending a
+   * request without it.
+   */
+  #declareQueryAndPathParameters(spec, undeclared, path, method, locator) {
+    const operation = spec.paths[path][method];
+    const isSwagger = isSwaggerElement(locator.document.parseResult.api);
+    for (const {
+      location,
+      name
+    } of undeclared) {
+      if (location !== 'query' && location !== 'path') continue;
+      if (location === 'path' && !path.includes(`{${name}}`)) {
+        throw new ClientError(`Path parameter "${name}" is not declared by the operation and its path "${path}" ` + `has no "{${name}}" to substitute it into`, {
+          operationPath: locator.jsonPointer
+        });
+      }
+      const required = location === 'path';
+      (operation.parameters ??= []).push(isSwagger ? {
+        name,
+        in: location,
+        required,
+        type: 'string'
+      } : {
+        name,
+        in: location,
+        required,
+        schema: {}
+      });
+    }
+  }
+
+  /**
+   * Sets the undeclared header parameters on the built request and appends the
+   * undeclared cookie parameters to its `Cookie` header. A header replaces any
+   * value the build gave it under any spelling — the default `Accept`, say —
+   * since the step naming it is the more specific intent. OpenAPI 2.0 has no
+   * cookie location, so its cookies always go this way.
+   */
+  #deliverHeadersAndCookies(request, undeclared) {
+    const present = name => Object.keys(request.headers).find(header => header.toLowerCase() === name.toLowerCase());
+    for (const {
+      location,
+      name,
+      value
+    } of undeclared) {
+      if (location !== 'header') continue;
+      const built = present(name);
+      if (built !== undefined) delete request.headers[built];
+      request.headers[name] = this.#stringify(value);
+    }
+    const cookies = undeclared.filter(({
+      location
+    }) => location === 'cookie').map(({
+      name,
+      value
+    }) => [name, this.#stringify(value)]);
+    if (cookies.length === 0) return;
+    // serialized as buildRequest serializes a declared cookie, so a `;` in the
+    // value is percent-encoded rather than splitting it into further cookies
+    const serialized = serializeCookie(cookies, {
+      encoders: {
+        value: cookieValueStrictPercentEncoder
+      },
+      validators: {
+        name: cookieNameLenientValidator
+      }
+    });
+    const cookieHeader = present('Cookie') ?? 'Cookie';
+    const existing = request.headers[cookieHeader];
+    request.headers[cookieHeader] = existing ? `${existing}; ${serialized}` : serialized;
+  }
+
+  /**
+   * A header or cookie value with no schema to serialize it by, the way
+   * OpenAPI's default for those locations (`simple` and `form`, not exploded)
+   * serializes a declared one: an array as `a,b`, an object as `k,v,k2,v2`,
+   * anything else via `String()`.
+   */
+  #stringify(value) {
+    if (Array.isArray(value)) return value.map(String).join(',');
+    if (typeof value === 'object' && value !== null) {
+      return Object.entries(value).flat().map(String).join(',');
+    }
+    return String(value);
+  }
+
   /**
    * Derives where the request is sent, returning the options to build with.
    *

package/types/runner.d.ts

@@ -1261,15 +1261,23 @@ export declare interface OpenAPIOperationRequestInfo {
 
 /**
  * Response from an OpenAPI operation execution.
+ *
+ * `body` is the payload parsed by its content type, what `$response.body`
+ * reads. The body as received is read through `text()`, `blob()` and
+ * `bytes()`, named after the WHATWG `Response` methods but synchronous, and
+ * empty when the response carried no body (e.g. `204`, `304`). `bytes()` and
+ * `blob()` always return the bytes received. A body that is valid UTF-8 is held
+ * as its decoded string, which a plain-text or XML `body` shares rather than
+ * duplicates, and is encoded back on read; any other body is held as bytes.
  * @public
  */
 export declare class OpenAPIOperationResponse {
+    #private;
     readonly ok: boolean;
     readonly url: string;
     readonly status: number;
     readonly statusText: string;
     readonly headers: Record<string, string>;
-    readonly text: string;
     readonly body: unknown;
     readonly request: OpenAPIOperationRequestInfo | undefined;
     constructor(raw: {
@@ -1278,10 +1286,24 @@ export declare class OpenAPIOperationResponse {
         status: number;
         statusText: string;
         headers: Record<string, string>;
-        text: string;
         body: unknown;
+        content: string | Uint8Array;
         request?: OpenAPIOperationRequestInfo;
     });
+    /**
+     * The body as text, like `Response.text()`; `''` when there is none.
+     */
+    text(): string;
+    /**
+     * The body as a `Blob` typed by the response's `Content-Type`, like
+     * `Response.blob()`.
+     */
+    blob(): Blob;
+    /**
+     * The body as bytes, like `Response.bytes()`; a fresh copy on every call, so
+     * the response stays immutable.
+     */
+    bytes(): Uint8Array;
 }
 
 /**
@@ -1295,10 +1317,15 @@ export declare class OpenAPIOperationResponse {
  * Headers are taken from the `Response` directly rather than from the
  * deserializer, which splits every value containing `", "` into an array:
  * values stay strings as sent, with repeated fields (`Set-Cookie` included)
- * combined by `Headers.get`.
+ * combined by `Headers.get`. The body is read once, as bytes, and handed to the
+ * deserializer from memory. A body that decodes as UTF-8 without loss is kept
+ * as that one string, the same one the deserializer parses, so a plain-text or
+ * XML `body` shares it; any other body (binary, another charset, a leading
+ * byte-order mark) is kept as the bytes, so they are never re-encoded lossily.
  * @public
  */
 export declare class OpenAPIOperationResponseNormalizer {
+    #private;
     /**
      * Deserializes the response body by content type and maps the result into the
      * runner's response model. `request` is the request the operation was