spindb 0.37.2 → 0.38.0

package/engines/qdrant/restore.ts

@@ -1,203 +0,0 @@
-/**
- * Qdrant restore module
- * Supports snapshot-based restore using Qdrant's snapshot files
- */
-
-import { copyFile, open, mkdir, rm } from 'fs/promises'
-import { existsSync, statSync } from 'fs'
-import { join, basename } from 'path'
-import { paths } from '../../config/paths'
-import { logDebug } from '../../core/error-handler'
-import type { BackupFormat, RestoreResult } from '../../types'
-
-/**
- * Detect backup format from file
- * Qdrant uses snapshot files which are tar.gz archives
- */
-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 - Qdrant uses single snapshot files',
-      restoreCommand: 'Qdrant requires a single .snapshot file for restore',
-    }
-  }
-
-  // Check file extension for .snapshot files
-  if (filePath.endsWith('.snapshot')) {
-    return {
-      format: 'snapshot',
-      description: 'Qdrant snapshot file',
-      restoreCommand:
-        'Copy to snapshots directory and use Qdrant API (spindb restore handles this)',
-    }
-  }
-
-  // Check file contents for gzip magic bytes (snapshot files are compressed)
-  try {
-    const buffer = Buffer.alloc(4)
-    const fd = await open(filePath, 'r')
-    try {
-      await fd.read(buffer, 0, 4, 0)
-      // Gzip magic bytes: 1f 8b
-      if (buffer[0] === 0x1f && buffer[1] === 0x8b) {
-        return {
-          format: 'snapshot',
-          description: 'Qdrant snapshot file (detected by magic bytes)',
-          restoreCommand:
-            'Copy to snapshots directory and use Qdrant API (spindb restore handles this)',
-        }
-      }
-    } finally {
-      await fd.close().catch(() => {})
-    }
-  } catch (error) {
-    logDebug(`Error reading backup file header: ${error}`)
-  }
-
-  return {
-    format: 'unknown',
-    description: 'Unknown backup format',
-    restoreCommand: 'Use .snapshot file for restore',
-  }
-}
-
-// Restore options for Qdrant
-export type RestoreOptions = {
-  containerName: string
-  dataDir?: string
-}
-
-/**
- * Restore from snapshot backup
- *
- * IMPORTANT: Qdrant should be stopped before snapshot restore.
- * The snapshot file is copied to the snapshots directory, then Qdrant should be restarted.
- * On startup, Qdrant will automatically restore from the snapshot.
- */
-async function restoreSnapshotBackup(
-  backupPath: string,
-  containerName: string,
-  dataDir?: string,
-): Promise<RestoreResult> {
-  const targetDir =
-    dataDir || paths.getContainerDataPath(containerName, { engine: 'qdrant' })
-  const snapshotsDir = join(targetDir, 'snapshots')
-  const snapshotName = basename(backupPath)
-  const targetPath = join(snapshotsDir, snapshotName)
-
-  logDebug(`Restoring snapshot to: ${targetPath}`)
-
-  // Ensure snapshots directory exists
-  if (!existsSync(snapshotsDir)) {
-    await mkdir(snapshotsDir, { recursive: true })
-  }
-
-  // Copy backup to snapshots directory FIRST to ensure it succeeds
-  // before removing any existing data (prevents data loss if copy fails)
-  await copyFile(backupPath, targetPath)
-
-  // Remove existing collections after successful copy for clean restore
-  const collectionsDir = join(targetDir, 'collections')
-  if (existsSync(collectionsDir)) {
-    logDebug('Removing existing collections for clean restore')
-    await rm(collectionsDir, { recursive: true, force: true })
-  }
-
-  return {
-    format: 'snapshot',
-    stdout:
-      `Restored snapshot to ${targetPath}. Restart Qdrant to load the data.\n` +
-      `Use: POST http://127.0.0.1:PORT/snapshots/recover to trigger recovery.`,
-    code: 0,
-  }
-}
-
-/**
- * Restore from backup
- * Supports snapshot format only
- */
-export async function restoreBackup(
-  backupPath: string,
-  options: RestoreOptions,
-): Promise<RestoreResult> {
-  const { containerName, dataDir } = 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 === 'snapshot') {
-    return restoreSnapshotBackup(backupPath, containerName, dataDir)
-  }
-
-  throw new Error(
-    `Invalid backup format: ${format.format}. Use .snapshot file for restore.`,
-  )
-}
-
-/**
- * Parse Qdrant connection string
- * Format: http://host[:port], https://host[:port], or grpc://host[:port]
- *
- * Qdrant uses collections instead of traditional databases
- */
-export function parseConnectionString(connectionString: string): {
-  host: string
-  port: number
-  protocol: 'http' | 'https' | 'grpc'
-} {
-  if (!connectionString || typeof connectionString !== 'string') {
-    throw new Error(
-      'Invalid Qdrant connection string: expected a non-empty string',
-    )
-  }
-
-  let url: URL
-  try {
-    url = new URL(connectionString)
-  } catch (error) {
-    throw new Error(
-      `Invalid Qdrant connection string: "${connectionString}". ` +
-        `Expected format: http://host[:port] or grpc://host[:port]`,
-      { cause: error },
-    )
-  }
-
-  // Validate protocol
-  let protocol: 'http' | 'https' | 'grpc'
-  if (url.protocol === 'http:') {
-    protocol = 'http'
-  } else if (url.protocol === 'https:') {
-    protocol = 'https'
-  } else if (url.protocol === 'grpc:') {
-    protocol = 'grpc'
-  } else {
-    throw new Error(
-      `Invalid Qdrant connection string: unsupported protocol "${url.protocol}". ` +
-        `Expected "http://", "https://", or "grpc://"`,
-    )
-  }
-
-  const host = url.hostname || '127.0.0.1'
-  const defaultPort = protocol === 'grpc' ? 6334 : 6333
-  const port = parseInt(url.port, 10) || defaultPort
-
-  return {
-    host,
-    port,
-    protocol,
-  }
-}

package/engines/qdrant/version-maps.ts

@@ -1,78 +0,0 @@
-/**
- * Qdrant 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 QDRANT_VERSION_MAP to match
- */
-
-import { logDebug } from '../../core/error-handler'
-
-/**
- * Map of major Qdrant versions to their latest stable patch versions.
- * Must match versions available in hostdb releases.json.
- */
-export const QDRANT_VERSION_MAP: Record<string, string> = {
-  // 1-part: major version -> latest
-  '1': '1.16.3',
-  // 2-part: major.minor -> latest patch
-  '1.16': '1.16.3',
-  // 3-part: exact version (identity mapping)
-  '1.16.3': '1.16.3',
-}
-
-/**
- * Supported major Qdrant versions (1-part format).
- * Used for grouping and display purposes.
- */
-export const SUPPORTED_MAJOR_VERSIONS = ['1']
-
-/**
- * Get the full version string for a major version.
- *
- * @param majorVersion - Major version (e.g., '1')
- * @returns Full version string (e.g., '1.16.3') or null if not supported
- */
-export function getFullVersion(majorVersion: string): string | null {
-  return QDRANT_VERSION_MAP[majorVersion] || null
-}
-
-/**
- * Normalize a version string to X.Y.Z format.
- *
- * @param version - Version string (e.g., '1', '1.16', '1.16.3')
- * @returns Normalized version (e.g., '1.16.3')
- */
-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., '1.16.3' => '1.16.3')
-  const fullVersion = QDRANT_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., "1", "1.16", "1.16.3")
-  const isValidFormat =
-    parts.length >= 1 &&
-    parts.length <= 3 &&
-    parts.every((p) => /^\d+$/.test(p))
-
-  if (!isValidFormat) {
-    logDebug(
-      `Qdrant version '${version}' has invalid format, may not be available in hostdb`,
-    )
-  } else {
-    logDebug(
-      `Qdrant version '${version}' not in version map, may not be available in hostdb`,
-    )
-  }
-  return version
-}

package/engines/qdrant/version-validator.ts

@@ -1,128 +0,0 @@
-/**
- * Qdrant version validation utilities
- * Handles version parsing, comparison, and compatibility checking
- */
-
-/**
- * Parse a Qdrant version string into components
- * Handles formats like "1.16.3", "1.16", "v1.16.3"
- */
-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 Qdrant version is supported by SpinDB
- * Minimum supported version: 1.0.0
- */
-export function isVersionSupported(version: string): boolean {
-  const parsed = parseVersion(version)
-  if (!parsed) return false
-
-  return parsed.major >= 1
-}
-
-/**
- * Get major version from full version string
- * e.g., "1.16.3" -> "1"
- */
-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., "1.16.3" -> "1.16"
- */
-export function getMajorMinorVersion(version: string): string {
-  const parsed = parseVersion(version)
-  if (!parsed) return version
-  return `${parsed.major}.${parsed.minor}`
-}
-
-/**
- * Compare two Qdrant 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
- * Qdrant snapshots 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 snapshot to older server
-  if (backup.major > restore.major) {
-    return {
-      compatible: false,
-      warning: `Cannot restore Qdrant ${backupVersion} snapshot 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)
-  return {
-    compatible: true,
-    warning: `Restoring Qdrant ${backupVersion} snapshot to ${restoreVersion} server. Qdrant will upgrade the snapshot 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
-}