ubersearch 1.6.2 → 1.7.1

package/src/core/orchestrator.ts

@@ -7,32 +7,11 @@
 import type { UberSearchConfig } from "../config/types";
 import type { CreditManager, CreditSnapshot } from "./credits";
 import type { ProviderRegistry } from "./provider";
-import type { StrategyContext } from "./strategy/ISearchStrategy";
+import type { EngineAttempt, StrategyContext, UberSearchOptions } from "./strategy/ISearchStrategy";
 import { StrategyFactory } from "./strategy/StrategyFactory";
 import type { EngineId, SearchResultItem } from "./types";
 
-export interface UberSearchOptions {
-  /** Override the default engine order */
-  engineOrderOverride?: EngineId[];
-
-  /** Maximum results per provider */
-  limit?: number;
-
-  /** Include raw provider responses */
-  includeRaw?: boolean;
-
-  /** Search strategy */
-  strategy?: "all" | "first-success";
-
-  /** SearXNG categories to search (e.g., ["general", "it", "science"]) */
-  categories?: string[];
-}
-
-export interface EngineAttempt {
-  engineId: EngineId;
-  success: boolean;
-  reason?: string;
-}
+export type { UberSearchOptions, EngineAttempt };
 
 export interface OrchestratorResult {
   /** Original query */
@@ -89,11 +68,6 @@ export class UberSearchOrchestrator {
     // Execute strategy
     const { results, attempts } = await strategy.execute(query, order, options, context);
 
-    // For 'all' strategy, sort results by score (descending)
-    if (strategyName === "all") {
-      results.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
-    }
-
     // Get credit snapshots
     const credits = this.credits.listSnapshots();
 

package/src/core/paths.ts

@@ -5,9 +5,9 @@
  * https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
  */
 
-import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const APP_NAME = "ubersearch";
@@ -108,17 +108,58 @@ export function getPackageRoot(): string {
   return dirname(dirname(currentDir));
 }
 
+/**
+ * Get candidate runtime roots where bundled SearXNG assets may live.
+ *
+ * This covers:
+ * - source checkouts (`<root>/providers/searxng`)
+ * - built JS output (`<root>/dist/providers/searxng`)
+ * - compiled binaries with copied assets next to the executable
+ */
+function getRuntimeRoots(): string[] {
+  const roots = new Set<string>();
+
+  roots.add(resolve(getPackageRoot()));
+  roots.add(resolve(dirname(process.execPath)));
+  roots.add(resolve(process.cwd()));
+
+  return [...roots];
+}
+
+function getBundledSearxngAssetCandidates(relativePath: string): string[] {
+  const candidates = new Set<string>();
+
+  for (const root of getRuntimeRoots()) {
+    candidates.add(join(root, "providers", "searxng", relativePath));
+    candidates.add(join(root, "dist", "providers", "searxng", relativePath));
+  }
+
+  return [...candidates];
+}
+
+function resolveBundledSearxngAsset(relativePath: string): string {
+  const candidates = getBundledSearxngAssetCandidates(relativePath);
+  const existing = candidates.find((candidate) => existsSync(candidate));
+
+  if (existing) {
+    return existing;
+  }
+
+  return candidates[0] ?? join(getPackageRoot(), "providers", "searxng", relativePath);
+}
+
+/**
+ * Get the bundled SearXNG docker-compose file path.
+ */
+export function getBundledSearxngComposePath(): string {
+  return resolveBundledSearxngAsset("docker-compose.yml");
+}
+
 /**
  * Get the bundled default settings.yml path
  */
 export function getDefaultSettingsPath(): string {
-  const packageRoot = getPackageRoot();
-  // In bundled mode, look in dist/providers/searxng/
-  // In dev mode, look in providers/searxng/
-  if (packageRoot.endsWith("/dist")) {
-    return join(packageRoot, "providers", "searxng", "config", "settings.yml");
-  }
-  return join(packageRoot, "providers", "searxng", "config", "settings.yml");
+  return resolveBundledSearxngAsset(join("config", "settings.yml"));
 }
 
 /**
@@ -129,11 +170,6 @@ export function bootstrapSearxngConfig(): boolean {
   const { configDir } = getSearxngPaths();
   const targetSettings = join(configDir, "settings.yml");
 
-  // If settings already exist, don't overwrite
-  if (existsSync(targetSettings)) {
-    return false;
-  }
-
   const defaultSettings = getDefaultSettingsPath();
 
   // If default settings don't exist, we can't bootstrap
@@ -145,12 +181,16 @@ export function bootstrapSearxngConfig(): boolean {
     return false;
   }
 
-  // Copy default settings to XDG config dir
+  // Use exclusive flag to prevent TOCTOU race and avoid overwriting
   try {
-    copyFileSync(defaultSettings, targetSettings);
+    const content = readFileSync(defaultSettings);
+    writeFileSync(targetSettings, content, { flag: "wx" });
     console.log(`[SearXNG] Bootstrapped default config to ${targetSettings}`);
     return true;
   } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "EEXIST") {
+      return false; // File already exists, no action needed
+    }
     console.error(`[SearXNG] Failed to bootstrap config:`, error);
     return false;
   }

package/src/core/provider.ts

@@ -23,20 +23,7 @@ export interface SearchProvider {
   getMissingConfigMessage(): string;
 }
 
-/**
- * Interface for providers that manage lifecycle (init, healthcheck, shutdown)
- */
-export interface ILifecycleProvider {
-  init(): Promise<void>;
-  healthcheck(): Promise<boolean>;
-  shutdown(): Promise<void>;
-  validateConfig(): Promise<{
-    valid: boolean;
-    errors: string[];
-    warnings: string[];
-  }>;
-  isLifecycleManaged(): boolean;
-}
+export type { ILifecycleProvider } from "./provider/ILifecycleProvider";
 
 /**
  * Registry to manage all available providers

package/src/core/retry.ts

@@ -0,0 +1,102 @@
+/**
+ * Retry Logic for Provider Operations
+ *
+ * Provides exponential backoff retry functionality for resilient
+ * provider operations
+ */
+
+import type { EngineId } from "./types";
+import { SearchError } from "./types";
+
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+  /** Maximum number of retry attempts */
+  maxAttempts?: number;
+
+  /** Initial delay between retries in milliseconds */
+  initialDelayMs?: number;
+
+  /** Multiplier for exponential backoff */
+  backoffMultiplier?: number;
+
+  /** Maximum delay between retries in milliseconds */
+  maxDelayMs?: number;
+
+  /** Whether to retry on specific error types */
+  retryableErrors?: Array<"network_error" | "api_error" | "rate_limit" | "no_results" | "timeout">;
+}
+
+/**
+ * Default retry configuration
+ */
+export const DEFAULT_RETRY_CONFIG: Required<RetryConfig> = {
+  maxAttempts: 3,
+  initialDelayMs: 1000,
+  backoffMultiplier: 2,
+  maxDelayMs: 10000,
+  retryableErrors: ["network_error", "api_error", "rate_limit", "no_results"],
+};
+
+/**
+ * Execute a function with retry logic and exponential backoff
+ *
+ * @param engineId - Engine ID for error messages
+ * @param fn - Function to execute with retry logic
+ * @param config - Retry configuration
+ * @returns Result of the function
+ * @throws SearchError if all retry attempts fail
+ */
+export async function withRetry<T>(
+  engineId: EngineId,
+  fn: () => Promise<T>,
+  config: RetryConfig = {},
+): Promise<T> {
+  // Skip retries in test environment to avoid timeouts
+  if (process.env.DISABLE_RETRY === "true") {
+    return fn();
+  }
+
+  const {
+    maxAttempts = DEFAULT_RETRY_CONFIG.maxAttempts,
+    initialDelayMs = DEFAULT_RETRY_CONFIG.initialDelayMs,
+    backoffMultiplier = DEFAULT_RETRY_CONFIG.backoffMultiplier,
+    maxDelayMs = DEFAULT_RETRY_CONFIG.maxDelayMs,
+    retryableErrors = DEFAULT_RETRY_CONFIG.retryableErrors,
+  } = config;
+
+  let lastError: unknown;
+  let delay = initialDelayMs;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (!(error instanceof SearchError)) {
+        throw error;
+      }
+
+      const shouldRetry = retryableErrors.includes(
+        error.reason as "network_error" | "api_error" | "rate_limit" | "no_results",
+      );
+
+      if (!shouldRetry || attempt >= maxAttempts) {
+        throw error;
+      }
+
+      const nextDelay = Math.min(delay * backoffMultiplier, maxDelayMs);
+
+      console.warn(
+        `[${engineId}] Attempt ${attempt}/${maxAttempts} failed: ${error.message}. Retrying in ${nextDelay}ms...`,
+      );
+
+      await new Promise((resolve) => setTimeout(resolve, nextDelay));
+      delay = nextDelay;
+    }
+  }
+
+  throw lastError;
+}

package/src/core/strategy/AllProvidersStrategy.ts

@@ -7,9 +7,10 @@
  * the overall search.
  */
 
-import { withRetry } from "../../providers/retry";
+import { getErrorMessage } from "../errorUtils";
 import { createLogger } from "../logger";
 import type { SearchProvider } from "../provider";
+import { withRetry } from "../retry";
 import type { EngineId, SearchResponse, SearchResultItem } from "../types";
 import { SearchError } from "../types";
 import type {
@@ -28,7 +29,7 @@ const log = createLogger("AllProviders");
 interface EngineSearchResult {
   engineId: EngineId;
   response?: SearchResponse;
-  error?: Error;
+  error?: unknown;
 }
 
 /**
@@ -81,8 +82,8 @@ export class AllProvidersStrategy implements ISearchStrategy {
         continue;
       }
 
-      // Check credit availability
-      if (!context.creditManager.hasSufficientCredits(engineId)) {
+      // Charge credits before search (atomic check+deduct to avoid race conditions)
+      if (!context.creditManager.charge(engineId)) {
         attempts.push({ engineId, success: false, reason: "out_of_credit" });
         continue;
       }
@@ -98,23 +99,14 @@ export class AllProvidersStrategy implements ISearchStrategy {
           }),
         );
 
-        // Deduct credits
-        if (!context.creditManager.charge(engineId)) {
-          // This shouldn't happen because we checked above, but handle gracefully
-          attempts.push({ engineId, success: false, reason: "out_of_credit" });
-          continue;
-        }
-
         // Record success
         attempts.push({ engineId, success: true });
 
-        // Add results, applying limit if specified
-        if (options.limit !== undefined) {
-          results.push(...response.items.slice(0, options.limit - results.length));
-        } else {
-          results.push(...response.items);
-        }
+        results.push(...response.items);
       } catch (error) {
+        // Refund credits for failed search
+        context.creditManager.refund(engineId);
+
         // Record failure
         if (error instanceof SearchError) {
           attempts.push({ engineId, success: false, reason: error.reason });
@@ -123,18 +115,11 @@ export class AllProvidersStrategy implements ISearchStrategy {
         }
 
         // Log debug message but continue with other providers
-        log.debug(
-          `Search failed for ${engineId}: ${error instanceof Error ? error.message : String(error)}`,
-        );
+        log.debug(`Search failed for ${engineId}: ${getErrorMessage(error)}`);
       }
     }
 
-    // Apply final limit if specified
-    if (options.limit !== undefined && results.length > options.limit) {
-      results.splice(options.limit);
-    }
-
-    return { results, attempts };
+    return { results: this.finalizeResults(results, options), attempts };
   }
 
   /**
@@ -163,7 +148,8 @@ export class AllProvidersStrategy implements ISearchStrategy {
         continue;
       }
 
-      if (!context.creditManager.hasSufficientCredits(engineId)) {
+      // Charge credits before search (atomic check+deduct to avoid race conditions)
+      if (!context.creditManager.charge(engineId)) {
         ineligibleAttempts.push({ engineId, success: false, reason: "out_of_credit" });
         continue;
       }
@@ -185,7 +171,7 @@ export class AllProvidersStrategy implements ISearchStrategy {
           );
           return { engineId, response };
         } catch (error) {
-          return { engineId, error: error instanceof Error ? error : new Error(String(error)) };
+          return { engineId, error };
         }
       },
     );
@@ -207,31 +193,35 @@ export class AllProvidersStrategy implements ISearchStrategy {
 
       if (settledResult.status === "rejected") {
         // Promise itself was rejected (shouldn't happen with our try/catch, but handle it)
-        attempts.push({ engineId, success: false, reason: "unknown" });
+        context.creditManager.refund(engineId);
+        const error = settledResult.reason;
+        if (error instanceof SearchError) {
+          attempts.push({ engineId, success: false, reason: error.reason });
+        } else {
+          attempts.push({ engineId, success: false, reason: "unknown" });
+        }
         log.debug(`Search failed for ${engineId}: Promise rejected`);
         continue;
       }
 
-      const { response, error } = settledResult.value;
+      if ("error" in settledResult.value) {
+        // Refund credits for failed search
+        context.creditManager.refund(engineId);
 
-      if (error) {
         // Search threw an error
+        const error = settledResult.value.error;
         if (error instanceof SearchError) {
           attempts.push({ engineId, success: false, reason: error.reason });
         } else {
           attempts.push({ engineId, success: false, reason: "unknown" });
         }
-        log.debug(`Search failed for ${engineId}: ${error.message}`);
+        log.debug(`Search failed for ${engineId}: ${getErrorMessage(error)}`);
         continue;
       }
 
-      if (response) {
-        // Deduct credits
-        if (!context.creditManager.charge(engineId)) {
-          attempts.push({ engineId, success: false, reason: "out_of_credit" });
-          continue;
-        }
+      const { response } = settledResult.value;
 
+      if (response) {
         // Record success
         attempts.push({ engineId, success: true });
 
@@ -249,11 +239,31 @@ export class AllProvidersStrategy implements ISearchStrategy {
       (a, b) => (engineOrder.get(a.engineId) ?? 0) - (engineOrder.get(b.engineId) ?? 0),
     );
 
-    // Apply final limit if specified
-    if (options.limit !== undefined && results.length > options.limit) {
-      results.splice(options.limit);
+    return { results: this.finalizeResults(results, options), attempts };
+  }
+
+  /**
+   * Deduplicate results by URL, sort by score, and apply limit.
+   */
+  private finalizeResults(
+    results: SearchResultItem[],
+    options: UberSearchOptions,
+  ): SearchResultItem[] {
+    const seen = new Set<string>();
+    const deduped: SearchResultItem[] = [];
+    for (const item of results) {
+      if (!seen.has(item.url)) {
+        seen.add(item.url);
+        deduped.push(item);
+      }
+    }
+
+    deduped.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+
+    if (options.limit !== undefined && deduped.length > options.limit) {
+      deduped.splice(options.limit);
     }
 
-    return { results, attempts };
+    return deduped;
   }
 }

package/src/core/strategy/FirstSuccessStrategy.ts

@@ -6,8 +6,9 @@
  * with insufficient credits and stops execution after the first success.
  */
 
-import { withRetry } from "../../providers/retry";
+import { getErrorMessage } from "../errorUtils";
 import { createLogger } from "../logger";
+import { withRetry } from "../retry";
 import type { EngineId } from "../types";
 import { SearchError } from "../types";
 import type {
@@ -53,8 +54,8 @@ export class FirstSuccessStrategy implements ISearchStrategy {
         continue;
       }
 
-      // Check credit availability
-      if (!context.creditManager.hasSufficientCredits(engineId)) {
+      // Charge credits before search (atomic check+deduct to avoid race conditions)
+      if (!context.creditManager.charge(engineId)) {
         attempts.push({ engineId, success: false, reason: "out_of_credit" });
         continue;
       }
@@ -70,18 +71,15 @@ export class FirstSuccessStrategy implements ISearchStrategy {
           }),
         );
 
-        // Deduct credits
-        if (!context.creditManager.charge(engineId)) {
-          attempts.push({ engineId, success: false, reason: "out_of_credit" });
-          continue;
-        }
-
         // Record success
         attempts.push({ engineId, success: true });
 
         // Return immediately with results from this provider
         return { results: response.items, attempts };
       } catch (error) {
+        // Refund credits for failed search
+        context.creditManager.refund(engineId);
+
         // Record failure and continue to next provider
         if (error instanceof SearchError) {
           attempts.push({ engineId, success: false, reason: error.reason });
@@ -90,9 +88,7 @@ export class FirstSuccessStrategy implements ISearchStrategy {
         }
 
         // Log debug message and continue
-        log.debug(
-          `Search failed for ${engineId}: ${error instanceof Error ? error.message : String(error)}`,
-        );
+        log.debug(`Search failed for ${engineId}: ${getErrorMessage(error)}`);
       }
     }
 

package/src/core/strategy/ISearchStrategy.ts

@@ -7,7 +7,7 @@
 
 import type { CreditManager } from "../credits";
 import type { ProviderRegistry } from "../provider";
-import type { EngineId, SearchResultItem } from "../types";
+import type { EngineId, SearchFailureReason, SearchResultItem } from "../types";
 
 /**
  * Context object providing dependencies to search strategies
@@ -58,7 +58,7 @@ export interface EngineAttempt {
   success: boolean;
 
   /** Reason for failure (if success=false) */
-  reason?: string;
+  reason?: SearchFailureReason;
 }
 
 /**

package/src/core/types.ts

@@ -33,6 +33,7 @@ export type SearchFailureReason =
   | "rate_limit"
   | "no_results"
   | "low_credit"
+  | "out_of_credit"
   | "config_error"
   | "no_provider"
   | "provider_unavailable"