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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usearazzo/runner",
-  "version": "1.0.1-alpha.11",
+  "version": "1.0.1-alpha.13",
   "description": "Runner for Arazzo Workflows.",
   "keywords": [
     "arazzo",
@@ -69,11 +69,12 @@
     "@speclynx/apidom-traverse": "^6.1.0",
     "@swaggerexpert/arazzo-criterion": "^1.0.1",
     "@swaggerexpert/arazzo-runtime-expression": "^3.3.0",
+    "@swaggerexpert/cookie": "^2.0.2",
     "@swaggerexpert/json-pointer": "^3.0.2",
     "@swaggerexpert/jsonpath": "^4.0.5",
     "@swaggerexpert/media-types": "^1.0.1",
-    "@usearazzo/parser": "1.0.1-alpha.11",
-    "@usearazzo/resolver": "1.0.1-alpha.11",
+    "@usearazzo/parser": "1.0.1-alpha.13",
+    "@usearazzo/resolver": "1.0.1-alpha.13",
     "@xmldom/xmldom": "^0.9.12",
     "fontoxpath": "^3.34.0",
     "ramda": "^0.32.0",
@@ -93,5 +94,5 @@
   "devDependencies": {
     "swagger-client": "^3.38.4"
   },
-  "gitHead": "3cfffaf0045eff162d73df30f840c35cc593af77"
+  "gitHead": "41c018418a867e1469de0b2393929f7ec129c447"
 }

package/src/client/OpenAPIOperationResponse.cjs

@@ -17,6 +17,14 @@ exports.default = void 0;
 
 /**
  * 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
  */
 class OpenAPIOperationResponse {
@@ -25,18 +33,45 @@ class OpenAPIOperationResponse {
   status;
   statusText;
   headers;
-  text;
   body;
   request;
+  #content;
   constructor(raw) {
     this.ok = raw.ok;
     this.url = raw.url;
     this.status = raw.status;
     this.statusText = raw.statusText;
     this.headers = raw.headers;
-    this.text = raw.text;
     this.body = raw.body;
+    this.#content = raw.content;
     this.request = raw.request;
   }
+
+  /**
+   * The body as text, like `Response.text()`; `''` when there is none.
+   */
+  text() {
+    return typeof this.#content === 'string' ? this.#content : new TextDecoder().decode(this.#content);
+  }
+
+  /**
+   * The body as a `Blob` typed by the response's `Content-Type`, like
+   * `Response.blob()`.
+   */
+  blob() {
+    // the lib types only take ArrayBuffer-backed views; the normalizer never
+    // produces a shared one.
+    return new Blob([this.#content], {
+      type: this.headers['content-type'] ?? ''
+    });
+  }
+
+  /**
+   * The body as bytes, like `Response.bytes()`; a fresh copy on every call, so
+   * the response stays immutable.
+   */
+  bytes() {
+    return typeof this.#content === 'string' ? new TextEncoder().encode(this.#content) : this.#content.slice();
+  }
 }
 var _default = exports.default = OpenAPIOperationResponse;

package/src/client/OpenAPIOperationResponse.mjs

@@ -11,6 +11,14 @@
 
 /**
  * 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
  */
 class OpenAPIOperationResponse {
@@ -19,18 +27,45 @@ class OpenAPIOperationResponse {
   status;
   statusText;
   headers;
-  text;
   body;
   request;
+  #content;
   constructor(raw) {
     this.ok = raw.ok;
     this.url = raw.url;
     this.status = raw.status;
     this.statusText = raw.statusText;
     this.headers = raw.headers;
-    this.text = raw.text;
     this.body = raw.body;
+    this.#content = raw.content;
     this.request = raw.request;
   }
+
+  /**
+   * The body as text, like `Response.text()`; `''` when there is none.
+   */
+  text() {
+    return typeof this.#content === 'string' ? this.#content : new TextDecoder().decode(this.#content);
+  }
+
+  /**
+   * The body as a `Blob` typed by the response's `Content-Type`, like
+   * `Response.blob()`.
+   */
+  blob() {
+    // the lib types only take ArrayBuffer-backed views; the normalizer never
+    // produces a shared one.
+    return new Blob([this.#content], {
+      type: this.headers['content-type'] ?? ''
+    });
+  }
+
+  /**
+   * The body as bytes, like `Response.bytes()`; a fresh copy on every call, so
+   * the response stays immutable.
+   */
+  bytes() {
+    return typeof this.#content === 'string' ? new TextEncoder().encode(this.#content) : this.#content.slice();
+  }
 }
 export default OpenAPIOperationResponse;

package/src/client/OpenAPIOperationResponseNormalizer.cjs

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
+var _mediaTypes = require("@swaggerexpert/media-types");
 var _swaggerClient = require("../vendor/swagger-client.cjs");
 var _OpenAPIOperationResponse = _interopRequireDefault(require("./OpenAPIOperationResponse.cjs"));
 // @ts-expect-error vendored swagger-client bundle has no type declarations
@@ -20,7 +21,11 @@ var _OpenAPIOperationResponse = _interopRequireDefault(require("./OpenAPIOperati
  * 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
  */
 class OpenAPIOperationResponseNormalizer {
@@ -31,7 +36,30 @@ class OpenAPIOperationResponseNormalizer {
    * carries none (e.g. a stubbed transport).
    */
   async normalize(response, request) {
-    const deserialized = await (0, _swaggerClient.deserializeResponse)(response, request?.url);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const text = this.#decodeLosslessly(bytes);
+    // the deserializer matches the raw Content-Type case-sensitively and against
+    // its parameters too, so it is handed only the parsed essence; the response's
+    // own `headers` below stay as sent.
+    const deserializerHeaders = new Headers(response.headers);
+    const contentType = response.headers.get('content-type');
+    const mediaType = contentType === null ? undefined : (0, _mediaTypes.parse)(contentType, {
+      type: 'media-type'
+    }).tree;
+    if (mediaType !== undefined) {
+      deserializerHeaders.set('content-type', `${mediaType.type}/${mediaType.subtype}`);
+    }
+    // the deserializer only reads the body through text() or blob(), by content
+    // type; answering from memory spares a second copy of the stream.
+    const deserialized = await (0, _swaggerClient.deserializeResponse)({
+      ok: response.ok,
+      url: response.url,
+      status: response.status,
+      statusText: response.statusText,
+      headers: deserializerHeaders,
+      text: async () => text ?? new TextDecoder().decode(bytes),
+      blob: async () => new Blob([bytes])
+    }, request?.url);
     const headers = Object.fromEntries(Array.from(response.headers.keys(), name => [name, response.headers.get(name)]));
     return new _OpenAPIOperationResponse.default({
       ok: deserialized.ok,
@@ -39,10 +67,26 @@ class OpenAPIOperationResponseNormalizer {
       status: deserialized.status,
       statusText: deserialized.statusText,
       headers,
-      text: deserialized.text,
       body: deserialized.body,
+      content: text ?? bytes,
       request
     });
   }
+
+  /**
+   * The bytes as a string that encodes back to exactly them, or `undefined`
+   * when there is none: invalid UTF-8, or a leading byte-order mark, which
+   * decoding strips.
+   */
+  #decodeLosslessly(bytes) {
+    if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return undefined;
+    try {
+      return new TextDecoder('utf-8', {
+        fatal: true
+      }).decode(bytes);
+    } catch {
+      return undefined;
+    }
+  }
 }
 var _default = exports.default = OpenAPIOperationResponseNormalizer;

package/src/client/OpenAPIOperationResponseNormalizer.mjs

@@ -1,3 +1,5 @@
+import { parse } from '@swaggerexpert/media-types';
+
 // @ts-expect-error vendored swagger-client bundle has no type declarations
 import { deserializeResponse } from '../vendor/swagger-client.mjs';
 import OpenAPIOperationResponse from "./OpenAPIOperationResponse.mjs";
@@ -12,7 +14,11 @@ import OpenAPIOperationResponse from "./OpenAPIOperationResponse.mjs";
  * 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
  */
 class OpenAPIOperationResponseNormalizer {
@@ -23,7 +29,30 @@ class OpenAPIOperationResponseNormalizer {
    * carries none (e.g. a stubbed transport).
    */
   async normalize(response, request) {
-    const deserialized = await deserializeResponse(response, request?.url);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const text = this.#decodeLosslessly(bytes);
+    // the deserializer matches the raw Content-Type case-sensitively and against
+    // its parameters too, so it is handed only the parsed essence; the response's
+    // own `headers` below stay as sent.
+    const deserializerHeaders = new Headers(response.headers);
+    const contentType = response.headers.get('content-type');
+    const mediaType = contentType === null ? undefined : parse(contentType, {
+      type: 'media-type'
+    }).tree;
+    if (mediaType !== undefined) {
+      deserializerHeaders.set('content-type', `${mediaType.type}/${mediaType.subtype}`);
+    }
+    // the deserializer only reads the body through text() or blob(), by content
+    // type; answering from memory spares a second copy of the stream.
+    const deserialized = await deserializeResponse({
+      ok: response.ok,
+      url: response.url,
+      status: response.status,
+      statusText: response.statusText,
+      headers: deserializerHeaders,
+      text: async () => text ?? new TextDecoder().decode(bytes),
+      blob: async () => new Blob([bytes])
+    }, request?.url);
     const headers = Object.fromEntries(Array.from(response.headers.keys(), name => [name, response.headers.get(name)]));
     return new OpenAPIOperationResponse({
       ok: deserialized.ok,
@@ -31,10 +60,26 @@ class OpenAPIOperationResponseNormalizer {
       status: deserialized.status,
       statusText: deserialized.statusText,
       headers,
-      text: deserialized.text,
       body: deserialized.body,
+      content: text ?? bytes,
       request
     });
   }
+
+  /**
+   * The bytes as a string that encodes back to exactly them, or `undefined`
+   * when there is none: invalid UTF-8, or a leading byte-order mark, which
+   * decoding strips.
+   */
+  #decodeLosslessly(bytes) {
+    if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return undefined;
+    try {
+      return new TextDecoder('utf-8', {
+        fatal: true
+      }).decode(bytes);
+    } catch {
+      return undefined;
+    }
+  }
 }
 export default OpenAPIOperationResponseNormalizer;

package/src/executor/OpenAPIOperationExecutor.cjs

@@ -9,6 +9,7 @@ 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 _cookie = require("@swaggerexpert/cookie");
 var _mediaTypes = require("@swaggerexpert/media-types");
 var _ramdaAdjunct = require("ramda-adjunct");
 var _swaggerClient = require("../vendor/swagger-client.cjs");
@@ -30,6 +31,21 @@ var _ClientError = _interopRequireDefault(require("../errors/ClientError.cjs"));
  * @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.
  *
@@ -148,9 +164,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, (0, _apidomCore.toValue)(operation.meta.get('path')), (0, _apidomCore.toValue)(operation.meta.get('http-method')), locator);
     let request;
     try {
-      const spec = assembled.toJSON();
       request = (0, _swaggerClient.buildRequest)({
         ...buildOptions,
         spec,
@@ -170,6 +188,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
@@ -195,6 +214,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 (!(0, _ramdaAdjunct.isPlainObject)(parameters)) return [];
+    const declared = new Set(((0, _apidomDatamodel.isArrayElement)(operation.parameters) ? [...operation.parameters] : []).filter(_apidomDatamodel.isObjectElement).map(parameter => `${(0, _apidomCore.toValue)(parameter.get('in'))}.${(0, _apidomCore.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 = (0, _apidomNsOpenapi.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.default(`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 = (0, _cookie.serializeCookie)(cookies, {
+      encoders: {
+        value: _cookie.cookieValueStrictPercentEncoder
+      },
+      validators: {
+        name: _cookie.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.
    *