@ceschiatti/redistail 0.0.1 → 0.0.3

package/src/cli/redistail.ts

@@ -0,0 +1,417 @@
+/**
+ * Main CLI program for redistail - Redis message monitoring utility.
+ *
+ * This module implements the main program effect that combines all services
+ * to create a complete Redis monitoring application. It handles CLI argument
+ * parsing, service initialization, signal handling, and message streaming.
+ *
+ * Requirements addressed:
+ * - 1.5: Help and version flag support
+ * - 2.5: Graceful shutdown for PubSub monitoring (Ctrl+C handling)
+ * - 3.5: Graceful shutdown for Stream monitoring (Ctrl+C handling)
+ * - 6.3: Topic validation and error handling
+ * - 6.4: Redis error recovery and continued monitoring
+ */
+
+import { BunRuntime } from '@effect/platform-bun';
+import { Console, Duration, Effect, pipe, Schedule, Stream } from 'effect';
+// Note: RedisPubSub and RedisStream are provided transitively via PubSubMonitorService and StreamMonitorService
+import { CLIConfigService, CLIConfigServiceLive } from './config-service.js';
+import { DisplayServiceTag, type DisplayService } from './display-service.js';
+import { PubSubAppLive, StreamAppLive } from './layers.js';
+import { PubSubMonitorService } from './pubsub-monitor-service.js';
+import { SignalHandlerService } from './signal-handler-service.js';
+import { StreamMonitorService } from './stream-monitor-service.js';
+import type { CLIConfig, RedistailError } from './types.js';
+
+// ============================================================================
+// Main Program Implementation
+// ============================================================================
+
+/**
+ * Main redistail program effect that combines all services
+ *
+ * This effect:
+ * 1. Parses CLI arguments and loads configuration
+ * 2. Handles help and version flags
+ * 3. Sets up signal handlers for graceful shutdown
+ * 4. Starts appropriate monitoring based on connection type
+ * 5. Streams and displays messages until interrupted
+ *
+ * Requirements 1.5, 2.5, 3.5, 6.3, 6.4
+ */
+export const redistailProgram = (
+  args: string[],
+): Effect.Effect<
+  void,
+  RedistailError,
+  | CLIConfigService
+  | SignalHandlerService
+  | DisplayService
+  | PubSubMonitorService
+  | StreamMonitorService
+> =>
+  Effect.gen(function* () {
+    // Parse CLI arguments
+    const cliConfigService = yield* CLIConfigService;
+    const cliConfig = yield* cliConfigService.parseArgs(args);
+
+    // Handle help and version flags (Requirement 1.5)
+    if (cliConfig.help) {
+      yield* cliConfigService.showHelp();
+      return;
+    }
+
+    if (cliConfig.version) {
+      yield* cliConfigService.showVersion();
+      return;
+    }
+
+    // Setup signal handlers for graceful shutdown (Requirements 2.5, 3.5)
+    const signalHandler = yield* SignalHandlerService;
+    yield* signalHandler.setupSignalHandlers();
+
+    // Get required services
+    const displayService = yield* DisplayServiceTag;
+
+    // Start monitoring based on connection type
+    yield* startMonitoring(cliConfig, displayService);
+  }) as Effect.Effect<
+    void,
+    RedistailError,
+    | CLIConfigService
+    | SignalHandlerService
+    | DisplayService
+    | PubSubMonitorService
+    | StreamMonitorService
+  >;
+
+/**
+ * Start monitoring based on the connection type specified in CLI config
+ *
+ * This function handles both PubSub and Stream monitoring with proper
+ * error handling and recovery (Requirements 6.3, 6.4)
+ */
+const startMonitoring = (
+  cliConfig: CLIConfig,
+  displayService: DisplayService,
+): Effect.Effect<
+  void,
+  RedistailError,
+  PubSubMonitorService | StreamMonitorService | CLIConfigService
+> =>
+  Effect.gen(function* () {
+    // Validate topic name (Requirement 6.3)
+    if (!cliConfig.topicName || cliConfig.topicName.trim().length === 0) {
+      yield* displayService.outputError('❌ Error: Topic name cannot be empty');
+      return yield* Effect.fail(
+        new Error('Invalid topic name') as RedistailError,
+      );
+    }
+
+    const topicName = cliConfig.topicName.trim();
+
+    // Log connection attempt to stderr
+    yield* displayService.outputError(
+      `🔗 Connecting to Redis ${cliConfig.connectionType} monitoring for topic: ${topicName}`,
+    );
+
+    if (cliConfig.connectionType === 'pubsub') {
+      yield* startPubSubMonitoring(topicName, displayService);
+    } else {
+      yield* startStreamMonitoring(topicName, displayService);
+    }
+  });
+
+/**
+ * Start PubSub monitoring with error recovery
+ *
+ * Requirements 2.5, 6.4: Graceful shutdown and Redis error recovery
+ */
+const startPubSubMonitoring = (
+  channel: string,
+  displayService: DisplayService,
+): Effect.Effect<void, RedistailError, PubSubMonitorService> =>
+  Effect.gen(function* () {
+    const pubSubMonitor = yield* PubSubMonitorService;
+
+    // Log successful connection
+    yield* displayService.outputError(
+      `✅ Connected to PubSub channel: ${channel}`,
+    );
+    yield* displayService.outputError(
+      '📡 Waiting for messages... (Press Ctrl+C to exit)',
+    );
+
+    // Create message stream with error recovery (Requirement 6.4)
+    const messageStream = pubSubMonitor.monitor(channel).pipe(
+      Stream.mapEffect((message) =>
+        displayService.formatPubSubMessage(message),
+      ),
+      Stream.mapEffect((formatted) => displayService.outputMessage(formatted)),
+      // Retry on recoverable errors with exponential backoff
+      Stream.retry(
+        pipe(
+          Schedule.exponential(Duration.seconds(1)),
+          Schedule.intersect(Schedule.recurs(5)), // Max 5 retry attempts
+          Schedule.tapInput(
+            (error: unknown) =>
+              displayService.outputError(
+                `⚠️  Connection error, retrying... ${String(error)}`,
+              ) as Effect.Effect<void, never, never>,
+          ),
+        ),
+      ),
+      // Handle non-recoverable errors gracefully
+      Stream.catchAll((error: unknown) =>
+        Stream.fromEffect(
+          pipe(
+            Effect.all([
+              displayService.outputError(
+                `❌ Fatal error in PubSub monitoring: ${String(error)}`,
+              ),
+              displayService.outputError(
+                '💡 Check Redis connection and try again',
+              ),
+            ]),
+            Effect.asVoid,
+          ) as Effect.Effect<void, never, never>,
+        ),
+      ),
+    ) as Stream.Stream<void, never, never>;
+
+    // Run the message stream until completion or interruption
+    yield* Stream.runDrain(messageStream);
+  });
+
+/**
+ * Start Stream monitoring with error recovery
+ *
+ * Requirements 3.5, 6.4: Graceful shutdown and Redis error recovery
+ */
+const startStreamMonitoring = (
+  streamKey: string,
+  displayService: DisplayService,
+): Effect.Effect<void, RedistailError, StreamMonitorService> =>
+  Effect.gen(function* () {
+    const streamMonitor = yield* StreamMonitorService;
+
+    // Log successful connection
+    yield* displayService.outputError(`✅ Connected to Stream: ${streamKey}`);
+    yield* displayService.outputError(
+      '📡 Waiting for stream entries... (Press Ctrl+C to exit)',
+    );
+
+    // Create message stream with error recovery (Requirement 6.4)
+    const messageStream = streamMonitor.monitor(streamKey).pipe(
+      Stream.mapEffect((message) =>
+        displayService.formatStreamMessage(message),
+      ),
+      Stream.mapEffect((formatted) => displayService.outputMessage(formatted)),
+      // Retry on recoverable errors with exponential backoff
+      Stream.retry(
+        pipe(
+          Schedule.exponential(Duration.seconds(1)),
+          Schedule.intersect(Schedule.recurs(5)), // Max 5 retry attempts
+          Schedule.tapInput(
+            (error: unknown) =>
+              displayService.outputError(
+                `⚠️  Connection error, retrying... ${String(error)}`,
+              ) as Effect.Effect<void, never, never>,
+          ),
+        ),
+      ),
+      // Handle non-recoverable errors gracefully
+      Stream.catchAll((error: unknown) =>
+        Stream.fromEffect(
+          pipe(
+            Effect.all([
+              displayService.outputError(
+                `❌ Fatal error in Stream monitoring: ${String(error)}`,
+              ),
+              displayService.outputError(
+                '💡 Check Redis connection and stream name, then try again',
+              ),
+            ]),
+            Effect.asVoid,
+          ) as Effect.Effect<void, never, never>,
+        ),
+      ),
+    ) as Stream.Stream<void, never, never>;
+
+    // Run the message stream until completion or interruption
+    yield* Stream.runDrain(messageStream);
+  });
+
+// ============================================================================
+// CLI Entry Point with Error Handling
+// ============================================================================
+
+/**
+ * CLI main function with comprehensive error handling and optimized layer selection
+ *
+ * This function provides the main entry point for the CLI binary with
+ * proper error handling, logging, and process management. It optimizes
+ * Redis connections by only loading the services needed for the specific mode:
+ *
+ * - PubSub mode: Only creates 2 Redis connections (publish + subscribe)
+ * - Stream mode: Only creates 2 Redis connections (producer + consumer)
+ * - Help/version: Uses minimal layer without Redis connections
+ * - Invalid args: Shows error without creating any connections
+ *
+ * This reduces Redis connections from 5 to just 2 per run, or 0 for help/errors.
+ */
+export const cliMain = (args: string[]): Effect.Effect<void, never, never> => {
+  // Early validation - check for help/version flags or missing arguments
+  // This prevents unnecessary Redis connections for simple cases
+  const hasHelpFlag = args.includes('--help') || args.includes('-h');
+  const hasVersionFlag = args.includes('--version') || args.includes('-v');
+  const hasMissingArgs = args.length < 2 && !hasHelpFlag && !hasVersionFlag;
+
+  // Handle help/version/error cases without Redis connections
+  if (hasHelpFlag || hasVersionFlag || hasMissingArgs) {
+    const simpleProgram = Effect.gen(function* () {
+      const cliConfigService = yield* CLIConfigService;
+
+      if (hasHelpFlag) {
+        yield* cliConfigService.showHelp();
+        return;
+      }
+
+      if (hasVersionFlag) {
+        yield* cliConfigService.showVersion();
+        return;
+      }
+
+      if (hasMissingArgs) {
+        yield* Console.error(
+          '❌ CLI Error: Missing required arguments. Usage: redistail <pubsub|stream> <topic-name>',
+        );
+        yield* Console.error('💡 Use --help for usage information');
+        return yield* Effect.sync(() => process.exit(1));
+      }
+    });
+
+    // Use minimal layer without Redis connections for these cases
+    return Effect.provide(simpleProgram, CLIConfigServiceLive) as Effect.Effect<
+      void,
+      never,
+      never
+    >;
+  }
+
+  // For actual monitoring, determine connection type and use appropriate layer
+  const connectionType = args[0];
+
+  // Create the program with error handling
+  const programWithErrorHandling = pipe(
+    redistailProgram(args),
+    // Handle all possible errors gracefully
+    Effect.catchAll((error: unknown) =>
+      Effect.gen(function* () {
+        // Determine error type and provide appropriate message
+        if (typeof error === 'object' && error !== null && '_tag' in error) {
+          const taggedError = error as { _tag: string; message?: string };
+
+          switch (taggedError._tag) {
+            case 'CLIError':
+              yield* Console.error(
+                `❌ CLI Error: ${taggedError.message || String(error)}`,
+              );
+              yield* Console.error('💡 Use --help for usage information');
+              break;
+            case 'ConfigError':
+              yield* Console.error(
+                `❌ Configuration Error: ${taggedError.message || String(error)}`,
+              );
+              yield* Console.error(
+                '💡 Check environment variables and Redis connection settings',
+              );
+              break;
+            case 'MonitoringError':
+              yield* Console.error(
+                `❌ Monitoring Error: ${taggedError.message || String(error)}`,
+              );
+              yield* Console.error(
+                '💡 Check Redis server availability and topic names',
+              );
+              break;
+            default:
+              yield* Console.error(`❌ Unexpected Error: ${String(error)}`);
+          }
+        } else {
+          yield* Console.error(`❌ Error: ${String(error)}`);
+        }
+
+        // Exit with error code
+        return yield* Effect.sync(() => process.exit(1));
+      }),
+    ),
+  );
+
+  // Select and provide the appropriate layer based on connection type
+  if (connectionType === 'pubsub') {
+    return Effect.provide(
+      programWithErrorHandling,
+      PubSubAppLive,
+    ) as Effect.Effect<void, never, never>;
+  }
+  if (connectionType === 'stream') {
+    return Effect.provide(
+      programWithErrorHandling,
+      StreamAppLive,
+    ) as Effect.Effect<void, never, never>;
+  }
+
+  // Invalid connection type - show error without Redis connections
+  const errorProgram = Effect.gen(function* () {
+    yield* Console.error(
+      `❌ CLI Error: Invalid connection type '${connectionType}'. Must be 'pubsub' or 'stream'`,
+    );
+    yield* Console.error('💡 Use --help for usage information');
+    return yield* Effect.sync(() => process.exit(1));
+  });
+
+  return Effect.provide(errorProgram, CLIConfigServiceLive) as Effect.Effect<
+    void,
+    never,
+    never
+  >;
+};
+
+// ============================================================================
+// Binary Entry Point
+// ============================================================================
+
+/**
+ * Entry point for the CLI binary
+ *
+ * This is the main entry point when redistail is executed as a CLI command.
+ * It processes command line arguments and runs the main program.
+ */
+if (import.meta.main) {
+  // Get command line arguments (skip node and script name)
+  const args = process.argv.slice(2);
+
+  // Run the main program with Bun runtime
+  BunRuntime.runMain(cliMain(args));
+}
+
+// ============================================================================
+// Library Exports
+// ============================================================================
+
+/**
+ * Re-export commonly used types and services for convenience
+ */
+export {
+  AppLive,
+  CLIConfigService,
+  DisplayServiceTag,
+  PubSubAppLive,
+  PubSubMonitorService,
+  SignalHandlerService,
+  StreamAppLive,
+  StreamMonitorService,
+} from './layers.js';
+export type { CLIConfig, RedistailConfig, RedistailError } from './types.js';

package/src/cli/signal-handler-service.ts

@@ -0,0 +1,210 @@
+/**
+ * Signal handler service for graceful shutdown of the redistail CLI utility.
+ *
+ * This module provides signal handling for SIGINT (Ctrl+C) and SIGTERM signals,
+ * ensuring proper cleanup and graceful shutdown for both PubSub and Stream monitoring.
+ */
+
+import { Context, Effect, Layer, Console } from 'effect';
+
+// ============================================================================
+// Service Interface
+// ============================================================================
+
+/**
+ * Service interface for handling process signals and graceful shutdown
+ */
+export interface SignalHandlerService {
+  /**
+   * Set up signal handlers for SIGINT and SIGTERM
+   */
+  readonly setupSignalHandlers: () => Effect.Effect<void>;
+
+  /**
+   * Perform graceful shutdown with cleanup
+   */
+  readonly gracefulShutdown: () => Effect.Effect<void>;
+
+  /**
+   * Check if shutdown has been requested
+   */
+  readonly isShutdownRequested: () => Effect.Effect<boolean>;
+}
+
+/**
+ * Service tag for dependency injection
+ */
+export const SignalHandlerService = Context.GenericTag<SignalHandlerService>(
+  'SignalHandlerService',
+);
+
+// ============================================================================
+// Service Implementation
+// ============================================================================
+
+/**
+ * Internal state to track shutdown requests
+ */
+interface SignalHandlerState {
+  shutdownInProgress: boolean;
+}
+
+/**
+ * Create the signal handler service implementation
+ */
+const createSignalHandler = (): SignalHandlerService => {
+  // Mutable state for tracking shutdown status
+  const state: SignalHandlerState = {
+    shutdownInProgress: false,
+  };
+
+  /**
+   * Perform graceful shutdown with cleanup
+   */
+  const gracefulShutdown = (): Effect.Effect<void> =>
+    Effect.gen(function* () {
+      // Prevent multiple shutdown attempts
+      if (state.shutdownInProgress) {
+        return;
+      }
+
+      state.shutdownInProgress = true;
+
+      // Log shutdown message
+      yield* Console.error('🛑 Shutting down redistail...');
+
+      // Give a brief moment for any pending operations to complete
+      yield* Effect.sleep('100 millis');
+
+      // Log completion and exit
+      yield* Console.error('✅ Shutdown complete');
+      return yield* Effect.sync(() => process.exit(0));
+    });
+
+  /**
+   * Handle shutdown signal with proper cleanup
+   */
+  const handleShutdownSignal = (signal: string): Effect.Effect<void> =>
+    Effect.gen(function* () {
+      // Prevent multiple shutdown attempts
+      if (state.shutdownInProgress) {
+        return;
+      }
+
+      state.shutdownInProgress = true;
+
+      // Log shutdown message to stderr
+      yield* Console.error(
+        `\n🛑 Received ${signal}, shutting down gracefully...`,
+      );
+
+      // Perform graceful shutdown
+      yield* gracefulShutdown();
+    });
+
+  /**
+   * Set up signal handlers for SIGINT and SIGTERM
+   */
+  const setupSignalHandlers = (): Effect.Effect<void> =>
+    Effect.sync(() => {
+      // Handle SIGINT (Ctrl+C)
+      process.on('SIGINT', () => {
+        Effect.runSync(handleShutdownSignal('SIGINT'));
+      });
+
+      // Handle SIGTERM (termination request)
+      process.on('SIGTERM', () => {
+        Effect.runSync(handleShutdownSignal('SIGTERM'));
+      });
+
+      // Handle uncaught exceptions gracefully
+      process.on('uncaughtException', (error) => {
+        Effect.runSync(
+          Effect.gen(function* () {
+            yield* Console.error(`❌ Uncaught exception: ${error.message}`);
+            yield* gracefulShutdown();
+          }),
+        );
+      });
+
+      // Handle unhandled promise rejections
+      process.on('unhandledRejection', (reason) => {
+        Effect.runSync(
+          Effect.gen(function* () {
+            yield* Console.error(`❌ Unhandled rejection: ${reason}`);
+            yield* gracefulShutdown();
+          }),
+        );
+      });
+    });
+
+  /**
+   * Check if shutdown has been requested
+   */
+  const isShutdownRequested = (): Effect.Effect<boolean> =>
+    Effect.sync(() => state.shutdownInProgress);
+
+  return {
+    setupSignalHandlers,
+    gracefulShutdown,
+    isShutdownRequested,
+  };
+};
+
+// ============================================================================
+// Service Layer
+// ============================================================================
+
+/**
+ * Live implementation layer for the SignalHandlerService
+ */
+export const SignalHandlerServiceLive = Layer.succeed(
+  SignalHandlerService,
+  createSignalHandler(),
+);
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Effect that sets up signal handlers and runs an effect
+ */
+export const withSignalHandling = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R | SignalHandlerService> =>
+  Effect.gen(function* () {
+    const signalHandler = yield* SignalHandlerService;
+
+    // Set up signal handlers
+    yield* signalHandler.setupSignalHandlers();
+
+    // Run the effect
+    return yield* effect;
+  });
+
+/**
+ * Check if shutdown has been requested
+ */
+export const checkShutdown = (): Effect.Effect<
+  boolean,
+  never,
+  SignalHandlerService
+> =>
+  Effect.gen(function* () {
+    const signalHandler = yield* SignalHandlerService;
+    return yield* signalHandler.isShutdownRequested();
+  });
+
+/**
+ * Perform graceful shutdown
+ */
+export const performShutdown = (): Effect.Effect<
+  void,
+  never,
+  SignalHandlerService
+> =>
+  Effect.gen(function* () {
+    const signalHandler = yield* SignalHandlerService;
+    yield* signalHandler.gracefulShutdown();
+  });