@ceschiatti/redistail 0.0.2 → 0.0.3

package/src/cli/stream-monitor-service.ts

@@ -0,0 +1,427 @@
+/**
+ * Stream monitoring service for the redistail CLI utility.
+ *
+ * This service provides Redis Stream monitoring capabilities with
+ * automatic reconnection, entry ID continuity tracking, and proper error handling.
+ * It integrates with the effect-redis RedisStream service and follows
+ * Effect-TS patterns for dependency injection and resource management.
+ */
+
+import {
+  Context,
+  Effect,
+  Layer,
+  Schedule,
+  Stream,
+  pipe,
+  Duration,
+  Option,
+} from 'effect';
+import { RedisStream } from 'effect-redis';
+
+import {
+  type StreamMessage,
+  type RedistailConfig,
+  type MonitoringError,
+  type ConfigError,
+  type StreamMonitorOptions,
+  StreamMessage as StreamMessageConstructor,
+  createStreamReadFailedError,
+} from './types';
+import { CLIConfigService } from './config-service';
+import type { RedisError, RedisValue } from 'effect-redis';
+
+// Get the service type from the Context.Tag
+type RedisStreamService = Context.Tag.Service<RedisStream>;
+
+// ============================================================================
+// Service Interface
+// ============================================================================
+
+/**
+ * Service interface for Stream monitoring operations
+ */
+export interface StreamMonitorService {
+  /**
+   * Monitor a Redis Stream with automatic reconnection and entry ID continuity
+   * @param streamKey - The stream key to monitor
+   * @param options - Optional monitoring configuration
+   * @returns Stream of Stream messages with error handling and reconnection
+   */
+  readonly monitor: (
+    streamKey: string,
+    options?: StreamMonitorOptions,
+  ) => Stream.Stream<StreamMessage, MonitoringError>;
+
+  /**
+   * Subscribe to a Redis Stream starting from the latest entry
+   * @param streamKey - The stream key to subscribe to
+   * @returns Effect that yields a stream of Stream messages
+   */
+  readonly subscribeFromLatest: (
+    streamKey: string,
+  ) => Effect.Effect<
+    Stream.Stream<StreamMessage, MonitoringError>,
+    MonitoringError
+  >;
+
+  /**
+   * Subscribe to a Redis Stream with custom options
+   * @param streamKey - The stream key to subscribe to
+   * @param options - Subscription options including start ID and block timeout
+   * @returns Effect that yields a stream of Stream messages
+   */
+  readonly subscribeWithOptions: (
+    streamKey: string,
+    options: StreamMonitorOptions,
+  ) => Effect.Effect<
+    Stream.Stream<StreamMessage, MonitoringError>,
+    MonitoringError
+  >;
+}
+
+/**
+ * Context tag for Stream monitoring service dependency injection
+ */
+export const StreamMonitorService = Context.GenericTag<StreamMonitorService>(
+  'StreamMonitorService',
+);
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Convert RedisError to MonitoringError
+ */
+const convertRedisError = (
+  error: RedisError,
+  context: string,
+): MonitoringError => {
+  return createStreamReadFailedError(
+    `${context}: ${error.message}`,
+    true,
+    error,
+  );
+};
+
+/**
+ * Transform Redis StreamEntry to StreamMessage
+ */
+const transformStreamEntry = (
+  streamKey: string,
+  entry: { id: RedisValue; message: Record<string, string> },
+): StreamMessage =>
+  StreamMessageConstructor({
+    timestamp: new Date(),
+    streamKey,
+    entryId: String(entry.id),
+    fields: entry.message,
+  });
+
+/**
+ * Create a stream subscription with reconnection and continuity tracking
+ */
+const createStreamSubscription = (
+  redisStreamService: RedisStreamService,
+  streamKey: string,
+  config: RedistailConfig,
+  options?: StreamMonitorOptions,
+): Stream.Stream<StreamMessage, MonitoringError> => {
+  const startId = options?.startId ?? '$'; // '$' means start from latest
+  const blockTimeout = options?.blockTimeout ?? config.monitoring.blockTimeout;
+  const count = options?.count;
+
+  return pipe(
+    // Create the base subscription stream
+    redisStreamService.subscribe(streamKey, {
+      id: startId,
+      block: blockTimeout,
+      count,
+    }),
+    // Handle Redis errors and convert to MonitoringError
+    Stream.mapError((error: RedisError) =>
+      convertRedisError(error, `Failed to read from stream '${streamKey}'`),
+    ),
+    // Transform Redis entries to StreamMessage format
+    Stream.map((entry) => transformStreamEntry(streamKey, entry)),
+    // Add automatic reconnection with exponential backoff
+    Stream.retry(
+      pipe(
+        Schedule.exponential(Duration.seconds(1)),
+        Schedule.intersect(
+          Schedule.recurs(config.monitoring.maxReconnectAttempts),
+        ),
+        Schedule.tapInput((error: MonitoringError) =>
+          Effect.logWarning(
+            `Stream monitoring error for '${streamKey}': ${error.message}. Retrying...`,
+          ),
+        ),
+      ),
+    ),
+    // Handle final failure after max retries
+    Stream.catchAll((error: MonitoringError) =>
+      Stream.fail(
+        createStreamReadFailedError(
+          `Failed to monitor stream '${streamKey}' after ${config.monitoring.maxReconnectAttempts} attempts: ${error.message}`,
+          false, // Not retryable after max attempts
+          error,
+        ),
+      ),
+    ),
+  );
+};
+
+// ============================================================================
+// Service Implementation
+// ============================================================================
+
+/**
+ * Creates a Stream monitor service implementation
+ */
+const createStreamMonitorService = (
+  redisStreamService: RedisStreamService,
+  config: RedistailConfig,
+): StreamMonitorService => ({
+  monitor: (streamKey: string, options?: StreamMonitorOptions) =>
+    createStreamSubscription(redisStreamService, streamKey, config, options),
+
+  subscribeFromLatest: (streamKey: string) =>
+    Effect.gen(function* () {
+      // Subscribe starting from the latest entry using '$' ID
+      const messageStream = pipe(
+        redisStreamService.subscribe(streamKey, {
+          id: '$', // Start from latest entries only
+          block: config.monitoring.blockTimeout,
+        }),
+        Stream.mapError((error: RedisError) =>
+          convertRedisError(
+            error,
+            `Failed to subscribe to stream '${streamKey}'`,
+          ),
+        ),
+        Stream.map((entry) => transformStreamEntry(streamKey, entry)),
+      );
+
+      return messageStream;
+    }),
+
+  subscribeWithOptions: (streamKey: string, options: StreamMonitorOptions) =>
+    Effect.gen(function* () {
+      // Subscribe with custom options
+      const subscribeOptions = {
+        id: options.startId ?? '$',
+        block: options.blockTimeout ?? config.monitoring.blockTimeout,
+        count: options.count,
+      };
+
+      const messageStream = pipe(
+        redisStreamService.subscribe(streamKey, subscribeOptions),
+        Stream.mapError((error: RedisError) =>
+          convertRedisError(
+            error,
+            `Failed to subscribe to stream '${streamKey}' with options`,
+          ),
+        ),
+        Stream.map((entry) => transformStreamEntry(streamKey, entry)),
+      );
+
+      return messageStream;
+    }),
+});
+
+// ============================================================================
+// Live Layer Implementation
+// ============================================================================
+
+/**
+ * Live layer for Stream monitoring service
+ * Depends on RedisStream and CLIConfigService services
+ */
+export const StreamMonitorServiceLive: Layer.Layer<
+  StreamMonitorService,
+  ConfigError,
+  RedisStream | CLIConfigService
+> = Layer.effect(
+  StreamMonitorService,
+  Effect.gen(function* () {
+    const redisStreamService = yield* RedisStream;
+    const configService = yield* CLIConfigService;
+    const config = yield* configService.loadConfig();
+    return createStreamMonitorService(redisStreamService, config);
+  }),
+);
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Helper function to create a monitoring stream with custom retry configuration
+ */
+export const createMonitoringStreamWithRetry = (
+  streamKey: string,
+  redisStreamService: RedisStreamService,
+  maxRetries: number,
+  baseDelaySeconds = 1,
+  startId = '$',
+): Stream.Stream<StreamMessage, MonitoringError> =>
+  pipe(
+    redisStreamService.subscribe(streamKey, {
+      id: startId,
+      block: 5000, // 5 second block timeout
+    }),
+    Stream.mapError((error: RedisError) =>
+      convertRedisError(error, `Failed to subscribe to stream '${streamKey}'`),
+    ),
+    Stream.map((entry) => transformStreamEntry(streamKey, entry)),
+    Stream.retry(
+      pipe(
+        Schedule.exponential(Duration.seconds(baseDelaySeconds)),
+        Schedule.intersect(Schedule.recurs(maxRetries)),
+        Schedule.tapInput((error: MonitoringError) =>
+          Effect.logWarning(
+            `Stream monitoring error for '${streamKey}': ${error.message}. Retrying...`,
+          ),
+        ),
+      ),
+    ),
+  );
+
+/**
+ * Helper function to validate stream key names
+ */
+export const validateStreamKey = (
+  streamKey: string,
+): Effect.Effect<string, MonitoringError> =>
+  Effect.gen(function* () {
+    if (!streamKey || typeof streamKey !== 'string') {
+      return yield* Effect.fail(
+        createStreamReadFailedError(
+          'Stream key must be a non-empty string',
+          false,
+        ),
+      );
+    }
+
+    const trimmedStreamKey = streamKey.trim();
+    if (trimmedStreamKey.length === 0) {
+      return yield* Effect.fail(
+        createStreamReadFailedError(
+          'Stream key cannot be empty or whitespace only',
+          false,
+        ),
+      );
+    }
+
+    return trimmedStreamKey;
+  });
+
+/**
+ * Helper function to create a monitored stream with validation
+ */
+export const monitorStreamWithValidation = (
+  streamKey: string,
+  streamService: StreamMonitorService,
+  options?: StreamMonitorOptions,
+): Stream.Stream<StreamMessage, MonitoringError> =>
+  pipe(
+    validateStreamKey(streamKey),
+    Effect.map((validStreamKey) =>
+      streamService.monitor(validStreamKey, options),
+    ),
+    Stream.unwrap,
+  );
+
+/**
+ * Helper function to create a stream subscription with entry ID continuity tracking
+ * This ensures that after reconnection, we resume from the last seen entry ID
+ */
+export const createStreamWithContinuity = (
+  streamKey: string,
+  redisStreamService: RedisStreamService,
+  config: RedistailConfig,
+  initialStartId = '$',
+): Stream.Stream<StreamMessage, MonitoringError> => {
+  // Use a ref to track the last seen entry ID for continuity
+  return pipe(
+    Effect.sync(() => ({ lastEntryId: initialStartId })),
+    Effect.map((state) =>
+      pipe(
+        redisStreamService.subscribe(streamKey, {
+          id: state.lastEntryId,
+          block: config.monitoring.blockTimeout,
+        }),
+        Stream.mapError((error: RedisError) =>
+          convertRedisError(error, `Failed to read from stream '${streamKey}'`),
+        ),
+        Stream.map((entry) => {
+          // Update the last seen entry ID for continuity
+          state.lastEntryId = String(entry.id);
+          return transformStreamEntry(streamKey, entry);
+        }),
+        // Add reconnection with continuity - use the updated lastEntryId
+        Stream.retry(
+          pipe(
+            Schedule.exponential(Duration.seconds(1)),
+            Schedule.intersect(
+              Schedule.recurs(config.monitoring.maxReconnectAttempts),
+            ),
+            Schedule.tapInput((error: MonitoringError) =>
+              Effect.logInfo(
+                `Stream reconnecting for '${streamKey}' from entry ID '${state.lastEntryId}': ${error.message}`,
+              ),
+            ),
+          ),
+        ),
+      ),
+    ),
+    Stream.unwrap,
+  );
+};
+
+/**
+ * Helper function to parse stream entry ID for comparison
+ * Stream IDs are in format "timestamp-sequence" (e.g., "1609459200000-0")
+ */
+export const parseStreamEntryId = (
+  entryId: string,
+): Option.Option<{ timestamp: number; sequence: number }> =>
+  pipe(
+    Effect.sync(() => {
+      const parts = entryId.split('-');
+      if (parts.length !== 2) return Option.none();
+
+      const timestamp = Number.parseInt(parts[0], 10);
+      const sequence = Number.parseInt(parts[1], 10);
+
+      if (Number.isNaN(timestamp) || Number.isNaN(sequence))
+        return Option.none();
+
+      return Option.some({ timestamp, sequence });
+    }),
+    Effect.runSync,
+  );
+
+/**
+ * Helper function to compare stream entry IDs
+ * Returns -1 if id1 < id2, 0 if equal, 1 if id1 > id2
+ */
+export const compareStreamEntryIds = (id1: string, id2: string): number => {
+  const parsed1 = parseStreamEntryId(id1);
+  const parsed2 = parseStreamEntryId(id2);
+
+  if (Option.isNone(parsed1) || Option.isNone(parsed2)) {
+    // Fallback to string comparison if parsing fails
+    return id1.localeCompare(id2);
+  }
+
+  const { timestamp: ts1, sequence: seq1 } = parsed1.value;
+  const { timestamp: ts2, sequence: seq2 } = parsed2.value;
+
+  if (ts1 !== ts2) {
+    return ts1 - ts2;
+  }
+
+  return seq1 - seq2;
+};