spindb 0.37.2 → 0.38.0

package/engines/weaviate/restore.ts

@@ -1,235 +0,0 @@
-/**
- * Weaviate restore module
- * Supports snapshot-based restore using Weaviate's filesystem backup API.
- *
- * Restore flow:
- * 1. Copy backup directory into target container's BACKUP_FILESYSTEM_PATH/<id>/
- * 2. Start Weaviate (handled by caller)
- * 3. Trigger restore via POST /v1/backups/filesystem/<id>/restore
- */
-
-import { cp, copyFile, open, mkdir, readFile } 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 or directory.
- * Weaviate backups are directories containing backup metadata and class data.
- */
-export async function detectBackupFormat(
-  filePath: string,
-): Promise<BackupFormat> {
-  if (!existsSync(filePath)) {
-    throw new Error(`Backup file not found: ${filePath}`)
-  }
-
-  const stats = statSync(filePath)
-
-  // Weaviate filesystem backups are directories
-  if (stats.isDirectory()) {
-    // Check if it contains a backup_config.json (Weaviate backup marker)
-    const configPath = join(filePath, 'backup_config.json')
-    if (existsSync(configPath)) {
-      return {
-        format: 'snapshot',
-        description: 'Weaviate filesystem backup directory',
-        restoreCommand:
-          'Copy to backups directory and use Weaviate restore API (spindb restore handles this)',
-      }
-    }
-
-    return {
-      format: 'snapshot',
-      description: 'Weaviate backup directory',
-      restoreCommand:
-        'Copy to backups directory and use Weaviate restore API (spindb restore handles this)',
-    }
-  }
-
-  // Check file extension for .snapshot files
-  if (filePath.endsWith('.snapshot')) {
-    return {
-      format: 'snapshot',
-      description: 'Weaviate snapshot file',
-      restoreCommand:
-        'Copy to backups directory and use Weaviate 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: 'Weaviate snapshot file (detected by magic bytes)',
-          restoreCommand:
-            'Copy to backups directory and use Weaviate API (spindb restore handles this)',
-        }
-      }
-    } finally {
-      await fd.close().catch(() => {})
-    }
-  } catch (error) {
-    logDebug(`Error reading backup file header: ${error}`)
-  }
-
-  // Check for JSON backup metadata
-  if (filePath.endsWith('.json')) {
-    return {
-      format: 'snapshot',
-      description: 'Weaviate backup metadata file',
-      restoreCommand: 'Use Weaviate restore API (spindb restore handles this)',
-    }
-  }
-
-  return {
-    format: 'unknown',
-    description: 'Unknown backup format',
-    restoreCommand: 'Use a Weaviate backup directory for restore',
-  }
-}
-
-// Restore options for Weaviate
-export type RestoreOptions = {
-  containerName: string
-  dataDir?: string
-}
-
-/**
- * Restore from snapshot backup.
- *
- * Copies the backup directory into the target container's backups path.
- * The caller must then start Weaviate and trigger the restore via API.
- */
-export async function restoreBackup(
-  backupPath: string,
-  options: RestoreOptions,
-): Promise<RestoreResult> {
-  const { containerName, dataDir } = options
-
-  if (!existsSync(backupPath)) {
-    throw new Error(`Backup not found: ${backupPath}`)
-  }
-
-  // Detect backup format
-  const format = await detectBackupFormat(backupPath)
-  logDebug(`Detected backup format: ${format.format}`)
-
-  if (format.format !== 'snapshot') {
-    throw new Error(
-      `Invalid backup format: ${format.format}. Use a Weaviate backup directory for restore.`,
-    )
-  }
-
-  const targetDir =
-    dataDir || paths.getContainerDataPath(containerName, { engine: 'weaviate' })
-  const backupsDir = join(targetDir, 'backups')
-
-  // Read the real backup ID from backup_config.json inside the backup directory.
-  // Weaviate validates that the directory name matches the internal backup ID.
-  let backupId = basename(backupPath)
-  const stats = statSync(backupPath)
-  if (stats.isDirectory()) {
-    const configPath = join(backupPath, 'backup_config.json')
-    if (existsSync(configPath)) {
-      try {
-        const configData = JSON.parse(await readFile(configPath, 'utf-8')) as {
-          id?: string
-        }
-        if (configData.id) {
-          backupId = configData.id
-          logDebug(`Read backup ID from config: ${backupId}`)
-        }
-      } catch (error) {
-        logDebug(`Failed to read backup_config.json: ${error}`)
-      }
-    }
-  }
-
-  const targetPath = join(backupsDir, backupId)
-
-  logDebug(`Restoring backup to: ${targetPath}`)
-
-  // Ensure backups directory exists
-  if (!existsSync(backupsDir)) {
-    await mkdir(backupsDir, { recursive: true })
-  }
-
-  if (stats.isDirectory()) {
-    // Copy entire backup directory
-    await cp(backupPath, targetPath, { recursive: true })
-  } else {
-    // Single file - create directory and copy file into it
-    if (!existsSync(targetPath)) {
-      await mkdir(targetPath, { recursive: true })
-    }
-    await copyFile(backupPath, join(targetPath, basename(backupPath)))
-  }
-
-  return {
-    format: 'snapshot',
-    stdout:
-      `Restored backup to ${targetPath}.\n` +
-      `After starting Weaviate, restore via: POST /v1/backups/filesystem/${backupId}/restore`,
-    code: 0,
-  }
-}
-
-/**
- * Parse Weaviate connection string
- * Format: http://host[:port], https://host[:port]
- *
- * Weaviate uses classes/collections instead of traditional databases
- */
-export function parseConnectionString(connectionString: string): {
-  host: string
-  port: number
-  protocol: 'http' | 'https'
-} {
-  if (!connectionString || typeof connectionString !== 'string') {
-    throw new Error(
-      'Invalid Weaviate connection string: expected a non-empty string',
-    )
-  }
-
-  let url: URL
-  try {
-    url = new URL(connectionString)
-  } catch (error) {
-    throw new Error(
-      `Invalid Weaviate connection string: "${connectionString}". ` +
-        `Expected format: http://host[:port]`,
-      { cause: error },
-    )
-  }
-
-  // Validate protocol
-  let protocol: 'http' | 'https'
-  if (url.protocol === 'http:') {
-    protocol = 'http'
-  } else if (url.protocol === 'https:') {
-    protocol = 'https'
-  } else {
-    throw new Error(
-      `Invalid Weaviate connection string: unsupported protocol "${url.protocol}". ` +
-        `Expected "http://" or "https://"`,
-    )
-  }
-
-  const host = url.hostname || '127.0.0.1'
-  const port = parseInt(url.port, 10) || 8080
-
-  return {
-    host,
-    port,
-    protocol,
-  }
-}

package/engines/weaviate/version-maps.ts

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

package/engines/weaviate/version-validator.ts

@@ -1,128 +0,0 @@
-/**
- * Weaviate version validation utilities
- * Handles version parsing, comparison, and compatibility checking
- */
-
-/**
- * Parse a Weaviate version string into components
- * Handles formats like "1.35.7", "1.35", "v1.35.7"
- */
-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 Weaviate 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.35.7" -> "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.35.7" -> "1.35"
- */
-export function getMajorMinorVersion(version: string): string {
-  const parsed = parseVersion(version)
-  if (!parsed) return version
-  return `${parsed.major}.${parsed.minor}`
-}
-
-/**
- * Compare two Weaviate 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
- * Weaviate 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 Weaviate ${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 Weaviate ${backupVersion} snapshot to ${restoreVersion} server. Weaviate 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
-}