@usearazzo/runner 1.0.1-alpha.12 → 1.0.1-alpha.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usearazzo/runner",
-  "version": "1.0.1-alpha.12",
+  "version": "1.0.1-alpha.14",
   "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.12",
-    "@usearazzo/resolver": "1.0.1-alpha.12",
+    "@usearazzo/parser": "1.0.1-alpha.14",
+    "@usearazzo/resolver": "1.0.1-alpha.14",
     "@xmldom/xmldom": "^0.9.12",
     "fontoxpath": "^3.34.0",
     "ramda": "^0.32.0",
@@ -93,5 +94,5 @@
   "devDependencies": {
     "swagger-client": "^3.38.4"
   },
-  "gitHead": "cc5d9b2fb744662650068a5993ebcdd19e8568c2"
+  "gitHead": "40a494596c0eed2f984fb87f544f3cf69488a6a7"
 }

package/src/document/ParameterIdentity.cjs

@@ -75,6 +75,14 @@ class ParameterIdentity {
     if (location === undefined || (0, _apidomDatamodel.isNullElement)(location)) return undefined;
     return (0, _apidomDatamodel.isStringElement)(location) ? (0, _apidomCore.toValue)(location) : null;
   }
+
+  /**
+   * The locations the Parameter Object defines: Arazzo 1.0.1's closed set plus
+   * 1.1.0's `querystring`. 1.0.0's field description also listed `body`, which
+   * its own summary of locations did not; 1.0.1 removed it as an erratum, so it
+   * is not a location in any version (a payload is the step's `requestBody`).
+   */
+  static LOCATIONS = ['path', 'query', 'header', 'cookie', 'querystring'];
   name;
   location;
   constructor(name, location) {
@@ -82,6 +90,14 @@ class ParameterIdentity {
     this.location = location;
   }
 
+  /**
+   * Whether the location is one the Parameter Object defines. An absent or
+   * malformed location is not.
+   */
+  get hasDefinedLocation() {
+    return ParameterIdentity.LOCATIONS.includes(this.location);
+  }
+
   /**
    * Whether this and the other identity name the same parameter. A malformed
    * location equals nothing, its own duplicate included.

package/src/document/ParameterIdentity.mjs

@@ -70,6 +70,14 @@ class ParameterIdentity {
     if (location === undefined || isNullElement(location)) return undefined;
     return isStringElement(location) ? toValue(location) : null;
   }
+
+  /**
+   * The locations the Parameter Object defines: Arazzo 1.0.1's closed set plus
+   * 1.1.0's `querystring`. 1.0.0's field description also listed `body`, which
+   * its own summary of locations did not; 1.0.1 removed it as an erratum, so it
+   * is not a location in any version (a payload is the step's `requestBody`).
+   */
+  static LOCATIONS = ['path', 'query', 'header', 'cookie', 'querystring'];
   name;
   location;
   constructor(name, location) {
@@ -77,6 +85,14 @@ class ParameterIdentity {
     this.location = location;
   }
 
+  /**
+   * Whether the location is one the Parameter Object defines. An absent or
+   * malformed location is not.
+   */
+  get hasDefinedLocation() {
+    return ParameterIdentity.LOCATIONS.includes(this.location);
+  }
+
   /**
    * Whether this and the other identity name the same parameter. A malformed
    * location equals nothing, its own duplicate included.

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.
    *

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/src/resolver/OpenAPIOperationParameterResolver.cjs

@@ -35,7 +35,11 @@ var _StepParameterResolver = _interopRequireDefault(require("./StepParameterReso
  * instead would let it capture *every* declared location of that name — see
  * `ParameterDelivery` for the lookup order that makes it so. A
  * non-string location throws for the same reason it deduplicates with nothing
- * in the normalizer: it names no location. And two *different* parameters the
+ * in the normalizer: it names no location. So does a location outside
+ * `path`, `query`, `header`, `cookie` and `querystring`: Arazzo 1.0.1 removed
+ * `in: body`, and forwarding one would let it still deliver a request body
+ * against an OpenAPI 2.0 operation, bypassing the step's `requestBody`, while
+ * an unknown location reaches nothing at all. And two *different* parameters the
  * map reports as colliding cannot both be delivered, so a collision throws
  * rather than silently dropping one — whether they collide on one key (the
  * scheme is not injective: a `querystring` parameter named `header.token` and
@@ -96,6 +100,13 @@ class OpenAPIOperationParameterResolver extends _StepParameterResolver.default {
           reason: 'malformed-location'
         });
       }
+      if (!identity.hasDefinedLocation) {
+        throw new _ResolverError.default(`Parameter "${name}" has location "${location}", which is not one of ` + `${_ParameterIdentity.default.LOCATIONS.join(', ')}`, {
+          ...scope,
+          target: name,
+          reason: 'invalid-location'
+        });
+      }
       const {
         key,
         outcome

package/src/resolver/OpenAPIOperationParameterResolver.mjs

@@ -28,7 +28,11 @@ import StepParameterResolver from "./StepParameterResolver.mjs";
  * instead would let it capture *every* declared location of that name — see
  * `ParameterDelivery` for the lookup order that makes it so. A
  * non-string location throws for the same reason it deduplicates with nothing
- * in the normalizer: it names no location. And two *different* parameters the
+ * in the normalizer: it names no location. So does a location outside
+ * `path`, `query`, `header`, `cookie` and `querystring`: Arazzo 1.0.1 removed
+ * `in: body`, and forwarding one would let it still deliver a request body
+ * against an OpenAPI 2.0 operation, bypassing the step's `requestBody`, while
+ * an unknown location reaches nothing at all. And two *different* parameters the
  * map reports as colliding cannot both be delivered, so a collision throws
  * rather than silently dropping one — whether they collide on one key (the
  * scheme is not injective: a `querystring` parameter named `header.token` and
@@ -89,6 +93,13 @@ class OpenAPIOperationParameterResolver extends StepParameterResolver {
           reason: 'malformed-location'
         });
       }
+      if (!identity.hasDefinedLocation) {
+        throw new ResolverError(`Parameter "${name}" has location "${location}", which is not one of ` + `${ParameterIdentity.LOCATIONS.join(', ')}`, {
+          ...scope,
+          target: name,
+          reason: 'invalid-location'
+        });
+      }
       const {
         key,
         outcome

package/types/runner.d.ts

@@ -1196,7 +1196,11 @@ export declare interface OpenAPIOperationNormalizerOptions {
  * instead would let it capture *every* declared location of that name — see
  * `ParameterDelivery` for the lookup order that makes it so. A
  * non-string location throws for the same reason it deduplicates with nothing
- * in the normalizer: it names no location. And two *different* parameters the
+ * in the normalizer: it names no location. So does a location outside
+ * `path`, `query`, `header`, `cookie` and `querystring`: Arazzo 1.0.1 removed
+ * `in: body`, and forwarding one would let it still deliver a request body
+ * against an OpenAPI 2.0 operation, bypassing the step's `requestBody`, while
+ * an unknown location reaches nothing at all. And two *different* parameters the
  * map reports as colliding cannot both be delivered, so a collision throws
  * rather than silently dropping one — whether they collide on one key (the
  * scheme is not injective: a `querystring` parameter named `header.token` and