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

package/src/executor/StepExecutor.mjs

@@ -0,0 +1,326 @@
+import { toValue } from '@speclynx/apidom-core';
+import { isArrayElement, isStringElement } from '@speclynx/apidom-datamodel';
+import { isCriterionElement } from '@speclynx/apidom-ns-arazzo-1';
+import RuntimeExpressionEvaluator from "../expression/RuntimeExpressionEvaluator.mjs";
+import CriterionEvaluator from "../criterion/CriterionEvaluator.mjs";
+import OpenAPIOperationParameterResolver from "../resolver/OpenAPIOperationParameterResolver.mjs";
+import RequestBodyResolver from "../resolver/RequestBodyResolver.mjs";
+import OutputResolver from "../resolver/OutputResolver.mjs";
+import ActionResolver from "../action/ActionResolver.mjs";
+import OpenAPIOperationLocatorNormalizer from "./OpenAPIOperationLocatorNormalizer.mjs";
+import ExecutionError from "../errors/ExecutionError.mjs";
+import RuntimeExpressionError from "../errors/RuntimeExpressionError.mjs";
+import { readAbortSignal, throwIfAborted } from "./abort.mjs";
+/**
+ * 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
+ */
+export const 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();
+  #requestBodyResolver = new RequestBodyResolver();
+  #outputResolver = new OutputResolver();
+  #criterionEvaluator = new CriterionEvaluator();
+  #actionResolver = new ActionResolver();
+  constructor(options) {
+    this.#document = options.document;
+    this.#registry = options.registry;
+    this.#locatorNormalizer = new OpenAPIOperationLocatorNormalizer(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 = 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 => isStringElement(step[field]));
+    if (declaredTargets.length > 1) {
+      throw new ExecutionError(`Step "${stepId}" declares more than one of ${STEP_TARGET_FIELDS.join(', ')} (mutually exclusive)`, {
+        stepId,
+        reason: 'ambiguous-target'
+      });
+    }
+    if (isStringElement(step.workflowId)) {
+      throw new ExecutionError(`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 = readAbortSignal(executeOptions);
+    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.
+      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 (isStringElement(step.operationId)) {
+      return this.#locatorNormalizer.normalizeOperationId(toValue(step.operationId), this.#document);
+    }
+    if (isStringElement(step.operationPath)) {
+      return this.#locatorNormalizer.normalizeOperationPath(toValue(step.operationPath), this.#document);
+    }
+    throw new ExecutionError(`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 (!isArrayElement(criteria)) return true;
+    for (const criterion of criteria) {
+      if (!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 && error.reason === 'unavailable-expression') {
+          return false;
+        }
+        throw error;
+      }
+    };
+    const scope = {
+      stepId: 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(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
+    };
+  }
+}
+export default StepExecutor;

package/src/executor/StepRetryRunner.cjs

@@ -0,0 +1,226 @@
+"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 _ExecutionError = _interopRequireDefault(require("../errors/ExecutionError.cjs"));
+/**
+ * What one attempt at a step produced.
+ *
+ * Both kinds of step reduce to this — an operation step (whose richer
+ * `StepExecutionResult` satisfies this shape) and a sub-workflow step
+ * (synthesized from the sub-run's outcome) — so the retry loop drives them
+ * identically and knows nothing about either.
+ * @internal
+ */
+
+/**
+ * The terminal outcome of a step once its retries are settled.
+ * @internal
+ */
+
+/**
+ * Options for the StepRetryRunner.
+ * @internal
+ */
+
+/**
+ * Which step is being run — carried for diagnostics, plus the run's cancellation
+ * so the wait between attempts can be cut short.
+ * @internal
+ */
+
+/**
+ * Runs a step until its `retry` failure actions are settled.
+ *
+ * On success, or an immediate non-retry failure, the step runs once. On a failure
+ * whose first matching action is a `retry`, the step is re-run up to that
+ * action's `retryLimit` (default 1), waiting `retryAfter` seconds between
+ * attempts. Per Arazzo 1.0.1 — "retryLimit MUST be exhausted prior to executing
+ * subsequent failure actions" — an exhausted retry falls through to the *next*
+ * matching failure action of the latest attempt, which may itself be another
+ * `retry` with its own independent budget, or a terminal `end` / `goto`. Each
+ * attempt re-runs the step and re-selects against the fresh outcome, so an action
+ * whose criteria stop matching stops being chosen.
+ *
+ * It is agnostic about what a step *is*: the caller supplies a thunk that runs one
+ * attempt and returns its {@link StepAttemptOutcome}, which is what lets an
+ * operation step and a sub-workflow step retry through identical machinery. That
+ * thunk is also where a caller puts anything it wants done per attempt — charging
+ * a run budget, say — so this class needs no notion of one; a thunk that throws
+ * ends the step there, without further attempts. One consequence is worth
+ * knowing: a `retryAfter` delay is awaited before the next attempt begins, so a
+ * caller whose per-attempt check is about to fail (a spent budget, say) still
+ * pays that delay before its error surfaces. Keeping the seam this narrow is
+ * worth one bounded wait on a run that was already doomed.
+ *
+ * A `retry` action's `stepId` / `workflowId` reference works the same way: this
+ * class only decides *when* one fires (once per firing, after the `retryAfter`
+ * wait, before the step is re-run) — it hands the action to
+ * {@link StepRetryRunContext.runReference} and knows nothing about *what* the
+ * reference is or how it runs. A caller that omits that callback gets the
+ * standalone rejection instead of a silently ignored reference.
+ *
+ * Cancellation is the one thing it will not wait out: the run's `AbortSignal`
+ * reaches the timer, which returns early, and the next attempt then trips the
+ * caller's own check. Turning an abort into an error stays the caller's job, as
+ * with the budget; the signal is here only because a wait already in progress
+ * cannot be cut short from inside the thunk.
+ * @internal
+ */
+class StepRetryRunner {
+  static #DEFAULT_RETRY_LIMIT = 1;
+  /**
+   * A real timer that stops waiting as soon as the run is cancelled, and leaves
+   * no pending timeout behind either way — a `retryAfter` of minutes would
+   * otherwise hold the event loop open long after the caller walked away.
+   *
+   * It resolves on abort rather than rejecting: turning a cancellation into an
+   * error is the caller's per-attempt check, which reports it uniformly for a
+   * run cancelled mid-wait and one cancelled mid-request.
+   */
+  static #DEFAULT_SLEEP = (ms, signal) => new Promise(resolve => {
+    if (signal?.aborted === true) {
+      resolve();
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    // unsubscribed when the wait ends normally, so a signal outliving many
+    // retries does not accumulate a listener per wait.
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, {
+      once: true
+    });
+  });
+  #sleep;
+  constructor(options = {}) {
+    this.#sleep = options.sleep ?? StepRetryRunner.#DEFAULT_SLEEP;
+  }
+
+  /**
+   * Runs `attempt` until the step succeeds, a terminal failure action is reached,
+   * or its retries are exhausted.
+   */
+  async run(attempt, context) {
+    // attempts already spent on each retry action, keyed by the action element.
+    // The element is the correct identity here: re-running the step returns the
+    // same element instances (the workflow is normalized once and `onFailure`'s
+    // getter returns its stored children — nothing re-refracts per call), and
+    // keying by the element survives the criteria re-filtering that varies
+    // `matchedActions` between attempts (position within that filtered list is
+    // NOT stable when a response change drops an earlier action). So each retry
+    // in a chain keeps its own independent budget across re-runs.
+    const retriesSpent = new Map();
+    let attempts = 0;
+    for (;;) {
+      const outcome = await attempt();
+      attempts += 1;
+      if (outcome.successful) {
+        return {
+          outcome,
+          action: outcome.action,
+          attempts
+        };
+      }
+
+      // walk the matching failure actions: fire the first retry that still has
+      // budget, else fall through to the first terminal (non-retry) action.
+      let fired = false;
+      let terminal;
+      for (const action of outcome.matchedActions) {
+        if (!this.#isRetry(action)) {
+          terminal = action;
+          break;
+        }
+        const spent = retriesSpent.get(action) ?? 0;
+        if (spent >= this.#retryLimit(action)) continue; // exhausted — try the next action
+
+        const carriesReference = this.#carriesReference(action);
+        // narrowed once here rather than asserted at the call site below: by
+        // the time `runReference` is invoked, its absence would already have
+        // thrown on the line above, so the type reflects that instead of
+        // relying on a non-null assertion to say so.
+        const runReference = carriesReference ? context.runReference : undefined;
+        if (carriesReference && runReference === undefined) this.#rejectReference(context);
+        retriesSpent.set(action, spent + 1);
+        // only sleep for a real, positive delay — skip the event-loop yield of
+        // sleep(0) for immediate retries, and never hand a custom sleep a
+        // zero/negative/NaN value.
+        const delayMs = this.#retryAfterMs(action);
+        if (delayMs > 0) await this.#sleep(delayMs, context.signal);
+        if (runReference !== undefined) await runReference(action);
+        fired = true;
+        break;
+      }
+      if (fired) continue; // re-run the step
+      return {
+        outcome,
+        action: terminal,
+        attempts
+      };
+    }
+  }
+
+  /**
+   * Whether a matched action is a `retry` failure action (narrowing it to
+   * {@link FailureActionElement} so `retryLimit` / `retryAfter` are accessible).
+   */
+  #isRetry(action) {
+    return (0, _apidomNsArazzo.isFailureActionElement)(action) && (0, _apidomCore.toValue)(action.type) === 'retry';
+  }
+
+  /**
+   * A `retry` action's attempt budget — its `retryLimit`, or the default of 1
+   * when unset or non-numeric.
+   */
+  #retryLimit(action) {
+    return (0, _apidomDatamodel.isNumberElement)(action.retryLimit) ? (0, _apidomCore.toValue)(action.retryLimit) : StepRetryRunner.#DEFAULT_RETRY_LIMIT;
+  }
+
+  /**
+   * The delay before a retry, in milliseconds — the action's `retryAfter`
+   * (seconds) converted. `0` when unset, non-numeric, or not a finite positive
+   * value (a negative or `NaN` `retryAfter` means "no wait", never a bad value
+   * handed to `sleep`).
+   */
+  #retryAfterMs(action) {
+    if (!(0, _apidomDatamodel.isNumberElement)(action.retryAfter)) return 0;
+    const ms = (0, _apidomCore.toValue)(action.retryAfter) * 1000;
+    return Number.isFinite(ms) && ms > 0 ? ms : 0;
+  }
+
+  /**
+   * Whether a `retry` action carries a `stepId` / `workflowId` reference to
+   * execute before retrying ("the reference is executed and the context is
+   * returned, after which the current step is retried").
+   */
+  #carriesReference(action) {
+    return (0, _apidomDatamodel.isStringElement)(action.stepId) || (0, _apidomDatamodel.isStringElement)(action.workflowId);
+  }
+
+  /**
+   * Rejects a referenced `retry` action when the caller supplied no
+   * {@link StepRetryRunContext.runReference}, so an unsupported caller
+   * (or a step retried directly against this runner in isolation) fails
+   * loudly rather than silently ignoring the reference.
+   */
+  #rejectReference(context) {
+    throw new _ExecutionError.default(`retry action on step "${context.stepId}" in workflow "${context.workflowId}" carries a stepId/workflowId reference, but no runReference was given to run it`, {
+      stepId: context.stepId,
+      workflowId: context.workflowId,
+      reason: 'retry-reference-unsupported'
+    });
+  }
+}
+var _default = exports.default = StepRetryRunner;