@usearazzo/runner 1.0.1-alpha.25 → 1.0.1-alpha.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usearazzo/runner",
-  "version": "1.0.1-alpha.25",
+  "version": "1.0.1-alpha.27",
   "description": "Runner for Arazzo Workflows.",
   "keywords": [
     "arazzo",
@@ -56,25 +56,25 @@
   "author": "Vladimir Gorej <vladimir.gorej@gmail.com>",
   "license": "Apache-2.0",
   "dependencies": {
-    "@babel/runtime-corejs3": "^8.0.8",
-    "@speclynx/apidom-core": "^6.1.2",
-    "@speclynx/apidom-datamodel": "^6.1.2",
-    "@speclynx/apidom-error": "^6.1.2",
-    "@speclynx/apidom-json-pointer": "^6.1.2",
-    "@speclynx/apidom-ns-arazzo-1": "^6.1.2",
-    "@speclynx/apidom-ns-openapi-2": "^6.1.2",
-    "@speclynx/apidom-ns-openapi-3-0": "^6.1.2",
-    "@speclynx/apidom-ns-openapi-3-1": "^6.1.2",
-    "@speclynx/apidom-reference": "^6.1.2",
-    "@speclynx/apidom-traverse": "^6.1.2",
+    "@babel/runtime-corejs3": "^8.1.0",
+    "@speclynx/apidom-core": "^7.0.1",
+    "@speclynx/apidom-datamodel": "^7.0.1",
+    "@speclynx/apidom-error": "^7.0.1",
+    "@speclynx/apidom-json-pointer": "^7.0.1",
+    "@speclynx/apidom-ns-arazzo-1": "^7.0.1",
+    "@speclynx/apidom-ns-openapi-2": "^7.0.1",
+    "@speclynx/apidom-ns-openapi-3-0": "^7.0.1",
+    "@speclynx/apidom-ns-openapi-3-1": "^7.0.1",
+    "@speclynx/apidom-reference": "^7.0.1",
+    "@speclynx/apidom-traverse": "^7.0.1",
     "@swaggerexpert/arazzo-criterion": "^1.0.1",
     "@swaggerexpert/arazzo-runtime-expression": "^3.3.0",
     "@swaggerexpert/cookie": "^2.1.1",
     "@swaggerexpert/json-pointer": "^3.0.2",
     "@swaggerexpert/jsonpath": "^4.0.5",
     "@swaggerexpert/media-types": "^1.0.2",
-    "@usearazzo/parser": "1.0.1-alpha.25",
-    "@usearazzo/resolver": "1.0.1-alpha.25",
+    "@usearazzo/parser": "1.0.1-alpha.27",
+    "@usearazzo/resolver": "1.0.1-alpha.27",
     "@xmldom/xmldom": "^0.9.12",
     "fontoxpath": "^3.34.0",
     "ramda": "^0.32.0",
@@ -94,5 +94,5 @@
   "devDependencies": {
     "swagger-client": "^3.38.4"
   },
-  "gitHead": "37de6e45a52dabf8a924f09fed3ae4d41396be7d"
+  "gitHead": "c2017ebba31c3a95f6f6dd0ba75058f0a19a8d0d"
 }

package/src/criterion/CriterionEvaluator.cjs

@@ -167,7 +167,7 @@ class CriterionEvaluator {
   #resolveType(criterion) {
     const type = criterion.type;
     if (type === undefined) return 'simple';
-    if ((0, _apidomNsArazzo.isCriterionExpressionTypeElement)(type) && (0, _apidomDatamodel.isStringElement)(type.type)) {
+    if ((0, _apidomNsArazzo.isExpressionTypeElement)(type) && (0, _apidomDatamodel.isStringElement)(type.type)) {
       return (0, _apidomCore.toValue)(type.type);
     }
     if ((0, _apidomDatamodel.isStringElement)(type)) return (0, _apidomCore.toValue)(type);
@@ -185,7 +185,7 @@ class CriterionEvaluator {
    */
   #resolveVersion(criterion) {
     const type = criterion.type;
-    if (!(0, _apidomNsArazzo.isCriterionExpressionTypeElement)(type) || type.version === undefined) {
+    if (!(0, _apidomNsArazzo.isExpressionTypeElement)(type) || type.version === undefined) {
       return undefined;
     }
     if ((0, _apidomDatamodel.isStringElement)(type.version)) {

package/src/criterion/CriterionEvaluator.mjs

@@ -1,6 +1,6 @@
 import { toValue } from '@speclynx/apidom-core';
 import { isStringElement } from '@speclynx/apidom-datamodel';
-import { isCriterionElement, isCriterionExpressionTypeElement } from '@speclynx/apidom-ns-arazzo-1';
+import { isCriterionElement, isExpressionTypeElement } from '@speclynx/apidom-ns-arazzo-1';
 import { test as isRuntimeExpression } from '@swaggerexpert/arazzo-runtime-expression';
 import CriterionError from "../errors/CriterionError.mjs";
 import CriterionEvaluationError from "../errors/CriterionEvaluationError.mjs";
@@ -157,7 +157,7 @@ class CriterionEvaluator {
   #resolveType(criterion) {
     const type = criterion.type;
     if (type === undefined) return 'simple';
-    if (isCriterionExpressionTypeElement(type) && isStringElement(type.type)) {
+    if (isExpressionTypeElement(type) && isStringElement(type.type)) {
       return toValue(type.type);
     }
     if (isStringElement(type)) return toValue(type);
@@ -175,7 +175,7 @@ class CriterionEvaluator {
    */
   #resolveVersion(criterion) {
     const type = criterion.type;
-    if (!isCriterionExpressionTypeElement(type) || type.version === undefined) {
+    if (!isExpressionTypeElement(type) || type.version === undefined) {
       return undefined;
     }
     if (isStringElement(type.version)) {

package/src/document/ArazzoDocument.cjs

@@ -56,8 +56,9 @@ class ArazzoDocument extends _APIDocument.default {
 
   /**
    * The workflows of this document that can be addressed by `workflowId`, in
-   * document order. Reads this document only: source descriptions are neither
-   * loaded nor listed.
+   * document order. A duplicated `workflowId` is listed once, for its first
+   * workflow. Reads this document only: source descriptions are neither loaded
+   * nor listed.
    */
   listWorkflows() {
     return [...this.workflowIndex].map(([workflowId, jsonPointer]) => {

package/src/document/ArazzoDocument.mjs

@@ -48,8 +48,9 @@ class ArazzoDocument extends APIDocument {
 
   /**
    * The workflows of this document that can be addressed by `workflowId`, in
-   * document order. Reads this document only: source descriptions are neither
-   * loaded nor listed.
+   * document order. A duplicated `workflowId` is listed once, for its first
+   * workflow. Reads this document only: source descriptions are neither loaded
+   * nor listed.
    */
   listWorkflows() {
     return [...this.workflowIndex].map(([workflowId, jsonPointer]) => {

package/src/errors/ResolverError.cjs

@@ -15,6 +15,13 @@ var _ArazzoRunnerError = _interopRequireDefault(require("./ArazzoRunnerError.cjs
  * @public
  */
 class ResolverError extends _ArazzoRunnerError.default {
+  /**
+   * A parameter of a Success / Failure Action declares an `in` inline, which
+   * the Arazzo Specification forbids; one inherited from a
+   * `$components.parameters` Reusable Object maps by name instead. Thrown
+   * before the workflow's first request.
+   */
+  static ActionParameterLocation = 'action-parameter-location';
   /** A parameter cannot be delivered unambiguously at its location. */
   static AmbiguousDelivery = 'ambiguous-delivery';
   /** An output or a request body payload holds a value that is not a valid runtime expression. */

package/src/errors/ResolverError.mjs

@@ -8,6 +8,13 @@ import ArazzoRunnerError from "./ArazzoRunnerError.mjs";
  * @public
  */
 class ResolverError extends ArazzoRunnerError {
+  /**
+   * A parameter of a Success / Failure Action declares an `in` inline, which
+   * the Arazzo Specification forbids; one inherited from a
+   * `$components.parameters` Reusable Object maps by name instead. Thrown
+   * before the workflow's first request.
+   */
+  static ActionParameterLocation = 'action-parameter-location';
   /** A parameter cannot be delivered unambiguously at its location. */
   static AmbiguousDelivery = 'ambiguous-delivery';
   /** An output or a request body payload holds a value that is not a valid runtime expression. */

package/src/executor/StepExecutor.cjs

@@ -224,7 +224,8 @@ class StepExecutor {
       action: matchedActions[0],
       matchedActions,
       successCriteria,
-      actionCriteria
+      actionCriteria,
+      actionContext: this.actionContext(postContext, stepId, outputs)
     };
   }
 
@@ -366,6 +367,28 @@ class StepExecutor {
     };
   }
 
+  /**
+   * The context a step's actions are taken in — see
+   * {@link StepExecutionResult.actionContext}: `context` with
+   * `$steps.{stepId}.outputs` replaced by the outputs the attempt just
+   * resolved, as a fresh object, so run state is never written.
+   *
+   * Public for the same reason as {@link StepExecutor.selectActions}: the
+   * workflow executor builds this context for a step targeting a
+   * `workflowId`, which never reaches {@link StepExecutor.execute}.
+   */
+  actionContext(context, stepId, outputs) {
+    return {
+      ...context,
+      steps: {
+        ...context.steps,
+        [stepId]: {
+          outputs
+        }
+      }
+    };
+  }
+
   /**
    * Evaluates one criterion into a {@link CriterionEvaluationRecord}. A
    * condition that cannot be evaluated is unmet and records why; any other

package/src/executor/StepExecutor.mjs

@@ -217,7 +217,8 @@ class StepExecutor {
       action: matchedActions[0],
       matchedActions,
       successCriteria,
-      actionCriteria
+      actionCriteria,
+      actionContext: this.actionContext(postContext, stepId, outputs)
     };
   }
 
@@ -359,6 +360,28 @@ class StepExecutor {
     };
   }
 
+  /**
+   * The context a step's actions are taken in — see
+   * {@link StepExecutionResult.actionContext}: `context` with
+   * `$steps.{stepId}.outputs` replaced by the outputs the attempt just
+   * resolved, as a fresh object, so run state is never written.
+   *
+   * Public for the same reason as {@link StepExecutor.selectActions}: the
+   * workflow executor builds this context for a step targeting a
+   * `workflowId`, which never reaches {@link StepExecutor.execute}.
+   */
+  actionContext(context, stepId, outputs) {
+    return {
+      ...context,
+      steps: {
+        ...context.steps,
+        [stepId]: {
+          outputs
+        }
+      }
+    };
+  }
+
   /**
    * Evaluates one criterion into a {@link CriterionEvaluationRecord}. A
    * condition that cannot be evaluated is unmet and records why; any other

package/src/executor/StepRetryRunner.cjs

@@ -149,7 +149,7 @@ class StepRetryRunner {
         // zero/negative/NaN value.
         const delayMs = this.#retryAfterMs(action);
         if (delayMs > 0) await this.#sleep(delayMs, context.signal);
-        if (runReference !== undefined) await runReference(action);
+        if (runReference !== undefined) await runReference(action, outcome);
         fired = true;
         break;
       }

package/src/executor/StepRetryRunner.mjs

@@ -139,7 +139,7 @@ class StepRetryRunner {
         // zero/negative/NaN value.
         const delayMs = this.#retryAfterMs(action);
         if (delayMs > 0) await this.#sleep(delayMs, context.signal);
-        if (runReference !== undefined) await runReference(action);
+        if (runReference !== undefined) await runReference(action, outcome);
         fired = true;
         break;
       }

package/src/executor/WorkflowExecutor.cjs

@@ -301,6 +301,16 @@ class WorkflowExecutor {
     // included: an unreadable assertion found at step three must not cost the
     // run the requests of steps one and two.
     for (const step of steps) this.#stepExecutor.assertSuccessCriteria(step, workflowId);
+    // and to every action's `parameters`, for the same reason: an `in` the
+    // specification forbids must not cost the run the requests before the
+    // step whose action carries it.
+    // the workflow's own default actions too: one every step overrides by
+    // name never reaches a step's list, yet the validator still reports it.
+    this.#assertActionParameters([workflow.successActions, workflow.failureActions], workflowId);
+    for (const step of steps) {
+      const stepId = (0, _apidomCore.toValue)(step.stepId);
+      this.#assertActionParameters([step.onSuccess, step.onFailure], workflowId, stepId);
+    }
     const dependencies = await this.#runDependencies(workflow, invocation, scope);
     if (dependencies.some(dependency => this.#settledFailed(dependency))) {
       // a declared prerequisite did not complete, so this workflow cannot be
@@ -396,7 +406,7 @@ class WorkflowExecutor {
               stepId,
               callStack: nested
             });
-            const transferredTo = await this.#runReferencedWorkflow(transition.workflowId, stepId, invocation, scope, 'goto');
+            const transferredTo = await this.#runReferencedWorkflow(transition.workflowId, stepId, invocation, scope, 'goto', this.#actionInputs(action?.parameters, outcome, invocation, stepId));
             runOutcome = {
               kind: 'transferred',
               transferredTo
@@ -572,16 +582,16 @@ class WorkflowExecutor {
    *   for entering the reference itself, matching the "1 for the step itself
    *   plus whatever its sub-run spends" convention a sub-workflow step
    *   already follows (without it, a reference to a workflow with few or no
-   *   steps of its own would cost nothing to fire). It runs with no inputs:
-   *   the specification gives a retry reference no input-mapping mechanism
-   *   of its own (the same gap `dependsOn` has), and `{}` is the only
-   *   spec-honest fallback — see issue `#62`. Its outputs are recorded via
-   *   `state.setWorkflow`, which *is* "context transfers back" — but its
-   *   `inputs` are preserved rather than overwritten with `{}` when this
-   *   workflowId was already recorded (by an earlier `dependsOn` prerequisite
-   *   or sub-workflow step sharing the id): this call's own lack of a real
-   *   inputs value must not erase one a different, better-informed caller
-   *   already gave.
+   *   steps of its own would cost nothing to fire). Its inputs are the
+   *   action's `parameters` (`#115`), resolved again on every firing
+   *   against the attempt that fired it — `{}` without them. Its outputs are
+   *   recorded via `state.setWorkflow`, which *is* "context transfers back",
+   *   together with the inputs it ran with when the action carries
+   *   `parameters`. Without them, the recorded `inputs` are preserved rather
+   *   than overwritten with `{}` when this workflowId was already recorded
+   *   (by an earlier `dependsOn` prerequisite or sub-workflow step sharing
+   *   the id): this call's own lack of a real inputs value must not erase one
+   *   a different, better-informed caller already gave.
    * - a `stepId` reference must name a step of the current workflow (checked
    *   lazily, at fire time, via the same lookup a `goto` target uses) and
    *   runs as one more attempt at that step, through
@@ -604,7 +614,7 @@ class WorkflowExecutor {
       state,
       callStack
     } = invocation;
-    return async action => {
+    return async (action, outcome) => {
       (0, _abort.throwIfAborted)(scope.signal, {
         workflowId,
         stepId,
@@ -623,13 +633,16 @@ class WorkflowExecutor {
       }
       if (hasWorkflowId) {
         const reference = (0, _apidomCore.toValue)(action.workflowId);
+        // resolved before the budget is charged, so an authoring error in them
+        // costs no budget unit.
+        const inputs = this.#actionInputs(action.parameters, outcome, invocation, stepId);
         this.#chargeBudget(scope, invocation, stepId);
-        const result = await this.#runReferencedWorkflow(reference, stepId, invocation, scope, 'retry');
+        const result = await this.#runReferencedWorkflow(reference, stepId, invocation, scope, 'retry', inputs);
         // the result's workflowId is the bare id the reference resolved to —
         // the key run state is recorded under, whichever document owns it.
         const refId = result.workflowId;
         state.setWorkflow(refId, {
-          inputs: state.getWorkflow(refId)?.inputs ?? {},
+          inputs: action.hasKey('parameters') ? inputs : state.getWorkflow(refId)?.inputs ?? {},
           outputs: result.outputs
         });
         retryReferences.push({
@@ -647,12 +660,12 @@ class WorkflowExecutor {
       });
       const refStep = steps[refIndex];
       const refSubWorkflows = [];
-      const outcome = await this.#chargedAttempt(this.#stepAttempt(refStep, refStepId, invocation, scope, refSubWorkflows), invocation, scope, refStepId)();
-      state.setStepOutputs(outcome.stepId, outcome.outputs);
+      const refOutcome = await this.#chargedAttempt(this.#stepAttempt(refStep, refStepId, invocation, scope, refSubWorkflows), invocation, scope, refStepId)();
+      state.setStepOutputs(refOutcome.stepId, refOutcome.outputs);
       retryReferences.push({
         kind: 'step',
         id: refStepId,
-        successful: outcome.successful,
+        successful: refOutcome.successful,
         ...(refSubWorkflows.length > 0 ? {
           subWorkflow: refSubWorkflows[0]
         } : {})
@@ -905,7 +918,8 @@ class WorkflowExecutor {
         action: matchedActions[0],
         matchedActions,
         successCriteria,
-        actionCriteria
+        actionCriteria,
+        actionContext: stepExecutor.actionContext(context, stepId, outputs)
       };
     };
   }
@@ -962,20 +976,95 @@ class WorkflowExecutor {
   /**
    * Runs a workflow an action references directly — a retry's `workflowId`
    * reference or a goto's transfer, plain id or cross-document expression —
-   * with `{}` inputs, since neither has an input-mapping mechanism of its own
-   * (issue `#62`).
+   * with the inputs its action's `parameters` resolved to (`#115`), `{}`
+   * without them.
    *
    * Shared rather than duplicated by its two callers, which otherwise repeat
-   * the identical "resolve the reference, then run with no inputs" sequence.
+   * the identical "resolve the reference, then run it" sequence.
    * A target its document does not define is rejected by the normalizer,
    * attributed to the calling workflow and `stepId`.
    */
-  async #runReferencedWorkflow(reference, stepId, invocation, scope, via) {
+  async #runReferencedWorkflow(reference, stepId, invocation, scope, via, inputs) {
     const locator = await this.#workflowLocatorNormalizer.normalize(reference, invocation.document, {
       workflowId: invocation.workflowId,
       stepId
     });
-    return this.#run(locator, {}, scope, invocation.callStack, via);
+    return this.#run(locator, inputs, scope, invocation.callStack, via);
+  }
+
+  /**
+   * The inputs a `goto` / `retry` action naming a `workflowId` passes its
+   * target: the action's own `parameters`, mapped by name and resolved against
+   * the context of the attempt that fired it — `$statusCode`, `$response.*`
+   * and the rest of that step outcome, plus the outputs it just produced.
+   * Resolved against the calling invocation's document, so its `$components`
+   * apply, never the target's. No `parameters` gives `{}`. Their shape was
+   * checked before the workflow's first request, by
+   * {@link WorkflowExecutor.#assertActionParameters}.
+   */
+  #actionInputs(parameters, outcome, invocation, stepId) {
+    const {
+      workflowId,
+      document
+    } = invocation;
+    return this.#parameterResolver.resolve(parameters, expression => this.#evaluate(outcome.actionContext, expression, document), {
+      workflowId,
+      stepId
+    });
+  }
+
+  /**
+   * Throws {@link ResolverError} unless every action in `lists` — a step's
+   * `onSuccess` / `onFailure`, or the workflow's own `successActions` /
+   * `failureActions` — has an absent `parameters` or a list free of inline `in`:
+   * `malformed-parameters` for one that is present but not a list,
+   * `action-parameter-location` for a Parameter Object that declares `in`. The
+   * specification says outright that "The `in` field MUST NOT be used" on
+   * them. An `in` arriving through a `$components.parameters` Reusable Object
+   * is not inline — a shared component carries `in` for the operation steps
+   * that use it — and the dereferencer marks the transcluded copy with
+   * `ref-fields`.
+   *
+   * Checked for every action, `workflowId` or not, before any step of the
+   * workflow runs: both are authoring errors the validator reports, so a run
+   * must not make requests on the way to discovering them. Valid `parameters`
+   * on an action naming no `workflowId` are still ignored, as the validator
+   * only warns about them. A list that is not an array is skipped here and left
+   * for the code that reads it to report. `stepId` is absent for the
+   * workflow's own lists, and the error then names the workflow alone.
+   */
+  #assertActionParameters(lists, workflowId, stepId) {
+    const owner = stepId === undefined ? `workflow "${workflowId}"` : `step "${stepId}" in workflow "${workflowId}"`;
+    for (const actions of lists) {
+      if (!(0, _apidomDatamodel.isArrayElement)(actions)) continue;
+      for (const action of actions) {
+        if (!(0, _apidomNsArazzo.isSuccessActionElement)(action) && !(0, _apidomNsArazzo.isFailureActionElement)(action)) continue;
+        if (!action.hasKey('parameters')) continue;
+        const scope = {
+          workflowId,
+          ...(stepId === undefined ? {} : {
+            stepId
+          }),
+          target: 'parameters'
+        };
+        const {
+          parameters
+        } = action;
+        if (!(0, _apidomDatamodel.isArrayElement)(parameters)) {
+          throw new _ResolverError.default('`parameters` is present but is not a list', {
+            ...scope,
+            reason: _ResolverError.default.MalformedParameters
+          });
+        }
+        const inline = [...parameters].some(parameter => (0, _apidomNsArazzo.isParameterElement)(parameter) && parameter.hasKey('in') && !parameter.meta.hasKey('ref-fields'));
+        if (inline) {
+          throw new _ResolverError.default(`An action parameter of ${owner} declares an \`in\`; action parameters map to the target workflow's inputs by name`, {
+            ...scope,
+            reason: _ResolverError.default.ActionParameterLocation
+          });
+        }
+      }
+    }
   }
 
   /**