arvo-event-handler 2.3.1 → 3.0.1

package/dist/MachineMemory/TelemetredSimple.js

@@ -0,0 +1,230 @@
+"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.TelemetredSimpleMachineMemory = void 0;
+var api_1 = require("@opentelemetry/api");
+var arvo_core_1 = require("arvo-core");
+var utils_1 = require("./utils");
+/**
+ * A telemetred In-memory implementation of machine state storage for single-instance NodeJS apps.
+ *
+ * Best for: Container apps, request-scoped workflows, testing, demos
+ * Not for: Multi-instance deployments, persistent workflows, distributed systems
+ *
+ * @example
+ * const memory = new TelemetredSimpleMachineMemory();
+ * const orchestrator = createArvoOrchestrator({
+ *   memory,
+ *   executionunits: 0.1,
+ *   machines: [workflow]
+ * });
+ */
+var TelemetredSimpleMachineMemory = /** @class */ (function () {
+    function TelemetredSimpleMachineMemory() {
+        this.memoryMap = new Map();
+        this.lockMap = new Map();
+    }
+    /**
+     * Gets stored state for a machine instance
+     * @param id Machine instance ID
+     * @returns State data or null if not found
+     * @throws {Error} When id is empty or undefined
+     */
+    TelemetredSimpleMachineMemory.prototype.read = function (id) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan({
+                            name: 'Read Simple Memory',
+                            spanOptions: {
+                                kind: api_1.SpanKind.INTERNAL,
+                                attributes: {
+                                    'arvo.memory.id': id,
+                                },
+                            },
+                            fn: function () { return __awaiter(_this, void 0, void 0, function () {
+                                var _a;
+                                return __generator(this, function (_b) {
+                                    if (!id) {
+                                        throw new Error('Machine ID is required for read operation');
+                                    }
+                                    return [2 /*return*/, (_a = this.memoryMap.get(id)) !== null && _a !== void 0 ? _a : null];
+                                });
+                            }); },
+                        })];
+                    case 1: return [2 /*return*/, _a.sent()];
+                }
+            });
+        });
+    };
+    /**
+     * Stores state for a machine instance
+     * @param id Machine instance ID
+     * @param data State to store
+     * @throws {Error} When id is empty/undefined or data is null/undefined
+     */
+    TelemetredSimpleMachineMemory.prototype.write = function (id, data) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan({
+                            name: 'Write Simple Memory',
+                            spanOptions: {
+                                kind: api_1.SpanKind.INTERNAL,
+                                attributes: {
+                                    'arvo.memory.id': id,
+                                    'arvo.memory.record.bytes': data ? (0, utils_1.getJsonSize)(data) : 0,
+                                },
+                            },
+                            fn: function () { return __awaiter(_this, void 0, void 0, function () {
+                                return __generator(this, function (_a) {
+                                    if (!id) {
+                                        throw new Error('Machine ID is required for write operation');
+                                    }
+                                    if (!data) {
+                                        throw new Error('Data is required for write operation');
+                                    }
+                                    this.memoryMap.set(id, __assign({}, data));
+                                    return [2 /*return*/];
+                                });
+                            }); },
+                        })];
+                    case 1: return [2 /*return*/, _a.sent()];
+                }
+            });
+        });
+    };
+    /**
+     * Attempts to acquire lock for machine instance
+     * @param id Machine instance ID
+     * @returns Success status of lock acquisition
+     * @throws {Error} When id is empty or undefined
+     */
+    TelemetredSimpleMachineMemory.prototype.lock = function (id) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan({
+                            name: 'Lock Simple Memory',
+                            spanOptions: {
+                                kind: api_1.SpanKind.INTERNAL,
+                                attributes: {
+                                    'arvo.memory.id': id,
+                                },
+                            },
+                            fn: function () { return __awaiter(_this, void 0, void 0, function () {
+                                return __generator(this, function (_a) {
+                                    if (!id) {
+                                        throw new Error('Machine ID is required for lock operation');
+                                    }
+                                    if (this.lockMap.get(id)) {
+                                        return [2 /*return*/, false];
+                                    }
+                                    this.lockMap.set(id, true);
+                                    return [2 /*return*/, true];
+                                });
+                            }); },
+                        })];
+                    case 1: return [2 /*return*/, _a.sent()];
+                }
+            });
+        });
+    };
+    /**
+     * Releases lock for machine instance
+     * @param id Machine instance ID
+     * @returns True when lock is released
+     * @throws {Error} When id is empty or undefined
+     */
+    TelemetredSimpleMachineMemory.prototype.unlock = function (id) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan({
+                            name: 'Unlock Simple Memory',
+                            spanOptions: {
+                                kind: api_1.SpanKind.INTERNAL,
+                                attributes: {
+                                    'arvo.memory.id': id,
+                                },
+                            },
+                            fn: function () { return __awaiter(_this, void 0, void 0, function () {
+                                return __generator(this, function (_a) {
+                                    if (!id) {
+                                        throw new Error('Machine ID is required for unlock operation');
+                                    }
+                                    this.lockMap.delete(id);
+                                    return [2 /*return*/, true];
+                                });
+                            }); },
+                        })];
+                    case 1: return [2 /*return*/, _a.sent()];
+                }
+            });
+        });
+    };
+    /**
+     * Clears all stored data and locks
+     */
+    TelemetredSimpleMachineMemory.prototype.clear = function (key) {
+        if (key) {
+            this.memoryMap.delete(key);
+            this.lockMap.delete(key);
+            return;
+        }
+        this.memoryMap.clear();
+        this.lockMap.clear();
+    };
+    return TelemetredSimpleMachineMemory;
+}());
+exports.TelemetredSimpleMachineMemory = TelemetredSimpleMachineMemory;

package/dist/MachineMemory/interface.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Manages machine state memory operations with optimistic locking strategy.
+ * Implements a "fail fast on acquire, be tolerant on release" approach for resource management.
+ * @template T - Structure of stored data
+ */
+export interface IMachineMemory<T extends Record<string, any>> {
+    /**
+     * Gets state data for machine ID (event.subject).
+     * Should implement minimal retries (e.g. 2-3 attempts) with backoff for transient failures.
+     * Must distinguish between:
+     * - No data exists: Returns null (normal case for new machines)
+     * - Operation failed: Throws error after all retries exhausted
+     *
+     * Retry strategy should be quick with reasonable timeout to avoid blocking:
+     * - Few retry attempts (2-3)
+     * - Short backoff delays (e.g. 100ms with exponential backoff)
+     * - Total operation time under 1s
+     *
+     * @param id - Machine ID
+     * @returns null if no data exists, T if data found
+     * @throws Error if read operation fails after retries (e.g. connection error, permission denied)
+     */
+    read(id: string): Promise<T | null>;
+    /**
+     * Saves state data for machine ID (event.subject).
+     * Should fail fast - if write fails, throw error immediately.
+     * No retry logic as consistency is critical and caller handles failures.
+     * @param id - Machine ID
+     * @param data - State to save
+     * @param prevData - The previous snapshot of the data
+     * @throws Error if write operation fails
+     */
+    write(id: string, data: T, prevData: T | null): Promise<void>;
+    /**
+     * Acquires execution lock for machine ID (event.subject).
+     * Should implement reasonable retries with backoff for transient lock conflicts.
+     * Must fail fast after retry attempts exhausted - no long polling.
+     * @param id - Machine ID
+     * @returns True if lock acquired successfully
+     * @throws Error if lock operation fails (not same as lock denial)
+     */
+    lock(id: string): Promise<boolean>;
+    /**
+     * Releases execution lock for machine ID (event.subject).
+     * Can retry a few times on failure but should not over-engineer.
+     * System will eventually recover even if unlock fails.
+     *
+     * Implementation MUST include lock expiry mechanism (TTL):
+     * - Set reasonable TTL when acquiring lock (e.g. 30s-5m based on execution patterns)
+     * - Ensure locks auto-expire to prevent deadlocks from unlock failures
+     * - Consider execution patterns when setting TTL to avoid premature expiry
+     *
+     * @param id - Machine ID
+     * @returns True if unlocked successfully
+     */
+    unlock(id: string): Promise<boolean>;
+}

package/dist/MachineMemory/interface.js

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

package/dist/MachineMemory/utils.d.ts

@@ -0,0 +1 @@
+export declare function getJsonSize(obj: Record<string, any>): number;

package/dist/MachineMemory/utils.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getJsonSize = getJsonSize;
+var arvo_core_1 = require("arvo-core");
+function getJsonSize(obj) {
+    try {
+        var jsonString = JSON.stringify(obj);
+        // Use TextEncoder to get actual UTF-8 byte length
+        return new TextEncoder().encode(jsonString).length;
+    }
+    catch (e) {
+        (0, arvo_core_1.logToSpan)({
+            level: 'WARNING',
+            message: "Error while calculating the size of the machine memory record. Error: ".concat(e.message),
+        });
+        return -1;
+    }
+}

package/dist/MachineRegistry/index.d.ts

@@ -0,0 +1,37 @@
+import { type ArvoEvent } from 'arvo-core';
+import type ArvoMachine from '../ArvoMachine';
+import type { IMachineRegistry } from './interface';
+import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
+/**
+ * Registry for managing and resolving ArvoMachine instances.
+ * Provides functionality to store multiple machine instances and resolve them based on events.
+ *
+ * @remarks
+ * The registry must contain at least one machine upon initialization.
+ * Each machine in the registry should have a unique combination of version and source.
+ */
+export declare class MachineRegistry implements IMachineRegistry {
+    machines: ArvoMachine<any, any, any, any, any>[];
+    /**
+     * Creates a new MachineRegistry instance with the provided machines.
+     *
+     * @param args - Variable number of ArvoMachine instances to register
+     * @throws {Error} When no machines are provided during initialization
+     */
+    constructor(...args: ArvoMachine<any, any, any, any, any>[]);
+    /**
+     * Resolves and returns a machine instance based on the provided event.
+     * The resolution is performed using the orchestrator information in the event's subject.
+     *
+     * @param event - The event containing orchestration subject information
+     * @param opentelemetry Telemetry configuration for tracing
+     * @returns The matching ArvoMachine instance or null if not found
+     *
+     * @example
+     * ```typescript
+     * const machine = registry.resolve(incomingEvent);
+     * // Use resolved machine for event processing
+     * ```
+     */
+    resolve(event: ArvoEvent, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): ArvoMachine<any, any, any, any, any> | null;
+}

package/dist/MachineRegistry/index.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MachineRegistry = void 0;
+var api_1 = require("@opentelemetry/api");
+var arvo_core_1 = require("arvo-core");
+/**
+ * Registry for managing and resolving ArvoMachine instances.
+ * Provides functionality to store multiple machine instances and resolve them based on events.
+ *
+ * @remarks
+ * The registry must contain at least one machine upon initialization.
+ * Each machine in the registry should have a unique combination of version and source.
+ */
+var MachineRegistry = /** @class */ (function () {
+    /**
+     * Creates a new MachineRegistry instance with the provided machines.
+     *
+     * @param args - Variable number of ArvoMachine instances to register
+     * @throws {Error} When no machines are provided during initialization
+     */
+    function MachineRegistry() {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        this.machines = args;
+        if (!this.machines.length) {
+            throw new Error('Machine registry initialization failed: No machines provided. At least one machine must be registered.');
+        }
+    }
+    /**
+     * Resolves and returns a machine instance based on the provided event.
+     * The resolution is performed using the orchestrator information in the event's subject.
+     *
+     * @param event - The event containing orchestration subject information
+     * @param opentelemetry Telemetry configuration for tracing
+     * @returns The matching ArvoMachine instance or null if not found
+     *
+     * @example
+     * ```typescript
+     * const machine = registry.resolve(incomingEvent);
+     * // Use resolved machine for event processing
+     * ```
+     */
+    MachineRegistry.prototype.resolve = function (event, opentelemetry) {
+        var _this = this;
+        if (opentelemetry === void 0) { opentelemetry = {
+            inheritFrom: 'CONTEXT',
+        }; }
+        return arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan({
+            name: 'Resolve Machine',
+            spanOptions: {
+                kind: api_1.SpanKind.INTERNAL,
+                attributes: event.otelAttributes,
+            },
+            context: opentelemetry.inheritFrom === 'EVENT'
+                ? {
+                    inheritFrom: 'TRACE_HEADERS',
+                    traceHeaders: {
+                        traceparent: event.traceparent,
+                        tracestate: event.tracestate,
+                    },
+                }
+                : {
+                    inheritFrom: 'CONTEXT',
+                    context: api_1.context.active(),
+                },
+            fn: function (span) {
+                var _a;
+                var subject = arvo_core_1.ArvoOrchestrationSubject.parse(event.subject);
+                var _b = subject.orchestrator, name = _b.name, version = _b.version;
+                span.setAttributes({
+                    'arvo.parsed.subject.orchestrator.name': name,
+                    'arvo.parsed.subject.orchestrator.version': version,
+                });
+                var machine = (_a = _this.machines.find(function (item) { return item.version === version && item.source === name; })) !== null && _a !== void 0 ? _a : null;
+                (0, arvo_core_1.logToSpan)({
+                    level: machine ? 'INFO' : 'WARNING',
+                    message: machine ? "Resolved machine for type ".concat(name, "@").concat(version) : "No machine found for ".concat(name, "@").concat(version),
+                });
+                return machine;
+            },
+        });
+    };
+    return MachineRegistry;
+}());
+exports.MachineRegistry = MachineRegistry;

package/dist/MachineRegistry/interface.d.ts

@@ -0,0 +1,21 @@
+import type { ArvoEvent } from 'arvo-core';
+import type ArvoMachine from '../ArvoMachine';
+import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
+/**
+ * Interface for managing and resolving state machine instances.
+ */
+export interface IMachineRegistry {
+    /**
+     * Collection of registered machine instances.
+     * Each machine should have a unique combination of version and source.
+     */
+    machines: ArvoMachine<any, any, any, any, any>[];
+    /**
+     * Resolves a machine instance based on event information.
+     *
+     * @param event - Event containing orchestration subject information
+     * @param opentelemetry - Configuration for telemetry and tracing
+     * @returns Matching ArvoMachine instance for the event or null if not found
+     */
+    resolve: (event: ArvoEvent, opentelemetry: ArvoEventHandlerOpenTelemetryOptions) => ArvoMachine<any, any, any, any, any> | null;
+}

package/dist/MachineRegistry/interface.js

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

package/dist/SyncEventResource/index.d.ts

@@ -0,0 +1,110 @@
+import { type ArvoEvent } from 'arvo-core';
+import type { IMachineMemory } from '../MachineMemory/interface';
+import type { AcquiredLockStatusType, ReleasedLockStatusType } from './types';
+import type { Span } from '@opentelemetry/api';
+/**
+ * A synchronous event resource that manages machine memory state based on event subjects.
+ *
+ * This class provides a distributed-system-safe mechanism for persisting and retrieving machine memory
+ * objects that are correlated with ArvoEvent subjects. It acts as a key-value store where
+ * the event subject serves as the key and the memory object serves as the value.
+ *
+ * Key features:
+ * - JSON serializable memory persistence
+ * - Optional resource locking for distributed concurrent access control
+ * - Subject-based memory correlation across multiple service instances
+ * - Transaction-safe operations with proper error handling
+ * - Optional OpenTelemetry span integration for observability
+ *
+ * @template T - The type of the memory object, must extend Record<string, any> and be JSON serializable
+ *
+ * @example
+ * ```typescript
+ * type MyMemory = {
+ *   counter: number;
+ *   status: string;
+ * }
+ *
+ * class MemoryImplementation implements IMachineMemory<MyMemory> { ... }
+ *
+ * const resource = new SyncEventResource<MyMemory>(
+ *   new MemoryImplementation(),
+ *   true // enable resource locking for distributed systems
+ * );
+ * ```
+ */
+export declare class SyncEventResource<T extends Record<string, any>> {
+    memory: IMachineMemory<T>;
+    requiresResourceLocking: boolean;
+    constructor(memory: IMachineMemory<T>, requiresResourceLocking: boolean);
+    /**
+     * Acquires a lock on the event subject to prevent concurrent access across distributed services.
+     *
+     * This method ensures distributed-system-safe access to the memory resource by preventing
+     * multiple service instances from modifying the same event subject simultaneously. If resource
+     * locking is disabled, it will skip the lock acquisition process. The lock is subject-specific,
+     * meaning different event subjects can be processed concurrently across services.
+     *
+     * @returns A promise that resolves to the lock acquisition status:
+     *          - 'ACQUIRED': Lock was successfully acquired
+     *          - 'NOT_ACQUIRED': Lock acquisition failed (resource busy by another service)
+     *          - 'NOOP': Lock acquisition was skipped (locking disabled)
+     *
+     * @throws {TransactionViolation} When lock acquisition fails due to system errors
+     */
+    acquireLock(event: ArvoEvent, span?: Span): Promise<AcquiredLockStatusType>;
+    /**
+     * Retrieves the current state from memory for the given event subject.
+     *
+     * This method reads the persisted memory object associated with the event's subject
+     * from the distributed storage system. If no memory exists for the subject, it returns null.
+     * The operation is wrapped in proper error handling to ensure transaction safety across
+     * distributed service instances.
+     *
+     * @returns A promise that resolves to the memory object if found, or null if no memory exists
+     *
+     * @throws {TransactionViolation} When the read operation fails due to storage errors
+     */
+    acquireState(event: ArvoEvent, span?: Span): Promise<T | null>;
+    /**
+     * Persists the updated memory state to distributed storage.
+     *
+     * This method writes the new memory record to the distributed storage system, associating
+     * it with the event's subject. It provides both the new record and the previous record for
+     * implementations that need to perform atomic updates, maintain audit trails, or handle
+     * optimistic concurrency control in distributed environments.
+     *
+     * @throws {TransactionViolation} When the write operation fails due to storage errors
+     */
+    persistState(event: ArvoEvent, record: T, prevRecord: T | null, span?: Span): Promise<void>;
+    /**
+     * Validates that the event subject conforms to the ArvoOrchestrationSubject format.
+     *
+     * This method ensures that the event subject follows the expected schema format
+     * required by the Arvo orchestration system. Invalid subjects will result in
+     * execution violations to prevent processing of malformed events across the
+     * distributed service architecture.
+     *
+     * @throws {ExecutionViolation} When the event subject format is invalid
+     *
+     * @protected
+     */
+    validateEventSubject(event: ArvoEvent, span?: Span): void;
+    /**
+     * Releases a previously acquired lock on the event subject.
+     *
+     * This method safely releases locks that were acquired during event processing to prevent
+     * resource leaks in distributed systems. It handles cases where no lock was acquired
+     * (NOOP operations) and provides proper error handling for unlock failures. Failed unlock
+     * operations are logged as potential resource leaks but do not throw exceptions to avoid
+     * disrupting the main processing flow as it assumes that the lock will have the lifedspan.
+     *
+     * @returns A promise that resolves to the lock release status:
+     *          - 'NOOP': No lock was acquired, so no operation was performed
+     *          - 'RELEASED': Lock was successfully released
+     *          - 'ERROR': Lock release failed, potential resource leak
+     *
+     * @protected
+     */
+    releaseLock(event: ArvoEvent, acquiredLock: AcquiredLockStatusType | null, span?: Span): Promise<ReleasedLockStatusType>;
+}