spindb 0.35.3 → 0.36.1

package/engines/weaviate/restore.ts

@@ -0,0 +1,235 @@
+/**
+ * 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

@@ -0,0 +1,78 @@
+/**
+ * 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

@@ -0,0 +1,128 @@
+/**
+ * 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
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.35.3",
+  "version": "0.36.1",
   "author": "Bob Bass <bob@bbass.co>",
   "license": "PolyForm-Noncommercial-1.0.0",
   "description": "Zero-config Docker-free local database containers. Create, backup, and clone a variety of popular databases.",
@@ -56,6 +56,7 @@
     "questdb",
     "typedb",
     "influxdb",
+    "weaviate",
     "layerbase",
     "docker-free",
     "tui",

package/types/index.ts

@@ -39,6 +39,7 @@ export enum Engine {
   QuestDB = 'questdb',
   TypeDB = 'typedb',
   InfluxDB = 'influxdb',
+  Weaviate = 'weaviate',
 }
 
 // Icon display mode for engine icons in CLI output
@@ -80,6 +81,7 @@ export const ALL_ENGINES = [
   Engine.QuestDB,
   Engine.TypeDB,
   Engine.InfluxDB,
+  Engine.Weaviate,
 ] as const
 
 // File-based engines (no server process, data stored in user project directories)
@@ -211,6 +213,7 @@ export type SurrealDBFormat = 'surql'
 export type QuestDBFormat = 'sql'
 export type TypeDBFormat = 'typeql'
 export type InfluxDBFormat = 'sql'
+export type WeaviateFormat = 'snapshot'
 
 // Query command types
 export type QueryResultRow = Record<string, unknown>
@@ -290,6 +293,7 @@ export type BackupFormatType =
   | QuestDBFormat
   | TypeDBFormat
   | InfluxDBFormat
+  | WeaviateFormat
 
 // Mapping from Engine to its corresponding backup format type
 type EngineFormatMap = {
@@ -311,6 +315,7 @@ type EngineFormatMap = {
   [Engine.QuestDB]: QuestDBFormat
   [Engine.TypeDB]: TypeDBFormat
   [Engine.InfluxDB]: InfluxDBFormat
+  [Engine.Weaviate]: WeaviateFormat
 }
 
 // Helper type to get format type for a specific engine
@@ -427,6 +432,8 @@ export type BinaryTool =
   | 'typedb_console_bin'
   // InfluxDB tools
   | 'influxdb3'
+  // Weaviate tools
+  | 'weaviate'
   // Web panels
   | 'pgweb'
   // TUI tools
@@ -523,6 +530,8 @@ export type SpinDBConfig = {
     typedb_console_bin?: BinaryConfig
     // InfluxDB tools
     influxdb3?: BinaryConfig
+    // Weaviate tools
+    weaviate?: BinaryConfig
     // Web panels
     pgweb?: BinaryConfig
     // TUI tools