spindb 0.37.2 → 0.38.0

package/engines/valkey/restore.ts

@@ -1,446 +0,0 @@
-/**
- * Valkey restore module
- * Supports two backup formats:
- * - RDB: Binary snapshot (restored by copying to data dir)
- * - Text: Valkey commands (.valkey file, restored by piping to valkey-cli)
- */
-
-import { spawn } from 'child_process'
-import { copyFile, open } from 'fs/promises'
-import { existsSync, statSync, createReadStream } from 'fs'
-import { join } from 'path'
-import { paths } from '../../config/paths'
-import { logDebug } from '../../core/error-handler'
-import { getValkeyCliPath, VALKEY_CLI_NOT_FOUND_ERROR } from './cli-utils'
-import type { BackupFormat, RestoreResult } from '../../types'
-
-/**
- * Common Valkey commands used to detect text-based backup files
- * These are the commands typically found at the start of a Valkey command dump
- */
-const VALKEY_COMMANDS = [
-  'SET',
-  'GET',
-  'DEL',
-  'MSET',
-  'MGET',
-  'SETNX',
-  'SETEX',
-  'PSETEX',
-  'APPEND',
-  'HSET',
-  'HGET',
-  'HMSET',
-  'HDEL',
-  'HGETALL',
-  'HSETNX',
-  'LPUSH',
-  'RPUSH',
-  'LPOP',
-  'RPOP',
-  'LSET',
-  'LINSERT',
-  'LREM',
-  'SADD',
-  'SREM',
-  'SMEMBERS',
-  'SPOP',
-  'ZADD',
-  'ZREM',
-  'ZINCRBY',
-  'ZRANGE',
-  'EXPIRE',
-  'EXPIREAT',
-  'PEXPIRE',
-  'TTL',
-  'PERSIST',
-  'FLUSHDB',
-  'FLUSHALL',
-  'SELECT',
-  'PFADD',
-  'GEOADD',
-  'XADD',
-]
-
-/**
- * Check if file content looks like Valkey commands
- * Returns true if the first non-comment, non-empty lines start with valid Valkey commands
- * Only reads first 4KB to avoid loading large files into memory
- */
-async function looksLikeValkeyCommands(filePath: string): Promise<boolean> {
-  try {
-    // Read only first 4KB - enough for several lines of Valkey commands
-    const HEADER_SIZE = 4096
-    const buffer = Buffer.alloc(HEADER_SIZE)
-
-    const fd = await open(filePath, 'r')
-    let bytesRead: number
-    try {
-      const result = await fd.read(buffer, 0, HEADER_SIZE, 0)
-      bytesRead = result.bytesRead
-    } finally {
-      await fd.close()
-    }
-
-    const content = buffer.toString('utf-8', 0, bytesRead)
-    // Use /\r?\n/ to handle both Unix (\n) and Windows (\r\n) line endings
-    const lines = content.split(/\r?\n/)
-
-    let commandsFound = 0
-    const linesToCheck = 10 // Check first 10 non-empty, non-comment lines
-
-    for (const line of lines) {
-      const trimmed = line.trim()
-
-      // Skip empty lines and comments
-      if (!trimmed || trimmed.startsWith('#')) continue
-
-      // Get the first word (command)
-      const firstWord = trimmed.split(/\s+/)[0].toUpperCase()
-
-      if (VALKEY_COMMANDS.includes(firstWord)) {
-        commandsFound++
-        if (commandsFound >= 2) {
-          // Found at least 2 valid Valkey commands - likely a Valkey dump
-          return true
-        }
-      } else {
-        // Found a line that doesn't start with a Valkey command
-        // Could be binary data or different format
-        return false
-      }
-
-      if (commandsFound >= linesToCheck) break
-    }
-
-    // If we found at least one command and no invalid lines, treat as Valkey
-    return commandsFound > 0
-  } catch {
-    return false
-  }
-}
-
-/**
- * Detect backup format from file
- * Supports:
- * - RDB: Binary format starting with "REDIS" (Valkey uses same RDB format)
- * - Text: Valkey commands (detected by .valkey extension OR content analysis)
- */
-export async function detectBackupFormat(
-  filePath: string,
-): Promise<BackupFormat> {
-  if (!existsSync(filePath)) {
-    throw new Error(`Backup file not found: ${filePath}`)
-  }
-
-  const stats = statSync(filePath)
-
-  if (stats.isDirectory()) {
-    return {
-      format: 'unknown',
-      description: 'Directory found - Valkey uses single file backups',
-      restoreCommand:
-        'Valkey requires a single .rdb or .valkey file for restore',
-    }
-  }
-
-  // Check file extension first for .valkey text files
-  if (filePath.endsWith('.valkey')) {
-    return {
-      format: 'text',
-      description: 'Valkey text commands',
-      restoreCommand:
-        'Pipe commands to valkey-cli (spindb restore handles this)',
-    }
-  }
-
-  // Check file contents for RDB format (binary, starts with "REDIS")
-  // Note: Valkey uses the same RDB format as Redis for compatibility
-  try {
-    const buffer = Buffer.alloc(5)
-    const fd = await open(filePath, 'r')
-    try {
-      await fd.read(buffer, 0, 5, 0)
-      const header = buffer.toString('ascii')
-
-      if (header === 'REDIS') {
-        return {
-          format: 'rdb',
-          description: 'Valkey RDB snapshot',
-          restoreCommand:
-            'Copy to data directory and restart Valkey (spindb restore handles this)',
-        }
-      }
-    } finally {
-      await fd.close().catch(() => {})
-    }
-  } catch (error) {
-    logDebug(`Error reading backup file header: ${error}`)
-  }
-
-  // Check file extension as fallback for RDB
-  if (filePath.endsWith('.rdb')) {
-    return {
-      format: 'rdb',
-      description: 'Valkey RDB snapshot (detected by extension)',
-      restoreCommand:
-        'Copy to data directory and restart Valkey (spindb restore handles this)',
-    }
-  }
-
-  // Content-based detection: check if file contains Valkey commands
-  // This allows files like "users.txt" or "data" to be detected as Valkey text dumps
-  if (await looksLikeValkeyCommands(filePath)) {
-    return {
-      format: 'text',
-      description: 'Valkey text commands (detected by content)',
-      restoreCommand:
-        'Pipe commands to valkey-cli (spindb restore handles this)',
-    }
-  }
-
-  return {
-    format: 'unknown',
-    description: 'Unknown backup format',
-    restoreCommand: 'Use .rdb (RDB snapshot) or file with Valkey commands',
-  }
-}
-
-// Restore options for Valkey
-export type RestoreOptions = {
-  containerName: string
-  dataDir?: string
-  // Port for running Valkey instance (required for text restore)
-  port?: number
-  // Database number to restore to (default: 0)
-  database?: string
-  // Clear database before restoring (FLUSHDB)
-  flush?: boolean
-}
-
-/**
- * Restore from text backup (.valkey file)
- * Streams commands to valkey-cli on the running Valkey instance
- */
-async function restoreTextBackup(
-  backupPath: string,
-  port: number,
-  database: string,
-  flush: boolean = false,
-): Promise<RestoreResult> {
-  const valkeyCli = await getValkeyCliPath()
-  if (!valkeyCli) {
-    throw new Error(VALKEY_CLI_NOT_FOUND_ERROR)
-  }
-
-  return new Promise<RestoreResult>((resolve, reject) => {
-    const args = ['-h', '127.0.0.1', '-p', String(port), '-n', database]
-    const proc = spawn(valkeyCli, args, {
-      stdio: ['pipe', 'pipe', 'pipe'],
-    })
-
-    let stdout = ''
-    let stderr = ''
-    let streamError: Error | null = null
-
-    proc.stdout.on('data', (data) => {
-      stdout += data.toString()
-    })
-
-    proc.stderr.on('data', (data) => {
-      stderr += data.toString()
-    })
-
-    proc.on('close', (code) => {
-      // If there was a stream error, report it
-      if (streamError) {
-        reject(streamError)
-        return
-      }
-
-      if (code === 0) {
-        resolve({
-          format: 'text',
-          stdout: stdout || 'Valkey commands executed successfully',
-          stderr: stderr || undefined,
-          code: 0,
-        })
-      } else {
-        reject(
-          new Error(
-            `valkey-cli exited with code ${code}${stderr ? `: ${stderr}` : ''}`,
-          ),
-        )
-      }
-    })
-
-    proc.on('error', (error) => {
-      reject(new Error(`Failed to spawn valkey-cli: ${error.message}`))
-    })
-
-    // Prepend FLUSHDB if requested (clear database before restore)
-    if (flush) {
-      logDebug('Prepending FLUSHDB to clear database before restore')
-      proc.stdin.write('FLUSHDB\n')
-    }
-
-    // Stream backup file to valkey-cli stdin
-    const fileStream = createReadStream(backupPath, { encoding: 'utf-8' })
-
-    fileStream.on('error', (error) => {
-      streamError = new Error(`Failed to read backup file: ${error.message}`)
-      fileStream.destroy()
-      proc.stdin.end()
-    })
-
-    proc.stdin.on('error', (error) => {
-      // Handle stdin errors (e.g., process closed unexpectedly)
-      streamError = new Error(
-        `Failed to write to valkey-cli stdin: ${error.message}`,
-      )
-      fileStream.destroy()
-    })
-
-    fileStream.pipe(proc.stdin)
-  })
-}
-
-/**
- * Restore from RDB backup
- *
- * IMPORTANT: Valkey must be stopped before RDB restore.
- * The RDB file is copied to the data directory, then Valkey should be restarted.
- */
-async function restoreRdbBackup(
-  backupPath: string,
-  containerName: string,
-  dataDir?: string,
-): Promise<RestoreResult> {
-  const targetDir =
-    dataDir || paths.getContainerDataPath(containerName, { engine: 'valkey' })
-  const targetPath = join(targetDir, 'dump.rdb')
-
-  logDebug(`Restoring RDB to: ${targetPath}`)
-
-  // Copy backup to data directory
-  await copyFile(backupPath, targetPath)
-
-  return {
-    format: 'rdb',
-    stdout: `Restored RDB to ${targetPath}. Restart Valkey to load the data.`,
-    code: 0,
-  }
-}
-
-/**
- * Restore from backup
- * Supports:
- * - RDB: Copy to data directory (requires Valkey to be stopped)
- * - Text: Pipe commands to valkey-cli (requires Valkey to be running)
- */
-export async function restoreBackup(
-  backupPath: string,
-  options: RestoreOptions,
-): Promise<RestoreResult> {
-  const {
-    containerName,
-    dataDir,
-    port,
-    database = '0',
-    flush = false,
-  } = options
-
-  if (!existsSync(backupPath)) {
-    throw new Error(`Backup file not found: ${backupPath}`)
-  }
-
-  // Detect backup format
-  const format = await detectBackupFormat(backupPath)
-  logDebug(`Detected backup format: ${format.format}`)
-
-  if (format.format === 'text') {
-    // Text format - pipe to valkey-cli (Valkey must be running)
-    if (!port) {
-      throw new Error(
-        'Port is required for restoring .valkey text files. Valkey must be running.',
-      )
-    }
-    return restoreTextBackup(backupPath, port, database, flush)
-  }
-
-  if (format.format === 'rdb') {
-    // RDB format - copy to data directory (Valkey should be stopped)
-    // Note: RDB restore always replaces everything (full snapshot)
-    return restoreRdbBackup(backupPath, containerName, dataDir)
-  }
-
-  throw new Error(
-    `Invalid backup format: ${format.format}. Use .rdb (RDB snapshot) or .valkey (text commands).`,
-  )
-}
-
-/**
- * Parse Valkey connection string
- * Format: redis://[user:password@]host[:port][/database]
- * (Uses redis:// scheme for client compatibility)
- *
- * Valkey databases are numbered 0-15 (default is 0)
- */
-export function parseConnectionString(connectionString: string): {
-  host: string
-  port: number
-  database: string
-  password?: string
-} {
-  if (!connectionString || typeof connectionString !== 'string') {
-    throw new Error(
-      'Invalid Valkey connection string: expected a non-empty string',
-    )
-  }
-
-  let url: URL
-  try {
-    url = new URL(connectionString)
-  } catch (error) {
-    // Mask credentials in error message if present
-    const sanitized = connectionString.replace(
-      /\/\/([^:]+):([^@]+)@/,
-      '//***:***@',
-    )
-    throw new Error(
-      `Invalid Valkey connection string: "${sanitized}". ` +
-        `Expected format: redis://[password@]host[:port][/database]`,
-      { cause: error },
-    )
-  }
-
-  // Validate protocol - accept both redis:// and rediss:// for compatibility
-  if (url.protocol !== 'redis:' && url.protocol !== 'rediss:') {
-    throw new Error(
-      `Invalid Valkey connection string: unsupported protocol "${url.protocol}". ` +
-        `Expected "redis://" or "rediss://"`,
-    )
-  }
-
-  const host = url.hostname || '127.0.0.1'
-  const port = parseInt(url.port, 10) || 6379
-
-  // Database is in pathname (e.g., /0, /1, etc.)
-  const dbStr = url.pathname.replace(/^\//, '') || '0'
-  const dbNum = parseInt(dbStr, 10)
-
-  // Validate database number (0-15)
-  if (isNaN(dbNum) || dbNum < 0 || dbNum > 15) {
-    throw new Error(`Invalid Valkey database number: ${dbStr}. Must be 0-15.`)
-  }
-
-  // Valkey uses password only (no username), but URL might have username field
-  const password = url.password || url.username || undefined
-
-  return {
-    host,
-    port,
-    database: String(dbNum),
-    password,
-  }
-}

package/engines/valkey/version-maps.ts

@@ -1,81 +0,0 @@
-/**
- * Valkey Version Maps
- *
- * TEMPORARY: This version map will be replaced by the hostdb npm package once published.
- * Until then, manually keep this in sync with robertjbass/hostdb releases.json:
- * https://github.com/robertjbass/hostdb/blob/main/releases.json
- *
- * When updating versions:
- * 1. Check hostdb releases.json for available versions
- * 2. Update VALKEY_VERSION_MAP to match
- */
-
-import { logDebug } from '../../core/error-handler'
-
-/**
- * Map of major Valkey versions to their latest stable patch versions.
- * Must match versions available in hostdb releases.json.
- */
-export const VALKEY_VERSION_MAP: Record<string, string> = {
-  // 1-part: major version -> latest
-  '8': '8.0.6',
-  '9': '9.0.1',
-  // 2-part: major.minor -> latest patch
-  '8.0': '8.0.6',
-  '9.0': '9.0.1',
-  // 3-part: exact version (identity mapping)
-  '8.0.6': '8.0.6',
-  '9.0.1': '9.0.1',
-}
-
-/**
- * Supported major Valkey versions (1-part format).
- * Used for grouping and display purposes.
- */
-export const SUPPORTED_MAJOR_VERSIONS = ['8', '9']
-
-/**
- * Get the full version string for a major version.
- *
- * @param majorVersion - Major version (e.g., '8', '9')
- * @returns Full version string (e.g., '8.0.6') or null if not supported
- */
-export function getFullVersion(majorVersion: string): string | null {
-  return VALKEY_VERSION_MAP[majorVersion] || null
-}
-
-/**
- * Normalize a version string to X.Y.Z format.
- *
- * @param version - Version string (e.g., '8', '8.0', '8.0.6')
- * @returns Normalized version (e.g., '8.0.6')
- */
-export function normalizeVersion(version: string): string {
-  // If it's in the version map (major, major.minor, or full version), return the mapped value
-  // Note: Full versions have identity mappings (e.g., '8.0.6' => '8.0.6')
-  const fullVersion = VALKEY_VERSION_MAP[version]
-  if (fullVersion) {
-    return fullVersion
-  }
-
-  // Unknown version - warn and return as-is
-  // This may cause download failures if the version doesn't exist in hostdb
-  const parts = version.split('.')
-
-  // Validate format: must be 1-3 numeric segments (e.g., "8", "8.0", "8.0.6")
-  const isValidFormat =
-    parts.length >= 1 &&
-    parts.length <= 3 &&
-    parts.every((p) => /^\d+$/.test(p))
-
-  if (!isValidFormat) {
-    logDebug(
-      `Valkey version '${version}' has invalid format, may not be available in hostdb`,
-    )
-  } else {
-    logDebug(
-      `Valkey version '${version}' not in version map, may not be available in hostdb`,
-    )
-  }
-  return version
-}

package/engines/valkey/version-validator.ts

@@ -1,131 +0,0 @@
-/**
- * Valkey version validation utilities
- * Handles version parsing, comparison, and compatibility checking
- */
-
-/**
- * Parse a Valkey version string into components
- * Handles formats like "8.0.6", "8.0", "v8.0.6"
- */
-export function parseVersion(versionString: string): {
-  major: number
-  minor: number
-  patch: number
-  raw: string
-} | null {
-  const cleaned = versionString.replace(/^v/, '').trim()
-  const parts = cleaned.split('.')
-
-  if (parts.length < 1) return null
-
-  const major = parseInt(parts[0], 10)
-  const minor = parts[1] ? parseInt(parts[1], 10) : 0
-  const patch = parts[2] ? parseInt(parts[2], 10) : 0
-
-  if (isNaN(major)) return null
-  if (parts[1] && isNaN(minor)) return null
-  if (parts[2] && isNaN(patch)) return null
-
-  return { major, minor, patch, raw: cleaned }
-}
-
-/**
- * Check if a Valkey version is supported by SpinDB
- * Minimum supported version: 8.0.0
- * Supports Valkey 8 and 9
- */
-export function isVersionSupported(version: string): boolean {
-  const parsed = parseVersion(version)
-  if (!parsed) return false
-
-  return parsed.major >= 8
-}
-
-/**
- * Get major version from full version string
- * e.g., "8.0.6" -> "8"
- */
-export function getMajorVersion(version: string): string {
-  const parsed = parseVersion(version)
-  return parsed ? String(parsed.major) : version
-}
-
-/**
- * Get major.minor version from full version string
- * e.g., "8.0.6" -> "8.0"
- */
-export function getMajorMinorVersion(version: string): string {
-  const parsed = parseVersion(version)
-  if (!parsed) return version
-  return `${parsed.major}.${parsed.minor}`
-}
-
-/**
- * Compare two Valkey versions
- * Returns: -1 if a < b, 0 if a == b, 1 if a > b, null if either version cannot be parsed
- */
-export function compareVersions(a: string, b: string): number | null {
-  const parsedA = parseVersion(a)
-  const parsedB = parseVersion(b)
-
-  if (!parsedA || !parsedB) {
-    return null
-  }
-
-  if (parsedA.major !== parsedB.major) {
-    return parsedA.major < parsedB.major ? -1 : 1
-  }
-  if (parsedA.minor !== parsedB.minor) {
-    return parsedA.minor < parsedB.minor ? -1 : 1
-  }
-  if (parsedA.patch !== parsedB.patch) {
-    return parsedA.patch < parsedB.patch ? -1 : 1
-  }
-  return 0
-}
-
-/**
- * Check if a backup version is compatible with the restore version
- * Valkey RDB files are generally forward-compatible within major versions
- */
-export function isVersionCompatible(
-  backupVersion: string,
-  restoreVersion: string,
-): { compatible: boolean; warning?: string } {
-  const backup = parseVersion(backupVersion)
-  const restore = parseVersion(restoreVersion)
-
-  if (!backup || !restore) {
-    return {
-      compatible: true,
-      warning: 'Could not parse versions, proceeding with restore',
-    }
-  }
-
-  // Cannot restore newer RDB to older server
-  if (backup.major > restore.major) {
-    return {
-      compatible: false,
-      warning: `Cannot restore Valkey ${backupVersion} RDB backup to ${restoreVersion} server. The backup is from a newer major version.`,
-    }
-  }
-
-  // Allow same major version
-  if (backup.major === restore.major) {
-    return { compatible: true }
-  }
-
-  // Allow upgrading from older major version (restore.major > backup.major)
-  // This is the only remaining case since we've handled: !backup || !restore,
-  // backup.major > restore.major, and backup.major === restore.major
-  return {
-    compatible: true,
-    warning: `Restoring Valkey ${backupVersion} RDB backup to ${restoreVersion} server. Valkey will upgrade the RDB format on next save.`,
-  }
-}
-
-// Validate that a version string matches supported format
-export function isValidVersionFormat(version: string): boolean {
-  const parsed = parseVersion(version)
-  return parsed !== null
-}