@cratis/chronicle 6.51.0 → 6.52.0

package/for_ChronicleOptions/when_configuring_message_sizes/with_message_sizes.spec.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { ChronicleOptions } from '../../ChronicleOptions.js';
+
+chai.should();
+
+const hundredMegabytes = 100 * 1024 * 1024;
+
+describe('when configuring message sizes', () => {
+    it('should allow 100 MB in both directions by default, matching the other clients', () => {
+        const options = ChronicleOptions.fromConnectionString('chronicle://localhost:35000');
+        options.maxReceiveMessageSize!.should.equal(hundredMegabytes);
+        options.maxSendMessageSize!.should.equal(hundredMegabytes);
+    });
+
+    it('should use the configured sizes', () => {
+        const options = ChronicleOptions.development({ maxReceiveMessageSize: 200, maxSendMessageSize: 300 });
+        options.maxReceiveMessageSize!.should.equal(200);
+        options.maxSendMessageSize!.should.equal(300);
+    });
+
+    it('should keep null as null so the gRPC default can be asked for explicitly', () => {
+        const options = ChronicleOptions.development({ maxReceiveMessageSize: null, maxSendMessageSize: null });
+        (options.maxReceiveMessageSize === null).should.be.true;
+        (options.maxSendMessageSize === null).should.be.true;
+    });
+});

package/observation/FastForwardOutcome.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents the outcome of fast forwarding an observer.
+ */
+export enum FastForwardOutcome {
+    /** The observer was moved to the tail of the event sequence. */
+    FastForwarded = 'FastForwarded',
+
+    /** The observer was already at the tail of the event sequence, so nothing was changed. */
+    AlreadyAtTail = 'AlreadyAtTail',
+
+    /** The observer is replaying, so it cannot be fast forwarded until the replay has completed. */
+    Replaying = 'Replaying',
+
+    /** The observer is retired or removed, so nothing was changed. */
+    NotAvailable = 'NotAvailable'
+}

package/observation/FastForwardResult.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventSequenceNumber } from '../eventSequences/EventSequenceNumber.js';
+import type { FastForwardOutcome } from './FastForwardOutcome.js';
+
+/**
+ * Represents the result of fast forwarding an observer.
+ */
+export interface FastForwardResult {
+    /** What happened. */
+    readonly outcome: FastForwardOutcome;
+
+    /** The next event sequence number the observer expected before the fast forward. */
+    readonly previousNextEventSequenceNumber: EventSequenceNumber;
+
+    /** The next event sequence number the observer expects after the fast forward. */
+    readonly nextEventSequenceNumber: EventSequenceNumber;
+}

package/observation/IObservers.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { FastForwardResult } from './FastForwardResult.js';
 import { ObserverInformation } from './ObserverInformation.js';
 import { ObserverRemovalResult } from './ObserverRemovalResult.js';
 
@@ -29,4 +30,13 @@ export interface IObservers {
      * @returns An {@link ObserverRemovalResult} describing what happened.
      */
     remove(observerId: string): Promise<ObserverRemovalResult>;
+
+    /**
+     * Fast forwards an observer to the tail of the event log, skipping every event it has not yet handled
+     * without invoking it. Its failed partitions are discarded. State it has already built is kept, so the
+     * effect of the skipped events is missing from it; replay the observer instead to rebuild.
+     * @param observerId - The identifier of the observer to fast forward.
+     * @returns A {@link FastForwardResult} describing what happened and where the observer is now.
+     */
+    fastForward(observerId: string): Promise<FastForwardResult>;
 }

package/observation/Observers.spec.ts

@@ -1,9 +1,10 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { ObserverRemovalOutcome as ContractObserverRemovalOutcome, ObserverRunningState as ContractObserverRunningState, ObserverType as ContractObserverType } from '@cratis/chronicle.contracts';
+import { FastForwardOutcome as ContractFastForwardOutcome, ObserverRemovalOutcome as ContractObserverRemovalOutcome, ObserverRunningState as ContractObserverRunningState, ObserverType as ContractObserverType } from '@cratis/chronicle.contracts';
 import { describe, expect, it, vi } from 'vitest';
 import type { ChronicleConnection } from '../connection/index.js';
+import { FastForwardOutcome } from './FastForwardOutcome.js';
 import { ObserverRemovalOutcome } from './ObserverRemovalOutcome.js';
 import { ObserverRunningState } from './ObserverRunningState.js';
 import { ObserverType } from './ObserverType.js';
@@ -21,14 +22,17 @@ function wireObserverInformation() {
     };
 }
 
-function createObservers(getObserversResult?: unknown, removeObserverResult?: unknown) {
+function createObservers(getObserversResult?: unknown, removeObserverResult?: unknown, fastForwardResult?: unknown) {
+    const fastForward = vi.fn().mockResolvedValue(
+        fastForwardResult ?? { Outcome: ContractFastForwardOutcome.FastForwarded, PreviousNextEventSequenceNumber: 5n, NextEventSequenceNumber: 101n }
+    );
     const getObservers = vi.fn().mockResolvedValue(getObserversResult ?? { items: [] });
     const removeObserver = vi.fn().mockResolvedValue(
         removeObserverResult ?? { Outcome: ContractObserverRemovalOutcome.Removed, BlockingNamespace: '' }
     );
-    const connection = { observers: { getObservers, removeObserver } } as unknown as ChronicleConnection;
+    const connection = { observers: { getObservers, removeObserver, fastForward } } as unknown as ChronicleConnection;
     const observers = new Observers('my-event-store', 'my-namespace', connection);
-    return { observers, getObservers, removeObserver };
+    return { observers, getObservers, removeObserver, fastForward };
 }
 
 describe('Observers', () => {
@@ -112,4 +116,37 @@ describe('Observers', () => {
             expect(result.blockingNamespace).toEqual('production');
         });
     });
+
+    describe('when fast forwarding an observer', () => {
+        it('should ask for that observer on the event log', async () => {
+            const { observers, fastForward } = createObservers();
+            await observers.fastForward('employee-alerts');
+
+            const request = fastForward.mock.calls[0][0];
+            expect(request.EventStore).toEqual('my-event-store');
+            expect(request.Namespace).toEqual('my-namespace');
+            expect(request.ObserverId).toEqual('employee-alerts');
+            expect(request.EventSequenceId).toEqual('event-log');
+        });
+
+        it('should report what happened and where the observer is now', async () => {
+            const { observers } = createObservers();
+            const result = await observers.fastForward('employee-alerts');
+
+            expect(result.outcome).toEqual(FastForwardOutcome.FastForwarded);
+            expect(result.previousNextEventSequenceNumber.value).toEqual(5n);
+            expect(result.nextEventSequenceNumber.value).toEqual(101n);
+        });
+
+        it('should report a replaying observer as replaying', async () => {
+            const { observers } = createObservers(undefined, undefined, {
+                Outcome: ContractFastForwardOutcome.ObserverReplaying,
+                PreviousNextEventSequenceNumber: 5n,
+                NextEventSequenceNumber: 5n
+            });
+            const result = await observers.fastForward('employee-alerts');
+
+            expect(result.outcome).toEqual(FastForwardOutcome.Replaying);
+        });
+    });
 });

package/observation/Observers.ts

@@ -3,9 +3,11 @@
 
 import { ChronicleConnection } from '../connection/index.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { FastForwardResult } from './FastForwardResult.js';
 import { IObservers } from './IObservers.js';
 import { ObserverInformation } from './ObserverInformation.js';
 import { ObserverRemovalResult } from './ObserverRemovalResult.js';
+import { toFastForwardResult } from './toFastForwardResult.js';
 import { toObserverInformation } from './toObserverInformation.js';
 import { toObserverRemovalResult } from './toObserverRemovalResult.js';
 
@@ -46,4 +48,16 @@ export class Observers implements IObservers {
 
         return toObserverRemovalResult(response);
     }
+
+    /** @inheritdoc */
+    async fastForward(observerId: string): Promise<FastForwardResult> {
+        const response = await this._connection.observers.fastForward({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ObserverId: observerId,
+            EventSequenceId: EventSequenceId.eventLog.value
+        });
+
+        return toFastForwardResult(response);
+    }
 }

package/observation/index.ts

@@ -14,6 +14,9 @@ export { toObserverInformation, toObserverType } from './toObserverInformation.j
 export { ObserverRemovalOutcome } from './ObserverRemovalOutcome.js';
 export type { ObserverRemovalResult } from './ObserverRemovalResult.js';
 export { toObserverRemovalOutcome, toObserverRemovalResult } from './toObserverRemovalResult.js';
+export { FastForwardOutcome } from './FastForwardOutcome.js';
+export type { FastForwardResult } from './FastForwardResult.js';
+export { toFastForwardOutcome, toFastForwardResult } from './toFastForwardResult.js';
 export type { IObservers } from './IObservers.js';
 export { Observers } from './Observers.js';
 export type { ICanBeNotifiedWhenReplay } from './ICanBeNotifiedWhenReplay.js';

package/observation/toFastForwardResult.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { FastForwardOutcome as ContractFastForwardOutcome, FastForwardResponse } from '@cratis/chronicle.contracts';
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber.js';
+import { FastForwardOutcome } from './FastForwardOutcome.js';
+import { FastForwardResult } from './FastForwardResult.js';
+
+/**
+ * Converts a wire {@link ContractFastForwardOutcome} into the client {@link FastForwardOutcome}.
+ * @param outcome - The wire outcome to convert.
+ * @returns The converted client outcome.
+ */
+export function toFastForwardOutcome(outcome: ContractFastForwardOutcome): FastForwardOutcome {
+    switch (outcome) {
+        case ContractFastForwardOutcome.FastForwarded:
+            return FastForwardOutcome.FastForwarded;
+        case ContractFastForwardOutcome.AlreadyAtTail:
+            return FastForwardOutcome.AlreadyAtTail;
+        case ContractFastForwardOutcome.ObserverReplaying:
+            return FastForwardOutcome.Replaying;
+        case ContractFastForwardOutcome.NotAvailable:
+            return FastForwardOutcome.NotAvailable;
+        default:
+            throw new Error(`Unknown fast forward outcome: ${outcome}`);
+    }
+}
+
+/**
+ * Converts a wire {@link FastForwardResponse} into the client {@link FastForwardResult}.
+ * @param response - The wire response to convert.
+ * @returns The converted client result.
+ */
+export function toFastForwardResult(response: FastForwardResponse): FastForwardResult {
+    return {
+        outcome: toFastForwardOutcome(response.Outcome),
+        previousNextEventSequenceNumber: new EventSequenceNumber(response.PreviousNextEventSequenceNumber),
+        nextEventSequenceNumber: new EventSequenceNumber(response.NextEventSequenceNumber)
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.51.0",
+    "version": "6.52.0",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
@@ -178,7 +178,7 @@
     },
     "dependencies": {
         "@bufbuild/protobuf": "^2.16.0",
-        "@cratis/chronicle.contracts": "19.31.10",
+        "@cratis/chronicle.contracts": "19.56.1",
         "@grpc/grpc-js": "^1.14.5",
         "@opentelemetry/api": "^1.9.1",
         "glob": "^13.0.6",

package/reactors/Reactors.ts

@@ -5,7 +5,7 @@ import 'reflect-metadata';
 import { createLogger } from '../logging/createLogger.js';
 import { runInBackgroundContext } from '../telemetry/runInBackgroundContext.js';
 import { Constructor } from '@cratis/fundamentals';
-import { ObservationState, ReactorMessage, ReplayState } from '@cratis/chronicle.contracts';
+import { EventGenerationDelivery, 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';
@@ -276,6 +276,8 @@ export class Reactors implements IReactors {
                             Key: EVENT_SOURCE_ID_KEY
                         })),
                         IsReplayable: !isOnceOnly(reactorType),
+                        IsNotReplayable: isOnceOnly(reactorType),
+                        GenerationDelivery: EventGenerationDelivery.Compatibility,
                         Tags: getTagsFor(reactorType).map(t => t.value),
                         Filters: {
                             FilterTags: getFilterTagsFor(reactorType).map(t => t.value),

package/reducers/ReducerObservation.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Constructor } from '@cratis/fundamentals';
+import { ReducerEventDispatcher } from './ReducerEventDispatcher.js';
+
+/**
+ * Identifies a single reducer observation: the reducer, where it observes and how its events are dispatched.
+ */
+export interface ReducerObservation {
+    /** The reducer identifier. */
+    readonly id: string;
+
+    /** The reducer type. */
+    readonly reducerType: Constructor;
+
+    /** The event sequence the reducer observes. */
+    readonly eventSequenceId: string;
+
+    /** The identifier of the read model the reducer produces. */
+    readonly readModelName: string;
+
+    /** The dispatcher routing events to the reducer's handlers. */
+    readonly dispatcher: ReducerEventDispatcher;
+}

package/reducers/ReducerObservationSession.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReducerObservation } from './ReducerObservation.js';
+
+/**
+ * A {@link ReducerObservation} that is running against an open observation stream.
+ */
+export interface ReducerObservationSession extends ReducerObservation {
+    /** Aborted when the observation is stopped. */
+    readonly signal: AbortSignal;
+
+    /** The long-lived reducer instance, or undefined when instances are activated per delivery. */
+    readonly reducerInstance: Record<string, Function> | undefined;
+}