arvo-event-handler 3.0.7 → 3.0.8

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/index.js

@@ -0,0 +1,228 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWithOrchestrationWrapper = exports.returnEventsWithLogging = void 0;
+var api_1 = require("@opentelemetry/api");
+var arvo_core_1 = require("arvo-core");
+var handlerErrors_1 = require("../handlerErrors");
+var acquireLockWithValidation_1 = require("./acquireLockWithValidation");
+var validateAndParseSubject_1 = require("./validateAndParseSubject");
+var returnEventsWithLogging = function (param, span) {
+    var _a, _b;
+    (0, arvo_core_1.logToSpan)({
+        level: 'INFO',
+        message: "Execution completed with issues and emitted ".concat((_b = (_a = param.events) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0, " events"),
+    }, span);
+    return param;
+};
+exports.returnEventsWithLogging = returnEventsWithLogging;
+/**
+ * Wraps orchestration execution with common infrastructure:
+ * - OpenTelemetry span management
+ * - Lock acquisition and release
+ * - State management
+ * - Error handling and system error generation
+ */
+var executeWithOrchestrationWrapper = function (_a, coreExecutionFn_1) { return __awaiter(void 0, [_a, coreExecutionFn_1], void 0, function (_b, coreExecutionFn) {
+    var _c;
+    var event = _b.event, opentelemetry = _b.opentelemetry, spanName = _b.spanName, source = _b.source, syncEventResource = _b.syncEventResource, executionunits = _b.executionunits, systemErrorDomain = _b.systemErrorDomain, selfContract = _b.selfContract, domain = _b.domain, _handlerType = _b._handlerType;
+    return __generator(this, function (_d) {
+        switch (_d.label) {
+            case 0: return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan({
+                    name: spanName,
+                    spanOptions: {
+                        kind: api_1.SpanKind.PRODUCER,
+                        attributes: __assign((_c = {}, _c[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = arvo_core_1.ArvoExecutionSpanKind.ORCHESTRATOR, _c[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = arvo_core_1.OpenInferenceSpanKind.CHAIN, _c), Object.fromEntries(Object.entries(event.otelAttributes).map(function (_a) {
+                            var key = _a[0], value = _a[1];
+                            return ["to_process.0.".concat(key), value];
+                        }))),
+                    },
+                    context: opentelemetry.inheritFrom === 'EVENT'
+                        ? {
+                            inheritFrom: 'TRACE_HEADERS',
+                            traceHeaders: {
+                                traceparent: event.traceparent,
+                                tracestate: event.tracestate,
+                            },
+                        }
+                        : {
+                            inheritFrom: 'CONTEXT',
+                            context: api_1.context.active(),
+                        },
+                    disableSpanManagement: true,
+                    fn: function (span) { return __awaiter(void 0, void 0, void 0, function () {
+                        var otelHeaders, orchestrationParentSubject, initEventId, acquiredLock, parsedEventSubject, state, _a, emittables, newState, i, _i, _b, _c, key, value, error_1, _d, errorToThrow, errorEvents;
+                        var _e, _f, _g, _h;
+                        return __generator(this, function (_j) {
+                            switch (_j.label) {
+                                case 0:
+                                    (0, arvo_core_1.logToSpan)({
+                                        level: 'INFO',
+                                        message: "Starting execution for ".concat(event.type, " on subject ").concat(event.subject),
+                                    }, span);
+                                    otelHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
+                                    orchestrationParentSubject = null;
+                                    initEventId = null;
+                                    acquiredLock = null;
+                                    _j.label = 1;
+                                case 1:
+                                    _j.trys.push([1, 6, 8, 10]);
+                                    parsedEventSubject = (0, validateAndParseSubject_1.validateAndParseSubject)(event, source, syncEventResource, span, 'orchestrator');
+                                    if (!parsedEventSubject) {
+                                        return [2 /*return*/, (0, exports.returnEventsWithLogging)({ events: [] }, span)];
+                                    }
+                                    return [4 /*yield*/, (0, acquireLockWithValidation_1.acquireLockWithValidation)(syncEventResource, event, span)];
+                                case 2:
+                                    // Lock acquisition
+                                    acquiredLock = _j.sent();
+                                    return [4 /*yield*/, syncEventResource.acquireState(event, span)];
+                                case 3:
+                                    state = _j.sent();
+                                    if ((state === null || state === void 0 ? void 0 : state.executionStatus) === 'failure') {
+                                        (0, arvo_core_1.logToSpan)({
+                                            level: 'WARNING',
+                                            message: "The orchestration has failed in a previous event. Ignoring event id: ".concat(event.id, " with event subject: ").concat(event.subject),
+                                        }, span);
+                                        return [2 /*return*/, (0, exports.returnEventsWithLogging)({ events: [] }, span)];
+                                    }
+                                    orchestrationParentSubject = (_e = state === null || state === void 0 ? void 0 : state.parentSubject) !== null && _e !== void 0 ? _e : null;
+                                    initEventId = (_f = state === null || state === void 0 ? void 0 : state.initEventId) !== null && _f !== void 0 ? _f : null;
+                                    if (!state) {
+                                        (0, arvo_core_1.logToSpan)({
+                                            level: 'INFO',
+                                            message: "Initializing new execution state for subject: ".concat(event.subject),
+                                        });
+                                        if (event.type !== source) {
+                                            (0, arvo_core_1.logToSpan)({
+                                                level: 'WARNING',
+                                                message: "Invalid initialization event detected. Expected type '".concat(source, "' but received '").concat(event.type, "'."),
+                                            });
+                                            return [2 /*return*/, (0, exports.returnEventsWithLogging)({ events: [] }, span)];
+                                        }
+                                    }
+                                    else {
+                                        (0, arvo_core_1.logToSpan)({
+                                            level: 'INFO',
+                                            message: "Resuming execution with existing state for subject: ".concat(event.subject),
+                                        });
+                                    }
+                                    // Extract parent subject from init event if applicable
+                                    if (event.type === source) {
+                                        orchestrationParentSubject = (_h = (_g = event === null || event === void 0 ? void 0 : event.data) === null || _g === void 0 ? void 0 : _g.parentSubject$$) !== null && _h !== void 0 ? _h : null;
+                                    }
+                                    return [4 /*yield*/, coreExecutionFn({
+                                            span: span,
+                                            otelHeaders: otelHeaders,
+                                            orchestrationParentSubject: orchestrationParentSubject,
+                                            initEventId: initEventId !== null && initEventId !== void 0 ? initEventId : event.id,
+                                            parsedEventSubject: parsedEventSubject,
+                                            state: state,
+                                            _handlerType: _handlerType,
+                                        })];
+                                case 4:
+                                    _a = _j.sent(), emittables = _a.emittables, newState = _a.newState;
+                                    span.setAttribute("arvo.".concat(_handlerType, ".execution.status"), newState.executionStatus);
+                                    // Add OpenTelemetry attributes for emitted events
+                                    for (i = 0; i < emittables.length; i++) {
+                                        for (_i = 0, _b = Object.entries(emittables[i].otelAttributes); _i < _b.length; _i++) {
+                                            _c = _b[_i], key = _c[0], value = _c[1];
+                                            span.setAttribute("to_emit.".concat(i, ".").concat(key), value);
+                                        }
+                                    }
+                                    // Persist state
+                                    return [4 /*yield*/, syncEventResource.persistState(event, newState, state, span)];
+                                case 5:
+                                    // Persist state
+                                    _j.sent();
+                                    (0, arvo_core_1.logToSpan)({
+                                        level: 'INFO',
+                                        message: "State update persisted in memory for subject ".concat(event.subject),
+                                    });
+                                    (0, arvo_core_1.logToSpan)({
+                                        level: 'INFO',
+                                        message: "Execution successfully completed and emitted ".concat(emittables.length, " events"),
+                                    });
+                                    return [2 /*return*/, (0, exports.returnEventsWithLogging)({ events: emittables }, span)];
+                                case 6:
+                                    error_1 = _j.sent();
+                                    return [4 /*yield*/, (0, handlerErrors_1.handleOrchestrationErrors)(_handlerType, {
+                                            error: error_1,
+                                            event: event,
+                                            otelHeaders: otelHeaders,
+                                            orchestrationParentSubject: orchestrationParentSubject,
+                                            initEventId: initEventId,
+                                            selfContract: selfContract,
+                                            systemErrorDomain: systemErrorDomain,
+                                            executionunits: executionunits,
+                                            source: source,
+                                            domain: domain,
+                                            syncEventResource: syncEventResource,
+                                        }, span)];
+                                case 7:
+                                    _d = _j.sent(), errorToThrow = _d.errorToThrow, errorEvents = _d.events;
+                                    if (errorToThrow)
+                                        throw errorToThrow;
+                                    return [2 /*return*/, {
+                                            events: errorEvents,
+                                        }];
+                                case 8: return [4 /*yield*/, syncEventResource.releaseLock(event, acquiredLock, span)];
+                                case 9:
+                                    _j.sent();
+                                    span.end();
+                                    return [7 /*endfinally*/];
+                                case 10: return [2 /*return*/];
+                            }
+                        });
+                    }); },
+                })];
+            case 1: return [2 /*return*/, _d.sent()];
+        }
+    });
+}); };
+exports.executeWithOrchestrationWrapper = executeWithOrchestrationWrapper;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/validateAndParseSubject.d.ts

@@ -0,0 +1,7 @@
+import type { Span } from '@opentelemetry/api';
+import { type ArvoEvent, type ArvoOrchestrationSubjectContent } from 'arvo-core';
+import type { SyncEventResource } from '../../SyncEventResource';
+/**
+ * Validates and parses orchestration subject
+ */
+export declare const validateAndParseSubject: (event: ArvoEvent, expectedSource: string, syncEventResource: SyncEventResource<any>, span: Span, handlerType: "orchestrator" | "resumable") => ArvoOrchestrationSubjectContent | null;

package/dist/ArvoOrchestrationUtils/orchestrationExecutionWrapper/validateAndParseSubject.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAndParseSubject = void 0;
+var arvo_core_1 = require("arvo-core");
+/**
+ * Validates and parses orchestration subject
+ */
+var validateAndParseSubject = function (event, expectedSource, syncEventResource, span, handlerType) {
+    var _a;
+    syncEventResource.validateEventSubject(event, span);
+    var parsedEventSubject = arvo_core_1.ArvoOrchestrationSubject.parse(event.subject);
+    span.setAttributes((_a = {},
+        _a["arvo.parsed.subject.".concat(handlerType, ".name")] = parsedEventSubject.orchestrator.name,
+        _a["arvo.parsed.subject.".concat(handlerType, ".version")] = parsedEventSubject.orchestrator.version,
+        _a));
+    if (parsedEventSubject.orchestrator.name !== expectedSource) {
+        (0, arvo_core_1.logToSpan)({
+            level: 'WARNING',
+            message: "Event subject mismatch - expected '".concat(expectedSource, "' but got '").concat(parsedEventSubject.orchestrator.name, "'"),
+        }, span);
+        return null;
+    }
+    return parsedEventSubject;
+};
+exports.validateAndParseSubject = validateAndParseSubject;

package/dist/ArvoOrchestrationUtils/types.d.ts

@@ -0,0 +1 @@
+export type ArvoOrchestrationHandlerType = 'orchestrator' | 'resumable';

package/dist/ArvoOrchestrationUtils/types.js

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

package/dist/ArvoOrchestrator/factory.js

@@ -13,6 +13,7 @@ exports.createArvoOrchestrator = void 0;
 var _1 = require(".");
 var MachineExecutionEngine_1 = require("../MachineExecutionEngine");
 var MachineRegistry_1 = require("../MachineRegistry");
+var errors_1 = require("../errors");
 /**
  * Creates a new Arvo orchestrator instance with default components.
  * For custom components, use ArvoOrchestrator constructor directly.
@@ -46,6 +47,18 @@ var createArvoOrchestrator = function (_a) {
     }
     var registry = new (MachineRegistry_1.MachineRegistry.bind.apply(MachineRegistry_1.MachineRegistry, __spreadArray([void 0], machines, false)))();
     var requiresResourceLocking = machines.some(function (machine) { return machine.requiresResourceLocking; });
+    var representativeMachine = registry.machines[0];
+    var lastSeenVersions = [];
+    for (var _i = 0, _b = registry.machines; _i < _b.length; _i++) {
+        var machine = _b[_i];
+        if (representativeMachine.source !== machine.source) {
+            throw new errors_1.ConfigViolation("All the machines in the orchestrator must have type '".concat(representativeMachine.source, "'"));
+        }
+        if (lastSeenVersions.includes(machine.version)) {
+            throw new errors_1.ConfigViolation("An orchestrator must have unique machine versions. Machine ID:".concat(machine.id, " has duplicate version ").concat(machine.version, "."));
+        }
+        lastSeenVersions.push(machine.version);
+    }
     return new _1.ArvoOrchestrator({
         executionunits: executionunits,
         memory: memory,

package/dist/ArvoOrchestrator/index.d.ts

@@ -1,13 +1,11 @@
-import { type ArvoContractRecord, type ArvoEvent, type OpenTelemetryHeaders } from 'arvo-core';
-import type ArvoMachine from '../ArvoMachine';
-import type { EnqueueArvoEventActionParam } from '../ArvoMachine/types';
+import { type ArvoContractRecord, type ArvoEvent } from 'arvo-core';
+import type IArvoEventHandler from '../IArvoEventHandler';
 import type { IMachineExectionEngine } from '../MachineExecutionEngine/interface';
 import type { IMachineMemory } from '../MachineMemory/interface';
 import type { IMachineRegistry } from '../MachineRegistry/interface';
-import type { ArvoOrchestratorParam, MachineMemoryRecord } from './types';
 import { SyncEventResource } from '../SyncEventResource';
-import IArvoEventHandler from '../IArvoEventHandler';
 import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
+import type { ArvoOrchestratorParam, MachineMemoryRecord } from './types';
 /**
  * Orchestrates state machine execution and lifecycle management.
  * Handles machine resolution, state management, event processing and error handling.
@@ -28,20 +26,6 @@ export declare class ArvoOrchestrator implements IArvoEventHandler {
      * @throws Error if machines in registry have different sources
      */
     constructor({ executionunits, memory, registry, executionEngine, requiresResourceLocking, systemErrorDomain, }: ArvoOrchestratorParam);
-    /**
-     * Creates emittable event from execution result
-     * @param event - Source event to emit
-     * @param machine - Machine that generated event
-     * @param otelHeaders - OpenTelemetry headers
-     * @param orchestrationParentSubject - Parent orchestration subject
-     * @param sourceEvent - Original triggering event
-     * @param initEventId - The id of the event which initiated the orchestration in the first place
-     * @param _domain - The domain of the event.
-     *
-     * @throws {ContractViolation} On schema/contract mismatch
-     * @throws {ExecutionViolation} On invalid parentSubject$$ format
-     */
-    protected createEmittableEvent(event: EnqueueArvoEventActionParam, machine: ArvoMachine<any, any, any, any, any>, otelHeaders: OpenTelemetryHeaders, orchestrationParentSubject: string | null, sourceEvent: ArvoEvent, initEventId: string, _domain: string | null): ArvoEvent;
     /**
      * Core orchestration method that executes state machines in response to events.
      *