@cratis/chronicle 6.15.0 → 6.16.0

package/reducers/Reducers.ts

@@ -4,7 +4,7 @@
 import 'reflect-metadata';
 import { diag } from '@opentelemetry/api';
 import { Constructor } from '@cratis/fundamentals';
-import { ObservationState, ReadModelObserverType, ReducerMessage } from '@cratis/chronicle.contracts';
+import { ObservationState, ReadModelObserverType, ReducerMessage, ReplayState } from '@cratis/chronicle.contracts';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
 import { ChronicleConnection } from '../connection/index.js';
 import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
@@ -21,6 +21,12 @@ import { getReadModelId } from '../readModels/readModel.js';
 import { buildReadModelDefinition } from '../readModels/buildReadModelDefinition.js';
 import { assertUniqueReadModelIds } from '../readModels/assertUniqueReadModelIds.js';
 import { JsonSchemaGenerator } from '../schemas/index.js';
+import type { IEventStore } from '../IEventStore.js';
+import type { ClientArtifactsActivator } from '../artifacts/ClientArtifactsActivator.js';
+import type { ActivatedArtifact } from '../artifacts/ActivatedArtifact.js';
+import { ArtifactKind } from '../artifacts/ArtifactKind.js';
+import { ArtifactDelivery } from '../artifacts/ArtifactDelivery.js';
+import { withActivatedArtifact, runActivated } from '../artifacts/withActivatedArtifact.js';
 
 /** Expression used to partition reducer observations by event source ID. */
 const EVENT_SOURCE_ID_KEY = '$eventSourceId';
@@ -117,7 +123,9 @@ export class Reducers implements IReducers {
         private readonly _eventStoreName: string,
         private readonly _namespace: string,
         lifecycle: ConnectionLifecycle,
-        private readonly _defaultSinkTypeId: string
+        private readonly _defaultSinkTypeId: string,
+        private readonly _eventStore?: IEventStore,
+        private readonly _artifactActivator?: ClientArtifactsActivator
     ) {
         this._lifecycle = lifecycle;
         lifecycle.onDisconnected(async () => {
@@ -333,7 +341,7 @@ export class Reducers implements IReducers {
         });
 
         try {
-            const reducerInstance = new (reducerType as new () => Record<string, Function>)();
+            const reducerInstance = this._artifactActivator ? undefined : new (reducerType as new () => Record<string, Function>)();
 
             for await (const operation of this._connection.reducers.observe(queue, { signal: controller.signal })) {
                 let lastSuccessfullyObservedEvent = SEQUENCE_NUMBER_UNAVAILABLE;
@@ -351,7 +359,18 @@ export class Reducers implements IReducers {
                 });
 
                 try {
-                    await notifyReplayLifecycle(reducerInstance, operation.ReplayState, operation.Partition);
+                    if (this._artifactActivator && operation.ReplayState !== ReplayState.REPLAY_STATE_None) {
+                        if (!this._eventStore) throw new Error('Reducer activation requires the owning event store.');
+                        await withActivatedArtifact(reducerType, {
+                            kind: ArtifactKind.Reducer, artifactId: id, eventStore: this._eventStore,
+                            readModels: this._eventStore.readModels, eventSequenceId, partition: operation.Partition,
+                            signal: controller.signal, delivery: ArtifactDelivery.ReplayNotification,
+                            replayState: operation.ReplayState
+                        }, this._artifactActivator, artifact => runActivated(artifact, () =>
+                            notifyReplayLifecycle(artifact.instance, operation.ReplayState, operation.Partition)));
+                    } else if (reducerInstance) {
+                        await notifyReplayLifecycle(reducerInstance, operation.ReplayState, operation.Partition);
+                    }
                 } catch (err) {
                     this._logger.error('Error notifying reducer of replay lifecycle transition', { reducerId: id, error: String(err) });
                     exceptionMessages.push(String(err));
@@ -363,41 +382,66 @@ export class Reducers implements IReducers {
                     ? JSON.parse(operation.InitialState) as unknown
                     : undefined;
 
-                for (const event of state === ObservationState.Failed ? [] : operation.Events) {
-                    try {
-                        const eventTypeId = event.Context?.EventType?.Id;
-                        if (!eventTypeId) {
-                            this._logger.warn('Event missing event type context', { reducerId: id });
-                            continue;
-                        }
-
-                        const entry = dispatcher.handlerFor(eventTypeId);
-                        if (!entry) {
-                            this._logger.debug('No handler registered for event type — skipping', { reducerId: id, eventTypeId });
+                const processEvents = async (artifact: ActivatedArtifact<Record<string, Function>>) => {
+                    for (const event of state === ObservationState.Failed ? [] : operation.Events) {
+                        try {
+                            const eventTypeId = event.Context?.EventType?.Id;
+                            if (!eventTypeId) {
+                                this._logger.warn('Event missing event type context', { reducerId: id });
+                                continue;
+                            }
+
+                            const entry = dispatcher.handlerFor(eventTypeId);
+                            if (!entry) {
+                                this._logger.debug('No handler registered for event type — skipping', { reducerId: id, eventTypeId });
+                                lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
+                                continue;
+                            }
+
+                            const content = JSON.parse(event.Content) as Record<string, unknown>;
+                            const context = toClientEventContext(event.Context!);
+
+                            this._logger.info('Invoking reducer handler', {
+                                reducerId: id,
+                                method: entry.methodName,
+                                sequenceNumber: event.Context!.SequenceNumber.toString(),
+                                eventTypeId,
+                                hasState: currentState !== undefined
+                            });
+
+                            currentState = await runActivated(artifact, () => dispatcher.invoke(artifact.instance, entry, content, currentState, context));
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
-                            continue;
+                        } catch (err) {
+                            this._logger.error('Error handling event in reducer', { reducerId: id, error: String(err) });
+                            exceptionMessages.push(String(err));
+                            exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
+                            state = ObservationState.Failed;
+                            break;
                         }
+                    }
+                };
 
-                        const content = JSON.parse(event.Content) as Record<string, unknown>;
-                        const context = toClientEventContext(event.Context!);
-
-                        this._logger.info('Invoking reducer handler', {
-                            reducerId: id,
-                            method: entry.methodName,
-                            sequenceNumber: event.Context!.SequenceNumber.toString(),
-                            eventTypeId,
-                            hasState: currentState !== undefined
-                        });
-
-                        currentState = await dispatcher.invoke(reducerInstance, entry, content, currentState, context);
-                        lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
+                const firstInvocableEvent = this._artifactActivator && state === ObservationState.Success
+                    ? operation.Events.find(event =>
+                        !!event.Context?.EventType?.Id && !!dispatcher.handlerFor(event.Context.EventType.Id))
+                    : undefined;
+                if (firstInvocableEvent && this._artifactActivator) {
+                    try {
+                        if (!this._eventStore) throw new Error('Reducer activation requires the owning event store.');
+                        await withActivatedArtifact(reducerType as new () => Record<string, Function>, {
+                            kind: ArtifactKind.Reducer, artifactId: id, eventStore: this._eventStore,
+                            readModels: this._eventStore.readModels, eventSequenceId, partition: operation.Partition,
+                            signal: controller.signal, delivery: ArtifactDelivery.Events,
+                            eventContext: toClientEventContext(firstInvocableEvent.Context!)
+                        }, this._artifactActivator, processEvents);
                     } catch (err) {
-                        this._logger.error('Error handling event in reducer', { reducerId: id, error: String(err) });
+                        this._logger.error('Error activating reducer', { reducerId: id, error: String(err) });
                         exceptionMessages.push(String(err));
                         exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
                         state = ObservationState.Failed;
-                        break;
                     }
+                } else {
+                    await processEvents({ instance: reducerInstance ?? {} });
                 }
 
                 if (state === ObservationState.Success && currentState !== undefined) {

package/reducers/for_Reducers/when_delivering/with_activation.spec.ts

@@ -0,0 +1,177 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventContext, EventType, ReplayState, ObservationState, type ReducerMessage } from '@cratis/chronicle.contracts';
+import { chai, describe, it, vi } from 'vitest';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import { ConnectionLifecycle } from '../../../connection/ConnectionLifecycle.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/IClientArtifactsProvider.js';
+import { ArtifactDelivery } from '../../../artifacts/ArtifactDelivery.js';
+import { ArtifactKind } from '../../../artifacts/ArtifactKind.js';
+import type { ArtifactActivationContext } from '../../../artifacts/ArtifactActivationContext.js';
+import type { ClientArtifactsActivator } from '../../../artifacts/ClientArtifactsActivator.js';
+import type { IEventStore } from '../../../IEventStore.js';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { reducer } from '../../reducer.js';
+import { Reducers } from '../../Reducers.js';
+
+chai.should();
+
+@eventType('reduction-activation-event')
+class ReductionEvent { constructor(readonly amount: number = 0) {} }
+class ReductionState { count = 0; }
+
+const instances: object[] = [];
+const notifications: string[] = [];
+
+@reducer('reduction-activation', undefined, ReductionState)
+class CountingReducer {
+    constructor() { instances.push(this); }
+    beginReplay() { notifications.push('begin'); }
+    endReplay() {}
+    reductionEvent(event: ReductionEvent, state: ReductionState | undefined) {
+        return { count: (state?.count ?? 0) + event.amount };
+    }
+}
+
+@reducer('reduction-notification-failure', undefined, ReductionState)
+class FailingNotificationReducer {
+    beginReplay() { throw new Error('notification failed'); }
+    endReplay() {}
+    reductionEvent() { notifications.push('unexpected event'); return { count: 42 }; }
+}
+
+@reducer('reduction-failure', undefined, ReductionState)
+class FailingReducer {
+    reductionEvent() { throw new Error('reduction failed'); }
+}
+
+function event(amount: number, sequence: bigint) {
+    return { Content: JSON.stringify({ amount }), Context: EventContext.fromPartial({
+        EventType: EventType.fromPartial({ Id: 'reduction-activation-event', Generation: 1 }),
+        EventSourceId: 'book-1', SequenceNumber: sequence
+    }) };
+}
+
+function batch(events: ReturnType<typeof event>[], replayState = ReplayState.REPLAY_STATE_None) {
+    return { Events: events, ReplayState: replayState, Partition: 'book-1', InitialState: '' };
+}
+
+async function observe(type: Function, batches: ReturnType<typeof batch>[], activator?: ClientArtifactsActivator) {
+    const acknowledgements: NonNullable<ReducerMessage['Content']>['Value1'][] = [];
+    const store = { namespace: { value: 'tenant-a' }, readModels: {} } as IEventStore;
+    const lifecycle = new ConnectionLifecycle();
+    let finished!: () => void;
+    const complete = new Promise<void>(resolve => { finished = resolve; });
+    async function* stream(queue: AsyncIterable<ReducerMessage>) {
+        const messages = queue[Symbol.asyncIterator]();
+        await messages.next();
+        for (const delivery of batches) {
+            yield delivery;
+            acknowledgements.push((await messages.next()).value!.Content!.Value1);
+        }
+        await lifecycle.disconnected(error => { throw error; });
+        finished();
+    }
+    const connection = { reducers: { observe: stream }, readModels: { registerMany: async () => ({}) } } as unknown as ChronicleConnection;
+    const artifacts = { reducers: [type], eventTypes: [ReductionEvent], readModels: [] } as unknown as IClientArtifactsProvider;
+    await new Reducers(artifacts, connection, 'store', 'tenant-a', lifecycle, 'sink', store, activator).register();
+    await complete;
+    return { acknowledgements, store };
+}
+
+describe('when delivering reducer batches', () => {
+    it('should reuse the default instance across deliveries and preserve reduction state', async () => {
+        instances.length = 0;
+        const result = await observe(CountingReducer, [batch([event(1, 1n), event(2, 2n)]), batch([event(3, 3n)])]);
+        instances.length.should.equal(1);
+        result.acknowledgements.map(value => JSON.parse(value!.ReadModelState)).should.deep.equal([{ count: 3 }, { count: 3 }]);
+    });
+
+    it('should activate once per batch and separately for replay notifications', async () => {
+        instances.length = 0;
+        notifications.length = 0;
+        const contexts: ArtifactActivationContext[] = [];
+        const steps: string[] = [];
+        const activator: ClientArtifactsActivator = (type, context) => {
+            contexts.push(context);
+            return { instance: new type(), run: async callback => { steps.push('enter');
+                try { return await callback(); } finally { steps.push('exit'); } },
+            dispose: () => { steps.push('dispose'); } };
+        };
+        const result = await observe(CountingReducer, [batch([event(1, 1n), event(2, 2n)], ReplayState.BeginReplay), batch([event(3, 3n)])], activator);
+        instances.length.should.equal(3);
+        contexts.map(context => context.delivery).should.deep.equal([ArtifactDelivery.ReplayNotification, ArtifactDelivery.Events, ArtifactDelivery.Events]);
+        contexts[0].kind.should.equal(ArtifactKind.Reducer);
+        contexts[1].eventStore.should.equal(result.store);
+        contexts[1].readModels.should.equal(result.store.readModels);
+        if (contexts[1].delivery === ArtifactDelivery.Events) contexts[1].eventContext.sequenceNumber.should.equal(1n);
+        notifications.should.deep.equal(['begin']);
+        steps.should.deep.equal(['enter', 'exit', 'dispose', 'enter', 'exit', 'enter', 'exit', 'dispose', 'enter', 'exit', 'dispose']);
+        result.acknowledgements[0]?.ReadModelState.should.equal('{"count":3}');
+    });
+
+    it('should notify before events on the default path', async () => {
+        notifications.length = 0;
+        const result = await observe(CountingReducer, [batch([event(1, 1n)], ReplayState.BeginReplay)]);
+        notifications.should.deep.equal(['begin']);
+        result.acknowledgements[0]?.ReadModelState.should.equal('{"count":1}');
+    });
+
+    it('should fail notification without running events in either mode', async () => {
+        for (const activator of [undefined, (type => ({ instance: new type() })) as ClientArtifactsActivator]) {
+            notifications.length = 0;
+            const result = await observe(FailingNotificationReducer, [batch([event(1, 1n)], ReplayState.BeginReplay)], activator);
+            notifications.should.deep.equal([]);
+            result.acknowledgements[0]?.State.should.equal(ObservationState.Failed);
+            result.acknowledgements[0]?.ExceptionMessages.should.deep.equal(['Error: notification failed']);
+        }
+    });
+
+    it('should fail event delivery on synchronous and asynchronous activation errors without disposing a lease', async () => {
+        for (const mode of ['sync', 'async'] as const) {
+            const dispose = vi.fn();
+            const message = `${mode} reducer activation failed`;
+            const activator: ClientArtifactsActivator = type => {
+                const lease = { instance: new type(), dispose };
+                if (mode === 'sync') throw new Error(message);
+                return Promise.reject(new Error(message)).then(() => lease);
+            };
+            const result = await observe(CountingReducer, [batch([event(1, 1n)])], activator);
+            result.acknowledgements[0]?.State.should.equal(ObservationState.Failed);
+            result.acknowledgements[0]?.ExceptionMessages.should.deep.equal([`Error: ${message}`]);
+            result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(4294967295n);
+            result.acknowledgements[0]?.ReadModelState.should.equal('');
+            dispose.mock.calls.length.should.equal(0);
+        }
+    });
+
+    it('should fail replay notification on synchronous and asynchronous activation errors without disposing a lease', async () => {
+        for (const mode of ['sync', 'async'] as const) {
+            notifications.length = 0;
+            const dispose = vi.fn();
+            const message = `${mode} reducer replay activation failed`;
+            const activator: ClientArtifactsActivator = type => {
+                const lease = { instance: new type(), dispose };
+                if (mode === 'sync') throw new Error(message);
+                return Promise.reject(new Error(message)).then(() => lease);
+            };
+            const result = await observe(CountingReducer, [batch([event(1, 1n)], ReplayState.BeginReplay)], activator);
+            result.acknowledgements[0]?.State.should.equal(ObservationState.Failed);
+            result.acknowledgements[0]?.ExceptionMessages.should.deep.equal([`Error: ${message}`]);
+            result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(4294967295n);
+            result.acknowledgements[0]?.ReadModelState.should.equal('');
+            notifications.should.deep.equal([]);
+            dispose.mock.calls.length.should.equal(0);
+        }
+    });
+
+    it('should dispose after handler failure without acknowledging the failed event', async () => {
+        let disposed = 0;
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(), dispose: () => { disposed++; } });
+        const result = await observe(FailingReducer, [batch([event(1, 1n)])], activator);
+        disposed.should.equal(1);
+        result.acknowledgements[0]?.State.should.equal(ObservationState.Failed);
+        result.acknowledgements[0]?.ExceptionMessages.should.deep.equal(['Error: reduction failed']);
+    });
+});