@cratis/chronicle 6.7.1 → 6.9.0

package/reactors/Reactors.replay.legacy.spec.ts

@@ -0,0 +1,241 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventContext, EventObservationState, EventType, ReactorMessage } from '@cratis/chronicle.contracts';
+import { describe, expect, it } from 'vitest';
+import type { IClientArtifactsProvider } from '../artifacts/index.js';
+import type { ChronicleConnection } from '../connection/index.js';
+import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
+import type { IEventLog } from '../eventSequences/IEventLog.js';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { onceOnly } from './onceOnly.js';
+import { reactor } from './reactor.js';
+import { Reactors } from './Reactors.js';
+import { replay } from './replay.js';
+
+@eventType('reactor-replay-event')
+class SomethingHappened {
+    constructor(readonly value: string = '') {}
+}
+
+async function observe(type: Function, states: EventObservationState[]) {
+    const lifecycle = new ConnectionLifecycle();
+    let registration!: ReactorMessage;
+    let result!: ReactorMessage;
+    let finish!: () => void;
+    const finished = new Promise<void>(resolve => { finish = resolve; });
+    async function* stream(queue: AsyncIterable<ReactorMessage>) {
+        const messages = queue[Symbol.asyncIterator]();
+        registration = (await messages.next()).value!;
+        yield {
+            Events: states.map((state, index) => ({
+                Context: EventContext.fromPartial({
+                    EventType: EventType.fromPartial({ Id: 'reactor-replay-event', Generation: 1 }),
+                    SequenceNumber: BigInt(index + 1), ObservationState: state
+                }),
+                Content: JSON.stringify({ value: 'hello' })
+            })),
+            Partition: 'source', ReplayState: 0, InitialState: ''
+        };
+        result = (await messages.next()).value!;
+        await lifecycle.disconnected(error => { throw error; });
+        finish();
+    }
+    const connection = { reactors: { observe: stream } } as unknown as ChronicleConnection;
+    const artifacts = { reactors: [type], eventTypes: [SomethingHappened] } as unknown as IClientArtifactsProvider;
+    await new Reactors(artifacts, connection, 'store', 'tenant', lifecycle, {} as IEventLog).register();
+    await finished;
+    return { registration: registration.Content?.Value0?.Reactor, result: result.Content?.Value1 };
+}
+
+// The client constructs reactor instances; share a sink for assertions across that boundary.
+let invoked: string[] = [];
+
+@reactor('default-replay-policy')
+class DefaultReactor {
+    somethingHappened(event: SomethingHappened) { invoked.push(`live:${event.value}`); }
+}
+
+@reactor('once-only-replay-policy')
+@onceOnly()
+class OnceOnlyReactor {
+    somethingHappened() { invoked.push('live'); }
+}
+
+@reactor('inherited-once-only-policy')
+class InheritedOnceOnlyReactor extends OnceOnlyReactor {}
+
+@reactor('method-once-only-policy')
+class MethodOnceOnlyReactor {
+    @onceOnly()
+    somethingHappened() { invoked.push('live'); }
+}
+
+@reactor('replay-alternative-policy')
+class AlternativeReactor {
+    @onceOnly()
+    somethingHappened() { invoked.push('live'); }
+
+    @replay()
+    replaySomethingHappened(event: SomethingHappened) { invoked.push(`replay:${event.value}`); }
+}
+
+@reactor('plain-replay-alternative-policy')
+class PlainAlternativeReactor {
+    somethingHappened() { invoked.push('live'); }
+
+    @replay()
+    replaySomethingHappened(event: SomethingHappened) { invoked.push(`replay:${event.value}`); }
+}
+
+@reactor('inherited-replay-policy')
+class InheritedReplayReactor extends PlainAlternativeReactor {}
+
+@reactor('overridden-replay-policy')
+class OverriddenReplayReactor extends PlainAlternativeReactor {
+    @replay()
+    replaySomethingHappened(event: SomethingHappened) { invoked.push(`derived:${event.value}`); }
+}
+
+@reactor('replay-marked-live-handler-policy')
+class ReplayMarkedLiveHandlerReactor {
+    @replay(SomethingHappened)
+    somethingHappened() { invoked.push('replay'); }
+}
+
+@reactor('unknown-replay-policy')
+class UnknownReplayReactor {
+    @replay()
+    replayWrongName() {}
+}
+
+class UnknownEvent {}
+
+@reactor('unregistered-replay-policy')
+class UnregisteredReplayReactor {
+    @replay(UnknownEvent)
+    rebuild() {}
+}
+
+@reactor('duplicate-replay-policy')
+class DuplicateReplayReactor {
+    @replay()
+    replaySomethingHappened() {}
+
+    @replay(SomethingHappened)
+    rebuild() {}
+}
+
+@reactor('once-only-replay-handler-policy')
+class OnceOnlyReplayHandlerReactor {
+    somethingHappened() { invoked.push('live'); }
+
+    @onceOnly()
+    @replay()
+    replaySomethingHappened() { invoked.push('replay'); }
+}
+
+@reactor('replay-only-policy')
+class ReplayOnlyReactor {
+    @replay(SomethingHappened)
+    rebuild(event: SomethingHappened) { invoked.push(`replay:${event.value}`); }
+}
+
+describe('reactor replay policy', () => {
+    it('registers reactors as replayable by default and dispatches ordinary handlers for both deliveries', async () => {
+        invoked = [];
+        const delivery = await observe(DefaultReactor, [EventObservationState.Initial, EventObservationState.Replay]);
+        expect(delivery.registration?.IsReplayable).toBe(true);
+        expect(invoked).toEqual(['live:hello', 'live:hello']);
+    });
+
+    it('registers a class marked onceOnly as non-replayable', async () => {
+        invoked = [];
+        const delivery = await observe(OnceOnlyReactor, [EventObservationState.Initial]);
+        expect(delivery.registration?.IsReplayable).toBe(false);
+        expect(invoked).toEqual(['live']);
+    });
+
+    it('does not inherit a class-level onceOnly marker on registration', async () => {
+        invoked = [];
+        const delivery = await observe(InheritedOnceOnlyReactor, [EventObservationState.Initial, EventObservationState.Replay]);
+        expect(delivery.registration?.IsReplayable).toBe(true);
+        expect(invoked).toEqual(['live', 'live']);
+    });
+
+    it('skips a method-level onceOnly handler only for replayed events and acknowledges both', async () => {
+        invoked = [];
+        const delivery = await observe(MethodOnceOnlyReactor, [EventObservationState.Initial, EventObservationState.Replay]);
+        expect(delivery.registration?.IsReplayable).toBe(true);
+        expect(invoked).toEqual(['live']);
+        expect(delivery.result?.LastSuccessfulObservation).toBe(2n);
+    });
+
+    it('runs the replay-specific handler instead of the ordinary handler during replay', async () => {
+        invoked = [];
+        const delivery = await observe(AlternativeReactor, [EventObservationState.Initial, EventObservationState.Replay]);
+        expect(invoked).toEqual(['live', 'replay:hello']);
+        expect(delivery.result?.LastSuccessfulObservation).toBe(2n);
+    });
+
+    it('runs only the alternative replay handler when both handlers are plain', async () => {
+        invoked = [];
+        await observe(PlainAlternativeReactor, [EventObservationState.Initial, EventObservationState.Replay]);
+        expect(invoked).toEqual(['live', 'replay:hello']);
+    });
+
+    it('discovers an inherited replay handler', async () => {
+        invoked = [];
+        await observe(InheritedReplayReactor, [EventObservationState.Initial, EventObservationState.Replay]);
+        expect(invoked).toEqual(['live', 'replay:hello']);
+    });
+
+    it('prefers a derived replay handler to the inherited one', async () => {
+        invoked = [];
+        await observe(OverriddenReplayReactor, [EventObservationState.Initial, EventObservationState.Replay]);
+        expect(invoked).toEqual(['live', 'derived:hello']);
+    });
+
+    it('does not invoke a replay-marked live-named handler on live delivery', async () => {
+        invoked = [];
+        await observe(ReplayMarkedLiveHandlerReactor, [EventObservationState.Initial, EventObservationState.Replay]);
+        expect(invoked).toEqual(['replay']);
+    });
+
+    it('rejects a convention replay handler with no registered event type', async () => {
+        await expect(observe(UnknownReplayReactor, [])).rejects.toThrow(/replayWrongName.*no registered event type/);
+    });
+
+    it('rejects an explicit replay handler for an unregistered event type', async () => {
+        await expect(observe(UnregisteredReplayReactor, [])).rejects.toThrow(/rebuild.*no registered event type/);
+    });
+
+    it('rejects two replay handlers for the same event type', async () => {
+        await expect(observe(DuplicateReplayReactor, [])).rejects.toThrow(/multiple replay handlers.*reactor-replay-event/);
+    });
+
+    it('rejects a static legacy replay method', () => {
+        expect(() => {
+            class StaticReplayReactor {
+                @replay(SomethingHappened)
+                static rebuild() {}
+            }
+            return StaticReplayReactor;
+        }).toThrow('Replay requires a public instance method.');
+    });
+
+    it('does not fall back to the ordinary handler when the replay handler is onceOnly', async () => {
+        invoked = [];
+        const delivery = await observe(OnceOnlyReplayHandlerReactor, [EventObservationState.Initial, EventObservationState.Replay]);
+        expect(invoked).toEqual(['live']);
+        expect(delivery.result?.LastSuccessfulObservation).toBe(2n);
+    });
+
+    it('subscribes to an event handled only during replay and acknowledges live deliveries', async () => {
+        invoked = [];
+        const delivery = await observe(ReplayOnlyReactor, [EventObservationState.Initial, EventObservationState.Replay]);
+        expect(delivery.registration?.EventTypes).toHaveLength(1);
+        expect(invoked).toEqual(['replay:hello']);
+        expect(delivery.result?.LastSuccessfulObservation).toBe(2n);
+    });
+});

package/reactors/Reactors.ts

@@ -4,7 +4,7 @@
 import 'reflect-metadata';
 import { diag } from '@opentelemetry/api';
 import { Constructor } from '@cratis/fundamentals';
-import { ObservationState, ReactorMessage } from '@cratis/chronicle.contracts';
+import { EventObservationState, ObservationState, ReactorMessage } from '@cratis/chronicle.contracts';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
 import { ChronicleConnection } from '../connection/index.js';
 import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
@@ -18,6 +18,8 @@ import { notifyReplayLifecycle } from '../observation/notifyReplayLifecycle.js';
 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 type { ReactorResultHandler } from './ReactorResultHandler.js';
 
 /** Expression used to partition reactor observations by event source ID. */
@@ -29,7 +31,8 @@ const SEQUENCE_NUMBER_UNAVAILABLE = 4294967295n;
 interface EventTypeEntry {
     readonly id: string;
     readonly generation: number;
-    readonly methodName: string;
+    readonly methodName?: string;
+    readonly replayMethodName?: string;
 }
 
 /**
@@ -240,7 +243,7 @@ export class Reactors implements IReactors {
                             EventType: { Id: et.id, Generation: et.generation, Tombstone: false },
                             Key: EVENT_SOURCE_ID_KEY
                         })),
-                        IsReplayable: false,
+                        IsReplayable: !isOnceOnly(reactorType),
                         Tags: getTagsFor(reactorType).map(t => t.value),
                         Filters: {
                             FilterTags: getFilterTagsFor(reactorType).map(t => t.value),
@@ -288,7 +291,19 @@ export class Reactors implements IReactors {
 
                         const entry = eventTypes.find(et => et.id === eventTypeId);
                         if (!entry) {
-                            this._logger.debug('No handler registered for event type — skipping', { reactorId: id, eventTypeId });
+                            this._logger.debug('No reactor handler found', { reactorId: id, eventTypeId });
+                            lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
+                            continue;
+                        }
+
+                        const isReplay = (event.Context!.ObservationState & EventObservationState.Replay) !== 0;
+                        const methodName = isReplay ? (entry.replayMethodName ?? entry.methodName) : entry.methodName;
+                        if (!methodName || (isReplay && isOnceOnly(reactorInstance[methodName]))) {
+                            if (isReplay && methodName && isOnceOnly(reactorInstance[methodName])) {
+                                this._logger.debug('Reactor handler skipped for replay', { reactorId: id, eventTypeId, method: methodName });
+                            } else {
+                                this._logger.debug('No reactor handler found', { reactorId: id, eventTypeId, isReplay });
+                            }
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                             continue;
                         }
@@ -299,12 +314,12 @@ export class Reactors implements IReactors {
 
                         this._logger.info('Invoking reactor handler', {
                             reactorId: id,
-                            method: entry.methodName,
+                            method: methodName,
                             sequenceNumber: event.Context!.SequenceNumber.toString(),
                             eventTypeId
                         });
 
-                        const handlerResult = await reactorInstance[entry.methodName](content, context);
+                        const handlerResult = await reactorInstance[methodName](content, context);
                         await dispatchReactorSideEffects(this._eventLog, handlerResult, context, reactorType as Function,
                             this._eventStoreName, this._namespace, this._resultHandler);
 
@@ -350,19 +365,55 @@ 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 eventTypeMeta = getEventTypeMetadata(eventTypeClass);
-            if (!eventTypeMeta) continue;
+            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
+                });
+            }
+        }
 
-            const className = (eventTypeClass as Function).name;
-            const methodName = className.charAt(0).toLowerCase() + className.slice(1);
+        // 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);
+            }
+        }
 
-            if (typeof proto[methodName] === 'function') {
+        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: eventTypeMeta.eventType.id.value,
-                    generation: eventTypeMeta.eventType.generation.value,
-                    methodName
+                    id: eventType.id,
+                    generation: eventType.generation,
+                    methodName: liveMethodName,
+                    replayMethodName
                 });
             }
         }

package/reactors/decorators.standard.spec.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { onceOnly, isOnceOnly } from './onceOnly.js';
+import { replay, getReplayEventType } from './replay.js';
+
+class EventForReplay {}
+
+@onceOnly()
+class StandardReactor {
+    @onceOnly()
+    eventForReplay() {}
+
+    @replay()
+    replayEventForReplay() {}
+
+    @replay(EventForReplay)
+    rebuild() {}
+}
+
+class OrdinaryReactor {}
+
+class InheritedReactor extends StandardReactor {}
+
+describe('standard reactor policy decorators', () => {
+    it('marks the class independently of its handlers', () => {
+        expect(isOnceOnly(StandardReactor)).toBe(true);
+        expect(isOnceOnly(OrdinaryReactor)).toBe(false);
+        expect(isOnceOnly(InheritedReactor)).toBe(false);
+    });
+
+    it('marks methods without modifying the class or other methods', () => {
+        expect(isOnceOnly(StandardReactor.prototype.eventForReplay)).toBe(true);
+        expect(isOnceOnly(StandardReactor.prototype.replayEventForReplay)).toBe(false);
+        expect(getReplayEventType(StandardReactor.prototype.replayEventForReplay)).toBe(true);
+        expect(getReplayEventType(StandardReactor.prototype.rebuild)).toBe(EventForReplay);
+    });
+});

package/reactors/index.ts

@@ -3,6 +3,8 @@
 
 export { ReactorId } from './ReactorId.js';
 export { reactor, getReactorMetadata, isReactor } from './reactor.js';
+export { onceOnly } from './onceOnly.js';
+export { replay } from './replay.js';
 export type { ReactorMetadata } from './reactor.js';
 export type { IReactors } from './IReactors.js';
 export { Reactors } from './Reactors.js';

package/reactors/onceOnly.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+
+const METADATA_KEY = 'chronicle:reactor:onceOnly';
+
+/**
+ * Reactors replay by default. Excludes a whole reactor from replay, or skips one
+ * handler for replayed events. A class-level marker is not inherited by subclasses.
+ * This does not prevent ordinary redelivery after a failed partition is retried.
+ * @returns A class or method decorator for legacy and standard TypeScript decorators.
+ */
+export function onceOnly(): ClassDecorator & MethodDecorator & ((value: Function, context: ClassDecoratorContext | ClassMethodDecoratorContext) => void) {
+    return (target: object, propertyOrContext?: string | symbol | ClassDecoratorContext | ClassMethodDecoratorContext, descriptor?: PropertyDescriptor) => {
+        if (typeof propertyOrContext === 'object') {
+            if (propertyOrContext.kind !== 'class' && propertyOrContext.kind !== 'method') {
+                throw new TypeError('Once-only can only decorate a reactor class or method.');
+            }
+            Reflect.defineMetadata(METADATA_KEY, true, target);
+        } else if (propertyOrContext === undefined) {
+            Reflect.defineMetadata(METADATA_KEY, true, target);
+        } else if (descriptor?.value) {
+            Reflect.defineMetadata(METADATA_KEY, true, descriptor.value);
+        } else {
+            throw new TypeError('Once-only can only decorate a reactor class or method.');
+        }
+    };
+}
+
+/** Whether this class or handler is marked as once-only (without inheriting the marker). */
+export function isOnceOnly(target: Function): boolean {
+    return Reflect.getOwnMetadata(METADATA_KEY, target) === true;
+}

package/reactors/replay.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+
+const METADATA_KEY = 'chronicle:reactor:replay';
+
+/**
+ * Marks a method as the alternative handler for an event during replay.
+ * Without an explicit event type, name the method `replay<EventClassName>`.
+ * The regular camelCase handler continues to handle live events, but this method replaces
+ * it during replay. Marking this replay handler with @onceOnly() means neither handler
+ * runs for replayed events.
+ * @param eventType - Optional event constructor for a differently named replay handler.
+ * @returns A method decorator for legacy and standard TypeScript decorators.
+ */
+export function replay(eventType?: Function): MethodDecorator & ((value: Function, context: ClassMethodDecoratorContext) => void) {
+    return (target: object, propertyOrContext: string | symbol | ClassMethodDecoratorContext, descriptor?: PropertyDescriptor) => {
+        const method = typeof propertyOrContext === 'object' ? target : descriptor?.value;
+        if (typeof propertyOrContext === 'object' && (propertyOrContext.kind !== 'method' || propertyOrContext.static || propertyOrContext.private)) {
+            throw new TypeError('Replay requires a public instance method.');
+        }
+        if (typeof propertyOrContext !== 'object' && typeof target === 'function') {
+            throw new TypeError('Replay requires a public instance method.');
+        }
+        if (typeof method !== 'function') {
+            throw new TypeError('Replay requires a method.');
+        }
+        Reflect.defineMetadata(METADATA_KEY, eventType ?? true, method);
+    };
+}
+
+/** Gets the explicit event type, or the convention marker, for a replay handler. */
+export function getReplayEventType(method: Function): Function | true | undefined {
+    return Reflect.getOwnMetadata(METADATA_KEY, method) as Function | true | undefined;
+}