arvo-event-handler
Version:
Type-safe event handler system with versioning, telemetry, and contract validation for distributed Arvo event-driven architectures, featuring routing and multi-handler support.
446 lines (445 loc) • 30.5 kB
JavaScript
"use strict";
var __extends = (this && this.__extends) || (function () {
var extendStatics = function (d, b) {
extendStatics = Object.setPrototypeOf ||
({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
return extendStatics(d, b);
};
return function (d, b) {
if (typeof b !== "function" && b !== null)
throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
extendStatics(d, b);
function __() { this.constructor = d; }
d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
};
})();
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;
};
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
var api_1 = require("@opentelemetry/api");
var arvo_core_1 = require("arvo-core");
var AbstractArvoEventHandler_1 = __importDefault(require("../AbstractArvoEventHandler"));
var errors_1 = require("../errors");
var utils_1 = require("../utils");
var ArvoDomain_1 = require("../ArvoDomain");
/**
* `ArvoEventHandler` is the foundational component for building stateless,
* contract-bound services in the Arvo system.
*
* It enforces strict contract validation, version-aware handler resolution,
* and safe, observable event emission — all while maintaining type safety,
* traceability, and support for multi-domain workflows.
*
* ## What It Does
* - Ensures incoming events match the contract's `type` and `dataschema`
* - Resolves the correct contract version using `dataschema`
* - Validates input and output data via Zod schemas
* - Executes the version-specific handler function
* - Emits one or more response events based on the handler result
* - Supports multi-domain broadcasting via `domain[]` on the emitted events
* - Automatically emits system error events (`sys.*.error`) on failure
* - Integrates deeply with OpenTelemetry for tracing and observability
*
* ## Error Boundaries
* ArvoEventHandler enforces a clear separation between:
*
* - **Violations** — structural, schema, or config errors that break the contract.
* These are thrown and must be handled explicitly by the caller.
*
* - **System Errors** — runtime exceptions during execution that are caught and
* emitted as standardized `sys.<contract>.error` events.
*
* ## Domain Broadcasting
* The handler supports multi-domain event distribution. When the handler
* returns an event with a `domain` array, it is broadcast to one or more
* routing contexts.
*
* ### System Error Domain Control
* By default, system error events are broadcast into the source event’s domain,
* the handler’s contract domain, and the `null` domain. This fallback ensures errors
* are visible across all relevant contexts. Developers can override this behavior
* using the optional `systemErrorDomain` field to specify an explicit set of
* domain values, including symbolic constants from {@link ArvoDomain}.
*
* ### Supported Domain Values:
* - A **concrete domain string** like `'audit.orders'` or `'human.review'`
* - `null` to emit with no domain (standard internal flow)
* - A **symbolic reference** from {@link ArvoDomain}
*
* ### Domain Resolution Rules:
* - Each item in the `domain` array is resolved via {@link resolveEventDomain}
* - Duplicate domains are deduplicated before emitting
* - If `domain` is omitted entirely, Arvo defaults to `[null]`
*
* ### Example:
* ```ts
* return {
* type: 'evt.user.registered',
* data: { ... },
* domain: ['analytics', ArvoDomain.FROM_TRIGGERING_EVENT, null]
* };
* ```
* This would emit at most 3 copies of the event, domained to:
* - `'analytics'`
* - the domain of the incoming event
* - no domain (default)
*
* ### Domain Usage Guidance
*
* > **Avoid setting `contract.domain` unless fully intentional.**
* 99% emitted event should default to `null` (standard processing pipeline).
*
* Contract-level domains enforce implicit routing for every emitted event
* in that handler, making the behavior harder to override and debug.
*
* Prefer:
* - Explicit per-event `domain` values in handler output
* - Using `null` or symbolic constants to control domain cleanly
*
* ## When to Use Domains
* Use domains when handling for specialized contexts:
* - `'human.review'` → for human-in-the-loop steps
* - `'analytics.workflow'` → to pipe events into observability systems
* - `'external.partner.sync'` → to route to external services
*/
var ArvoEventHandler = /** @class */ (function (_super) {
__extends(ArvoEventHandler, _super);
/**
* Initializes a new ArvoEventHandler instance with the specified contract and configuration.
* Validates handler implementations against contract versions during initialization.
*
* The constructor ensures that handler implementations exist for all supported contract
* versions and configures OpenTelemetry span attributes for monitoring event handling.
*
* @param param - Handler configuration including contract, execution units, and handler implementations
* @throws When handler implementations are missing for any contract version
*/
function ArvoEventHandler(param) {
var _a;
var _b, _c;
var _this = _super.call(this) || this;
_this.systemErrorDomain = undefined;
_this.contract = param.contract;
_this.executionunits = param.executionunits;
_this.handler = param.handler;
_this.systemErrorDomain = param.systemErrorDomain;
for (var _i = 0, _d = Object.keys(_this.contract.versions); _i < _d.length; _i++) {
var contractVersions = _d[_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), ((_c = (_b = param.spanOptions) === null || _b === void 0 ? void 0 : _b.attributes) !== null && _c !== void 0 ? _c : {})), { 'arvo.handler.source': _this.source, 'arvo.contract.uri': _this.contract.uri }) });
return _this;
}
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 this handler, used as the default domain for emitted events.
* Can be overridden by individual handler implementations for cross-domain workflows.
* Returns null if no domain is specified, indicating standard processing context.
*/
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.
*
* @param event - The incoming event to process
* @param opentelemetry - Configuration for OpenTelemetry context inheritance, defaults to inheriting from the event
* @returns Promise resolving to a structured result containing an array of output events
* @returns Structured response containing:
* - `events`: Array of events to be emitted (may contain multiple events per handler output due to domain broadcasting)
*
* @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_1) {
return __awaiter(this, arguments, void 0, function (event, opentelemetry) {
var otelConfig;
var _this = this;
if (opentelemetry === void 0) { opentelemetry = {
inheritFrom: 'EVENT',
}; }
return __generator(this, function (_a) {
switch (_a.label) {
case 0:
otelConfig = (0, utils_1.createEventHandlerTelemetryConfig)("Handler<".concat(this.contract.uri, ">"), this.spanOptions, opentelemetry, 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, result, _j, _k, _dom, _l, _m, _o, key, value;
var _this = this;
var _p, _q, _r, _s, _t, _u, _v, _w, _x, _y;
return __generator(this, function (_z) {
switch (_z.label) {
case 0:
otelSpanHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
_z.label = 1;
case 1:
_z.trys.push([1, 3, 4, 5]);
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("to_process.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((_p = parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.version) !== null && _p !== void 0 ? _p : 'latest');
}
catch (_0) {
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,
})];
case 2:
_handleOutput = _z.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 = (_q = handlerResult.domain) === null || _q === void 0 ? void 0 : _q.map(function (item) {
return (0, ArvoDomain_1.resolveEventDomain)({
domainToResolve: item,
handlerSelfContract: handlerContract_1,
eventContract: handlerContract_1,
triggeringEvent: event,
});
})) !== null && _r !== void 0 ? _r : [null];
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("to_emit.".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');
}
}
(0, arvo_core_1.logToSpan)({
level: 'INFO',
message: "Event processing completed successfully. Generated ".concat(result.length, " event(s)"),
});
(0, arvo_core_1.logToSpan)({
level: 'INFO',
message: 'Event handled successfully',
});
return [2 /*return*/, {
events: result,
}];
case 3:
error_1 = _z.sent();
(0, arvo_core_1.exceptionToSpan)(error_1);
span.setStatus({
code: api_1.SpanStatusCode.ERROR,
message: "Event processing failed: ".concat(error_1.message),
});
if (error_1.name.includes('ViolationError')) {
throw error_1;
}
result = [];
for (_j = 0, _k = Array.from(new Set(this.systemErrorDomain
? this.systemErrorDomain.map(function (item) {
return (0, ArvoDomain_1.resolveEventDomain)({
domainToResolve: item,
handlerSelfContract: _this.contract.version('latest'),
eventContract: _this.contract.version('latest'),
triggeringEvent: event,
});
})
: [event.domain, this.domain, null])); _j < _k.length; _j++) {
_dom = _k[_j];
result.push((0, arvo_core_1.createArvoEventFactory)(this.contract.version('latest')).systemError({
source: this.source,
subject: event.subject,
// The system error must always got back to
// the source
to: event.source,
error: error_1,
executionunits: this.executionunits,
traceparent: (_v = otelSpanHeaders.traceparent) !== null && _v !== void 0 ? _v : undefined,
tracestate: (_w = otelSpanHeaders.tracestate) !== null && _w !== void 0 ? _w : undefined,
accesscontrol: (_x = event.accesscontrol) !== null && _x !== void 0 ? _x : undefined,
parentid: (_y = event.id) !== null && _y !== void 0 ? _y : undefined,
domain: _dom,
}));
for (_l = 0, _m = Object.entries(result[result.length - 1].otelAttributes); _l < _m.length; _l++) {
_o = _m[_l], key = _o[0], value = _o[1];
span.setAttribute("to_emit.".concat(result.length - 1, ".").concat(key), value);
}
}
return [2 /*return*/, {
events: result,
}];
case 4:
span.end();
return [7 /*endfinally*/];
case 5: return [2 /*return*/];
}
});
}); } }))];
case 1: return [2 /*return*/, _a.sent()];
}
});
});
};
Object.defineProperty(ArvoEventHandler.prototype, "systemErrorSchema", {
/**
* Provides access to the system error event schema configuration.
*
* The schema defines the structure of error events emitted during execution failures.
* These events are automatically generated when runtime errors occur and follow a
* standardized format for consistent error handling across the system.
*
* Error events follow the naming convention: `sys.<contract-type>.error`
*
* @example
* For a contract handling 'com.user.create' events, system error events
* will have the type 'sys.com.user.create.error'
*
* @returns The error event schema containing type and validation rules
*/
get: function () {
return this.contract.systemError;
},
enumerable: false,
configurable: true
});
return ArvoEventHandler;
}(AbstractArvoEventHandler_1.default));
exports.default = ArvoEventHandler;