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

package/src/client/OpenAPIOperationResponseNormalizer.cjs

@@ -0,0 +1,48 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _swaggerClient = require("../vendor/swagger-client.cjs");
+var _OpenAPIOperationResponse = _interopRequireDefault(require("./OpenAPIOperationResponse.cjs"));
+// @ts-expect-error vendored swagger-client bundle has no type declarations
+
+/**
+ * Normalizes a raw WHATWG `Response` into an {@link OpenAPIOperationResponse}.
+ *
+ * Wraps the vendored swagger-client response deserializer (upstream
+ * `serializeRes`, aliased at the vendor boundary), whose battle-tested
+ * content-type dispatch (JSON/XML/YAML/text vs binary) means the response
+ * model runtime expressions and criteria see is defined here, on the runner's
+ * side of the {@link HTTPClient} seam, and stays identical across transports.
+ * 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`.
+ * @public
+ */
+class OpenAPIOperationResponseNormalizer {
+  /**
+   * Deserializes the response body by content type and maps the result into the
+   * runner's response model. `request` is the request the operation was
+   * executed with; its `url` doubles as the fallback when the `Response`
+   * carries none (e.g. a stubbed transport).
+   */
+  async normalize(response, request) {
+    const deserialized = await (0, _swaggerClient.deserializeResponse)(response, request?.url);
+    const headers = Object.fromEntries(Array.from(response.headers.keys(), name => [name, response.headers.get(name)]));
+    return new _OpenAPIOperationResponse.default({
+      ok: deserialized.ok,
+      url: deserialized.url,
+      status: deserialized.status,
+      statusText: deserialized.statusText,
+      headers,
+      text: deserialized.text,
+      body: deserialized.body,
+      request
+    });
+  }
+}
+var _default = exports.default = OpenAPIOperationResponseNormalizer;

package/src/client/OpenAPIOperationResponseNormalizer.mjs

@@ -0,0 +1,40 @@
+// @ts-expect-error vendored swagger-client bundle has no type declarations
+import { deserializeResponse } from '../vendor/swagger-client.mjs';
+import OpenAPIOperationResponse from "./OpenAPIOperationResponse.mjs";
+/**
+ * Normalizes a raw WHATWG `Response` into an {@link OpenAPIOperationResponse}.
+ *
+ * Wraps the vendored swagger-client response deserializer (upstream
+ * `serializeRes`, aliased at the vendor boundary), whose battle-tested
+ * content-type dispatch (JSON/XML/YAML/text vs binary) means the response
+ * model runtime expressions and criteria see is defined here, on the runner's
+ * side of the {@link HTTPClient} seam, and stays identical across transports.
+ * 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`.
+ * @public
+ */
+class OpenAPIOperationResponseNormalizer {
+  /**
+   * Deserializes the response body by content type and maps the result into the
+   * runner's response model. `request` is the request the operation was
+   * executed with; its `url` doubles as the fallback when the `Response`
+   * carries none (e.g. a stubbed transport).
+   */
+  async normalize(response, request) {
+    const deserialized = await deserializeResponse(response, request?.url);
+    const headers = Object.fromEntries(Array.from(response.headers.keys(), name => [name, response.headers.get(name)]));
+    return new OpenAPIOperationResponse({
+      ok: deserialized.ok,
+      url: deserialized.url,
+      status: deserialized.status,
+      statusText: deserialized.statusText,
+      headers,
+      text: deserialized.text,
+      body: deserialized.body,
+      request
+    });
+  }
+}
+export default OpenAPIOperationResponseNormalizer;

package/src/client/ParameterDelivery.cjs

@@ -0,0 +1,119 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+/**
+ * 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.
+ * @internal
+ */
+
+/**
+ * A parameter claim: the delivery key the `(location, name)` pair encodes to,
+ * and how the claim resolved against the map's earlier entries.
+ * @internal
+ */
+
+/**
+ * The parameters map an OpenAPI operation is executed with — the single owner
+ * of the vendored swagger-client's parameter-addressing scheme.
+ *
+ * The client accepts two key shapes in its `parameters` map and, for each
+ * parameter the operation declares, consults the bare `name` *before* the
+ * qualified `'{in}.{name}'` key (deminified from the vendored bundle:
+ * `r = m[e.name]; if (r === undefined) r = m[`${e.in}.${e.name}`]`). Two
+ * consequences shape everything that feeds the map:
+ *
+ * - qualified keys are what let parameters differing only in their location
+ *   coexist — the client builds the same key from the declared parameter and
+ *   matches it verbatim, never splitting it, so dots in a name are safe;
+ * - a bare key silently outranks the qualified keys of every declared
+ *   parameter bearing that name, so nothing may emit one for a location the
+ *   client can address.
+ *
+ * Arazzo's `querystring` is the one location the client cannot address — it
+ * names no OpenAPI location — so it keeps the bare name, which can still
+ * reach a same-named declared parameter. Every other location is qualified,
+ * including an unrecognized one: an unmatched qualified key is inert, where a
+ * bare one would capture.
+ *
+ * Keys are claimed first-wins. The scheme is not injective, so the map also
+ * discriminates a genuine duplicate from a collision of two different
+ * parameters on one key: given a key, the claimant's name is determined by
+ * its location (the key embeds the name, or is the name), so the location
+ * 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.
+ *
+ * Diff this against the vendored bundle's lookup when bumping swagger-client.
+ * @internal
+ */
+class ParameterDelivery {
+  /**
+   * The key a `(location, name)` pair is delivered under — `'{in}.{name}'`,
+   * or the bare name for `querystring`. See the class doc for why.
+   */
+  static keyFor(location, name) {
+    return location === 'querystring' ? name : `${location}.${name}`;
+  }
+  #values = {};
+  #claimedBy = new Map();
+  #bareNames = new Set();
+  #qualifiedNames = new Set();
+
+  /**
+   * Claims the delivery key for a `(location, name)` pair, first-wins.
+   * 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).
+   */
+  claim(location, name) {
+    const key = ParameterDelivery.keyFor(location, name);
+    const claimant = this.#claimedBy.get(key);
+    if (claimant !== undefined) {
+      return {
+        key,
+        outcome: claimant === location ? 'duplicate' : 'collision'
+      };
+    }
+    const bare = key === name;
+    if (bare ? this.#qualifiedNames.has(name) : this.#bareNames.has(name)) {
+      return {
+        key,
+        outcome: 'collision'
+      };
+    }
+    (bare ? this.#bareNames : this.#qualifiedNames).add(name);
+    this.#claimedBy.set(key, location);
+    return {
+      key,
+      outcome: 'claimed'
+    };
+  }
+  set(key, value) {
+    // defined rather than assigned: a key like `__proto__` hits the
+    // Object.prototype accessor on bracket assignment, so no own property is
+    // ever created and the parameter is silently lost — and an object value
+    // additionally rewrites the record's prototype
+    Object.defineProperty(this.#values, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+  }
+
+  /**
+   * The accumulated record, in the shape `buildRequest` consumes.
+   */
+  toRecord() {
+    return this.#values;
+  }
+}
+var _default = exports.default = ParameterDelivery;

package/src/client/ParameterDelivery.mjs

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ * @internal
+ */
+
+/**
+ * A parameter claim: the delivery key the `(location, name)` pair encodes to,
+ * and how the claim resolved against the map's earlier entries.
+ * @internal
+ */
+
+/**
+ * The parameters map an OpenAPI operation is executed with — the single owner
+ * of the vendored swagger-client's parameter-addressing scheme.
+ *
+ * The client accepts two key shapes in its `parameters` map and, for each
+ * parameter the operation declares, consults the bare `name` *before* the
+ * qualified `'{in}.{name}'` key (deminified from the vendored bundle:
+ * `r = m[e.name]; if (r === undefined) r = m[`${e.in}.${e.name}`]`). Two
+ * consequences shape everything that feeds the map:
+ *
+ * - qualified keys are what let parameters differing only in their location
+ *   coexist — the client builds the same key from the declared parameter and
+ *   matches it verbatim, never splitting it, so dots in a name are safe;
+ * - a bare key silently outranks the qualified keys of every declared
+ *   parameter bearing that name, so nothing may emit one for a location the
+ *   client can address.
+ *
+ * Arazzo's `querystring` is the one location the client cannot address — it
+ * names no OpenAPI location — so it keeps the bare name, which can still
+ * reach a same-named declared parameter. Every other location is qualified,
+ * including an unrecognized one: an unmatched qualified key is inert, where a
+ * bare one would capture.
+ *
+ * Keys are claimed first-wins. The scheme is not injective, so the map also
+ * discriminates a genuine duplicate from a collision of two different
+ * parameters on one key: given a key, the claimant's name is determined by
+ * its location (the key embeds the name, or is the name), so the location
+ * 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.
+ *
+ * Diff this against the vendored bundle's lookup when bumping swagger-client.
+ * @internal
+ */
+class ParameterDelivery {
+  /**
+   * The key a `(location, name)` pair is delivered under — `'{in}.{name}'`,
+   * or the bare name for `querystring`. See the class doc for why.
+   */
+  static keyFor(location, name) {
+    return location === 'querystring' ? name : `${location}.${name}`;
+  }
+  #values = {};
+  #claimedBy = new Map();
+  #bareNames = new Set();
+  #qualifiedNames = new Set();
+
+  /**
+   * Claims the delivery key for a `(location, name)` pair, first-wins.
+   * 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).
+   */
+  claim(location, name) {
+    const key = ParameterDelivery.keyFor(location, name);
+    const claimant = this.#claimedBy.get(key);
+    if (claimant !== undefined) {
+      return {
+        key,
+        outcome: claimant === location ? 'duplicate' : 'collision'
+      };
+    }
+    const bare = key === name;
+    if (bare ? this.#qualifiedNames.has(name) : this.#bareNames.has(name)) {
+      return {
+        key,
+        outcome: 'collision'
+      };
+    }
+    (bare ? this.#bareNames : this.#qualifiedNames).add(name);
+    this.#claimedBy.set(key, location);
+    return {
+      key,
+      outcome: 'claimed'
+    };
+  }
+  set(key, value) {
+    // defined rather than assigned: a key like `__proto__` hits the
+    // Object.prototype accessor on bracket assignment, so no own property is
+    // ever created and the parameter is silently lost — and an object value
+    // additionally rewrites the record's prototype
+    Object.defineProperty(this.#values, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+  }
+
+  /**
+   * The accumulated record, in the shape `buildRequest` consumes.
+   */
+  toRecord() {
+    return this.#values;
+  }
+}
+export default ParameterDelivery;

package/src/constants.cjs

@@ -0,0 +1,9 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MAX_HTTP_CACHE_STALE_AGE = exports.MAX_HTTP_CACHE_ENTRIES = exports.MAX_DOCUMENT_REGISTRY_SIZE = void 0;
+const MAX_HTTP_CACHE_ENTRIES = exports.MAX_HTTP_CACHE_ENTRIES = 6;
+const MAX_HTTP_CACHE_STALE_AGE = exports.MAX_HTTP_CACHE_STALE_AGE = 120_000; // 2 minutes in milliseconds
+const MAX_DOCUMENT_REGISTRY_SIZE = exports.MAX_DOCUMENT_REGISTRY_SIZE = 4;

package/src/constants.mjs

@@ -0,0 +1,3 @@
+export const MAX_HTTP_CACHE_ENTRIES = 6;
+export const MAX_HTTP_CACHE_STALE_AGE = 120_000; // 2 minutes in milliseconds
+export const MAX_DOCUMENT_REGISTRY_SIZE = 4;

package/src/criterion/CriterionEvaluator.cjs

@@ -0,0 +1,205 @@
+"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 _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _arazzoRuntimeExpression = require("@swaggerexpert/arazzo-runtime-expression");
+var _CriterionError = _interopRequireDefault(require("../errors/CriterionError.cjs"));
+var _RegexCriterionEvaluator = _interopRequireDefault(require("./RegexCriterionEvaluator.cjs"));
+var _SimpleCriterionEvaluator = _interopRequireDefault(require("./SimpleCriterionEvaluator.cjs"));
+var _JSONPathCriterionEvaluator = _interopRequireDefault(require("./JSONPathCriterionEvaluator.cjs"));
+var _XPathCriterionEvaluator = _interopRequireDefault(require("./XPathCriterionEvaluator.cjs"));
+/**
+ * Resolves a runtime expression to a value during criterion evaluation.
+ *
+ * Used both for a criterion's `context` (regex/jsonpath/xpath) and for the
+ * expressions embedded in a `simple` condition. It should resolve leniently —
+ * an unresolvable reference returning `undefined` fails the criterion rather
+ * than throwing (a common way to drive it is
+ * `(expression) => runtimeExpressionEvaluator.evaluate(expression)` with a
+ * lenient evaluator).
+ * @public
+ */
+
+/**
+ * Options for the CriterionEvaluator.
+ * @public
+ */
+
+/**
+ * Evaluates an Arazzo Criterion Object to a boolean.
+ *
+ * Dispatches on the criterion's `type` (defaulting to `simple` when omitted):
+ * - `simple` — evaluates the condition directly, resolving the runtime
+ *   expressions embedded in it.
+ * - `regex` — resolves the `context` runtime expression, then applies the
+ *   pattern to the resolved value.
+ * - `jsonpath` — resolves the `context` runtime expression, then applies the
+ *   JSONPath query to the resolved value (met when the query matches). Only the
+ *   `rfc9535` version is supported (the spec default); an explicit other version
+ *   throws.
+ * - `xpath` — resolves the `context` runtime expression, then applies the XPath
+ *   3.1 query to the resolved XML value (met by the Effective Boolean Value).
+ *   Only the `xpath-31` version is supported (the spec default); an explicit
+ *   other version throws.
+ *
+ * The evaluator is agnostic about how runtime expressions are resolved: the
+ * caller supplies a {@link CriterionContextResolver} per evaluation, keeping
+ * runtime-state, document, and registry concerns in the runtime expression
+ * evaluator rather than duplicated here.
+ * @public
+ */
+class CriterionEvaluator {
+  #simple;
+  #regex;
+  #jsonpath;
+  #xpath;
+  constructor(options = {}) {
+    this.#simple = options.simple ?? new _SimpleCriterionEvaluator.default();
+    this.#regex = options.regex ?? new _RegexCriterionEvaluator.default();
+    this.#jsonpath = options.jsonpath ?? new _JSONPathCriterionEvaluator.default();
+    this.#xpath = options.xpath ?? new _XPathCriterionEvaluator.default();
+  }
+
+  /**
+   * Evaluates a criterion element, returning whether the condition is met.
+   *
+   * `resolve` turns a runtime expression into a value: for `simple` it resolves
+   * the expressions embedded in the condition; for the other types it resolves
+   * the criterion's `context` expression that the condition is applied to.
+   */
+  evaluate(criterion, resolve) {
+    if (!(0, _apidomNsArazzo.isCriterionElement)(criterion)) {
+      throw new _CriterionError.default('Element is not a Criterion Object', {
+        reason: 'invalid-criterion'
+      });
+    }
+    const condition = (0, _apidomDatamodel.isStringElement)(criterion.condition) ? (0, _apidomCore.toValue)(criterion.condition) : undefined;
+    // `condition` is required; an empty string is not a meaningful condition
+    // (e.g. an empty regex would match unconditionally), so reject it too.
+    if (condition === undefined || condition === '') {
+      throw new _CriterionError.default('Criterion is missing a "condition"', {
+        reason: 'missing-condition'
+      });
+    }
+    const type = this.#resolveType(criterion);
+    this.#requireValidContext(criterion, type);
+    switch (type) {
+      case 'simple':
+        return this.#simple.evaluate(condition, resolve);
+      case 'regex':
+        return this.#regex.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+      case 'jsonpath':
+        // only rfc9535 is supported; it is the spec default, so an omitted
+        // version is accepted. draft-goessner has different semantics and is
+        // rejected rather than mis-evaluated.
+        this.#requireVersion(criterion, type, condition, 'rfc9535');
+        return this.#jsonpath.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+      case 'xpath':
+        // only XPath 3.1 is supported; xpath-31 is the spec default, so an
+        // omitted version is accepted. Older versions are rejected.
+        this.#requireVersion(criterion, type, condition, 'xpath-31');
+        return this.#xpath.evaluate(condition, this.#resolveContext(criterion, type, resolve));
+      default:
+        throw new _CriterionError.default(`Unknown criterion type "${type}"`, {
+          condition,
+          type,
+          reason: 'unknown-type'
+        });
+    }
+  }
+
+  /**
+   * Determines the criterion `type`, defaulting to `simple` only when the field
+   * is omitted. The `type` field may be a bare string or a Criterion Expression
+   * Type Object (whose own `type` names the flavor). A present-but-unreadable
+   * `type` throws a {@link CriterionError} rather than silently defaulting.
+   */
+  #resolveType(criterion) {
+    const type = criterion.type;
+    if (type === undefined) return 'simple';
+    if ((0, _apidomNsArazzo.isCriterionExpressionTypeElement)(type) && (0, _apidomDatamodel.isStringElement)(type.type)) {
+      return (0, _apidomCore.toValue)(type.type);
+    }
+    if ((0, _apidomDatamodel.isStringElement)(type)) return (0, _apidomCore.toValue)(type);
+    throw new _CriterionError.default('Criterion has an invalid "type"', {
+      reason: 'invalid-type'
+    });
+  }
+
+  /**
+   * Extracts the expression `version` from a Criterion Expression Type Object,
+   * or `undefined` when no version is declared (a bare-string `type`, or a type
+   * object without a `version`) — in which case the spec default for the type
+   * applies. A `version` that is present but not a string is malformed and
+   * throws a {@link CriterionError} rather than silently defaulting.
+   */
+  #resolveVersion(criterion) {
+    const type = criterion.type;
+    if (!(0, _apidomNsArazzo.isCriterionExpressionTypeElement)(type) || type.version === undefined) {
+      return undefined;
+    }
+    if ((0, _apidomDatamodel.isStringElement)(type.version)) {
+      return (0, _apidomCore.toValue)(type.version);
+    }
+    throw new _CriterionError.default('Criterion has an invalid expression type "version"', {
+      reason: 'invalid-version'
+    });
+  }
+
+  /**
+   * Enforces that a versioned condition type declares only the one version this
+   * runner supports. An omitted version is accepted (it is the spec default);
+   * any other declared version throws a {@link CriterionError}.
+   */
+  #requireVersion(criterion, type, condition, supported) {
+    const version = this.#resolveVersion(criterion);
+    if (version !== undefined && version !== supported) {
+      throw new _CriterionError.default(`Unsupported ${type} version "${version}" (only ${supported})`, {
+        condition,
+        type,
+        reason: 'unsupported-version'
+      });
+    }
+  }
+
+  /**
+   * Enforces that a present `context` is a valid runtime expression, for every
+   * criterion type: the spec types it `{expression}`, and `simple` ignores it,
+   * so a malformed one would otherwise go unnoticed there.
+   */
+  #requireValidContext(criterion, type) {
+    const {
+      context
+    } = criterion;
+    if (context === undefined) return;
+    if (!(0, _apidomDatamodel.isStringElement)(context) || !(0, _arazzoRuntimeExpression.test)((0, _apidomCore.toValue)(context))) {
+      throw new _CriterionError.default('Criterion has a "context" that is not a valid runtime expression', {
+        type,
+        reason: 'invalid-context'
+      });
+    }
+  }
+
+  /**
+   * Resolves the criterion's `context` runtime expression to the value the
+   * condition is applied to. The condition types that need a context (`regex`,
+   * `jsonpath`, `xpath`) must declare one; a criterion of such a type without a
+   * `context` throws a {@link CriterionError}.
+   */
+  #resolveContext(criterion, type, resolve) {
+    if (!(0, _apidomDatamodel.isStringElement)(criterion.context)) {
+      throw new _CriterionError.default(`Criterion type "${type}" requires a "context"`, {
+        type,
+        reason: 'missing-context'
+      });
+    }
+    return resolve((0, _apidomCore.toValue)(criterion.context));
+  }
+}
+var _default = exports.default = CriterionEvaluator;