@nimbus-cqrs/eventsourcingdb 2.5.0 → 3.0.0-beta.1

package/esm/lib/eventObserver.js

@@ -1,299 +0,0 @@
-import { calculateBackoffDelay as coreCalculateBackoffDelay, getLogger, withRetry, } from '@nimbus-cqrs/core';
-import { SpanStatusCode } from '@opentelemetry/api';
-import { getEventSourcingDBClient } from './client.js';
-import { isEventData } from './eventMapping.js';
-import { observerConnectionReconnectsCounter, observerConnectionRetryAttemptsCounter, observerEventsHandledCounter, observerHandlerRetryAttemptsCounter, observerHandlingDuration, withObserveEventSpan, } from './tracing.js';
-const DEFAULT_RETRY_OPTIONS = {
-    maxRetries: 3,
-    initialRetryDelayMs: 3000,
-};
-/**
- * Returns a promise that resolves after the given number of milliseconds.
- */
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-const OBSERVER_BACKOFF_OPTIONS = {
-    jitterFactor: 0.3,
-    maxDelayMs: Infinity,
-};
-/**
- * Calculates an exponential backoff delay with jitter for a given
- * retry attempt. The jitter adds up to 30% of the base delay to
- * avoid thundering-herd effects.
- *
- * @param initialDelayMs - The base delay in milliseconds before
- *   exponential scaling.
- * @param attempt - The zero-based retry attempt number.
- * @returns The backoff delay in milliseconds.
- *
- * @deprecated Import {@link calculateBackoffDelay} from
- *   `@nimbus-cqrs/core` instead. This wrapper keeps the historical
- *   30% jitter default used by EventSourcingDB observers.
- */
-export const calculateBackoffDelay = (initialDelayMs, attempt) => coreCalculateBackoffDelay(initialDelayMs, attempt, OBSERVER_BACKOFF_OPTIONS);
-/**
- * Reads the legacy connection-retry alias accepted on an event observer.
- */
-const readLegacyRetryOptions = (eventObserver) => eventObserver.retryOptions;
-/**
- * Resolves connection retry options, preferring
- * {@link EventObserver.connectionRetryOptions} and falling back to the
- * legacy retryOptions alias.
- */
-const resolveConnectionRetryOptions = (eventObserver) => {
-    const legacyRetryOptions = readLegacyRetryOptions(eventObserver);
-    return {
-        maxRetries: eventObserver.connectionRetryOptions?.maxRetries ??
-            legacyRetryOptions?.maxRetries ??
-            DEFAULT_RETRY_OPTIONS.maxRetries,
-        initialRetryDelayMs: eventObserver.connectionRetryOptions?.initialRetryDelayMs ??
-            legacyRetryOptions?.initialRetryDelayMs ??
-            DEFAULT_RETRY_OPTIONS.initialRetryDelayMs,
-    };
-};
-/**
- * Resolves handler retry options from {@link EventObserver.handlerRetryOptions}.
- */
-const resolveHandlerRetryOptions = (eventObserver) => ({
-    maxRetries: eventObserver.handlerRetryOptions?.maxRetries ??
-        DEFAULT_RETRY_OPTIONS.maxRetries,
-    initialRetryDelayMs: eventObserver.handlerRetryOptions?.initialRetryDelayMs ??
-        DEFAULT_RETRY_OPTIONS.initialRetryDelayMs,
-});
-/**
- * Logs an informational message when an event observer connects or
- * reconnects to EventSourcingDB. When {@link retryCount} is greater
- * than zero the message indicates a successful reconnection.
- *
- * @param subject - The observed subject.
- * @param retryCount - The number of retries that preceded this
- *   connection (0 for the initial connection).
- * @param data - Additional context logged alongside the message.
- */
-const logObserverConnection = (subject, retryCount, data) => {
-    const retryLabel = retryCount === 1 ? 'retry' : 'retries';
-    const message = retryCount > 0
-        ? `Reconnected event observer for subject "${subject}" after ${retryCount} ${retryLabel}`
-        : `Observing events for subject "${subject}"`;
-    getLogger().info({ category: 'Nimbus', message, data });
-};
-/**
- * Handles a connection / stream error by logging it and waiting with
- * exponential backoff before the next reconnect attempt. When the
- * maximum number of retries is exceeded a critical log entry is
- * emitted and no further retries are attempted.
- *
- * @param error - The error that caused the observer to disconnect.
- * @param subject - The observed subject.
- * @param retryCount - The current (1-based) retry attempt number.
- * @param maxRetries - The maximum number of allowed retries.
- * @param initialRetryDelayMs - The base delay used for exponential
- *   backoff calculation.
- * @returns `true` if the observer should retry, `false` if retries
- *   are exhausted.
- */
-const handleConnectionError = async (error, subject, retryCount, maxRetries, initialRetryDelayMs) => {
-    if (retryCount > maxRetries) {
-        getLogger().critical({
-            category: 'Nimbus',
-            message: `Failed to observe events for subject "${subject}" after ${maxRetries} ${maxRetries === 1 ? 'retry' : 'retries'}.`,
-        });
-        return false;
-    }
-    observerConnectionRetryAttemptsCounter.add(1, { subject });
-    const backoffDelay = coreCalculateBackoffDelay(initialRetryDelayMs, retryCount - 1, OBSERVER_BACKOFF_OPTIONS);
-    getLogger().error({
-        category: 'Nimbus',
-        message: `Error observing events for subject "${subject}" (retry ${retryCount}/${maxRetries}), retrying in ${backoffDelay}ms`,
-        error: error,
-    });
-    await delay(backoffDelay);
-    return true;
-};
-const recordHandlerMetrics = (metricLabels, status, startTime) => {
-    observerEventsHandledCounter.add(1, { ...metricLabels, status });
-    observerHandlingDuration.record((performance.now() - startTime) / 1000, metricLabels);
-};
-/**
- * Invokes the event handler with in-place retries. Does not reconnect
- * the observe stream. When all retries are exhausted, calls
- * {@link EventObserver.onHandlerError} or logs critically, then
- * returns without throwing so the observer can skip the event.
- */
-const handleEventWithRetry = async (eventObserver, event, handlerRetryOptions, span, startTime) => {
-    const { maxRetries, initialRetryDelayMs } = handlerRetryOptions;
-    const metricLabels = {
-        subject: eventObserver.subject,
-        event_type: event.type,
-    };
-    try {
-        await withRetry(() => eventObserver.eventHandler(event), {
-            maxRetries,
-            initialDelayMs: initialRetryDelayMs,
-            maxDelayMs: Infinity,
-            jitterFactor: 0.3,
-            onRetry: ({ error, attempt, delayMs }) => {
-                observerHandlerRetryAttemptsCounter.add(1, metricLabels);
-                span.addEvent('retry', {
-                    attempt,
-                    delay_ms: delayMs,
-                });
-                getLogger().error({
-                    category: 'Nimbus',
-                    message: `Error handling event "${event.id}" (${event.type}) for subject "${eventObserver.subject}" (retry ${attempt}/${maxRetries}), retrying in ${delayMs}ms`,
-                    error,
-                    ...(isEventData(event.data)
-                        ? {
-                            correlationId: event.data.nimbusMeta.correlationid,
-                        }
-                        : {}),
-                });
-            },
-        });
-        recordHandlerMetrics(metricLabels, 'success', startTime);
-    }
-    catch (error) {
-        const handlerError = error instanceof Error
-            ? error
-            : new Error(String(error));
-        recordHandlerMetrics(metricLabels, 'skipped', startTime);
-        span.setStatus({
-            code: SpanStatusCode.ERROR,
-            message: handlerError.message,
-        });
-        span.recordException(handlerError);
-        await handleHandlerExhausted(eventObserver, event, handlerError, maxRetries);
-    }
-};
-/**
- * Handles exhausted handler retries by invoking
- * {@link EventObserver.onHandlerError} or emitting a critical log.
- */
-const handleHandlerExhausted = async (eventObserver, event, handlerError, maxRetries) => {
-    if (eventObserver.onHandlerError) {
-        try {
-            await eventObserver.onHandlerError(handlerError, event);
-        }
-        catch (err) {
-            // Isolate user callback failures so the poison
-            // event is still skipped and observation continues.
-            const callbackError = err instanceof Error
-                ? err
-                : new Error(String(err));
-            getLogger().critical({
-                category: 'Nimbus',
-                message: `onHandlerError failed for event "${event.id}" (${event.type}) for subject "${eventObserver.subject}". Skipping event.`,
-                error: callbackError,
-                ...(isEventData(event.data)
-                    ? {
-                        correlationId: event.data.nimbusMeta.correlationid,
-                    }
-                    : {}),
-            });
-        }
-        return;
-    }
-    getLogger().critical({
-        category: 'Nimbus',
-        message: `Failed to handle event "${event.id}" (${event.type}) for subject "${eventObserver.subject}" after ${maxRetries} ${maxRetries === 1 ? 'retry' : 'retries'}. Skipping event.`,
-        error: handlerError,
-        ...(isEventData(event.data)
-            ? {
-                correlationId: event.data.nimbusMeta.correlationid,
-            }
-            : {}),
-    });
-};
-/**
- * Starts observing events for the given {@link EventObserver} with
- * automatic reconnection on stream failure and separate in-place
- * retries for handler failures.
- *
- * Events are consumed from the stream and each one is passed to the
- * observer's event handler inside an OpenTelemetry span. If the event
- * carries a `traceparent`, the span is linked to the original writer's
- * trace for end-to-end distributed tracing.
- *
- * Handler failures are retried without reconnecting. After handler
- * retries are exhausted the event is skipped (lower bound advanced)
- * so observation can continue. When the connection drops, exponential
- * backoff with jitter is applied up to the configured maximum number
- * of connection retries.
- *
- * @param eventObserver - The event observer configuration.
- * @returns A promise that resolves when the observe stream ends or
- *   connection retries are exhausted.
- */
-export const observeWithRetry = async (eventObserver) => {
-    const connectionRetryOptions = resolveConnectionRetryOptions(eventObserver);
-    const handlerRetryOptions = resolveHandlerRetryOptions(eventObserver);
-    let connectionRetryCount = 0;
-    let lastProcessedEventId;
-    while (true) {
-        try {
-            // Resolve the client on every attempt so a re-initialized
-            // singleton is picked up after reconnecting to EventSourcingDB.
-            const eventSourcingDBClient = getEventSourcingDBClient();
-            // Once we have a concrete position, use it as lower bound and
-            // drop fromLatestEvent; otherwise fall back to the original options.
-            const lowerBound = lastProcessedEventId
-                ? { id: lastProcessedEventId, type: 'exclusive' }
-                : eventObserver.lowerBound;
-            const fromLatestEvent = lastProcessedEventId
-                ? undefined
-                : eventObserver.fromLatestEvent;
-            logObserverConnection(eventObserver.subject, connectionRetryCount, {
-                recursive: eventObserver.recursive ?? false,
-                lowerBound,
-                fromLatestEvent,
-            });
-            for await (const event of eventSourcingDBClient.observeEvents(eventObserver.subject, {
-                recursive: eventObserver.recursive ?? false,
-                ...(lowerBound ? { lowerBound } : {}),
-                ...(fromLatestEvent ? { fromLatestEvent } : {}),
-            })) {
-                // Stream is healthy once events flow again. Count a successful
-                // reconnect only here so failed reconnect attempts are excluded.
-                if (connectionRetryCount > 0) {
-                    observerConnectionReconnectsCounter.add(1, {
-                        subject: eventObserver.subject,
-                    });
-                }
-                connectionRetryCount = 0;
-                const traceContext = event.traceparent
-                    ? {
-                        traceparent: event.traceparent,
-                        tracestate: event.tracestate,
-                    }
-                    : undefined;
-                const startTime = performance.now();
-                await withObserveEventSpan(event, eventObserver.subject, traceContext, async (span) => {
-                    await handleEventWithRetry(eventObserver, event, handlerRetryOptions, span, startTime);
-                });
-                // Advance after success or skip so poison events do not block
-                // the stream and reconnects resume past the last attempted event.
-                lastProcessedEventId = event.id;
-            }
-            // If the loop completes normally (stream ended), we're done
-            return;
-        }
-        catch (error) {
-            connectionRetryCount++;
-            const shouldRetry = await handleConnectionError(error, eventObserver.subject, connectionRetryCount, connectionRetryOptions.maxRetries, connectionRetryOptions.initialRetryDelayMs);
-            if (!shouldRetry) {
-                return;
-            }
-        }
-    }
-};
-/**
- * Initializes an event observer by starting the observation loop in
- * the background (non-blocking). The observer will keep running and
- * reconnecting according to its connection retry options until the
- * stream ends or connection retries are exhausted. Handler failures
- * are retried separately and do not stop the observer.
- *
- * @param eventObserver - The event observer configuration.
- */
-export const initEventObserver = (eventObserver) => {
-    void observeWithRetry(eventObserver);
-};

package/esm/lib/writeEvents.d.ts

@@ -1,11 +0,0 @@
-import type { Event } from '@nimbus-cqrs/core';
-import type { Precondition } from 'eventsourcingdb';
-/**
- * Writes one or more Nimbus events to EventSourcingDB. Each event is
- * converted into an EventSourcingDB event candidate before being persisted.
- *
- * @param events - The Nimbus events to write.
- * @param preconditions - Optional preconditions that must be met for the write to succeed.
- */
-export declare const writeEvents: (events: Event[], preconditions?: Precondition[]) => Promise<void>;
-//# sourceMappingURL=writeEvents.d.ts.map

package/esm/lib/writeEvents.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"writeEvents.d.ts","sourceRoot":"","sources":["../../src/lib/writeEvents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qDAAqD,CAAC;AAEjF,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAapE;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACpB,QAAQ,KAAK,EAAE,EACf,gBAAgB,YAAY,EAAE,KAC/B,OAAO,CAAC,IAAI,CAsBd,CAAC"}

package/esm/lib/writeEvents.js

@@ -1,28 +0,0 @@
-import { context, propagation } from '@opentelemetry/api';
-import { getEventSourcingDBClient } from './client.js';
-import { nimbusEventToEventSourcingDBEventCandidate } from './eventMapping.js';
-import { eventSizeBytes, withSpan } from './tracing.js';
-const textEncoder = new TextEncoder();
-/**
- * Returns the UTF-8 byte length of a serialized Nimbus event.
- */
-const getEventSizeBytes = (event) => textEncoder.encode(JSON.stringify(event)).length;
-/**
- * Writes one or more Nimbus events to EventSourcingDB. Each event is
- * converted into an EventSourcingDB event candidate before being persisted.
- *
- * @param events - The Nimbus events to write.
- * @param preconditions - Optional preconditions that must be met for the write to succeed.
- */
-export const writeEvents = (events, preconditions) => {
-    return withSpan('writeEvents', async () => {
-        const eventSourcingDBClient = getEventSourcingDBClient();
-        const carrier = {};
-        propagation.inject(context.active(), carrier);
-        const eventCandidates = events.map((event) => {
-            eventSizeBytes.record(getEventSizeBytes(event));
-            return nimbusEventToEventSourcingDBEventCandidate(event, carrier['traceparent'], carrier['tracestate']);
-        });
-        await eventSourcingDBClient.writeEvents(eventCandidates, preconditions);
-    });
-};

package/esm/package.json

@@ -1,3 +0,0 @@
-{
-  "type": "module"
-}