@usearazzo/runner 1.0.1-alpha.16 → 1.0.1-alpha.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usearazzo/runner",
-  "version": "1.0.1-alpha.16",
+  "version": "1.0.1-alpha.18",
   "description": "Runner for Arazzo Workflows.",
   "keywords": [
     "arazzo",
@@ -56,7 +56,7 @@
   "author": "Vladimir Gorej <vladimir.gorej@gmail.com>",
   "license": "Apache-2.0",
   "dependencies": {
-    "@babel/runtime-corejs3": "^8.0.7",
+    "@babel/runtime-corejs3": "^8.0.8",
     "@speclynx/apidom-core": "^6.1.0",
     "@speclynx/apidom-datamodel": "^6.1.0",
     "@speclynx/apidom-error": "^6.1.0",
@@ -72,9 +72,9 @@
     "@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.16",
-    "@usearazzo/resolver": "1.0.1-alpha.16",
+    "@swaggerexpert/media-types": "^1.0.2",
+    "@usearazzo/parser": "1.0.1-alpha.18",
+    "@usearazzo/resolver": "1.0.1-alpha.18",
     "@xmldom/xmldom": "^0.9.12",
     "fontoxpath": "^3.34.0",
     "ramda": "^0.32.0",
@@ -94,5 +94,5 @@
   "devDependencies": {
     "swagger-client": "^3.38.4"
   },
-  "gitHead": "9ff2a68d209a5d178658f9a568c2d136178d40b8"
+  "gitHead": "29cba37b82d02fa4b11e7d8acf3ba9f96dc44e10"
 }

package/src/ArazzoRunner.cjs

@@ -45,6 +45,7 @@ class ArazzoRunner {
    * Loads the entry Arazzo document at `uri` (a file system path or URL) and
    * returns a runner bound to it.
    *
+   * @throws DocumentLoadError - When the document cannot be read or loaded
    * @throws UnmatchedProviderError - When no provider can load the document
    * @throws InvalidEntryDocumentError - When the document is not an Arazzo
    * document, or the given registry already backs another entry document

package/src/ArazzoRunner.mjs

@@ -36,6 +36,7 @@ class ArazzoRunner {
    * Loads the entry Arazzo document at `uri` (a file system path or URL) and
    * returns a runner bound to it.
    *
+   * @throws DocumentLoadError - When the document cannot be read or loaded
    * @throws UnmatchedProviderError - When no provider can load the document
    * @throws InvalidEntryDocumentError - When the document is not an Arazzo
    * document, or the given registry already backs another entry document

package/src/client/ParameterDelivery.cjs

@@ -4,10 +4,19 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
+/**
+ * A key starting with an `in` value the client builds qualified keys from —
+ * the OpenAPI locations, including OpenAPI 2.0's `formData` and `body`. The
+ * client qualifies whatever `in` an operation declares, so a non-standard one
+ * is not covered.
+ */
+const QUALIFIED_KEY = /^(?:path|query|header|cookie|formData|body)\./;
+
 /**
  * The outcome of claiming a delivery key: `claimed` for a first claim,
- * `duplicate` when the same `(name, in)` parameter claims its key again, and
- * `collision` when a *different* parameter produces an already-claimed key.
+ * `duplicate` when the same `(name, in)` parameter claims its key again,
+ * `collision` when a *different* parameter produces an already-claimed key,
+ * and `misaddressed` when a bare key has the shape of a qualified one.
  * @internal
  */
 
@@ -47,8 +56,16 @@ exports.default = void 0;
  * alone identifies the claimant. A bare key and a qualified key sharing one
  * name are a collision too, even though the keys differ — the client consults
  * the bare name first for every declared parameter bearing it, so the bare
- * entry would silently capture the qualified one. What to do about a
- * collision is the caller's policy — the map only reports it.
+ * entry would silently capture the qualified one.
+ *
+ * A bare key that starts with a location the client qualifies keys with
+ * (`querystring` named `header.X-Foo`) is misaddressed even when it claims
+ * alone: the client matches it as the qualified key of every declared
+ * parameter that location and the rest of the name identify, so the value
+ * would reach the header `X-Foo` — and `OpenAPIOperationExecutor` reads such
+ * a key the same way when it delivers undeclared parameters. What to do about
+ * a collision or a misaddressed key is the caller's policy — the map only
+ * reports it.
  *
  * Diff this against the vendored bundle's lookup when bumping swagger-client.
  * @internal
@@ -71,10 +88,16 @@ class ParameterDelivery {
    * Only a `claimed` outcome entitles the caller to {@link ParameterDelivery.set}
    * the key; a `duplicate` means the same parameter already holds it, and a
    * `collision` means a different parameter does — on the same key, or across
-   * a bare/qualified pair sharing the name (see the class doc).
+   * a bare/qualified pair sharing the name (see the class doc). A
+   * `misaddressed` bare key is never claimed.
    */
   claim(location, name) {
     const key = ParameterDelivery.keyFor(location, name);
+    const bare = key === name;
+    if (bare && QUALIFIED_KEY.test(name)) return {
+      key,
+      outcome: 'misaddressed'
+    };
     const claimant = this.#claimedBy.get(key);
     if (claimant !== undefined) {
       return {
@@ -82,7 +105,6 @@ class ParameterDelivery {
         outcome: claimant === location ? 'duplicate' : 'collision'
       };
     }
-    const bare = key === name;
     if (bare ? this.#qualifiedNames.has(name) : this.#bareNames.has(name)) {
       return {
         key,

package/src/client/ParameterDelivery.mjs

@@ -1,7 +1,16 @@
+/**
+ * A key starting with an `in` value the client builds qualified keys from —
+ * the OpenAPI locations, including OpenAPI 2.0's `formData` and `body`. The
+ * client qualifies whatever `in` an operation declares, so a non-standard one
+ * is not covered.
+ */
+const QUALIFIED_KEY = /^(?:path|query|header|cookie|formData|body)\./;
+
 /**
  * The outcome of claiming a delivery key: `claimed` for a first claim,
- * `duplicate` when the same `(name, in)` parameter claims its key again, and
- * `collision` when a *different* parameter produces an already-claimed key.
+ * `duplicate` when the same `(name, in)` parameter claims its key again,
+ * `collision` when a *different* parameter produces an already-claimed key,
+ * and `misaddressed` when a bare key has the shape of a qualified one.
  * @internal
  */
 
@@ -41,8 +50,16 @@
  * alone identifies the claimant. A bare key and a qualified key sharing one
  * name are a collision too, even though the keys differ — the client consults
  * the bare name first for every declared parameter bearing it, so the bare
- * entry would silently capture the qualified one. What to do about a
- * collision is the caller's policy — the map only reports it.
+ * entry would silently capture the qualified one.
+ *
+ * A bare key that starts with a location the client qualifies keys with
+ * (`querystring` named `header.X-Foo`) is misaddressed even when it claims
+ * alone: the client matches it as the qualified key of every declared
+ * parameter that location and the rest of the name identify, so the value
+ * would reach the header `X-Foo` — and `OpenAPIOperationExecutor` reads such
+ * a key the same way when it delivers undeclared parameters. What to do about
+ * a collision or a misaddressed key is the caller's policy — the map only
+ * reports it.
  *
  * Diff this against the vendored bundle's lookup when bumping swagger-client.
  * @internal
@@ -65,10 +82,16 @@ class ParameterDelivery {
    * Only a `claimed` outcome entitles the caller to {@link ParameterDelivery.set}
    * the key; a `duplicate` means the same parameter already holds it, and a
    * `collision` means a different parameter does — on the same key, or across
-   * a bare/qualified pair sharing the name (see the class doc).
+   * a bare/qualified pair sharing the name (see the class doc). A
+   * `misaddressed` bare key is never claimed.
    */
   claim(location, name) {
     const key = ParameterDelivery.keyFor(location, name);
+    const bare = key === name;
+    if (bare && QUALIFIED_KEY.test(name)) return {
+      key,
+      outcome: 'misaddressed'
+    };
     const claimant = this.#claimedBy.get(key);
     if (claimant !== undefined) {
       return {
@@ -76,7 +99,6 @@ class ParameterDelivery {
         outcome: claimant === location ? 'duplicate' : 'collision'
       };
     }
-    const bare = key === name;
     if (bare ? this.#qualifiedNames.has(name) : this.#bareNames.has(name)) {
       return {
         key,

package/src/errors/DocumentLoadError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs"));
+/** @public */
+class DocumentLoadError extends _ArazzoRunnerError.default {}
+var _default = exports.default = DocumentLoadError;

package/src/errors/DocumentLoadError.mjs

@@ -0,0 +1,4 @@
+import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
+/** @public */
+class DocumentLoadError extends ArazzoRunnerError {}
+export default DocumentLoadError;

package/src/index.cjs

@@ -119,6 +119,12 @@ Object.defineProperty(exports, "CriterionEvaluator", {
     return _CriterionEvaluator.default;
   }
 });
+Object.defineProperty(exports, "DocumentLoadError", {
+  enumerable: true,
+  get: function () {
+    return _DocumentLoadError.default;
+  }
+});
 Object.defineProperty(exports, "DocumentRegistry", {
   enumerable: true,
   get: function () {
@@ -420,6 +426,7 @@ var _NormalizationError = _interopRequireDefault(require("./errors/Normalization
 var _ExtractionError = _interopRequireDefault(require("./errors/ExtractionError.cjs"));
 var _InvalidEntryDocumentError = _interopRequireDefault(require("./errors/InvalidEntryDocumentError.cjs"));
 var _UnmatchedProviderError = _interopRequireDefault(require("./errors/UnmatchedProviderError.cjs"));
+var _DocumentLoadError = _interopRequireDefault(require("./errors/DocumentLoadError.cjs"));
 var _RuntimeExpressionError = _interopRequireDefault(require("./errors/RuntimeExpressionError.cjs"));
 var _CriterionError = _interopRequireDefault(require("./errors/CriterionError.cjs"));
 var _ResolverError = _interopRequireDefault(require("./errors/ResolverError.cjs"));

package/src/index.mjs

@@ -69,6 +69,7 @@ export { default as NormalizationError } from "./errors/NormalizationError.mjs";
 export { default as ExtractionError } from "./errors/ExtractionError.mjs";
 export { default as InvalidEntryDocumentError } from "./errors/InvalidEntryDocumentError.mjs";
 export { default as UnmatchedProviderError } from "./errors/UnmatchedProviderError.mjs";
+export { default as DocumentLoadError } from "./errors/DocumentLoadError.mjs";
 export { default as RuntimeExpressionError } from "./errors/RuntimeExpressionError.mjs";
 export { default as CriterionError } from "./errors/CriterionError.mjs";
 export { default as ResolverError } from "./errors/ResolverError.mjs";

package/src/registry/DocumentRegistry.cjs

@@ -10,6 +10,8 @@ var _empty = require("@speclynx/apidom-reference/configuration/empty");
 var _ArazzoDocument = _interopRequireDefault(require("../document/ArazzoDocument.cjs"));
 var _ArazzoDocumentRegistryProvider = _interopRequireDefault(require("./providers/ArazzoDocumentRegistryProvider.cjs"));
 var _OpenAPIDocumentRegistryProvider = _interopRequireDefault(require("./providers/OpenAPIDocumentRegistryProvider.cjs"));
+var _ArazzoRunnerError = _interopRequireDefault(require("../errors/ArazzoRunnerError.cjs"));
+var _DocumentLoadError = _interopRequireDefault(require("../errors/DocumentLoadError.cjs"));
 var _InvalidEntryDocumentError = _interopRequireDefault(require("../errors/InvalidEntryDocumentError.cjs"));
 var _UnmatchedProviderError = _interopRequireDefault(require("../errors/UnmatchedProviderError.cjs"));
 var constants = _interopRequireWildcard(require("../constants.cjs"));
@@ -49,16 +51,29 @@ class DocumentRegistry {
    * Acquires a document by URI. Returns cached document if available,
    * otherwise detects the format, loads via the matching provider,
    * caches, and returns it.
+   *
+   * @throws DocumentLoadError - When the document cannot be read or loaded
+   * @throws UnmatchedProviderError - When no provider can load the document
    */
   async acquire(uri) {
     const canonicalURI = this.#canonicalize(uri);
     const cachedDocument = this.#get(canonicalURI);
     if (cachedDocument) return cachedDocument;
     for (const provider of this.#providers) {
-      if (await provider.canProvide(canonicalURI)) {
-        const document = await provider.provide(canonicalURI);
-        this.#set(canonicalURI, document);
-        return document;
+      try {
+        if (await provider.canProvide(canonicalURI)) {
+          const document = await provider.provide(canonicalURI);
+          this.#set(canonicalURI, document);
+          return document;
+        }
+      } catch (error) {
+        // a document that cannot be read or loaded fails in ApiDOM or the parser;
+        // wrapping it keeps every load failure inside the runner's error hierarchy.
+        if (error instanceof _ArazzoRunnerError.default) throw error;
+        throw new _DocumentLoadError.default(`Failed to load the document at "${canonicalURI}"`, {
+          uri: canonicalURI,
+          cause: error
+        });
       }
     }
     throw new _UnmatchedProviderError.default(`No provider can handle the document at "${canonicalURI}"`, {
@@ -97,6 +112,10 @@ class DocumentRegistry {
   /**
    * Acquires the entry Arazzo document and marks it with `isEntry: true`.
    * Validates that the document is an Arazzo specification.
+   *
+   * @throws DocumentLoadError - When the document cannot be read or loaded
+   * @throws UnmatchedProviderError - When no provider can load the document
+   * @throws InvalidEntryDocumentError - When the document is not an Arazzo document
    */
   async acquireEntryDocument(uri) {
     const document = await this.acquire(uri);

package/src/registry/DocumentRegistry.mjs

@@ -2,6 +2,8 @@ import { url } from '@speclynx/apidom-reference/configuration/empty';
 import ArazzoDocument from "../document/ArazzoDocument.mjs";
 import ArazzoDocumentRegistryProvider from "./providers/ArazzoDocumentRegistryProvider.mjs";
 import OpenAPIDocumentRegistryProvider from "./providers/OpenAPIDocumentRegistryProvider.mjs";
+import ArazzoRunnerError from "../errors/ArazzoRunnerError.mjs";
+import DocumentLoadError from "../errors/DocumentLoadError.mjs";
 import InvalidEntryDocumentError from "../errors/InvalidEntryDocumentError.mjs";
 import UnmatchedProviderError from "../errors/UnmatchedProviderError.mjs";
 import * as constants from "../constants.mjs";
@@ -40,16 +42,29 @@ class DocumentRegistry {
    * Acquires a document by URI. Returns cached document if available,
    * otherwise detects the format, loads via the matching provider,
    * caches, and returns it.
+   *
+   * @throws DocumentLoadError - When the document cannot be read or loaded
+   * @throws UnmatchedProviderError - When no provider can load the document
    */
   async acquire(uri) {
     const canonicalURI = this.#canonicalize(uri);
     const cachedDocument = this.#get(canonicalURI);
     if (cachedDocument) return cachedDocument;
     for (const provider of this.#providers) {
-      if (await provider.canProvide(canonicalURI)) {
-        const document = await provider.provide(canonicalURI);
-        this.#set(canonicalURI, document);
-        return document;
+      try {
+        if (await provider.canProvide(canonicalURI)) {
+          const document = await provider.provide(canonicalURI);
+          this.#set(canonicalURI, document);
+          return document;
+        }
+      } catch (error) {
+        // a document that cannot be read or loaded fails in ApiDOM or the parser;
+        // wrapping it keeps every load failure inside the runner's error hierarchy.
+        if (error instanceof ArazzoRunnerError) throw error;
+        throw new DocumentLoadError(`Failed to load the document at "${canonicalURI}"`, {
+          uri: canonicalURI,
+          cause: error
+        });
       }
     }
     throw new UnmatchedProviderError(`No provider can handle the document at "${canonicalURI}"`, {
@@ -88,6 +103,10 @@ class DocumentRegistry {
   /**
    * Acquires the entry Arazzo document and marks it with `isEntry: true`.
    * Validates that the document is an Arazzo specification.
+   *
+   * @throws DocumentLoadError - When the document cannot be read or loaded
+   * @throws UnmatchedProviderError - When no provider can load the document
+   * @throws InvalidEntryDocumentError - When the document is not an Arazzo document
    */
   async acquireEntryDocument(uri) {
     const document = await this.acquire(uri);

package/src/resolver/OpenAPIOperationParameterResolver.cjs

@@ -41,12 +41,15 @@ var _StepParameterResolver = _interopRequireDefault(require("./StepParameterReso
  * 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
- * a header parameter named `token` both produce `header.token`) or across a
- * bare/qualified pair sharing a name (a `querystring` `token` next to a
- * header `token`), where the client would consult the bare name first and
- * silently capture the qualified value.
+ * rather than silently dropping one — a bare/qualified pair sharing a name (a
+ * `querystring` `token` next to a header `token`), where the client would
+ * consult the bare name first and silently capture the qualified value. A
+ * `querystring` parameter whose name starts with a location the client
+ * qualifies keys with (`header.X-Foo`) throws even alone: the client would
+ * match its bare key as the qualified key of a declared header `X-Foo` and
+ * deliver it there. The same check rejects it, in either order, next to a
+ * header parameter `X-Foo` producing that very key — the scheme is not
+ * injective, so the two could otherwise collide on one key.
  * @public
  */
 class OpenAPIOperationParameterResolver extends _StepParameterResolver.default {
@@ -113,8 +116,9 @@ class OpenAPIOperationParameterResolver extends _StepParameterResolver.default {
       } = delivery.claim(location, name);
       // the same parameter declared again: the earlier, more specific one won
       if (outcome === 'duplicate') continue;
-      if (outcome === 'collision') {
-        throw new _ResolverError.default(`Parameter "${name}" (in: ${location}) collides with another parameter on the ` + `delivery key "${key}" and cannot be delivered unambiguously`, {
+      if (outcome !== 'claimed') {
+        const why = outcome === 'collision' ? `collides with another parameter on the delivery key "${key}"` : 'has a name the client reads as the delivery key of another location';
+        throw new _ResolverError.default(`Parameter "${name}" (in: ${location}) ${why} and cannot be delivered unambiguously`, {
           ...scope,
           target: name,
           reason: 'ambiguous-delivery'

package/src/resolver/OpenAPIOperationParameterResolver.mjs

@@ -34,12 +34,15 @@ import StepParameterResolver from "./StepParameterResolver.mjs";
  * 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
- * a header parameter named `token` both produce `header.token`) or across a
- * bare/qualified pair sharing a name (a `querystring` `token` next to a
- * header `token`), where the client would consult the bare name first and
- * silently capture the qualified value.
+ * rather than silently dropping one — a bare/qualified pair sharing a name (a
+ * `querystring` `token` next to a header `token`), where the client would
+ * consult the bare name first and silently capture the qualified value. A
+ * `querystring` parameter whose name starts with a location the client
+ * qualifies keys with (`header.X-Foo`) throws even alone: the client would
+ * match its bare key as the qualified key of a declared header `X-Foo` and
+ * deliver it there. The same check rejects it, in either order, next to a
+ * header parameter `X-Foo` producing that very key — the scheme is not
+ * injective, so the two could otherwise collide on one key.
  * @public
  */
 class OpenAPIOperationParameterResolver extends StepParameterResolver {
@@ -106,8 +109,9 @@ class OpenAPIOperationParameterResolver extends StepParameterResolver {
       } = delivery.claim(location, name);
       // the same parameter declared again: the earlier, more specific one won
       if (outcome === 'duplicate') continue;
-      if (outcome === 'collision') {
-        throw new ResolverError(`Parameter "${name}" (in: ${location}) collides with another parameter on the ` + `delivery key "${key}" and cannot be delivered unambiguously`, {
+      if (outcome !== 'claimed') {
+        const why = outcome === 'collision' ? `collides with another parameter on the delivery key "${key}"` : 'has a name the client reads as the delivery key of another location';
+        throw new ResolverError(`Parameter "${name}" (in: ${location}) ${why} and cannot be delivered unambiguously`, {
           ...scope,
           target: name,
           reason: 'ambiguous-delivery'