spindb 0.37.2 → 0.38.0

package/engines/mongodb/restore.ts

@@ -1,361 +0,0 @@
-/**
- * MongoDB restore module
- * Wraps mongorestore for restoring database backups
- */
-
-import { spawn, type SpawnOptions } from 'child_process'
-import { existsSync, readdirSync, statSync } from 'fs'
-import { open } from 'fs/promises'
-import { join } from 'path'
-import { logDebug, logWarning } from '../../core/error-handler'
-import { getMongorestorePath, MONGORESTORE_NOT_FOUND_ERROR } from './cli-utils'
-import type { BackupFormat, RestoreResult } from '../../types'
-
-// Detect the format of a MongoDB backup
-export async function detectBackupFormat(
-  filePath: string,
-): Promise<BackupFormat> {
-  if (!existsSync(filePath)) {
-    throw new Error(`Backup file not found: ${filePath}`)
-  }
-
-  const stats = statSync(filePath)
-
-  // Directory dump
-  if (stats.isDirectory()) {
-    return {
-      format: 'directory',
-      description: 'MongoDB directory dump (BSON files)',
-      restoreCommand: `mongorestore --host 127.0.0.1 --port PORT --db DATABASE ${filePath}`,
-    }
-  }
-
-  // Check file contents for archive format
-  try {
-    const buffer = Buffer.alloc(16)
-    const fd = await open(filePath, 'r')
-    let header: string
-    try {
-      await fd.read(buffer, 0, 16, 0)
-      header = buffer.toString('utf8', 0, 6)
-    } finally {
-      await fd.close().catch(() => {})
-    }
-
-    // Check for gzip magic number
-    if (buffer[0] === 0x1f && buffer[1] === 0x8b) {
-      return {
-        format: 'archive-gzip',
-        description: 'MongoDB archive (gzip compressed)',
-        restoreCommand: `mongorestore --host 127.0.0.1 --port PORT --db DATABASE --archive=${filePath} --gzip`,
-      }
-    }
-
-    // Check for uncompressed archive (starts with "mtools")
-    if (header === 'mtools' || header.includes('mongo')) {
-      return {
-        format: 'archive',
-        description: 'MongoDB archive (uncompressed)',
-        restoreCommand: `mongorestore --host 127.0.0.1 --port PORT --db DATABASE --archive=${filePath}`,
-      }
-    }
-
-    // Check for BSON file
-    if (filePath.endsWith('.bson')) {
-      return {
-        format: 'bson',
-        description: 'MongoDB BSON file',
-        restoreCommand: `mongorestore --host 127.0.0.1 --port PORT --db DATABASE ${filePath}`,
-      }
-    }
-
-    // Default to archive format
-    return {
-      format: 'unknown',
-      description: 'Unknown format - attempting as archive',
-      restoreCommand: `mongorestore --host 127.0.0.1 --port PORT --db DATABASE --archive=${filePath}`,
-    }
-  } catch {
-    return {
-      format: 'unknown',
-      description: 'Could not detect format',
-      restoreCommand: `mongorestore --host 127.0.0.1 --port PORT ${filePath}`,
-    }
-  }
-}
-
-// Restore options
-export type RestoreOptions = {
-  port: number
-  database: string
-  drop?: boolean // Drop existing data before restore
-  validateVersion?: boolean
-  sourceDatabase?: string // Original database name in the backup (for namespace remapping)
-  containerVersion?: string // Container's MongoDB version for version-matched lookup
-}
-
-/**
- * Add namespace remapping args for archive format restores.
- * Uses sourceDatabase if provided, otherwise uses $prefix$ placeholder.
- *
- * IMPORTANT: mongorestore uses $prefix$ and $suffix$ as special capture groups:
- * - $prefix$ captures the database name from the source namespace
- * - $suffix$ captures the collection name from the source namespace
- *
- * Do NOT use `*` instead of `$prefix$` - while `*` is a wildcard in some contexts,
- * mongorestore requires matching capture groups on both sides of the remap.
- * Using `*.*` on the left with `db.$suffix$` on the right fails with:
- * "Different number of asterisks in from and to"
- */
-function addNamespaceRemapArgs(
-  args: string[],
-  sourceDatabase: string | undefined,
-  targetDatabase: string,
-): void {
-  const nsFromDb = sourceDatabase ?? '$prefix$'
-  args.push(
-    `--nsFrom=${nsFromDb}.$suffix$`,
-    `--nsTo=${targetDatabase}.$suffix$`,
-  )
-}
-
-// Restore a MongoDB backup using mongorestore
-export async function restoreBackup(
-  backupPath: string,
-  options: RestoreOptions,
-): Promise<RestoreResult> {
-  const {
-    port,
-    database,
-    drop = true,
-    sourceDatabase,
-    containerVersion,
-  } = options
-
-  const mongorestore = await getMongorestorePath(containerVersion)
-  if (!mongorestore) {
-    throw new Error(MONGORESTORE_NOT_FOUND_ERROR)
-  }
-
-  // Detect backup format
-  const format = await detectBackupFormat(backupPath)
-  logDebug(`Detected backup format: ${format.format}`)
-
-  const args: string[] = ['--host', '127.0.0.1', '--port', String(port)]
-
-  if (drop) {
-    args.push('--drop')
-  }
-
-  // Handle different formats
-  // For directory format, --db works directly
-  // For archive format, we need namespace remapping since --db alone doesn't remap
-  const isArchiveFormat =
-    format.format === 'archive-gzip' ||
-    format.format === 'archive' ||
-    format.format === 'unknown'
-
-  if (!isArchiveFormat) {
-    // Directory and BSON formats: --db works directly
-    args.push('--db', database)
-  }
-
-  if (format.format === 'directory') {
-    // Directory dump - look for database subdirectory
-    // First try the target database name
-    const targetDbDir = join(backupPath, database)
-    if (existsSync(targetDbDir)) {
-      args.push(targetDbDir)
-    } else {
-      // For restores to a different database, find any database subdirectory
-      // (mongodump creates backupPath/{sourceDatabase}/)
-      const entries = readdirSync(backupPath, { withFileTypes: true })
-      const dbDirs = entries.filter((e) => e.isDirectory())
-
-      if (dbDirs.length === 1) {
-        // Single database directory - use it
-        const sourceDbDir = join(backupPath, dbDirs[0].name)
-        logDebug(`Using source database directory: ${sourceDbDir}`)
-        args.push(sourceDbDir)
-      } else if (dbDirs.length > 1) {
-        // Multiple directories - try to find one with BSON files
-        const dbWithBson = dbDirs.find((d) => {
-          const dirPath = join(backupPath, d.name)
-          const files = readdirSync(dirPath)
-          return files.some((f) => f.endsWith('.bson'))
-        })
-        if (dbWithBson) {
-          const sourceDbDir = join(backupPath, dbWithBson.name)
-          logDebug(
-            `Using source database directory with BSON files: ${sourceDbDir}`,
-          )
-          args.push(sourceDbDir)
-        } else {
-          args.push(backupPath)
-        }
-      } else {
-        // No subdirectories - use path directly
-        args.push(backupPath)
-      }
-    }
-  } else if (format.format === 'archive-gzip') {
-    args.push('--archive=' + backupPath, '--gzip')
-    addNamespaceRemapArgs(args, sourceDatabase, database)
-  } else if (format.format === 'archive') {
-    args.push('--archive=' + backupPath)
-    addNamespaceRemapArgs(args, sourceDatabase, database)
-  } else if (format.format === 'bson') {
-    // BSON files are passed directly without --archive flag
-    args.push(backupPath)
-  } else {
-    // Default to archive for unknown formats
-    args.push('--archive=' + backupPath, '--gzip')
-    addNamespaceRemapArgs(args, sourceDatabase, database)
-  }
-
-  logDebug(`Running mongorestore with args: ${args.join(' ')}`)
-
-  // Note: Don't use shell mode - spawn handles paths with spaces correctly
-  // when shell: false (the default). Shell mode breaks paths like "C:\Program Files\..."
-  const spawnOptions: SpawnOptions = {
-    stdio: ['pipe', 'pipe', 'pipe'],
-  }
-
-  return new Promise((resolve, reject) => {
-    const proc = spawn(mongorestore, args, spawnOptions)
-
-    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) {
-        resolve({
-          format: format.format,
-          stdout,
-          stderr,
-          code,
-        })
-      } else {
-        // mongorestore may exit with non-zero but still restore some data
-        if (
-          stderr.includes('continuing') ||
-          stderr.includes('documents restored')
-        ) {
-          logWarning(`mongorestore completed with warnings: ${stderr}`)
-          resolve({
-            format: format.format,
-            stdout,
-            stderr,
-            code: code ?? undefined,
-          })
-        } else {
-          reject(new Error(stderr || `mongorestore exited with code ${code}`))
-        }
-      }
-    })
-  })
-}
-
-/**
- * Parsed MongoDB connection string result
- * For SRV URIs, only `uri` and `database` are set (host/port resolved via DNS)
- * For standard URIs, host/port are parsed directly
- */
-export type ParsedConnectionString =
-  | {
-      isSrv: true
-      uri: string
-      database: string
-    }
-  | {
-      isSrv: false
-      host: string
-      port: string
-      database: string
-      user?: string
-      password?: string
-    }
-
-/**
- * Parse a MongoDB connection string
- *
- * Supported formats:
- * - mongodb://[user:password@]host[:port]/database
- * - mongodb+srv://[user:password@]host/database
- *
- * SRV URIs use DNS to resolve hosts/ports and must be passed as --uri to mongodump/mongorestore.
- *
- * Database name handling:
- * - Extracted from the URL pathname (e.g., "/mydb" → "mydb")
- * - Leading slash is stripped automatically
- * - If no database is specified (empty pathname or just "/"), defaults to "test"
- *   following MongoDB's convention for the default database name
- *
- * @param connectionString - MongoDB connection URI
- * @returns Parsed connection details with `isSrv` discriminator
- * @throws Error with descriptive message if:
- *   - Input is null, undefined, or not a string
- *   - URL is malformed (credentials are masked in error message)
- *   - Protocol is not "mongodb://" or "mongodb+srv://"
- */
-export function parseConnectionString(
-  connectionString: string,
-): ParsedConnectionString {
-  if (!connectionString || typeof connectionString !== 'string') {
-    throw new Error(
-      'Invalid MongoDB 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 MongoDB connection string: "${sanitized}". ` +
-        `Expected format: mongodb://[user:password@]host[:port]/database`,
-      { cause: error },
-    )
-  }
-
-  // Validate protocol
-  if (url.protocol !== 'mongodb:' && url.protocol !== 'mongodb+srv:') {
-    throw new Error(
-      `Invalid MongoDB connection string: unsupported protocol "${url.protocol}". ` +
-        `Expected "mongodb://" or "mongodb+srv://"`,
-    )
-  }
-
-  const database = url.pathname.replace(/^\//, '') || 'test'
-
-  // SRV URIs must be passed as-is via --uri (DNS resolves actual hosts/ports)
-  if (url.protocol === 'mongodb+srv:') {
-    return {
-      isSrv: true,
-      uri: connectionString,
-      database,
-    }
-  }
-
-  // Standard mongodb:// URIs can be parsed into host/port
-  const host = url.hostname || '127.0.0.1'
-  const port = url.port || '27017'
-  const user = url.username || undefined
-  const password = url.password || undefined
-
-  return { isSrv: false, host, port, database, user, password }
-}

package/engines/mongodb/version-maps.ts

@@ -1,91 +0,0 @@
-/**
- * MongoDB version mapping
- *
- * 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
- *
- * To update: Check releases.json, find databases.mongodb, copy all version strings.
- */
-
-import { logDebug } from '../../core/error-handler'
-
-/**
- * Map major versions to full versions
- * Keys are major.minor versions (e.g., "7.0", "8.0", "8.2")
- * Values are full versions from hostdb releases.json
- */
-export const MONGODB_VERSION_MAP: Record<string, string> = {
-  // 1-part: major version → LTS
-  '7': '7.0.28',
-  '8': '8.0.17',
-  // 2-part: major.minor → latest patch
-  '7.0': '7.0.28',
-  '8.0': '8.0.17',
-  '8.2': '8.2.3',
-  // 3-part: exact version (identity mapping)
-  '7.0.28': '7.0.28',
-  '8.0.17': '8.0.17',
-  '8.2.3': '8.2.3',
-}
-
-/**
- * Supported major MongoDB versions (2-part format).
- * Used for grouping and display purposes.
- */
-export const SUPPORTED_MAJOR_VERSIONS = ['7.0', '8.0', '8.2']
-
-/**
- * Fallback map of major versions to stable patch versions
- * Used when hostdb repository is unreachable
- */
-export const FALLBACK_VERSION_MAP: Record<string, string> = MONGODB_VERSION_MAP
-
-/**
- * Get the full version for a major version
- * @param majorVersion - Major version (e.g., "7.0", "8.0")
- * @returns Full version or null if not found
- */
-export function getFullVersion(majorVersion: string): string | null {
-  // Try exact match first
-  if (MONGODB_VERSION_MAP[majorVersion]) {
-    return MONGODB_VERSION_MAP[majorVersion]
-  }
-
-  // Try matching major only (e.g., "8" -> highest 8.x version)
-  const majorOnly = majorVersion.split('.')[0]
-  const matchingVersions = Object.entries(MONGODB_VERSION_MAP)
-    .filter(([key]) => key.split('.')[0] === majorOnly)
-    .sort(([a], [b]) => b.localeCompare(a, undefined, { numeric: true }))
-
-  if (matchingVersions.length > 0) {
-    return matchingVersions[0][1]
-  }
-
-  return null
-}
-
-/**
- * Normalize a version string to a full version
- * @param version - Version string (major, major.minor, or full)
- * @returns Full version string
- */
-export function normalizeVersion(version: string): string {
-  // If already a full version (x.y.z), return as-is
-  if (/^\d+\.\d+\.\d+$/.test(version)) {
-    return version
-  }
-
-  // Delegate to getFullVersion for major/major.minor lookup
-  const fullVersion = getFullVersion(version)
-  if (fullVersion) {
-    return fullVersion
-  }
-
-  // Unknown version format - log debug and return as-is
-  // This may cause download failures if the version doesn't exist in hostdb
-  logDebug(
-    `MongoDB version '${version}' not in version map, may not be available in hostdb`,
-  )
-  return version
-}

package/engines/mongodb/version-validator.ts

@@ -1,160 +0,0 @@
-// MongoDB version validation and compatibility checking
-
-import { existsSync, readdirSync } from 'fs'
-import { readFile } from 'fs/promises'
-import { join } from 'path'
-import { logDebug } from '../../core/error-handler'
-
-/**
- * Parse a version string into components
- * Handles formats like "8.0.4", "8.0", "v8.0.4"
- */
-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 < 2) return null
-
-  const major = parseInt(parts[0], 10)
-  const minor = parseInt(parts[1], 10)
-  const patch = parts[2] ? parseInt(parts[2], 10) : 0
-
-  if (isNaN(major) || isNaN(minor)) return null
-
-  return { major, minor, patch, raw: cleaned }
-}
-
-/**
- * Compare two 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
- * MongoDB allows restoring from older versions but not newer
- *
- * Compatible scenarios:
- * - Same major.minor version (e.g., 8.0.2 -> 8.0.4)
- * - One major version difference (e.g., 7.0.x -> 8.0.x)
- *
- * Incompatible:
- * - Restoring newer dump to older server
- * - More than one major version difference
- */
-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 dump to older server
-  if (backup.major > restore.major) {
-    return {
-      compatible: false,
-      warning: `Cannot restore MongoDB ${backupVersion} 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 one major version upgrade (e.g., 7.0 -> 8.0)
-  if (restore.major - backup.major === 1) {
-    return {
-      compatible: true,
-      warning: `Restoring MongoDB ${backupVersion} backup to ${restoreVersion} server. Consider running database upgrade procedures after restore.`,
-    }
-  }
-
-  // More than one major version difference
-  return {
-    compatible: false,
-    warning: `Cannot restore MongoDB ${backupVersion} backup to ${restoreVersion} server. The version difference is too large.`,
-  }
-}
-
-/**
- * Extract version from a mongodump directory
- * Mongodump creates a metadata.json file with version info
- */
-export async function extractVersionFromDump(
-  dumpPath: string,
-): Promise<string | null> {
-  try {
-    // Check if it's a directory dump
-    if (!existsSync(dumpPath)) {
-      return null
-    }
-
-    // Look for oplog.bson or any .metadata.json file
-    const files = readdirSync(dumpPath, { recursive: true }) as string[]
-
-    for (const file of files) {
-      if (file.endsWith('.metadata.json')) {
-        const metadataPath = join(dumpPath, file)
-        const content = await readFile(metadataPath, 'utf8')
-        const metadata = JSON.parse(content)
-
-        // Check for version in metadata
-        if (metadata.version) {
-          return metadata.version
-        }
-      }
-    }
-
-    return null
-  } catch (error) {
-    logDebug(`Failed to extract version from dump: ${error}`)
-    return null
-  }
-}
-
-/**
- * Get major.minor version from full version string
- * e.g., "8.0.4" -> "8.0"
- */
-export function getMajorMinorVersion(version: string): string {
-  const parsed = parseVersion(version)
-  if (!parsed) return version
-  return `${parsed.major}.${parsed.minor}`
-}
-
-// Validate that a version string matches supported format
-export function isValidVersionFormat(version: string): boolean {
-  const parsed = parseVersion(version)
-  return parsed !== null
-}