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

package/src/executor/OpenAPIOperationLocatorNormalizer.mjs

@@ -0,0 +1,189 @@
+import { test as isRuntimeExpression } from '@swaggerexpert/arazzo-runtime-expression';
+import { URIFragmentIdentifier, testJSONPointer } from '@swaggerexpert/json-pointer';
+import { url } from '@speclynx/apidom-reference/configuration/empty';
+import OpenAPIDocument from "../document/OpenAPIDocument.mjs";
+import RuntimeExpressionEvaluator from "../expression/RuntimeExpressionEvaluator.mjs";
+import ExtractionError from "../errors/ExtractionError.mjs";
+import SourceDescriptionsLocatorNormalizer from "./SourceDescriptionsLocatorNormalizer.mjs";
+/**
+ * A canonical OpenAPI operation locator: the OpenAPI document that owns the
+ * operation and a JSON Pointer locating the operation within it
+ * (`/paths/{path}/{method}`).
+ *
+ * A step names its operation in one of several ways — a plain `operationId`, a
+ * `$sourceDescriptions` runtime expression, or an `operationPath` — which are
+ * all locators for the same thing. The normalizer reduces any of them to this
+ * single canonical form.
+ * @public
+ */
+/**
+ * Normalizes a step's OpenAPI operation locator to a canonical
+ * {@link OpenAPIOperationLocator} — the OpenAPI document and a JSON Pointer to
+ * the operation within it.
+ *
+ * A step names its operation with either `operationId` or `operationPath`:
+ * - `operationId` is a plain operation name, or a whole runtime expression
+ *   `$sourceDescriptions.{name}.{operationId}`. Per the Arazzo Specification, a
+ *   plain name is only valid when a single (non-arazzo) source description is
+ *   defined; multiple sources require the expression form. A plain name is
+ *   therefore resolved against the first source description that has it.
+ * - `operationPath` embeds a `{$sourceDescriptions.{name}.url}` runtime
+ *   expression followed by a JSON Pointer to the operation.
+ *
+ * The `type` declared on a source description is not trusted (it may be absent
+ * or wrong); a source is classified by what it actually parses to. The
+ * normalizer acquires the referenced source documents from the registry on
+ * demand.
+ * @public
+ */
+class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormalizer {
+  /**
+   * Normalizes a plain or expression `operationId` to a canonical locator.
+   *
+   * A whole runtime expression (`$sourceDescriptions.{name}.{operationId}`) is
+   * resolved against its named source; a plain name is resolved against the
+   * first source description that has it.
+   */
+  async normalizeOperationId(operationId, document) {
+    if (isRuntimeExpression(operationId)) {
+      return this.#resolveSourced(operationId, document);
+    }
+    return this.#resolvePlainOperationId(operationId, document);
+  }
+
+  /**
+   * Normalizes an `operationPath` —
+   * `{$sourceDescriptions.{name}.url}#/json/pointer` — to a canonical locator.
+   *
+   * The reference is interpolated (resolving
+   * `{$sourceDescriptions.{name}.url}` to the source's URL) into a URI
+   * reference; its fragment is the JSON Pointer to the operation (decoded from
+   * the URI fragment representation) and the part before the fragment is the
+   * source document to acquire.
+   *
+   * The runner only needs a URL and a JSON Pointer, so it does not enforce that
+   * the source description is identified by a runtime expression rather than a
+   * literal URL (a literal URL interpolates to itself and still resolves) — that
+   * is a conformance concern for the validator. It fails only when the URL does
+   * not resolve to an OpenAPI source or the JSON Pointer is invalid.
+   */
+  async normalizeOperationPath(operationPath, document) {
+    const evaluator = new RuntimeExpressionEvaluator({}, {
+      strict: false,
+      document,
+      registry: this.registry
+    });
+    const uriReference = evaluator.interpolate(operationPath);
+    const documentURI = url.sanitize(url.stripHash(uriReference));
+    if (documentURI === '') {
+      throw new ExtractionError(`operationPath "${operationPath}" does not resolve to a source description URL`, {
+        pointer: operationPath,
+        uri: document.uri
+      });
+    }
+    const jsonPointer = URIFragmentIdentifier.fromURIReference(uriReference);
+    if (!testJSONPointer(jsonPointer)) {
+      throw new ExtractionError(`operationPath "${operationPath}" has an invalid JSON Pointer`, {
+        pointer: operationPath,
+        uri: document.uri
+      });
+    }
+    const source = await this.registry.acquire(documentURI);
+    if (!OpenAPIDocument.is(source)) {
+      throw new ExtractionError(`operationPath "${operationPath}" does not reference an OpenAPI document`, {
+        pointer: operationPath,
+        uri: documentURI
+      });
+    }
+    return {
+      document: source,
+      jsonPointer
+    };
+  }
+
+  /**
+   * Parses a `$sourceDescriptions.{name}.{reference}` expression, asserting
+   * it is a source-descriptions expression.
+   */
+  #parseSourceDescriptionsExpression(expression) {
+    const parsed = this.parseSourceDescriptionsExpression(expression);
+    if (parsed === undefined) {
+      throw new ExtractionError(`Unsupported operationId expression "${expression}"`, {
+        operationId: expression
+      });
+    }
+    return parsed;
+  }
+  async #resolveSourced(expression, document) {
+    const {
+      sourceName,
+      reference: operationId
+    } = this.#parseSourceDescriptionsExpression(expression);
+    const openapiDocument = await this.#sourceDocument(sourceName, document);
+    const jsonPointer = openapiDocument.operationIndex.get(operationId);
+    if (jsonPointer === undefined) {
+      throw new ExtractionError(`Operation "${operationId}" not found in source description "${sourceName}"`, {
+        operationId,
+        uri: openapiDocument.uri
+      });
+    }
+    return {
+      document: openapiDocument,
+      jsonPointer
+    };
+  }
+
+  /**
+   * Resolves a plain operationId against the single OpenAPI source description.
+   *
+   * Per the Arazzo Specification a plain operationId is only valid when a single
+   * non-arazzo source description is defined; multiple such sources require the
+   * `$sourceDescriptions` expression form. The first OpenAPI source is therefore
+   * the one it targets: the operationId is looked up there and the lookup fails
+   * if it is absent — subsequent OpenAPI sources are not searched (their
+   * presence would make the plain operationId ambiguous, and hence invalid).
+   * Non-OpenAPI (arazzo) sources are skipped. Sources are acquired one at a time
+   * until the first OpenAPI source is reached.
+   */
+  async #resolvePlainOperationId(operationId, document) {
+    for (const uri of document.sourceDescriptionURIs()) {
+      const source = await this.registry.acquire(uri);
+      if (!OpenAPIDocument.is(source)) continue;
+      const jsonPointer = source.operationIndex.get(operationId);
+      if (jsonPointer === undefined) {
+        throw new ExtractionError(`Operation "${operationId}" not found in source description at "${source.uri}"`, {
+          operationId,
+          uri: source.uri
+        });
+      }
+      return {
+        document: source,
+        jsonPointer
+      };
+    }
+    throw new ExtractionError(`Operation "${operationId}" has no OpenAPI source description`, {
+      operationId,
+      uri: document.uri
+    });
+  }
+
+  /**
+   * Acquires a source description by name and asserts it is an OpenAPI document.
+   */
+  async #sourceDocument(sourceName, document) {
+    const uri = document.resolveSourceDescriptionURI(sourceName);
+    if (uri === undefined) {
+      throw new ExtractionError(`Source description "${sourceName}" not found`, {
+        uri: document.uri
+      });
+    }
+    const source = await this.registry.acquire(uri);
+    if (!OpenAPIDocument.is(source)) {
+      throw new ExtractionError(`Source description "${sourceName}" is not an OpenAPI document`, {
+        uri
+      });
+    }
+    return source;
+  }
+}
+export default OpenAPIOperationLocatorNormalizer;

package/src/executor/SourceDescriptionsLocatorNormalizer.cjs

@@ -0,0 +1,44 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _parser = require("@usearazzo/parser");
+/**
+ * Base of the locator normalizers that resolve
+ * `$sourceDescriptions.{name}.{reference}` runtime expressions — the OpenAPI
+ * operation locator and the Arazzo workflow locator. Owns the registry handle
+ * and the one grammar-facing parse, so the expression node's name and field
+ * shape are encoded once rather than per subclass.
+ * @public
+ */
+class SourceDescriptionsLocatorNormalizer {
+  registry;
+  constructor(registry) {
+    this.registry = registry;
+  }
+
+  /**
+   * Parses a `$sourceDescriptions.{name}.{reference}` expression, or returns
+   * `undefined` when the string is not one (whether it fails to parse or
+   * parses to another expression kind) — each subclass raises its own error
+   * type, message, and context for its own position.
+   */
+  parseSourceDescriptionsExpression(expression) {
+    const {
+      result,
+      tree
+    } = (0, _parser.parseRuntimeExpression)(expression);
+    if (!result.success || tree.type !== 'SourceDescriptionsExpression') return undefined;
+    const {
+      sourceName,
+      reference
+    } = tree;
+    return {
+      sourceName,
+      reference
+    };
+  }
+}
+var _default = exports.default = SourceDescriptionsLocatorNormalizer;

package/src/executor/SourceDescriptionsLocatorNormalizer.mjs

@@ -0,0 +1,38 @@
+import { parseRuntimeExpression } from '@usearazzo/parser';
+/**
+ * Base of the locator normalizers that resolve
+ * `$sourceDescriptions.{name}.{reference}` runtime expressions — the OpenAPI
+ * operation locator and the Arazzo workflow locator. Owns the registry handle
+ * and the one grammar-facing parse, so the expression node's name and field
+ * shape are encoded once rather than per subclass.
+ * @public
+ */
+class SourceDescriptionsLocatorNormalizer {
+  registry;
+  constructor(registry) {
+    this.registry = registry;
+  }
+
+  /**
+   * Parses a `$sourceDescriptions.{name}.{reference}` expression, or returns
+   * `undefined` when the string is not one (whether it fails to parse or
+   * parses to another expression kind) — each subclass raises its own error
+   * type, message, and context for its own position.
+   */
+  parseSourceDescriptionsExpression(expression) {
+    const {
+      result,
+      tree
+    } = parseRuntimeExpression(expression);
+    if (!result.success || tree.type !== 'SourceDescriptionsExpression') return undefined;
+    const {
+      sourceName,
+      reference
+    } = tree;
+    return {
+      sourceName,
+      reference
+    };
+  }
+}
+export default SourceDescriptionsLocatorNormalizer;

package/src/executor/StepExecutor.cjs

@@ -0,0 +1,333 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.STEP_TARGET_FIELDS = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _RuntimeExpressionEvaluator = _interopRequireDefault(require("../expression/RuntimeExpressionEvaluator.cjs"));
+var _CriterionEvaluator = _interopRequireDefault(require("../criterion/CriterionEvaluator.cjs"));
+var _OpenAPIOperationParameterResolver = _interopRequireDefault(require("../resolver/OpenAPIOperationParameterResolver.cjs"));
+var _RequestBodyResolver = _interopRequireDefault(require("../resolver/RequestBodyResolver.cjs"));
+var _OutputResolver = _interopRequireDefault(require("../resolver/OutputResolver.cjs"));
+var _ActionResolver = _interopRequireDefault(require("../action/ActionResolver.cjs"));
+var _OpenAPIOperationLocatorNormalizer = _interopRequireDefault(require("./OpenAPIOperationLocatorNormalizer.cjs"));
+var _ExecutionError = _interopRequireDefault(require("../errors/ExecutionError.cjs"));
+var _RuntimeExpressionError = _interopRequireDefault(require("../errors/RuntimeExpressionError.cjs"));
+var _abort = require("./abort.cjs");
+/**
+ * The mutually exclusive fields by which a step names its target. A step may
+ * declare at most one. Extend this as the Arazzo Specification adds targets
+ * (e.g. `channelPath` in 1.1.0) so every exclusivity check stays complete —
+ * both this module's and the workflow executor's, which makes the same check
+ * for a step it intercepts before {@link StepExecutor.execute}.
+ * @internal
+ */
+const STEP_TARGET_FIELDS = exports.STEP_TARGET_FIELDS = ['operationId', 'operationPath', 'workflowId'];
+
+/**
+ * A read-only source of the runtime expression context for a step.
+ *
+ * The step executor only reads accumulated run state — it produces the
+ * pre-request context (`toContext()`) and the post-request context
+ * (`toContext(request, response)`) — and never mutates it, so it depends on
+ * this narrow interface rather than the full execution state.
+ * @public
+ */
+
+/**
+ * Options for the StepExecutor.
+ * @public
+ */
+
+/**
+ * The outcome of executing a single step.
+ * @public
+ */
+
+/**
+ * Executes a single Arazzo step that invokes an OpenAPI operation.
+ *
+ * The pipeline locates the step's operation (`operationId` / `operationPath`),
+ * resolves the step's parameters and request body against the pre-request
+ * context, delegates to {@link OpenAPIOperationExecutor} to run the located
+ * operation, then evaluates `successCriteria`, resolves `outputs`, and selects
+ * the `onSuccess`/`onFailure` action against the post-request context.
+ *
+ * It reads run state through a {@link ContextSource} and mutates nothing — the
+ * caller records the returned outputs and interprets the returned action. A step
+ * targeting a `workflowId` (a sub-workflow) is not an operation step and throws
+ * {@link ExecutionError}; running sub-workflows is the workflow executor's
+ * concern. A received response with unmet criteria is a normal
+ * `successful: false` outcome; malformed input (e.g. an invalid criterion or
+ * expression) throws, as does a run the caller has cancelled through an
+ * `AbortSignal` in the execute options.
+ * @public
+ */
+class StepExecutor {
+  #document;
+  #registry;
+  #locatorNormalizer;
+  #operationExecutor;
+  #parameterResolver = new _OpenAPIOperationParameterResolver.default();
+  #requestBodyResolver = new _RequestBodyResolver.default();
+  #outputResolver = new _OutputResolver.default();
+  #criterionEvaluator = new _CriterionEvaluator.default();
+  #actionResolver = new _ActionResolver.default();
+  constructor(options) {
+    this.#document = options.document;
+    this.#registry = options.registry;
+    this.#locatorNormalizer = new _OpenAPIOperationLocatorNormalizer.default(options.registry);
+    this.#operationExecutor = options.operationExecutor;
+  }
+
+  /**
+   * A step executor bound to the given document, sharing this one's registry
+   * and operation executor — this instance itself when the document is
+   * already the one it is bound to.
+   *
+   * A step executor's identity includes the document its steps belong to: a
+   * plain `operationId` resolves against *that* document's source
+   * descriptions, and `$components` / `$sourceDescriptions` expressions
+   * resolve against it too. A cross-document workflow run therefore derives
+   * a sibling per foreign document rather than re-pointing this one.
+   */
+  forDocument(document) {
+    if (document === this.#document) return this;
+    return new StepExecutor({
+      document,
+      registry: this.#registry,
+      operationExecutor: this.#operationExecutor
+    });
+  }
+
+  /**
+   * Executes the step against the given run state, returning its outcome.
+   *
+   * `executeOptions` is an opaque bag passed through to the operation executor
+   * (e.g. a `server` to run the step against, or an `AbortSignal`). The
+   * Arazzo-derived options (`operationId`, `parameters`, `requestBody`) always
+   * take precedence over it.
+   *
+   * A `signal` in that bag is honored here and not only at the transport: an
+   * already-aborted signal throws `reason: 'aborted'` instead of issuing a
+   * request nobody is waiting for, whose wire-level cancellation would surface
+   * as a transport {@link ClientError} — a request that failed on its own terms
+   * — rather than as the withdrawal it is.
+   */
+  async execute(step, state, executeOptions = {}) {
+    const stepId = (0, _apidomCore.toValue)(step.stepId);
+
+    // a step's target fields are mutually exclusive; declaring more than one is
+    // malformed and has no defined resolution.
+    const declaredTargets = STEP_TARGET_FIELDS.filter(field => (0, _apidomDatamodel.isStringElement)(step[field]));
+    if (declaredTargets.length > 1) {
+      throw new _ExecutionError.default(`Step "${stepId}" declares more than one of ${STEP_TARGET_FIELDS.join(', ')} (mutually exclusive)`, {
+        stepId,
+        reason: 'ambiguous-target'
+      });
+    }
+    if ((0, _apidomDatamodel.isStringElement)(step.workflowId)) {
+      throw new _ExecutionError.default(`Step "${stepId}" targets a workflowId; use the workflow executor`, {
+        stepId,
+        reason: 'workflow-step'
+      });
+    }
+
+    // locate which operation the step invokes — reduced to a (document, JSON
+    // Pointer) locator that the operation executor extracts, normalizes,
+    // assembles into a standalone doc, and runs.
+    const locator = await this.#locateOperation(step, stepId);
+
+    // resolve parameters and request body against the pre-request context.
+    // keyed by '{in}.{name}' rather than bare name, so two parameters that
+    // legally differ only in their location each reach their own place.
+    const scope = {
+      stepId
+    };
+    const preContext = state.toContext();
+    const parameters = this.#parameterResolver.resolve(step.parameters, expression => this.#evaluate(preContext, expression), scope);
+    const requestBody = this.#requestBodyResolver.resolve(step.requestBody, expression => this.#evaluate(preContext, expression), scope);
+
+    // checked here rather than on entry: locating the operation and resolving
+    // the expressions above are awaited, so a run cancelled during them would
+    // still reach this line — and this is the last moment before the step has a
+    // live side effect. The signal stays in the bag, so a request already in
+    // flight is aborted by the transport as before.
+    const signal = (0, _abort.readAbortSignal)(executeOptions);
+    (0, _abort.throwIfAborted)(signal, {
+      stepId
+    });
+
+    // the Arazzo-derived parameters and request body are spread after the opaque
+    // executeOptions bag so they take precedence over it. the operation executor
+    // then forces the operation target on top of this before executing.
+    let response;
+    try {
+      response = await this.#operationExecutor.execute(locator, {
+        ...executeOptions,
+        parameters,
+        ...this.#requestBodyOptions(requestBody)
+      });
+    } catch (error) {
+      // a transport that honors the signal rejects the request it was told to
+      // drop, which the operation executor wraps as a `ClientError` — the shape
+      // reserved for a request that failed on its own terms. Cancelled while
+      // cancelled, it did not: reporting it as the abort keeps one error shape
+      // whether the run was withdrawn between two steps or mid-flight, and keeps
+      // the whole feature from reading differently per transport.
+      (0, _abort.throwIfAborted)(signal, {
+        stepId
+      });
+      throw error;
+    }
+
+    // evaluate criteria, outputs, and the next action against the post-request
+    // context (with $request / $url / $method and $response / $statusCode).
+    const postContext = state.toContext(this.#requestContext(response), this.#responseContext(response));
+    const successful = this.evaluateCriteria(step, postContext);
+    const outputs = this.#outputResolver.resolve(step.outputs, expression => this.#evaluate(postContext, expression), scope);
+    const matchedActions = this.selectActions(step, successful, postContext);
+    return {
+      stepId,
+      response,
+      successful,
+      outputs,
+      action: matchedActions[0],
+      matchedActions
+    };
+  }
+
+  /**
+   * The request-body execute options for the step, as a typed partial to spread
+   * into the client options.
+   *
+   * Empty when the step has no request body; the `requestContentType` key is
+   * present only when a content type was resolved, so it is omitted rather than
+   * spread as `undefined`.
+   */
+  #requestBodyOptions(requestBody) {
+    if (requestBody === undefined) return {};
+    return requestBody.contentType === undefined ? {
+      requestBody: requestBody.payload
+    } : {
+      requestBody: requestBody.payload,
+      requestContentType: requestBody.contentType
+    };
+  }
+  async #locateOperation(step, stepId) {
+    if ((0, _apidomDatamodel.isStringElement)(step.operationId)) {
+      return this.#locatorNormalizer.normalizeOperationId((0, _apidomCore.toValue)(step.operationId), this.#document);
+    }
+    if ((0, _apidomDatamodel.isStringElement)(step.operationPath)) {
+      return this.#locatorNormalizer.normalizeOperationPath((0, _apidomCore.toValue)(step.operationPath), this.#document);
+    }
+    throw new _ExecutionError.default(`Step "${stepId}" has no operationId or operationPath`, {
+      stepId,
+      reason: 'missing-operation'
+    });
+  }
+
+  /**
+   * Evaluates the step's `successCriteria`; all criteria must pass. A step with
+   * no criteria succeeds on a received response.
+   *
+   * Public for the same reason as {@link StepExecutor.selectActions}: a step
+   * targeting a `workflowId` is run by the workflow executor and never reaches
+   * {@link StepExecutor.execute}, but its criteria are still the author's
+   * assertion about the step and must be evaluated somewhere.
+   */
+  evaluateCriteria(step, context) {
+    const criteria = step.successCriteria;
+    // no (or non-array) successCriteria: the step succeeds on a received response.
+    if (!(0, _apidomDatamodel.isArrayElement)(criteria)) return true;
+    for (const criterion of criteria) {
+      if (!(0, _apidomNsArazzo.isCriterionElement)(criterion)) continue;
+      const met = this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression));
+      if (!met) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Selects every matching `onSuccess` / `onFailure` action for the outcome, in
+   * list order, gating each action's criteria against the context.
+   *
+   * The step's own list is the whole story here: a step that declares none of
+   * its own already carries the workflow-level defaults, inherited by
+   * {@link ArazzoWorkflowNormalizer} — the same place a step's inherited
+   * `parameters` come from — so there is no fallback left to apply at selection
+   * time.
+   *
+   * The full matching list (not just the first) is returned so the caller can
+   * honor "retryLimit exhausted prior to subsequent failure actions"; the common
+   * caller simply takes the first.
+   *
+   * Public because selecting a step's actions is meaningful beyond running one:
+   * the workflow executor selects them for a step targeting a `workflowId`, which
+   * it runs itself and which therefore never reaches
+   * {@link StepExecutor.execute}. Both callers reach the criteria evaluator and
+   * the expression context through this one method rather than wiring their own.
+   */
+  selectActions(step, successful, context) {
+    const isCriterionMet = criterion => {
+      try {
+        return this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression));
+      } catch (error) {
+        // an action's criteria decide whether it applies to this outcome, and
+        // actions are shared — inherited from the workflow, reused from
+        // components. A condition on an HTTP exchange cannot apply to a step
+        // that calls a workflow, so the action does not match; the run does not
+        // abort over a default written for the operation steps.
+        if (error instanceof _RuntimeExpressionError.default && error.reason === 'unavailable-expression') {
+          return false;
+        }
+        throw error;
+      }
+    };
+    const scope = {
+      stepId: (0, _apidomCore.toValue)(step.stepId)
+    };
+    return successful ? this.#actionResolver.resolveOnSuccess(step.onSuccess, isCriterionMet, scope) : this.#actionResolver.resolveOnFailure(step.onFailure, isCriterionMet, scope);
+  }
+
+  /**
+   * Resolves a runtime expression leniently against a context, forwarding
+   * `$components` / `$sourceDescriptions` resolution to the document and
+   * registry.
+   */
+  #evaluate(context, expression) {
+    return new _RuntimeExpressionEvaluator.default(context, {
+      strict: false,
+      document: this.#document,
+      registry: this.#registry
+    }).evaluate(expression);
+  }
+  #responseContext(response) {
+    return {
+      statusCode: response.status,
+      header: response.headers,
+      body: response.body
+    };
+  }
+
+  /**
+   * The request context (`$url`, `$method`, `$request.header.*`,
+   * `$request.body`) from the request the client actually sent, or `undefined`
+   * when the client did not report one.
+   */
+  #requestContext(response) {
+    const request = response.request;
+    if (request === undefined) return undefined;
+    return {
+      url: request.url,
+      method: request.method,
+      header: request.headers,
+      body: request.body
+    };
+  }
+}
+var _default = exports.default = StepExecutor;