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

package/src/executor/abort.cjs

@@ -0,0 +1,70 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.throwIfAborted = exports.readAbortSignal = void 0;
+var _ExecutionError = _interopRequireDefault(require("../errors/ExecutionError.cjs"));
+/**
+ * Where a run was when it observed the caller's abort — carried into the error
+ * so both the message and its structured fields name the boundary the run
+ * stopped at. Both names are optional because the observers sit at different
+ * depths: the workflow executor knows the workflow and (between attempts) the
+ * step, while a {@link StepExecutor} used on its own knows only the step.
+ * @internal
+ */
+
+/**
+ * Reads the `AbortSignal` a caller put in the opaque execute options bag, or
+ * `undefined` when there is none.
+ *
+ * Duck-typed rather than `instanceof AbortSignal`: the bag is the caller's, and
+ * a signal made in another realm (a worker, a test harness, a polyfill) must
+ * still cancel the run.
+ *
+ * The whole surface the runner uses is required, not just `aborted`: what comes
+ * back is subscribed to as well as read (the abortable retry wait), so admitting
+ * a bare `{ aborted: false }` would trade a wrong-but-working run for a
+ * `TypeError` thrown from inside a `retryAfter` delay. Anything short of that
+ * surface is treated as no signal at all — the bag is open, and a value the
+ * runner cannot drive is not a cancellation.
+ * @internal
+ */
+const readAbortSignal = options => {
+  const signal = options.signal;
+  if (typeof signal !== 'object' || signal === null) return undefined;
+  const usable = typeof signal.aborted === 'boolean' && typeof signal.addEventListener === 'function' && typeof signal.removeEventListener === 'function';
+  return usable ? signal : undefined;
+};
+
+/**
+ * Throws `reason: 'aborted'` when the caller has cancelled the run, and does
+ * nothing otherwise.
+ *
+ * Cancellation throws rather than resolving as a `failed` result because it is
+ * not a workflow outcome: nothing was judged by `successCriteria`, no failure
+ * action was consulted, and the steps that did not run were not *decided*
+ * against. A result would be indistinguishable from the API having answered.
+ * The signal's own `reason` travels as the error's `cause`, so a caller that
+ * aborted with a meaningful value keeps it.
+ * @internal
+ */
+exports.readAbortSignal = readAbortSignal;
+const throwIfAborted = (signal, context) => {
+  if (signal?.aborted !== true) return;
+  const {
+    workflowId,
+    stepId,
+    callStack
+  } = context;
+  const where = [stepId === undefined ? undefined : `step "${stepId}"`, workflowId === undefined ? undefined : `workflow "${workflowId}"`].filter(part => part !== undefined).join(' in ');
+  throw new _ExecutionError.default(`run aborted before ${where}`, {
+    workflowId,
+    stepId,
+    reason: 'aborted',
+    path: callStack?.path,
+    cause: signal.reason
+  });
+};
+exports.throwIfAborted = throwIfAborted;

package/src/executor/abort.mjs

@@ -0,0 +1,60 @@
+import ExecutionError from "../errors/ExecutionError.mjs";
+/**
+ * Where a run was when it observed the caller's abort — carried into the error
+ * so both the message and its structured fields name the boundary the run
+ * stopped at. Both names are optional because the observers sit at different
+ * depths: the workflow executor knows the workflow and (between attempts) the
+ * step, while a {@link StepExecutor} used on its own knows only the step.
+ * @internal
+ */
+/**
+ * Reads the `AbortSignal` a caller put in the opaque execute options bag, or
+ * `undefined` when there is none.
+ *
+ * Duck-typed rather than `instanceof AbortSignal`: the bag is the caller's, and
+ * a signal made in another realm (a worker, a test harness, a polyfill) must
+ * still cancel the run.
+ *
+ * The whole surface the runner uses is required, not just `aborted`: what comes
+ * back is subscribed to as well as read (the abortable retry wait), so admitting
+ * a bare `{ aborted: false }` would trade a wrong-but-working run for a
+ * `TypeError` thrown from inside a `retryAfter` delay. Anything short of that
+ * surface is treated as no signal at all — the bag is open, and a value the
+ * runner cannot drive is not a cancellation.
+ * @internal
+ */
+export const readAbortSignal = options => {
+  const signal = options.signal;
+  if (typeof signal !== 'object' || signal === null) return undefined;
+  const usable = typeof signal.aborted === 'boolean' && typeof signal.addEventListener === 'function' && typeof signal.removeEventListener === 'function';
+  return usable ? signal : undefined;
+};
+
+/**
+ * Throws `reason: 'aborted'` when the caller has cancelled the run, and does
+ * nothing otherwise.
+ *
+ * Cancellation throws rather than resolving as a `failed` result because it is
+ * not a workflow outcome: nothing was judged by `successCriteria`, no failure
+ * action was consulted, and the steps that did not run were not *decided*
+ * against. A result would be indistinguishable from the API having answered.
+ * The signal's own `reason` travels as the error's `cause`, so a caller that
+ * aborted with a meaningful value keeps it.
+ * @internal
+ */
+export const throwIfAborted = (signal, context) => {
+  if (signal?.aborted !== true) return;
+  const {
+    workflowId,
+    stepId,
+    callStack
+  } = context;
+  const where = [stepId === undefined ? undefined : `step "${stepId}"`, workflowId === undefined ? undefined : `workflow "${workflowId}"`].filter(part => part !== undefined).join(' in ');
+  throw new ExecutionError(`run aborted before ${where}`, {
+    workflowId,
+    stepId,
+    reason: 'aborted',
+    path: callStack?.path,
+    cause: signal.reason
+  });
+};

package/src/expression/RuntimeExpressionContext.cjs

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/src/expression/RuntimeExpressionContext.mjs

@@ -0,0 +1 @@
+export {};

package/src/expression/RuntimeExpressionEvaluator.cjs

@@ -0,0 +1,337 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _parser = require("@usearazzo/parser");
+var _arazzoRuntimeExpression = require("@swaggerexpert/arazzo-runtime-expression");
+var _jsonPointer = require("@swaggerexpert/json-pointer");
+var _json = _interopRequireDefault(require("@swaggerexpert/json-pointer/evaluate/realms/json"));
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _apidomCore = require("@speclynx/apidom-core");
+var _RuntimeExpressionError = _interopRequireDefault(require("../errors/RuntimeExpressionError.cjs"));
+var _ArazzoDocument = _interopRequireDefault(require("../document/ArazzoDocument.cjs"));
+var _OpenAPIDocument = _interopRequireDefault(require("../document/OpenAPIDocument.cjs"));
+/**
+ * Options for the RuntimeExpressionEvaluator.
+ * @public
+ */
+
+/**
+ * The request/response side of the context a `$request`/`$response` source is
+ * evaluated against. Both request and response contexts are assignable to this
+ * shape; sources absent from a side (e.g. `$response.query`) resolve to
+ * `undefined` naturally.
+ */
+
+/**
+ * Realm for drilling JSON Pointers into payload values. Composing the ApiDOM
+ * realm ahead of the JSON realm lets a single `evaluate` call handle plain JS
+ * values, ApiDOM elements, and mixed trees: the ApiDOM realm claims elements
+ * and falls through to the JSON realm for plain values. Order matters — the
+ * JSON realm would otherwise greedily claim ApiDOM elements and fail.
+ */
+const pointerRealm = (0, _jsonPointer.composeRealms)(new _apidomJsonPointer.ApiDOMEvaluationRealm(), new _json.default());
+
+/**
+ * The expression roots that describe one HTTP exchange — unavailable in a step
+ * that calls a workflow, which makes none.
+ */
+const HTTP_EXCHANGE_NODES = new Set(['UrlExpression', 'MethodExpression', 'StatusCodeExpression', 'RequestExpression', 'ResponseExpression']);
+
+/**
+ * Evaluates Arazzo runtime expressions against a context.
+ *
+ * A single evaluator is bound to one context and can evaluate many expressions
+ * against it — matching how a step executor resolves a step's parameters,
+ * success criteria, and outputs from the same state.
+ *
+ * The context holds only runtime state (`$inputs`, `$steps`, `$request`,
+ * `$response`, …). Static, document-sourced expressions are resolved on demand:
+ * `$components` and `$workflows.{workflowId}.steps.{stepId}` from the
+ * evaluator's document, and `$sourceDescriptions` from the external document
+ * (via the registry) the source name points at. A step reference resolves to
+ * the Step Object as authored — a locator, not the step's execution result.
+ *
+ * A reference resolves to `undefined` when it is absent. Runtime values
+ * originate from JSON (or ApiDOM), which cannot represent `undefined` — an
+ * absent value is a missing property and an explicit null is `null` — so
+ * `undefined` unambiguously marks "unresolved".
+ *
+ * Three modes are supported:
+ * - {@link RuntimeExpressionEvaluator.evaluate} resolves a pure expression
+ *   (e.g. `$response.body#/id`) to its typed value.
+ * - {@link RuntimeExpressionEvaluator.interpolate} renders a template with
+ *   embedded `{expression}` occurrences to a string.
+ * - {@link RuntimeExpressionEvaluator.resolve} applies Arazzo "value" semantics:
+ *   a value that is itself a complete expression resolves to a typed value,
+ *   otherwise the value is interpolated to a string.
+ * @public
+ */
+class RuntimeExpressionEvaluator {
+  #context;
+  #strict;
+  #document;
+  #registry;
+  constructor(context, options = {}) {
+    this.#context = context;
+    this.#strict = options.strict ?? true;
+    this.#document = options.document;
+    this.#registry = options.registry;
+  }
+
+  /**
+   * Evaluates a pure runtime expression to its typed value.
+   *
+   * The expression must be the bare form without surrounding braces
+   * (e.g. `$inputs.username`, `$response.body#/pets/0/id`). In strict mode an
+   * unresolvable reference throws; otherwise it returns `undefined`.
+   */
+  evaluate(expression) {
+    const node = this.#parse(expression);
+    this.#assertAvailable(node, expression);
+    const value = this.#evaluateNode(node, expression);
+    if (value === undefined && this.#strict) {
+      throw new _RuntimeExpressionError.default(`Runtime expression "${expression}" could not be resolved against the context`, {
+        expression,
+        reason: 'unresolved-reference'
+      });
+    }
+    return value;
+  }
+
+  /**
+   * Renders a template string, replacing each embedded `{expression}` with the
+   * string form of its evaluated value. Returns a string.
+   *
+   * Object and array values are serialized with `JSON.stringify`. In non-strict
+   * mode, unresolvable references render as an empty string. A `{…}` that is not
+   * a valid embedded expression (e.g. a literal JSON payload) is left unchanged.
+   */
+  interpolate(template) {
+    return (0, _arazzoRuntimeExpression.interpolate)(template, expression => this.evaluate(expression));
+  }
+
+  /**
+   * Resolves an Arazzo "value" string.
+   *
+   * A value that is itself a complete runtime expression (the unbraced form,
+   * e.g. `$inputs.userId`) resolves to its typed value — "runtime expressions
+   * preserve the type of the referenced value". Any other string is an
+   * expression-string template: embedded `{expression}` occurrences are
+   * interpolated and a string is returned, so a whole-string `{expression}`
+   * yields the string representation of its value, not the typed value. A
+   * string containing no expressions is returned unchanged.
+   */
+  resolve(value) {
+    // `test` returns true only when the entire string is a valid runtime
+    // expression, so a braced or mixed string falls through to interpolation.
+    return (0, _arazzoRuntimeExpression.test)(value) ? this.evaluate(value) : this.interpolate(value);
+  }
+
+  /**
+   * Parses an expression to its AST, throwing on failure regardless of strict mode.
+   */
+  #parse(expression) {
+    let result;
+    try {
+      result = (0, _parser.parseRuntimeExpression)(expression);
+    } catch (error) {
+      throw new _RuntimeExpressionError.default(`Failed to parse runtime expression "${expression}"`, {
+        cause: error,
+        expression,
+        reason: 'parse-error'
+      });
+    }
+    if (!result.result.success || result.tree === undefined) {
+      throw new _RuntimeExpressionError.default(`Invalid runtime expression "${expression}"`, {
+        expression,
+        reason: 'invalid-expression'
+      });
+    }
+    return result.tree;
+  }
+
+  /**
+   * Rejects an HTTP-exchange expression in a step that calls a workflow. Such a
+   * step made no HTTP call, so the expression is an authoring error there — not
+   * a reference that merely did not resolve — and throws regardless of `strict`.
+   */
+  #assertAvailable(node, expression) {
+    const {
+      calledWorkflow
+    } = this.#context;
+    if (calledWorkflow === undefined || !HTTP_EXCHANGE_NODES.has(node.type)) return;
+    throw new _RuntimeExpressionError.default(`Runtime expression "${expression}" is not available: step "${calledWorkflow.stepId}" calls workflow "${calledWorkflow.workflowId}", not an operation, so it has no HTTP request or response`, {
+      expression,
+      reason: 'unavailable-expression'
+    });
+  }
+
+  /**
+   * Walks an AST node against the context, returning the referenced value or
+   * `undefined` when the reference does not resolve.
+   */
+  #evaluateNode(node, expression) {
+    switch (node.type) {
+      case 'UrlExpression':
+        return this.#context.request?.url;
+      case 'MethodExpression':
+        return this.#context.request?.method;
+      case 'StatusCodeExpression':
+        return this.#context.response?.statusCode;
+      case 'RequestExpression':
+        return this.#source(node.source, this.#context.request);
+      case 'ResponseExpression':
+        return this.#source(node.source, this.#context.response);
+      case 'InputsExpression':
+        return this.#drill(this.#get(this.#context.inputs, node.name));
+      case 'OutputsExpression':
+        return this.#drill(this.#get(this.#context.outputs, node.name));
+      case 'StepsExpression':
+        return this.#drill(this.#get(this.#context.steps?.[node.stepId]?.outputs, node.outputName), node.jsonPointer?.value);
+      case 'WorkflowsExpression':
+        return this.#drill(this.#get(this.#context.workflows?.[node.workflowId]?.[node.field], node.fieldName), node.jsonPointer?.value);
+      case 'WorkflowsStepsExpression':
+        return this.#step(this.#document, node.workflowId, node.stepId);
+      case 'SourceDescriptionsExpression':
+        return this.#sourceDescription(node);
+      case 'ComponentsExpression':
+        return this.#component(node.componentType, node.componentName);
+      default:
+        throw new _RuntimeExpressionError.default(`Unsupported runtime expression node "${node.type}"`, {
+          expression,
+          reason: 'unsupported-node'
+        });
+    }
+  }
+
+  /**
+   * Evaluates a `$request`/`$response` source reference against the request or
+   * response side of the context.
+   */
+  #source(source, message) {
+    const {
+      reference
+    } = source;
+    switch (reference.type) {
+      case 'HeaderReference':
+        return this.#header(message?.header, reference.token);
+      case 'QueryReference':
+        return this.#get(message?.query, reference.name);
+      case 'PathReference':
+        return this.#get(message?.path, reference.name);
+      case 'BodyReference':
+        return this.#drill(message?.body, reference.jsonPointer?.value);
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Resolves `$components.{field}.{name}` by drilling into the evaluator's
+   * document. Returns `undefined` when no document is configured or the
+   * component is absent.
+   */
+  #component(field, name) {
+    return this.#drillDocument(this.#document, (0, _jsonPointer.compile)(['components', field, name]));
+  }
+
+  /**
+   * Resolves `{workflowId}.steps.{stepId}` to the Step Object in an Arazzo
+   * document. Returns `undefined` when the document is absent or not Arazzo, or
+   * the workflow or step is unknown.
+   */
+  #step(document, workflowId, stepId) {
+    if (document === undefined || !_ArazzoDocument.default.is(document)) return undefined;
+    const pointer = document.stepIndex.getStep(workflowId, stepId);
+    return pointer === undefined ? undefined : this.#drillDocument(document, pointer);
+  }
+
+  /**
+   * Resolves `$sourceDescriptions.{name}.{reference}` with the resolution
+   * priority defined by the Arazzo Specification:
+   *
+   * 1. `{reference}` is matched as an operationId (OpenAPI source) or workflowId
+   *    (Arazzo source) in the referenced document, resolving to that operation
+   *    or workflow. A `{workflowId}.steps.{stepId}` reference resolves to that
+   *    step of the referenced Arazzo document.
+   * 2. failing that, `{reference}` is matched as a field of the Source
+   *    Description Object itself (e.g. `url`, `type`) — so
+   *    `$sourceDescriptions.{name}.url` yields the source's URL. An operationId
+   *    that collides with a field name takes precedence (tier 1 wins).
+   *
+   * Returns `undefined` when nothing matches.
+   */
+  #sourceDescription({
+    sourceName,
+    reference,
+    stepsReference
+  }) {
+    const uri = this.#document?.resolveSourceDescriptionURI(sourceName);
+
+    // tier 1: operationId / workflowId / workflow step in the referenced document.
+    const apiDocument = uri === undefined ? undefined : this.#registry?.get(uri);
+    if (apiDocument !== undefined) {
+      if (stepsReference !== undefined) {
+        return this.#step(apiDocument, stepsReference.workflowId, stepsReference.stepId);
+      }
+      const pointer = _OpenAPIDocument.default.is(apiDocument) ? apiDocument.operationIndex.get(reference) : _ArazzoDocument.default.is(apiDocument) ? apiDocument.workflowIndex.get(reference) : undefined;
+      if (pointer !== undefined) return this.#drillDocument(apiDocument, pointer);
+    }
+
+    // tier 2: a field of the Source Description Object (url, type, ...).
+    return this.#document?.resolveSourceDescriptionField(sourceName, reference);
+  }
+
+  /**
+   * Reads a property from a context slot, or `undefined` when the slot is not
+   * an object or lacks the key. Own properties only, so prototype members
+   * (`constructor`, `toString`) never leak into a resolution.
+   */
+  #get(slot, key) {
+    if (typeof slot !== 'object' || slot === null) return undefined;
+    if (!Object.hasOwn(slot, key)) return undefined;
+    return slot[key];
+  }
+
+  /**
+   * Reads a header case-insensitively. The parser already lowercases the header
+   * token, so only the context keys (populated from an HTTP response with
+   * arbitrary casing) need normalizing to match.
+   */
+  #header(headers, token) {
+    if (headers === undefined) return undefined;
+    const key = Object.keys(headers).find(k => k.toLowerCase() === token);
+    return key === undefined ? undefined : headers[key];
+  }
+
+  /**
+   * Drills a JSON Pointer into a document's API element. Returns `undefined`
+   * when the document is absent or the pointer does not resolve.
+   */
+  #drillDocument(document, pointer) {
+    return document === undefined ? undefined : this.#drill(document.parseResult.api, pointer);
+  }
+
+  /**
+   * Drills an optional JSON Pointer into a payload value, returning the plain
+   * runtime value. `toValue` is idempotent on plain values, so the leaf is plain
+   * whether the payload was JSON or an ApiDOM element (see `pointerRealm`).
+   */
+  #drill(value, pointer) {
+    if (value === undefined) return undefined;
+    if (pointer === undefined) return (0, _apidomCore.toValue)(value);
+    try {
+      return (0, _apidomCore.toValue)((0, _jsonPointer.evaluate)(value, pointer, {
+        realm: pointerRealm
+      }));
+    } catch (error) {
+      if (error instanceof _jsonPointer.JSONPointerEvaluateError) return undefined;
+      throw error;
+    }
+  }
+}
+var _default = exports.default = RuntimeExpressionEvaluator;