ubersearch 0.0.0-development

package/src/core/docker/dockerComposeHelper.ts

@@ -0,0 +1,177 @@
+/**
+ * Docker Compose Helper
+ *
+ * Manages Docker Compose services for local providers
+ */
+
+import { exec } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+import { getSearxngPaths } from "../paths";
+
+const execAsync = promisify(exec);
+
+export interface DockerComposeOptions {
+  cwd?: string;
+  timeout?: number;
+}
+
+/**
+ * Helper for managing Docker Compose services
+ */
+export class DockerComposeHelper {
+  constructor(private composeFile: string) {}
+
+  /**
+   * Execute docker compose command
+   */
+  private async execDockerCompose(
+    args: string[],
+    options: DockerComposeOptions = {},
+  ): Promise<string> {
+    const cmd = `docker compose -f "${this.composeFile}" ${args.join(" ")}`;
+    const cwd = options.cwd || this.getComposeDir();
+    const timeout = options.timeout || 30000;
+
+    try {
+      // Get SearXNG paths and ensure directories exist
+      const { configDir, dataDir } = getSearxngPaths();
+
+      const { stdout, stderr } = await execAsync(cmd, {
+        cwd,
+        timeout,
+        env: {
+          ...process.env,
+          SEARXNG_CONFIG: configDir,
+          SEARXNG_DATA: dataDir,
+        },
+      });
+
+      if (stderr && !stderr.includes("warning")) {
+        console.warn(`Docker Compose warning: ${stderr}`);
+      }
+
+      return stdout;
+    } catch (error: unknown) {
+      const err = error as { message?: string; stdout?: string; stderr?: string };
+      const errorMessage = err.message ?? "Unknown error";
+      const timedOut = errorMessage.includes("timed out") || errorMessage.includes("ETIMEDOUT");
+
+      const errorDetails = [
+        `Docker Compose command ${timedOut ? "timed out" : "failed"}: ${errorMessage}`,
+        `Command: ${cmd}`,
+      ];
+      if (err.stdout) {
+        errorDetails.push(`Output: ${err.stdout}`);
+      }
+      if (err.stderr) {
+        errorDetails.push(`Error: ${err.stderr}`);
+      }
+
+      throw new Error(errorDetails.join("\n"));
+    }
+  }
+
+  /**
+   * Get directory containing compose file
+   */
+  private getComposeDir(): string {
+    return require("node:path").dirname(this.composeFile);
+  }
+
+  /**
+   * Start services
+   * @param services Optional list of services to start
+   */
+  async up(services?: string[], options?: DockerComposeOptions): Promise<void> {
+    const args = ["up", "-d"];
+    if (services && services.length > 0) {
+      args.push(...services);
+    }
+
+    await this.execDockerCompose(args, options);
+  }
+
+  /**
+   * Stop services
+   * @param services Optional list of services to stop
+   */
+  async stop(services?: string[], options?: DockerComposeOptions): Promise<void> {
+    const args = ["stop"];
+    if (services && services.length > 0) {
+      args.push(...services);
+    }
+
+    await this.execDockerCompose(args, options);
+  }
+
+  /**
+   * Stop and remove containers
+   */
+  async down(options?: DockerComposeOptions): Promise<void> {
+    await this.execDockerCompose(["down"], options);
+  }
+
+  /**
+   * Get service logs
+   * @param services Optional list of services
+   * @param tail Number of lines to show (default: 50)
+   */
+  async logs(
+    services?: string[],
+    tail: number = 50,
+    options?: DockerComposeOptions,
+  ): Promise<string> {
+    const args = ["logs", "--tail", String(tail)];
+    if (services && services.length > 0) {
+      args.push(...services);
+    }
+
+    return await this.execDockerCompose(args, options);
+  }
+
+  /**
+   * List running services
+   */
+  async ps(options?: DockerComposeOptions): Promise<string> {
+    return await this.execDockerCompose(["ps"], options);
+  }
+
+  /**
+   * Check if services are running
+   * @param service Optional specific service to check
+   */
+  async isRunning(service?: string, options?: DockerComposeOptions): Promise<boolean> {
+    try {
+      const output = await this.ps(options);
+
+      if (service) {
+        return output.includes(service) && !output.includes("Exit");
+      }
+
+      // Check if any services are running
+      return output.includes("Up");
+    } catch (_error) {
+      return false;
+    }
+  }
+
+  /**
+   * Check if Docker is available
+   */
+  static async isDockerAvailable(): Promise<boolean> {
+    try {
+      await execAsync("docker version", { timeout: 5000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if compose file exists
+   */
+  composeFileExists(): boolean {
+    return existsSync(this.composeFile);
+  }
+}

package/src/core/docker/dockerLifecycleManager.ts

@@ -0,0 +1,361 @@
+/**
+ * Docker Lifecycle Manager
+ *
+ * Handles Docker container lifecycle operations independently from search logic.
+ * Enables composition over inheritance for providers that need Docker management.
+ *
+ * @example
+ * ```typescript
+ * const dockerManager = new DockerLifecycleManager({
+ *   composeFile: './docker-compose.yml',
+ *   containerName: 'my-service',
+ *   healthEndpoint: 'http://localhost:8080/health',
+ *   autoStart: true,
+ *   autoStop: true
+ * });
+ *
+ * await dockerManager.init();
+ * const isHealthy = await dockerManager.healthcheck();
+ * await dockerManager.shutdown();
+ * ```
+ */
+
+import { createLogger } from "../logger";
+import { bootstrapSearxngConfig } from "../paths";
+import { DockerComposeHelper } from "./dockerComposeHelper";
+
+const log = createLogger("DockerLifecycle");
+
+export interface DockerLifecycleConfig {
+  containerName?: string;
+  composeFile?: string;
+  healthEndpoint?: string;
+  autoStart: boolean;
+  autoStop: boolean;
+  initTimeoutMs?: number;
+  projectRoot?: string; // Base path for resolving relative compose file paths
+}
+
+/**
+ * Manages Docker container lifecycle operations for providers
+ */
+export class DockerLifecycleManager {
+  private config: DockerLifecycleConfig;
+  private dockerHelper?: DockerComposeHelper;
+  private initialized = false;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(config: DockerLifecycleConfig) {
+    this.config = config;
+
+    // Initialize Docker helper if compose file is provided
+    if (config.composeFile) {
+      this.dockerHelper = new DockerComposeHelper(config.composeFile);
+    }
+  }
+
+  /**
+   * Initialize the Docker lifecycle manager
+   *
+   * Auto-starts containers if configured and performs health checks.
+   * Thread-safe - multiple calls return the same promise.
+   *
+   * @throws Error if container startup fails
+   */
+  async init(): Promise<void> {
+    if (this.initPromise) {
+      return this.initPromise;
+    }
+
+    if (!this.config.autoStart || !this.dockerHelper) {
+      this.initialized = true;
+      return;
+    }
+
+    this.initPromise = this.performInit().catch((error) => {
+      log.error("Initialization failed:", error);
+      this.initialized = false;
+      throw error;
+    });
+    return this.initPromise;
+  }
+
+  /**
+   * Wrap a promise with a timeout
+   */
+  private async withTimeout<T>(
+    promise: Promise<T>,
+    timeoutMs: number,
+    operation: string,
+  ): Promise<T> {
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => reject(new Error(`${operation} timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+
+    return Promise.race([promise, timeoutPromise]);
+  }
+
+  private async performInit(): Promise<void> {
+    if (!this.dockerHelper) {
+      return;
+    }
+
+    // Bootstrap SearXNG config if needed (copy default settings.yml)
+    bootstrapSearxngConfig();
+
+    // Check if Docker is available (with timeout)
+    const dockerAvailable = await this.withTimeout(
+      DockerComposeHelper.isDockerAvailable(),
+      10000,
+      "Docker availability check",
+    );
+    if (!dockerAvailable) {
+      log.warn("Docker is not available. Cannot auto-start container.");
+      this.initialized = true;
+      return;
+    }
+
+    // Check if container is already running (with timeout)
+    const isRunning = await this.withTimeout(this.healthcheck(), 5000, "Initial health check");
+    if (isRunning) {
+      log.info("Container is already running.");
+      this.initialized = true;
+      return;
+    }
+
+    // Auto-start container
+    log.info("Starting Docker container...");
+    try {
+      // Run from project root to ensure correct path resolution
+      const projectRoot = this.config.projectRoot || process.cwd();
+      await this.dockerHelper.up(
+        this.config.containerName ? [this.config.containerName] : undefined,
+        { cwd: projectRoot },
+      );
+      log.info("Container started successfully.");
+
+      // Wait for health check if endpoint is configured
+      if (this.config.healthEndpoint) {
+        await this.waitForHealth();
+      }
+
+      this.initialized = true;
+    } catch (error) {
+      log.error("Failed to start container:", error);
+      throw error;
+    } finally {
+      this.initPromise = null;
+    }
+  }
+
+  /**
+   * Check if container is healthy
+   *
+   * Checks both container running status and health endpoint if configured.
+   *
+   * @returns true if container is healthy, false otherwise
+   */
+  async healthcheck(): Promise<boolean> {
+    // Check if container is running
+    if (this.dockerHelper) {
+      const projectRoot = this.config.projectRoot || process.cwd();
+      const isRunning = await this.dockerHelper.isRunning(this.config.containerName, {
+        cwd: projectRoot,
+      });
+      if (!isRunning) {
+        return false;
+      }
+    }
+
+    // Check health endpoint if configured
+    if (this.config.healthEndpoint) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 3000);
+
+        const response = await fetch(this.config.healthEndpoint, {
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+        return response.ok;
+      } catch {
+        return false;
+      }
+    }
+
+    // If no health endpoint, assume healthy if initialized
+    return this.initialized;
+  }
+
+  /**
+   * Wait for health endpoint to be ready
+   */
+  private async waitForHealth(timeoutMs: number = 30000): Promise<void> {
+    if (!this.config.healthEndpoint) {
+      return;
+    }
+
+    log.info("Waiting for health check...");
+
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+      if (await this.healthcheck()) {
+        log.info("Health check passed.");
+        return;
+      }
+
+      await this.sleep(1000);
+    }
+
+    throw new Error(
+      `[DockerLifecycleManager] Health check failed after ${timeoutMs}ms. ` +
+        `Endpoint: ${this.config.healthEndpoint}`,
+    );
+  }
+
+  /**
+   * Shutdown Docker lifecycle manager
+   *
+   * Stops containers if autoStop is enabled. Errors during shutdown are logged
+   * but not thrown to prevent cleanup failures from propagating.
+   */
+  async shutdown(): Promise<void> {
+    if (!this.config.autoStop || !this.dockerHelper) {
+      return;
+    }
+
+    const projectRoot = this.config.projectRoot || process.cwd();
+    const isRunning = await this.dockerHelper.isRunning(this.config.containerName, {
+      cwd: projectRoot,
+    });
+    if (!isRunning) {
+      return;
+    }
+
+    log.info("Stopping Docker container...");
+    try {
+      await this.dockerHelper.stop(
+        this.config.containerName ? [this.config.containerName] : undefined,
+        { cwd: projectRoot },
+      );
+      log.info("Container stopped.");
+    } catch (error) {
+      log.error("Failed to stop container:", error);
+      // Don't throw on shutdown errors
+    }
+  }
+
+  /**
+   * Validate Docker configuration
+   *
+   * Performs comprehensive validation of Docker configuration including:
+   * - Docker availability
+   * - Compose file existence and validity
+   * - Health endpoint URL validation
+   * - Container name format validation
+   *
+   * @returns Validation results with errors and warnings
+   */
+  async validateDockerConfig(): Promise<{
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+  }> {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    // Check Docker is available
+    const dockerAvailable = await DockerComposeHelper.isDockerAvailable();
+    if (!dockerAvailable) {
+      errors.push("Docker is not available or not running");
+      return { valid: false, errors, warnings };
+    }
+
+    // Check compose file exists
+    if (this.config.composeFile) {
+      const composeExists = await this.dockerHelper?.composeFileExists();
+      if (!composeExists) {
+        errors.push(`Compose file not found: ${this.config.composeFile}`);
+      }
+    }
+
+    // Check if compose file is valid
+    if (this.dockerHelper) {
+      try {
+        const projectRoot = this.config.projectRoot || process.cwd();
+        await this.dockerHelper.ps({ cwd: projectRoot });
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("config")) {
+          errors.push(`Invalid compose file: ${message}`);
+        }
+      }
+    }
+
+    // Check health endpoint if configured
+    if (this.config.healthEndpoint) {
+      try {
+        // Try to parse the URL
+        new URL(this.config.healthEndpoint);
+      } catch {
+        warnings.push(`Health endpoint URL is invalid: ${this.config.healthEndpoint}`);
+      }
+    }
+
+    // Check container name if specified
+    if (this.config.containerName && !/^[a-zA-Z0-9_-]+$/.test(this.config.containerName)) {
+      warnings.push(`Container name contains invalid characters: ${this.config.containerName}`);
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+
+  /**
+   * Helper: Sleep for ms milliseconds
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Check if lifecycle manager is initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Check if container is running
+   *
+   * @returns true if container is running, false otherwise
+   */
+  async isRunning(): Promise<boolean> {
+    if (!this.dockerHelper) {
+      return false;
+    }
+
+    try {
+      const projectRoot = this.config.projectRoot || process.cwd();
+      return await this.dockerHelper.isRunning(this.config.containerName, {
+        cwd: projectRoot,
+      });
+    } catch (error) {
+      log.warn("Error checking if container is running:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Get the current configuration
+   *
+   * @returns Current Docker lifecycle configuration
+   */
+  getConfig(): DockerLifecycleConfig {
+    return { ...this.config };
+  }
+}

package/src/core/docker/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Docker core module exports
+ */
+
+export type { DockerComposeOptions } from "./dockerComposeHelper";
+export { DockerComposeHelper } from "./dockerComposeHelper";
+export type { DockerLifecycleConfig } from "./dockerLifecycleManager";
+export { DockerLifecycleManager } from "./dockerLifecycleManager";

package/src/core/logger.ts

@@ -0,0 +1,146 @@
+/**
+ * Logger Abstraction
+ *
+ * Provides a consistent logging interface across the codebase.
+ * Supports log levels and can be configured for different environments.
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error" | "none";
+
+/**
+ * Logger configuration
+ */
+export interface LoggerConfig {
+  /** Minimum log level to output */
+  level: LogLevel;
+  /** Prefix for all log messages */
+  prefix?: string;
+  /** Whether to include timestamps */
+  timestamp?: boolean;
+}
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  none: 4,
+};
+
+/**
+ * Simple logger implementation
+ */
+export class Logger {
+  private config: LoggerConfig;
+
+  constructor(config: Partial<LoggerConfig> = {}) {
+    this.config = {
+      level: config.level ?? (process.env.DEBUG ? "debug" : "info"),
+      prefix: config.prefix,
+      timestamp: config.timestamp ?? false,
+    };
+  }
+
+  /**
+   * Check if a log level should be output
+   */
+  private shouldLog(level: LogLevel): boolean {
+    return LOG_LEVELS[level] >= LOG_LEVELS[this.config.level];
+  }
+
+  /**
+   * Format a log message
+   */
+  private format(_level: LogLevel, message: string): string {
+    const parts: string[] = [];
+
+    if (this.config.timestamp) {
+      parts.push(new Date().toISOString());
+    }
+
+    if (this.config.prefix) {
+      parts.push(`[${this.config.prefix}]`);
+    }
+
+    parts.push(message);
+    return parts.join(" ");
+  }
+
+  /**
+   * Log a debug message
+   */
+  debug(message: string, ...args: unknown[]): void {
+    if (this.shouldLog("debug")) {
+      console.log(this.format("debug", message), ...args);
+    }
+  }
+
+  /**
+   * Log an info message
+   */
+  info(message: string, ...args: unknown[]): void {
+    if (this.shouldLog("info")) {
+      console.log(this.format("info", message), ...args);
+    }
+  }
+
+  /**
+   * Log a warning message
+   */
+  warn(message: string, ...args: unknown[]): void {
+    if (this.shouldLog("warn")) {
+      console.warn(this.format("warn", message), ...args);
+    }
+  }
+
+  /**
+   * Log an error message
+   */
+  error(message: string, ...args: unknown[]): void {
+    if (this.shouldLog("error")) {
+      console.error(this.format("error", message), ...args);
+    }
+  }
+
+  /**
+   * Create a child logger with a prefix
+   */
+  child(prefix: string): Logger {
+    const parentPrefix = this.config.prefix;
+    return new Logger({
+      ...this.config,
+      prefix: parentPrefix ? `${parentPrefix}:${prefix}` : prefix,
+    });
+  }
+
+  /**
+   * Set the log level
+   */
+  setLevel(level: LogLevel): void {
+    this.config.level = level;
+  }
+}
+
+/**
+ * Default logger instance
+ * Can be configured globally via environment variables:
+ * - DEBUG: Set to any value to enable debug logging
+ * - LOG_LEVEL: Set to debug, info, warn, error, or none
+ */
+export const logger = new Logger({
+  level: (process.env.LOG_LEVEL as LogLevel) ?? (process.env.DEBUG ? "debug" : "warn"),
+});
+
+/**
+ * Create a logger with a specific prefix
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger('DockerLifecycle');
+ * log.info('Starting container...');
+ * // Output: [DockerLifecycle] Starting container...
+ * ```
+ */
+export function createLogger(prefix: string): Logger {
+  return logger.child(prefix);
+}