spindb 0.37.2 → 0.38.0

package/engines/redis/backup.ts

@@ -1,389 +0,0 @@
-/**
- * Redis backup module
- * Supports two formats:
- * - RDB: Binary snapshot via BGSAVE (default, compact, fast restore)
- * - Text: Human-readable Redis commands (.redis file)
- */
-
-import { spawn } from 'child_process'
-import { copyFile, stat, mkdir, writeFile } from 'fs/promises'
-import { existsSync } from 'fs'
-import { join, dirname } from 'path'
-import { logDebug, logWarning } from '../../core/error-handler'
-import { paths } from '../../config/paths'
-import { getRedisCliPath, REDIS_CLI_NOT_FOUND_ERROR } from './cli-utils'
-import type { ContainerConfig, BackupOptions, BackupResult } from '../../types'
-
-/**
- * Execute a Redis command via stdin piping
- * This is safer than shell command construction as it handles
- * keys/values with spaces and special characters correctly
- */
-async function execRedisCommand(
-  redisCli: string,
-  port: number,
-  command: string,
-): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const proc = spawn(redisCli, ['-h', '127.0.0.1', '-p', String(port)], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-    })
-
-    let stdout = ''
-    let stderr = ''
-
-    proc.stdout.on('data', (data: Buffer) => {
-      stdout += data.toString()
-    })
-    proc.stderr.on('data', (data: Buffer) => {
-      stderr += data.toString()
-    })
-
-    proc.on('error', reject)
-
-    proc.on('close', (code) => {
-      if (code === 0 || code === null) {
-        resolve(stdout)
-      } else {
-        reject(new Error(stderr || `redis-cli exited with code ${code}`))
-      }
-    })
-
-    // Write command to stdin and close
-    proc.stdin.write(command + '\n')
-    proc.stdin.end()
-  })
-}
-
-/**
- * Escape a string value for Redis command output
- * Wraps in single quotes and escapes backslashes and single quotes
- */
-function escapeRedisValue(value: string): string {
-  // Escape backslashes first, then single quotes (order matters!)
-  // e.g., "test\'value" → "test\\\'value" (backslash and quote both escaped)
-  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
-}
-
-/**
- * Create a text-based backup (.redis file)
- * Exports all keys as Redis commands that can be replayed
- */
-async function createTextBackup(
-  container: ContainerConfig,
-  outputPath: string,
-): Promise<BackupResult> {
-  const { port } = container
-
-  const redisCli = await getRedisCliPath()
-  if (!redisCli) {
-    throw new Error(REDIS_CLI_NOT_FOUND_ERROR)
-  }
-
-  const commands: string[] = []
-  commands.push('# Redis backup generated by SpinDB')
-  commands.push(`# Date: ${new Date().toISOString()}`)
-  commands.push('')
-
-  // Get all keys using KEYS * (for small datasets this is fine)
-  // For production with millions of keys, SCAN would be better
-  const keysOutput = await execRedisCommand(redisCli, port, 'KEYS *')
-  // Use /\r?\n/ to handle both Unix (\n) and Windows (\r\n) line endings
-  const keys = keysOutput
-    .trim()
-    .split(/\r?\n/)
-    .map((k) => k.trim())
-    .filter((k) => k)
-
-  logDebug(`Found ${keys.length} keys to backup`)
-
-  for (const key of keys) {
-    // Get key type - quote key to handle spaces/special chars
-    const typeOutput = await execRedisCommand(
-      redisCli,
-      port,
-      `TYPE "${key.replace(/"/g, '\\"')}"`,
-    )
-    const keyType = typeOutput.trim()
-
-    // Get TTL
-    const ttlOutput = await execRedisCommand(
-      redisCli,
-      port,
-      `TTL "${key.replace(/"/g, '\\"')}"`,
-    )
-    const ttl = parseInt(ttlOutput.trim(), 10)
-
-    // Quote the key for output commands
-    const quotedKey =
-      key.includes(' ') || /[*?[\]{}$`"'\\!<>|;&()]/.test(key)
-        ? `"${key.replace(/"/g, '\\"')}"`
-        : key
-
-    switch (keyType) {
-      case 'string': {
-        const value = await execRedisCommand(
-          redisCli,
-          port,
-          `GET "${key.replace(/"/g, '\\"')}"`,
-        )
-        commands.push(`SET ${quotedKey} ${escapeRedisValue(value.trim())}`)
-        break
-      }
-      case 'hash': {
-        const hashData = await execRedisCommand(
-          redisCli,
-          port,
-          `HGETALL "${key.replace(/"/g, '\\"')}"`,
-        )
-        const lines = hashData
-          .trim()
-          .split(/\r?\n/)
-          .map((l) => l.trim())
-          .filter((l) => l)
-        if (lines.length >= 2) {
-          const pairs: string[] = []
-          for (let i = 0; i < lines.length; i += 2) {
-            const field = lines[i].trim()
-            const value = lines[i + 1]?.trim() || ''
-            // Quote field if it contains special chars
-            const quotedField =
-              field.includes(' ') || /[*?[\]{}$`"'\\!<>|;&()]/.test(field)
-                ? `"${field.replace(/"/g, '\\"')}"`
-                : field
-            pairs.push(`${quotedField} ${escapeRedisValue(value)}`)
-          }
-          commands.push(`HSET ${quotedKey} ${pairs.join(' ')}`)
-        }
-        break
-      }
-      case 'list': {
-        const listData = await execRedisCommand(
-          redisCli,
-          port,
-          `LRANGE "${key.replace(/"/g, '\\"')}" 0 -1`,
-        )
-        const items = listData
-          .trim()
-          .split(/\r?\n/)
-          .map((l) => l.trim())
-          .filter((l) => l)
-        if (items.length > 0) {
-          const escapedItems = items.map((item) =>
-            escapeRedisValue(item.trim()),
-          )
-          commands.push(`RPUSH ${quotedKey} ${escapedItems.join(' ')}`)
-        }
-        break
-      }
-      case 'set': {
-        const setData = await execRedisCommand(
-          redisCli,
-          port,
-          `SMEMBERS "${key.replace(/"/g, '\\"')}"`,
-        )
-        const members = setData
-          .trim()
-          .split(/\r?\n/)
-          .map((l) => l.trim())
-          .filter((l) => l)
-        if (members.length > 0) {
-          const escapedMembers = members.map((m) => escapeRedisValue(m.trim()))
-          commands.push(`SADD ${quotedKey} ${escapedMembers.join(' ')}`)
-        }
-        break
-      }
-      case 'zset': {
-        const zsetData = await execRedisCommand(
-          redisCli,
-          port,
-          `ZRANGE "${key.replace(/"/g, '\\"')}" 0 -1 WITHSCORES`,
-        )
-        const lines = zsetData
-          .trim()
-          .split(/\r?\n/)
-          .map((l) => l.trim())
-          .filter((l) => l)
-        if (lines.length >= 2) {
-          const pairs: string[] = []
-          for (let i = 0; i < lines.length; i += 2) {
-            const member = lines[i].trim()
-            const score = lines[i + 1]?.trim() || '0'
-            pairs.push(`${score} ${escapeRedisValue(member)}`)
-          }
-          commands.push(`ZADD ${quotedKey} ${pairs.join(' ')}`)
-        }
-        break
-      }
-      default:
-        logWarning(`Skipping key ${key} with unsupported type: ${keyType}`)
-    }
-
-    // Add EXPIRE if key has TTL
-    if (ttl > 0) {
-      commands.push(`EXPIRE ${quotedKey} ${ttl}`)
-    }
-  }
-
-  // Ensure output directory exists
-  const outputDir = dirname(outputPath)
-  if (!existsSync(outputDir)) {
-    await mkdir(outputDir, { recursive: true })
-  }
-
-  // Write commands to file
-  const content = commands.join('\n') + '\n'
-  await writeFile(outputPath, content, 'utf-8')
-
-  const stats = await stat(outputPath)
-
-  return {
-    path: outputPath,
-    format: 'text',
-    size: stats.size,
-  }
-}
-
-/**
- * Create a backup using BGSAVE (RDB format)
- *
- * Redis backups are RDB files (binary snapshots).
- * The backup process:
- * 1. Trigger BGSAVE command
- * 2. Poll LASTSAVE until timestamp changes (backup complete)
- * 3. Copy dump.rdb to output path
- */
-async function createRdbBackup(
-  container: ContainerConfig,
-  outputPath: string,
-): Promise<BackupResult> {
-  const { port, name } = container
-
-  const redisCli = await getRedisCliPath()
-  if (!redisCli) {
-    throw new Error(REDIS_CLI_NOT_FOUND_ERROR)
-  }
-
-  // Trigger background save
-  let bgsaveResponse: string
-  try {
-    bgsaveResponse = await execRedisCommand(redisCli, port, 'BGSAVE')
-    bgsaveResponse = bgsaveResponse.trim()
-  } catch (error) {
-    const execError = error as Error
-    throw new Error(`BGSAVE command failed: ${execError.message}`)
-  }
-
-  logDebug(`BGSAVE response: ${bgsaveResponse}`)
-
-  // Check for Redis error responses in stdout
-  // Redis returns errors like "ERR ..." or "(error) ..." in stdout
-  if (
-    bgsaveResponse.startsWith('ERR') ||
-    bgsaveResponse.startsWith('(error)')
-  ) {
-    // Special case: if a save is already in progress, we can wait for it
-    if (bgsaveResponse.includes('Background save already in progress')) {
-      logDebug('BGSAVE already in progress, waiting for it to complete')
-    } else {
-      throw new Error(`BGSAVE failed: ${bgsaveResponse}`)
-    }
-  } else if (
-    !bgsaveResponse.includes('Background saving started') &&
-    !bgsaveResponse.includes('Background save already in progress')
-  ) {
-    // Unexpected response - warn but continue (might be a different Redis version)
-    logDebug(
-      `Unexpected BGSAVE response (continuing anyway): ${bgsaveResponse}`,
-    )
-  }
-
-  // Wait for save to complete by checking rdb_bgsave_in_progress
-  // This is more reliable than LASTSAVE timestamp which has 1-second resolution
-  const startTime = Date.now()
-  const timeout = 60000 // 1 minute timeout
-
-  while (Date.now() - startTime < timeout) {
-    const infoOutput = await execRedisCommand(
-      redisCli,
-      port,
-      'INFO persistence',
-    )
-
-    // Check if BGSAVE is still in progress
-    const inProgress = infoOutput.includes('rdb_bgsave_in_progress:1')
-    if (!inProgress) {
-      // Also check for errors
-      const statusMatch = infoOutput.match(/rdb_last_bgsave_status:(\w+)/)
-      const status = statusMatch?.[1]
-      if (status === 'err') {
-        throw new Error('BGSAVE failed. Check Redis logs for details.')
-      }
-      logDebug('BGSAVE completed successfully')
-      break
-    }
-
-    await new Promise((r) => setTimeout(r, 100))
-  }
-
-  if (Date.now() - startTime >= timeout) {
-    throw new Error('BGSAVE timed out after 60 seconds')
-  }
-
-  // Get the RDB file path from Redis data directory
-  const dataDir = paths.getContainerDataPath(name, { engine: 'redis' })
-  const rdbPath = join(dataDir, 'dump.rdb')
-
-  if (!existsSync(rdbPath)) {
-    throw new Error(
-      `RDB file not found at ${rdbPath} after BGSAVE. Check Redis configuration.`,
-    )
-  }
-
-  // Ensure output directory exists
-  const outputDir = dirname(outputPath)
-  if (!existsSync(outputDir)) {
-    await mkdir(outputDir, { recursive: true })
-  }
-
-  // Copy RDB file to output path
-  await copyFile(rdbPath, outputPath)
-
-  const stats = await stat(outputPath)
-
-  return {
-    path: outputPath,
-    format: 'rdb',
-    size: stats.size,
-  }
-}
-
-/**
- * Create a backup
- * Supports two formats:
- * - 'text': Human-readable Redis commands (.redis file)
- * - 'rdb' (default): Binary RDB snapshot
- */
-export async function createBackup(
-  container: ContainerConfig,
-  outputPath: string,
-  options: BackupOptions,
-): Promise<BackupResult> {
-  // 'text' format means text-based commands for Redis
-  if (options.format === 'text') {
-    return createTextBackup(container, outputPath)
-  }
-  // Default to RDB format
-  return createRdbBackup(container, outputPath)
-}
-
-/**
- * Create a backup for cloning purposes
- * Always uses RDB format for speed and reliability
- */
-export async function createCloneBackup(
-  container: ContainerConfig,
-  outputPath: string,
-): Promise<BackupResult> {
-  return createRdbBackup(container, outputPath)
-}

package/engines/redis/binary-manager.ts

@@ -1,44 +0,0 @@
-/**
- * Redis Binary Manager
- *
- * Handles downloading, extracting, and managing Redis binaries from hostdb.
- * Extends BaseBinaryManager for shared download/extraction logic.
- */
-
-import {
-  BaseBinaryManager,
-  type BinaryManagerConfig,
-} from '../../core/base-binary-manager'
-import { getBinaryUrl } from './binary-urls'
-import { normalizeVersion } from './version-maps'
-import { Engine, type Platform, type Arch } from '../../types'
-
-class RedisBinaryManager extends BaseBinaryManager {
-  protected readonly config: BinaryManagerConfig = {
-    engine: Engine.Redis,
-    engineName: 'redis',
-    displayName: 'Redis',
-    serverBinary: 'redis-server',
-  }
-
-  protected getBinaryUrlFromModule(
-    version: string,
-    platform: Platform,
-    arch: Arch,
-  ): string {
-    return getBinaryUrl(version, platform, arch)
-  }
-
-  protected normalizeVersionFromModule(version: string): string {
-    return normalizeVersion(version)
-  }
-
-  protected parseVersionFromOutput(stdout: string): string | null {
-    // Extract version from output like "Redis server v=7.4.7 sha=00000000:0 malloc=jemalloc-5.3.0 bits=64 build=..."
-    const match = stdout.match(/v=(\d+\.\d+\.\d+)/)
-    const altMatch = !match ? stdout.match(/(\d+\.\d+\.\d+)/) : null
-    return match?.[1] ?? altMatch?.[1] ?? null
-  }
-}
-
-export const redisBinaryManager = new RedisBinaryManager()

package/engines/redis/binary-urls.ts

@@ -1,117 +0,0 @@
-import { REDIS_VERSION_MAP } from './version-maps'
-import { buildHostdbUrl } from '../../core/hostdb-client'
-import { logDebug } from '../../core/error-handler'
-import { Engine, Platform, type Arch } from '../../types'
-
-/**
- * Supported platform identifiers for hostdb downloads.
- * hostdb uses standard Node.js platform naming - this set validates
- * that a platform/arch combination is supported, not transforms it.
- */
-const SUPPORTED_PLATFORMS = new Set([
-  'darwin-arm64',
-  'darwin-x64',
-  'linux-arm64',
-  'linux-x64',
-  'win32-x64',
-])
-
-/**
- * Get the hostdb platform identifier
- *
- * hostdb uses standard platform naming that matches Node.js identifiers directly.
- * This function validates the platform/arch combination is supported.
- *
- * @param platform - Node.js platform (e.g., 'darwin', 'linux', 'win32')
- * @param arch - Node.js architecture (e.g., 'arm64', 'x64')
- * @returns hostdb platform identifier or null if unsupported
- */
-export function getHostdbPlatform(
-  platform: Platform,
-  arch: Arch,
-): string | null {
-  const key = `${platform}-${arch}`
-  return SUPPORTED_PLATFORMS.has(key) ? key : null
-}
-
-/**
- * Build the download URL for Redis binaries from hostdb
- *
- * Format: https://registry.layerbase.host/redis-{version}/redis-{version}-{platform}-{arch}.{ext}
- *
- * @param version - Redis version (e.g., '7', '7.4.7')
- * @param platform - Platform identifier (e.g., 'darwin', 'linux', 'win32')
- * @param arch - Architecture identifier (e.g., 'arm64', 'x64')
- * @returns Download URL for the binary
- */
-export function getBinaryUrl(
-  version: string,
-  platform: Platform,
-  arch: Arch,
-): string {
-  const platformKey = `${platform}-${arch}`
-  const hostdbPlatform = getHostdbPlatform(platform, arch)
-  if (!hostdbPlatform) {
-    throw new Error(`Unsupported platform: ${platformKey}`)
-  }
-
-  // Normalize version (handles major version lookup and X.Y -> X.Y.Z conversion)
-  const fullVersion = normalizeVersion(version, REDIS_VERSION_MAP)
-  const ext = platform === Platform.Win32 ? 'zip' : 'tar.gz'
-
-  return buildHostdbUrl(Engine.Redis, {
-    version: fullVersion,
-    hostdbPlatform,
-    extension: ext,
-  })
-}
-
-/**
- * Normalize version string to X.Y.Z format
- *
- * Note: Redis does not use validateSemverLikeVersion() because:
- * 1. Redis uses a lenient approach - unknown versions log a warning and pass through
- * 2. This allows testing new versions before they're added to the version map
- * 3. Invalid versions will fail at download time with a clear 404 error
- *
- * @param version - Version string (e.g., '7', '7.4', '7.4.7')
- * @param versionMap - Optional version map for major version lookup
- * @returns Normalized version (e.g., '7.4.7')
- */
-function normalizeVersion(
-  version: string,
-  versionMap: Record<string, string> = REDIS_VERSION_MAP,
-): string {
-  // Check if it's an exact key in the map (handles "7", "8", "7.4", etc.)
-  if (versionMap[version]) {
-    return versionMap[version]
-  }
-
-  const parts = version.split('.')
-
-  // If it's already a full version (X.Y.Z), return as-is
-  if (parts.length === 3) {
-    return version
-  }
-
-  // For two-part versions (e.g., "7.4"), first try exact two-part key, then fall back to major
-  if (parts.length === 2) {
-    const twoPart = `${parts[0]}.${parts[1]}`
-    if (versionMap[twoPart]) {
-      return versionMap[twoPart]
-    }
-    // Fall back to major version for latest patch
-    const major = parts[0]
-    const mapped = versionMap[major]
-    if (mapped) {
-      return mapped
-    }
-  }
-
-  // Unknown version format - log and return as-is
-  // This may cause download failures if the version doesn't exist in hostdb
-  logDebug(
-    `Redis version '${version}' not in version map, may not be available in hostdb`,
-  )
-  return version
-}

package/engines/redis/cli-utils.ts

@@ -1,42 +0,0 @@
-/**
- * Shared Redis CLI utilities
- *
- * Provides common functions for locating Redis binaries,
- * used by both backup.ts and restore.ts to avoid duplication.
- */
-
-import { existsSync } from 'fs'
-import { configManager } from '../../core/config-manager'
-import { platformService } from '../../core/platform-service'
-
-/**
- * Get the path to redis-cli binary
- *
- * Lookup order:
- * 1. configManager cache (bundled/downloaded binaries from hostdb)
- * 2. System PATH (fallback for system-installed redis-tools)
- *
- * @returns Path to redis-cli or null if not found
- */
-export async function getRedisCliPath(): Promise<string | null> {
-  // Check if we have a cached/bundled redis-cli from hostdb
-  const cachedPath = await configManager.getBinaryPath('redis-cli')
-  if (cachedPath && existsSync(cachedPath)) {
-    return cachedPath
-  }
-
-  // Fallback to system PATH
-  return platformService.findToolPath('redis-cli')
-}
-
-/**
- * Error message for missing redis-cli
- * Directs users to download via hostdb (preferred) or system package manager (fallback)
- */
-export const REDIS_CLI_NOT_FOUND_ERROR =
-  'redis-cli not found. Download Redis binaries:\n' +
-  '  spindb engines download redis\n' +
-  '\n' +
-  'Or install system-wide:\n' +
-  '  macOS: brew install redis\n' +
-  '  Ubuntu: sudo apt install redis-tools'

package/engines/redis/hostdb-releases.ts

@@ -1,23 +0,0 @@
-/**
- * hostdb Releases Module for Redis
- *
- * Fetches Redis binary information from the hostdb repository at
- * https://github.com/robertjbass/hostdb
- */
-
-import { createHostdbReleases } from '../../core/hostdb-releases-factory'
-import { REDIS_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS } from './version-maps'
-import { redisBinaryManager } from './binary-manager'
-import { Engine } from '../../types'
-
-const hostdbReleases = createHostdbReleases({
-  engine: Engine.Redis,
-  displayName: 'Redis',
-  versionMap: REDIS_VERSION_MAP,
-  supportedMajorVersions: SUPPORTED_MAJOR_VERSIONS,
-  groupingStrategy: 'single-digit',
-  listInstalled: () => redisBinaryManager.listInstalled(),
-})
-
-export const fetchAvailableVersions = hostdbReleases.fetchAvailableVersions
-export const getLatestVersion = hostdbReleases.getLatestVersion