@cratis/chronicle 6.21.0 → 6.22.1

package/reactors/Reactors.ts

@@ -4,11 +4,10 @@
 import 'reflect-metadata';
 import { diag } from '@opentelemetry/api';
 import { Constructor } from '@cratis/fundamentals';
-import { EventObservationState, ObservationState, ReactorMessage, ReplayState } from '@cratis/chronicle.contracts';
+import { ObservationState, ReactorMessage, ReplayState } from '@cratis/chronicle.contracts';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
 import { ChronicleConnection } from '../connection/index.js';
 import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
-import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
 import { toClientEventContext } from '../events/toClientEventContext.js';
 import { getTagsFor } from '../events/tagDecorator.js';
 import { getFilterTagsFor } from '../events/filterEventsByTagDecorator.js';
@@ -19,7 +18,8 @@ import { IReactors } from './IReactors.js';
 import { dispatchReactorSideEffects } from './ReactorSideEffects.js';
 import { getReactorMetadata } from './reactor.js';
 import { isOnceOnly } from './onceOnly.js';
-import { getReplayEventType } from './replay.js';
+import { getReactorEventTypes, selectReactorHandler, invokeReactorHandler } from './ReactorDispatcher.js';
+import type { ReactorEventTypeEntry } from './ReactorDispatcher.js';
 import type { ReactorResultHandler } from './ReactorResultHandler.js';
 import type { ReactorServices } from './ReactorServices.js';
 import type { IEventStore } from '../IEventStore.js';
@@ -36,13 +36,6 @@ const EVENT_SOURCE_ID_KEY = '$eventSourceId';
 /** Sentinel sequence number sent back when no event was successfully processed. */
 const SEQUENCE_NUMBER_UNAVAILABLE = 4294967295n;
 
-interface EventTypeEntry {
-    readonly id: string;
-    readonly generation: number;
-    readonly methodName?: string;
-    readonly replayMethodName?: string;
-}
-
 /**
  * A push-based async queue that implements {@link AsyncIterable} for use with nice-grpc
  * bidirectional streaming. Values pushed via {@link send} are yielded in order to
@@ -187,7 +180,7 @@ export class Reactors implements IReactors {
         if (this._disposed) return;
         const metadata = getReactorMetadata(reactorType)!;
         const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
-        const eventTypes = this.getEventTypesFor(reactorType);
+        const eventTypes = getReactorEventTypes(reactorType, this._clientArtifacts.eventTypes);
 
         this._logger.info('Starting reactor observation', {
             reactorId: id,
@@ -203,7 +196,7 @@ export class Reactors implements IReactors {
         id: string,
         reactorType: Constructor,
         eventSequenceId: string,
-        eventTypes: EventTypeEntry[]
+        eventTypes: ReactorEventTypeEntry[]
     ): Promise<void> {
         try {
             await this.observeReactor(id, reactorType, eventSequenceId, eventTypes);
@@ -246,7 +239,7 @@ export class Reactors implements IReactors {
         id: string,
         reactorType: Constructor,
         eventSequenceId: string,
-        eventTypes: EventTypeEntry[]
+        eventTypes: ReactorEventTypeEntry[]
     ): Promise<void> {
         const queue = new AsyncQueue<ReactorMessage>();
         const controller = new AbortController();
@@ -323,12 +316,8 @@ export class Reactors implements IReactors {
                 }
 
                 const selectHandler = (event: typeof eventsToObserve.Events[number]) => {
-                    const entry = eventTypes.find(candidate => candidate.id === event.Context?.EventType?.Id);
-                    if (!entry) return undefined;
-                    const isReplay = (event.Context!.ObservationState & EventObservationState.Replay) !== 0;
-                    const methodName = isReplay ? (entry.replayMethodName ?? entry.methodName) : entry.methodName;
-                    const method = methodName ? (reactorInstance?.[methodName] ?? (reactorType.prototype as Record<string, Function>)[methodName]) : undefined;
-                    return { methodName, isReplay, skipReplay: isReplay && method !== undefined && isOnceOnly(method) };
+                    return selectReactorHandler(eventTypes, reactorType, reactorInstance,
+                        event.Context?.EventType?.Id, event.Context?.ObservationState ?? 0);
                 };
 
                 const processEvents = async (artifact: ActivatedArtifact<Record<string, Function>>) => {
@@ -369,11 +358,9 @@ export class Reactors implements IReactors {
                                 eventTypeId
                             });
 
-                            await runActivated(artifact, async () => {
-                                const handlerResult = await artifact.instance[methodName](content, context, services);
-                                await dispatchReactorSideEffects(this._eventLog, handlerResult, context, reactorType as Function,
-                                    this._eventStoreName, this._namespace, this._resultHandler);
-                            }, { delivery: ArtifactDelivery.Events, eventContext: context, methodName });
+                            await invokeReactorHandler(artifact, methodName, content, context, services, result =>
+                                dispatchReactorSideEffects(this._eventLog, result, context, reactorType as Function,
+                                    this._eventStoreName, this._namespace, this._resultHandler));
 
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                         } catch (err) {
@@ -446,65 +433,6 @@ export class Reactors implements IReactors {
         }
     }
 
-    private getEventTypesFor(reactorType: Constructor): EventTypeEntry[] {
-        const proto = reactorType.prototype as Record<string, unknown>;
-        const entries: EventTypeEntry[] = [];
-        const replayHandlers = new Map<string, string>();
-        const eventTypes = new Map<string, { eventTypeClass: Function; id: string; generation: number }>();
-
-        for (const eventTypeClass of this._clientArtifacts.eventTypes) {
-            const metadata = getEventTypeMetadata(eventTypeClass);
-            if (metadata) {
-                eventTypes.set((eventTypeClass as Function).name, {
-                    eventTypeClass: eventTypeClass as Function,
-                    id: metadata.eventType.id.value,
-                    generation: metadata.eventType.generation.value
-                });
-            }
-        }
-
-        // A derived method shadows a base method of the same name, even if it is not marked for replay.
-        const seenMethods = new Set<string>();
-        for (let current = proto; current && current !== Object.prototype; current = Object.getPrototypeOf(current) as Record<string, unknown>) {
-            for (const name of Object.getOwnPropertyNames(current)) {
-                if (seenMethods.has(name)) continue;
-                seenMethods.add(name);
-                const method = current[name];
-                if (typeof method !== 'function') continue;
-                const replayEventType = getReplayEventType(method);
-                if (replayEventType === undefined) continue;
-
-                const eventType = replayEventType === true
-                    ? eventTypes.get(name.startsWith('replay') ? name.slice('replay'.length) : '')
-                    : [...eventTypes.values()].find(candidate => candidate.eventTypeClass === replayEventType);
-                if (!eventType) {
-                    throw new Error(`Replay handler '${name}' on reactor '${(reactorType as Function).name}' has no registered event type.`);
-                }
-                if (replayHandlers.has(eventType.id)) {
-                    throw new Error(`Reactor '${(reactorType as Function).name}' has multiple replay handlers for event type '${eventType.id}': '${replayHandlers.get(eventType.id)}' and '${name}'.`);
-                }
-                replayHandlers.set(eventType.id, name);
-            }
-        }
-
-        for (const [className, eventType] of eventTypes) {
-            const methodName = className.charAt(0).toLowerCase() + className.slice(1);
-            const liveMethod = proto[methodName];
-            const liveMethodName = typeof liveMethod === 'function' && getReplayEventType(liveMethod) === undefined ? methodName : undefined;
-            const replayMethodName = replayHandlers.get(eventType.id);
-            if (liveMethodName || replayMethodName) {
-                entries.push({
-                    id: eventType.id,
-                    generation: eventType.generation,
-                    methodName: liveMethodName,
-                    replayMethodName
-                });
-            }
-        }
-
-        return entries;
-    }
-
     private disconnectAll(): void {
         for (const controller of this._observations.values()) controller.abort();
         for (const queue of this._queues.values()) queue.complete();

package/testing/InProcessEventSequence.ts

@@ -34,6 +34,19 @@ import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOpe
 // JS trim() omits U+0085, which the kernel trims. Reject unproven non-ASCII whitespace and controls.
 const unprovenFilterCharacters = /[\u007f-\u009f]|(?=[^\x00-\x7f])\p{White_Space}/u;
 
+// Observers ReactorScenario registers to latch unsupported operations, keyed by sequence.
+const unsupportedObservers = new WeakMap<object, (error: UnsupportedEventSequenceOperation) => void>();
+
+/**
+ * Observe every unsupported operation a scenario sequence reports, however the caller receives it.
+ * Internal to the testing harness; ReactorScenario uses it to fail deliveries that swallow such errors.
+ * @param sequence - The in-process sequence to observe.
+ * @param observer - Called with each unsupported-operation error the sequence creates.
+ */
+export function observeUnsupportedOperations(sequence: object, observer: (error: UnsupportedEventSequenceOperation) => void): void {
+    unsupportedObservers.set(sequence, observer);
+}
+
 /** Fixture-backed, scenario-local append sequence; no kernel or observer scheduler is started. */
 export class InProcessEventSequence implements IEventSequence {
     readonly id: EventSequenceId;
@@ -455,6 +468,8 @@ export class InProcessEventSequence implements IEventSequence {
     }
 
     private unsupported(operation: string, artifact: string, reason: string): UnsupportedEventSequenceOperation {
-        return new UnsupportedEventSequenceOperation(operation, artifact, reason);
+        const error = new UnsupportedEventSequenceOperation(operation, artifact, reason);
+        unsupportedObservers.get(this)?.(error);
+        return error;
     }
 }

package/testing/ReactorDeliveryResult.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventContext } from '../events/EventContext.js';
+
+/** Observable outcome of one ordered source-partition delivery (not a kernel checkpoint). */
+export interface ReactorDeliveryResult {
+    readonly sourceId: string;
+    readonly handled: readonly EventContext[];
+    readonly skipped: readonly EventContext[];
+    readonly completed: boolean;
+    readonly error?: unknown;
+}

package/testing/ReactorScenario.rejections.spec.ts

@@ -0,0 +1,100 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field } from '@cratis/fundamentals';
+import { chai, describe, it } from 'vitest';
+import { ArtifactCompletionFailed } from '../artifacts/ArtifactCompletionFailed.js';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { reactor } from '../reactors/reactor.js';
+import { ReactorScenario } from './ReactorScenario.js';
+import { UnsupportedReactorOperation } from './UnsupportedReactorOperation.js';
+
+chai.should();
+@eventType('rejection-event')
+class Registered {
+    @field(String) name: string;
+    constructor(name: string) { this.name = name; }
+}
+class Unregistered { constructor(readonly name: string) {} }
+const options = { artifacts: { eventTypes: [Registered] }, constraints: 'disabled' as const };
+
+async function rejected(operation: string, call: () => Promise<unknown>): Promise<void> {
+    await call().then(() => { throw new Error('expected rejection'); }, error => {
+        (error instanceof UnsupportedReactorOperation).should.be.true;
+        error.operation.should.equal(operation);
+        error.message.should.contain('Use a kernel-backed test.');
+    });
+}
+
+describe('unsupported reactor operations', () => {
+    it('rejects missing registration, custom sequence and commands during configuration', () => {
+        class Plain {}
+        (() => new ReactorScenario(Plain, options)).should.throw(UnsupportedReactorOperation, 'Use a kernel-backed test.');
+        @reactor('custom-sequence', 'custom') class Custom { registered() {} }
+        (() => new ReactorScenario(Custom, options)).should.throw(UnsupportedReactorOperation, 'Use a kernel-backed test.');
+        @reactor('commands') class Commands { registered() {} }
+        (() => new ReactorScenario(Commands, { ...options, commandTypes: [Unregistered] }))
+            .should.throw(UnsupportedReactorOperation, 'Use a kernel-backed test.');
+    });
+
+    it('rejects replay and redelivery asynchronously without mutation', async () => {
+        @reactor('replay-rejection') class R { registered() {} }
+        const scenario = new ReactorScenario(R, options);
+        await rejected('replay', () => scenario.replay());
+        await rejected('redeliver', () => scenario.redeliver());
+        await rejected('when.events', () => scenario.when.forEventSource('A').events());
+        scenario.results.length.should.equal(0);
+        scenario.sideEffects.length.should.equal(0);
+    });
+
+    it('rejects unsupported returned values instead of silently dropping them', async () => {
+        for (const value of [{ command: true }, [new Registered('ok'), { command: true }], [undefined]]) {
+            @reactor('unknown-result') class R { registered() { return value; } }
+            const scenario = new ReactorScenario(R, options);
+            await rejected('handler.return', () => scenario.when.forEventSource('A').events(new Registered('one')));
+            scenario.sideEffects.length.should.equal(0);
+            scenario.results[0].completed.should.be.false;
+        }
+    });
+
+    it('rejects unsupported setup before invocation and without delivery results', async () => {
+        let called = 0;
+        @reactor('unsupported-input') class R { registered() { called++; } }
+        const scenario = new ReactorScenario(R, options);
+        await scenario.given.forEventSource('A').events(new Registered('ok'), new Unregistered('bad')).then(() => {
+            throw new Error('expected rejection');
+        }, error => { error.message.should.contain('Use a kernel-backed test.'); });
+        called.should.equal(0);
+        scenario.results.length.should.equal(0);
+        await scenario.when.forEventSource('A').events(new Registered('after'));
+        scenario.results[0].handled[0].sequenceNumber.should.equal(0n);
+    });
+
+    it('rejects missing read-model services instead of supplying fake data', async () => {
+        @reactor('read-model-rejection') class R {
+            registered(_event: Registered, _context: unknown, services: { readModels: { findInstanceById(): unknown } }) {
+                return services.readModels.findInstanceById();
+            }
+        }
+        const scenario = new ReactorScenario(R, options);
+        await rejected('services.readModels.findInstanceById', () => scenario.when.forEventSource('A').events(new Registered('one')));
+    });
+
+    it('preserves processing-only, completion-only and activation failures', async () => {
+        @reactor('failure-rejection') class R { registered() { throw new Error('handler'); } }
+        const processing = new ReactorScenario(R, { ...options, artifactActivator: type => ({ instance: new type() }) });
+        await processing.when.forEventSource('A').events(new Registered('one')).then(() => { throw new Error('expected rejection'); },
+            error => { String(error).should.contain('handler'); });
+        processing.results[0].completed.should.be.false;
+        @reactor('completion-rejection') class Complete { registered() {} }
+        const completion = new ReactorScenario(Complete, { ...options, artifactActivator: type => ({ instance: new type(),
+            complete: () => { throw new Error('completion'); } }) });
+        await completion.when.forEventSource('A').events(new Registered('one')).then(() => { throw new Error('expected rejection'); },
+            error => { (error instanceof ArtifactCompletionFailed).should.be.true; chai.expect(error.processingError).to.be.undefined; });
+        completion.results[0].completed.should.be.false;
+        const activation = new ReactorScenario(Complete, { ...options, artifactActivator: () => { throw new Error('activation'); } });
+        await activation.when.forEventSource('A').events(new Registered('one')).then(() => { throw new Error('expected rejection'); },
+            error => { String(error).should.contain('activation'); });
+        activation.results[0].handled.length.should.equal(0);
+    });
+});