arvo-event-handler
Version:
A complete set of orthogonal event handler and orchestration primitives for Arvo based applications, featuring declarative state machines (XState), imperative resumables for agentic workflows, contract-based routing, OpenTelemetry observability, and in-me
299 lines (298 loc) • 23.3 kB
JavaScript
"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 };
}
};
var __rest = (this && this.__rest) || function (s, e) {
var t = {};
for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
t[p] = s[p];
if (s != null && typeof Object.getOwnPropertySymbols === "function")
for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
t[p[i]] = s[p[i]];
}
return t;
};
Object.defineProperty(exports, "__esModule", { value: true });
var api_1 = require("@opentelemetry/api");
var arvo_core_1 = require("arvo-core");
var ArvoDomain_1 = require("../ArvoDomain");
var handlerErrors_1 = require("../ArvoOrchestrationUtils/handlerErrors");
var orchestrationExecutionWrapper_1 = require("../ArvoOrchestrationUtils/orchestrationExecutionWrapper");
var errors_1 = require("../errors");
var utils_1 = require("../utils");
/**
* The foundational component for building stateless,
* contract-bound services in the Arvo system.
*/
var ArvoEventHandler = /** @class */ (function () {
function ArvoEventHandler(param) {
var _a;
var _b, _c, _d, _e;
this.contract = param.contract;
this.executionunits = (_b = param.executionunits) !== null && _b !== void 0 ? _b : 0;
this.handler = param.handler;
this.defaultEventEmissionDomains = __assign({ systemError: [ArvoDomain_1.ArvoDomain.ORCHESTRATION_CONTEXT], emits: [ArvoDomain_1.ArvoDomain.ORCHESTRATION_CONTEXT] }, ((_c = param.defaultEventEmissionDomains) !== null && _c !== void 0 ? _c : {}));
for (var _i = 0, _f = Object.keys(this.contract.versions); _i < _f.length; _i++) {
var contractVersions = _f[_i];
if (!this.handler[contractVersions]) {
throw new Error("Contract ".concat(this.contract.uri, " requires handler implementation for version ").concat(contractVersions));
}
}
this.spanOptions = __assign(__assign({ kind: api_1.SpanKind.CONSUMER }, param.spanOptions), { attributes: __assign(__assign((_a = {}, _a[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = arvo_core_1.ArvoExecutionSpanKind.EVENT_HANDLER, _a[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = arvo_core_1.OpenInferenceSpanKind.CHAIN, _a), ((_e = (_d = param.spanOptions) === null || _d === void 0 ? void 0 : _d.attributes) !== null && _e !== void 0 ? _e : {})), { 'arvo.handler.source': this.source, 'arvo.contract.uri': this.contract.uri }) });
}
Object.defineProperty(ArvoEventHandler.prototype, "source", {
/** The source identifier for events produced by this handler */
get: function () {
return this.contract.type;
},
enumerable: false,
configurable: true
});
Object.defineProperty(ArvoEventHandler.prototype, "domain", {
/** The contract-defined domain for the handler */
get: function () {
return this.contract.domain;
},
enumerable: false,
configurable: true
});
/**
* Processes an incoming event according to the handler's contract specifications. This method
* handles the complete lifecycle of event processing including validation, execution, error
* handling, and multi-domain event broadcasting, while maintaining detailed telemetry through OpenTelemetry.
*
* @throws {ContractViolation} when input or output event data violates the contract schema,
* or when event emission fails due to invalid data
* @throws {ConfigViolation} when event type doesn't match contract type, when the
* contract version expected by the event does not exist
* in handler configuration, or when contract URI mismatch occurs
* @throws {ExecutionViolation} for explicitly handled runtime errors that should bubble up
*/
ArvoEventHandler.prototype.execute = function (event, opentelemetry) {
return __awaiter(this, void 0, void 0, function () {
var otelConfig;
var _this = this;
var _a, _b;
return __generator(this, function (_c) {
switch (_c.label) {
case 0:
otelConfig = (0, utils_1.createEventHandlerTelemetryConfig)(((_b = (_a = this.spanOptions).spanName) === null || _b === void 0 ? void 0 : _b.call(_a, { selfContractUri: this.contract.uri, consumedEvent: event })) ||
"Handler<".concat(this.contract.uri, ">"), this.spanOptions, opentelemetry !== null && opentelemetry !== void 0 ? opentelemetry : { inheritFrom: 'EVENT' }, event);
return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan(__assign(__assign({}, otelConfig), { fn: function (span) { return __awaiter(_this, void 0, void 0, function () {
var otelSpanHeaders, _i, _a, _b, key, value, parsedDataSchema, handlerContract_1, inputEventValidation, _handleOutput, outputs, result, _c, outputs_1, item, __extensions, handlerResult, domains, _d, _e, _dom, _f, _g, _h, key, value, error_1, errorEvents, _j, _k, _l, errEvtIdx, errEvt, _m, _o, _p, key, value;
var _q, _r, _s, _t, _u;
return __generator(this, function (_v) {
switch (_v.label) {
case 0:
otelSpanHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
_v.label = 1;
case 1:
_v.trys.push([1, 3, 4, 5]);
span.setAttribute('arvo.handler.execution.status', 'normal');
span.setAttribute('arvo.handler.execution.type', 'handler');
span.setStatus({ code: api_1.SpanStatusCode.OK });
for (_i = 0, _a = Object.entries(event.otelAttributes); _i < _a.length; _i++) {
_b = _a[_i], key = _b[0], value = _b[1];
span.setAttribute("consumable.0.".concat(key), value);
}
if (this.contract.type !== event.type) {
throw new errors_1.ConfigViolation("Event type mismatch: Received '".concat(event.type, "', expected '").concat(this.contract.type, "'"));
}
(0, arvo_core_1.logToSpan)({
level: 'INFO',
message: "Event type '".concat(event.type, "' validated against contract '").concat(this.contract.uri, "'"),
});
parsedDataSchema = arvo_core_1.EventDataschemaUtil.parse(event);
// If the URI exists but conflicts with the contract's URI
// Here we are only concerned with the URI bit not the version
if ((parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.uri) && (parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.uri) !== this.contract.uri) {
throw new errors_1.ContractViolation("Contract URI mismatch: Handler expects '".concat(this.contract.uri, "' but event dataschema specifies '").concat(event.dataschema, "'. Events must reference the same contract URI as their handler."));
}
// If the version does not exist then just warn. The latest version will be used in this case
if (!(parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.version)) {
(0, arvo_core_1.logToSpan)({
level: 'WARNING',
message: "Version resolution failed for event with dataschema '".concat(event.dataschema, "'. Defaulting to latest version (=").concat(this.contract.version('latest').version, ") of contract (uri=").concat(this.contract.uri, ")"),
});
}
try {
handlerContract_1 = this.contract.version((_q = parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.version) !== null && _q !== void 0 ? _q : 'latest');
}
catch (_w) {
throw new errors_1.ConfigViolation("Invalid contract version: ".concat(parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.version, ". Available versions: ").concat(Object.keys(this.contract.versions).join(', ')));
}
(0, arvo_core_1.logToSpan)({
level: 'INFO',
message: "Processing event with contract version ".concat(handlerContract_1.version),
});
inputEventValidation = handlerContract_1.accepts.schema.safeParse(event.data);
if (inputEventValidation.error) {
throw new errors_1.ContractViolation("Input event payload validation failed: ".concat(inputEventValidation.error));
}
(0, arvo_core_1.logToSpan)({
level: 'INFO',
message: "Event payload validated successfully against contract ".concat(arvo_core_1.EventDataschemaUtil.create(handlerContract_1)),
});
(0, arvo_core_1.logToSpan)({
level: 'INFO',
message: "Executing handler for event type '".concat(event.type, "'"),
});
return [4 /*yield*/, this.handler[handlerContract_1.version]({
event: event.toJSON(),
source: this.source,
contract: handlerContract_1,
domain: {
self: this.domain,
event: event.domain,
},
span: span,
spanHeaders: otelSpanHeaders,
})];
case 2:
_handleOutput = _v.sent();
if (!_handleOutput)
return [2 /*return*/, {
events: [],
}];
outputs = [];
if (Array.isArray(_handleOutput)) {
outputs = _handleOutput;
}
else {
outputs = [_handleOutput];
}
result = [];
for (_c = 0, outputs_1 = outputs; _c < outputs_1.length; _c++) {
item = outputs_1[_c];
try {
__extensions = item.__extensions, handlerResult = __rest(item, ["__extensions"]);
domains = ((_r = handlerResult.domain) !== null && _r !== void 0 ? _r : this.defaultEventEmissionDomains.emits).map(function (item) {
return (0, ArvoDomain_1.resolveEventDomain)({
parentSubject: null,
currentSubject: event.subject,
domainToResolve: item,
handlerSelfContract: handlerContract_1,
eventContract: handlerContract_1,
triggeringEvent: event,
});
});
for (_d = 0, _e = Array.from(new Set(domains)); _d < _e.length; _d++) {
_dom = _e[_d];
result.push((0, arvo_core_1.createArvoEventFactory)(handlerContract_1).emits(__assign(__assign({}, handlerResult), { traceparent: otelSpanHeaders.traceparent || undefined, tracestate: otelSpanHeaders.tracestate || undefined, source: this.source, subject: event.subject,
// 'source'
// prioritise returned 'to', 'redirectto' and then
to: (0, utils_1.coalesceOrDefault)([handlerResult.to, event.redirectto], event.source), executionunits: (0, utils_1.coalesce)(handlerResult.executionunits, this.executionunits), accesscontrol: (_t = (_s = handlerResult.accesscontrol) !== null && _s !== void 0 ? _s : event.accesscontrol) !== null && _t !== void 0 ? _t : undefined, parentid: event.id, domain: _dom }), __extensions));
for (_f = 0, _g = Object.entries(result[result.length - 1].otelAttributes); _f < _g.length; _f++) {
_h = _g[_f], key = _h[0], value = _h[1];
span.setAttribute("emittables.".concat(result.length - 1, ".").concat(key), value);
}
}
}
catch (e) {
throw new errors_1.ContractViolation((_u = e === null || e === void 0 ? void 0 : e.message) !== null && _u !== void 0 ? _u : 'Invalid data');
}
}
return [2 /*return*/, (0, orchestrationExecutionWrapper_1.returnEventsWithLogging)({ events: result }, span)];
case 3:
error_1 = _v.sent();
span.setAttribute('arvo.handler.execution.status', 'failure');
(0, arvo_core_1.exceptionToSpan)(error_1);
span.setStatus({
code: api_1.SpanStatusCode.ERROR,
message: "Event processing failed: ".concat(error_1.message),
});
if ((0, arvo_core_1.isViolationError)(error_1)) {
throw error_1;
}
errorEvents = (0, handlerErrors_1.createSystemErrorEvents)({
error: error_1,
event: event,
otelHeaders: otelSpanHeaders,
orchestrationParentSubject: null,
initEventId: event.id,
selfContract: this.contract.version('any'),
systemErrorDomain: this.defaultEventEmissionDomains.systemError,
executionunits: this.executionunits,
source: this.source,
handlerType: 'handler',
});
for (_j = 0, _k = Object.entries(errorEvents); _j < _k.length; _j++) {
_l = _k[_j], errEvtIdx = _l[0], errEvt = _l[1];
for (_m = 0, _o = Object.entries(errEvt.otelAttributes); _m < _o.length; _m++) {
_p = _o[_m], key = _p[0], value = _p[1];
span.setAttribute("emittables.".concat(errEvtIdx, ".").concat(key), value);
}
}
return [2 /*return*/, (0, orchestrationExecutionWrapper_1.returnEventsWithLogging)({
events: errorEvents,
}, span)];
case 4:
span.end();
return [7 /*endfinally*/];
case 5: return [2 /*return*/];
}
});
}); } }))];
case 1: return [2 /*return*/, _c.sent()];
}
});
});
};
Object.defineProperty(ArvoEventHandler.prototype, "systemErrorSchema", {
/**
* Provides access to the system error event schema configuration.
*/
get: function () {
return this.contract.systemError;
},
enumerable: false,
configurable: true
});
return ArvoEventHandler;
}());
exports.default = ArvoEventHandler;