spindb 0.37.2 → 0.38.0

package/engines/tigerbeetle/restore.ts

@@ -1,130 +0,0 @@
-/**
- * TigerBeetle restore module
- * Supports restoring from a TigerBeetle data file backup.
- *
- * Restore copies the backup data file into the container's data directory.
- * The server must be stopped before restore.
- */
-
-import { copyFile, mkdir, stat } from 'fs/promises'
-import { existsSync } from 'fs'
-import { join } from 'path'
-import { logDebug } from '../../core/error-handler'
-import type { BackupFormat, RestoreResult } from '../../types'
-
-/**
- * Detect backup format from a file path.
- * TigerBeetle backups are single binary data files.
- */
-export async function detectBackupFormat(
-  filePath: string,
-): Promise<BackupFormat> {
-  if (!existsSync(filePath)) {
-    throw new Error(`Backup file not found: ${filePath}`)
-  }
-
-  const stats = await stat(filePath)
-
-  // TigerBeetle data files are regular files (not directories)
-  if (stats.isFile()) {
-    if (filePath.endsWith('.tigerbeetle')) {
-      return {
-        format: 'binary',
-        description: 'TigerBeetle data file',
-        restoreCommand: 'Copy to data directory (spindb restore handles this)',
-      }
-    }
-
-    // Check for common backup naming patterns
-    return {
-      format: 'binary',
-      description: 'TigerBeetle data file (assumed from file)',
-      restoreCommand: 'Copy to data directory (spindb restore handles this)',
-    }
-  }
-
-  return {
-    format: 'unknown',
-    description: 'Unknown backup format',
-    restoreCommand: 'Use a TigerBeetle data file (.tigerbeetle) for restore',
-  }
-}
-
-// Restore options for TigerBeetle
-export type RestoreOptions = {
-  containerName: string
-  dataDir: string
-}
-
-/**
- * Restore from a TigerBeetle data file backup.
- * Copies the backup file into the container's data directory.
- */
-export async function restoreBackup(
-  backupPath: string,
-  options: RestoreOptions,
-): Promise<RestoreResult> {
-  const { dataDir } = options
-
-  if (!existsSync(backupPath)) {
-    throw new Error(`Backup not found: ${backupPath}`)
-  }
-
-  const format = await detectBackupFormat(backupPath)
-  logDebug(`Detected backup format: ${format.format}`)
-
-  // Ensure data directory exists
-  if (!existsSync(dataDir)) {
-    await mkdir(dataDir, { recursive: true })
-  }
-
-  const targetPath = join(dataDir, '0_0.tigerbeetle')
-
-  logDebug(`Restoring TigerBeetle data file to: ${targetPath}`)
-  await copyFile(backupPath, targetPath)
-
-  return {
-    format: 'binary',
-    stdout: `Restored TigerBeetle data file to ${targetPath}`,
-    code: 0,
-  }
-}
-
-/**
- * Parse TigerBeetle connection string
- * Format: host:port or 127.0.0.1:port
- *
- * TigerBeetle uses a custom binary protocol (no URI scheme).
- */
-export function parseConnectionString(connectionString: string): {
-  host: string
-  port: number
-} {
-  if (!connectionString || typeof connectionString !== 'string') {
-    throw new Error(
-      'Invalid TigerBeetle connection string: expected a non-empty string',
-    )
-  }
-
-  const trimmed = connectionString.trim()
-
-  // Parse host:port format
-  const parts = trimmed.split(':')
-  if (parts.length !== 2) {
-    throw new Error(
-      `Invalid TigerBeetle connection string: "${trimmed}". ` +
-        'Expected format: host:port (e.g., 127.0.0.1:3000)',
-    )
-  }
-
-  const host = parts[0] || '127.0.0.1'
-  const port = parseInt(parts[1], 10)
-
-  if (isNaN(port) || port <= 0 || port > 65535) {
-    throw new Error(
-      `Invalid TigerBeetle port: "${parts[1]}". Expected a number between 1 and 65535.`,
-    )
-  }
-
-  return { host, port }
-}

package/engines/tigerbeetle/version-validator.ts

@@ -1,126 +0,0 @@
-/**
- * TigerBeetle version validation utilities
- * Handles version parsing, comparison, and compatibility checking
- */
-
-/**
- * Parse a TigerBeetle version string into components
- * Handles formats like "0.16.70", "0.16", "v0.16.70"
- */
-export function parseVersion(versionString: string): {
-  major: number
-  minor: number
-  patch: number
-  raw: string
-} | null {
-  const cleaned = versionString.replace(/^v/, '').trim()
-  if (!cleaned) return null
-
-  const parts = cleaned.split('.')
-
-  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 TigerBeetle version is supported by SpinDB
- * Minimum supported version: 0.16.0
- */
-export function isVersionSupported(version: string): boolean {
-  const parsed = parseVersion(version)
-  if (!parsed) return false
-
-  // Support 0.16+
-  if (parsed.major === 0) {
-    return parsed.minor >= 16
-  }
-  return parsed.major >= 1
-}
-
-/**
- * Get major version from full version string (xy-format: 2-part)
- * e.g., "0.16.70" -> "0.16"
- */
-export function getMajorVersion(version: string): string {
-  const parsed = parseVersion(version)
-  if (!parsed) return version
-  return `${parsed.major}.${parsed.minor}`
-}
-
-/**
- * Get major.minor version from full version string.
- * Intentional alias for getMajorVersion — both return the 2-part xy-format
- * version (e.g., "0.16"). Kept as a separate export for API consistency
- * with other engine version validators.
- */
-export function getMajorMinorVersion(version: string): string {
-  return getMajorVersion(version)
-}
-
-/**
- * Compare two TigerBeetle 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
- * TigerBeetle data files are generally compatible within minor 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',
-    }
-  }
-
-  // Must be same major.minor for TigerBeetle
-  if (backup.major !== restore.major || backup.minor !== restore.minor) {
-    return {
-      compatible: false,
-      warning: `Cannot restore TigerBeetle ${backupVersion} data to ${restoreVersion} server. Major.minor versions must match.`,
-    }
-  }
-
-  return { compatible: true }
-}
-
-/**
- * Validate that a version string matches supported format
- */
-export function isValidVersionFormat(version: string): boolean {
-  const parsed = parseVersion(version)
-  return parsed !== null
-}

package/engines/typedb/backup.ts

@@ -1,167 +0,0 @@
-/**
- * TypeDB backup module
- *
- * TypeDB exports databases as two files: schema (.typeql) and data (.typeql).
- * We use the console's `database export` command which creates both files.
- */
-
-import { spawn } from 'child_process'
-import { mkdir } from 'fs/promises'
-import { stat } from 'fs/promises'
-import { dirname } from 'path'
-import { logDebug } from '../../core/error-handler'
-import { requireTypeDBConsolePath, getConsoleBaseArgs } from './cli-utils'
-import type { ContainerConfig, BackupOptions, BackupResult } from '../../types'
-
-/**
- * Create a TypeQL backup using typedb console export
- *
- * TypeDB export creates two files derived from outputPath:
- * - {base}-schema.typeql (schema definitions)
- * - {base}-data.typeql (data inserts)
- *
- * The returned BackupResult.path is the original outputPath (base path),
- * NOT a single backup file. Callers (e.g., restore) must derive the actual
- * file paths using the same `-schema.typeql` / `-data.typeql` convention.
- * See also: restore.ts restoreTypeQLBackup() which mirrors this derivation.
- */
-async function createTypeQLBackup(
-  container: ContainerConfig,
-  outputPath: string,
-  database: string,
-): Promise<BackupResult> {
-  const consolePath = await requireTypeDBConsolePath(container.version)
-  const { port } = container
-
-  // Ensure output directory exists
-  await mkdir(dirname(outputPath), { recursive: true })
-
-  // Derive schema and data paths from output path
-  const schemaPath = outputPath.endsWith('.typeql')
-    ? outputPath.replace(/\.typeql$/, '-schema.typeql')
-    : outputPath + '-schema.typeql'
-  const dataPath = outputPath.endsWith('.typeql')
-    ? outputPath.replace(/\.typeql$/, '-data.typeql')
-    : outputPath + '-data.typeql'
-
-  const args = [
-    ...getConsoleBaseArgs(port),
-    '--command',
-    `database export ${database} ${schemaPath} ${dataPath}`,
-  ]
-
-  const sanitizedArgs = args.map((a, i) =>
-    args[i - 1] === '--password' ? '***' : a,
-  )
-  logDebug(`Running: typedb_console_bin ${sanitizedArgs.join(' ')}`)
-
-  return new Promise<BackupResult>((resolve, reject) => {
-    const proc = spawn(consolePath, args, {
-      stdio: ['ignore', 'pipe', 'pipe'],
-    })
-
-    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', async (code) => {
-      if (code === 0) {
-        try {
-          // Calculate total size of both files (schema + data)
-          let schemaSize: number | null = null
-          let dataSize: number | null = null
-          const errors: string[] = []
-          try {
-            const schemaStats = await stat(schemaPath)
-            schemaSize = schemaStats.size
-          } catch (err) {
-            errors.push(`schema(${schemaPath}): ${err}`)
-          }
-          try {
-            const dataStats = await stat(dataPath)
-            dataSize = dataStats.size
-          } catch (err) {
-            errors.push(`data(${dataPath}): ${err}`)
-          }
-
-          if (
-            errors.length > 0 ||
-            schemaSize === null ||
-            dataSize === null ||
-            schemaSize === 0 ||
-            dataSize === 0
-          ) {
-            reject(
-              new Error(
-                `Backup produced empty or missing files: schema=${schemaPath}, data=${dataPath}` +
-                  (errors.length > 0
-                    ? `. Stat errors: ${errors.join('; ')}`
-                    : ''),
-              ),
-            )
-            return
-          }
-
-          // path is the base outputPath; actual files are schemaPath and dataPath
-          resolve({
-            path: outputPath,
-            format: 'typeql',
-            size: schemaSize + dataSize,
-          })
-        } catch (error) {
-          reject(new Error(`Backup files not created: ${error}`))
-        }
-      } else if (code === null) {
-        const detail = stderr || stdout
-        reject(
-          new Error(
-            `typedb console export was terminated by signal${detail ? `: ${detail}` : ''}`,
-          ),
-        )
-      } else {
-        const detail = stderr || stdout
-        reject(
-          new Error(
-            `typedb console export exited with code ${code}${detail ? `: ${detail}` : ''}`,
-          ),
-        )
-      }
-    })
-  })
-}
-
-/**
- * Create a backup
- *
- * @param container - Container configuration
- * @param outputPath - Path to write backup file
- * @param options - Backup options
- */
-export async function createBackup(
-  container: ContainerConfig,
-  outputPath: string,
-  options: BackupOptions,
-): Promise<BackupResult> {
-  const database = options.database || container.database
-
-  return createTypeQLBackup(container, outputPath, database)
-}
-
-/**
- * Create a backup for cloning purposes
- * Uses TypeQL format for reliability
- */
-export async function createCloneBackup(
-  container: ContainerConfig,
-  outputPath: string,
-): Promise<BackupResult> {
-  return createTypeQLBackup(container, outputPath, container.database)
-}

package/engines/typedb/binary-manager.ts

@@ -1,200 +0,0 @@
-/**
- * TypeDB Binary Manager
- *
- * Handles downloading, extracting, and managing TypeDB binaries from hostdb.
- * Extends BaseBinaryManager for shared download/extraction logic.
- *
- * TypeDB archives extract to a `typedb/` directory with nested structure:
- *   typedb/
- *   ├── typedb                  (launcher script)
- *   ├── server/
- *   │   ├── typedb_server_bin   (server binary)
- *   │   └── config.yml          (default config)
- *   ├── console/
- *   │   └── typedb_console_bin  (console binary)
- *   └── LICENSE
- *
- * We reorganize this preserving the relative structure the launcher expects:
- *   bin/
- *   ├── typedb                  (launcher)
- *   ├── server/
- *   │   └── typedb_server_bin   (server binary)
- *   ├── console/
- *   │   └── typedb_console_bin  (console binary)
- *   └── config.yml              (moved for reference)
- *   server/
- *   └── config.yml              (default config for reference)
- */
-
-import { existsSync } from 'fs'
-import { mkdir, readdir } from 'fs/promises'
-import { join } from 'path'
-import {
-  BaseBinaryManager,
-  type BinaryManagerConfig,
-} from '../../core/base-binary-manager'
-import { moveEntry } from '../../core/fs-error-utils'
-import { logDebug } from '../../core/error-handler'
-import { paths } from '../../config/paths'
-import { getBinaryUrl } from './binary-urls'
-import { normalizeVersion } from './version-maps'
-import { Engine, Platform, type Arch } from '../../types'
-
-class TypeDBBinaryManager extends BaseBinaryManager {
-  protected readonly config: BinaryManagerConfig = {
-    engine: Engine.TypeDB,
-    engineName: 'typedb',
-    displayName: 'TypeDB',
-    serverBinary: 'typedb',
-  }
-
-  protected getBinaryUrlFromModule(
-    version: string,
-    platform: Platform,
-    arch: Arch,
-  ): string {
-    return getBinaryUrl(version, platform, arch)
-  }
-
-  protected normalizeVersionFromModule(version: string): string {
-    return normalizeVersion(version)
-  }
-
-  protected parseVersionFromOutput(stdout: string): string | null {
-    // Try standard three-part semver (e.g., "3.8.0")
-    const threePartMatch = stdout.match(/(\d+\.\d+\.\d+)/)
-    if (threePartMatch) {
-      return threePartMatch[1]
-    }
-
-    // Fallback: two-part version (e.g., "3.8")
-    const twoPartMatch = stdout.match(/(\d+\.\d+)/)
-    if (twoPartMatch) {
-      logDebug(
-        `TypeDB version parsed as two-part: ${twoPartMatch[1]} (from: ${stdout.trim().slice(0, 100)})`,
-      )
-      return twoPartMatch[1]
-    }
-
-    logDebug(
-      `Could not parse TypeDB version from output: ${stdout.trim().slice(0, 100)}`,
-    )
-    return null
-  }
-
-  /**
-   * Override moveExtractedEntries to handle TypeDB's nested directory structure.
-   *
-   * TypeDB archives extract to: typedb/server/typedb_server_bin, typedb/console/typedb_console_bin
-   * We reorganize to: bin/typedb, bin/server/typedb_server_bin, bin/console/typedb_console_bin
-   * And preserve server/config.yml for reference.
-   */
-  protected async moveExtractedEntries(
-    extractDir: string,
-    binPath: string,
-  ): Promise<void> {
-    const entries = await readdir(extractDir, { withFileTypes: true })
-    const ext = process.platform === 'win32' ? '.exe' : ''
-    const batExt = process.platform === 'win32' ? '.bat' : ''
-
-    // Find the typedb directory (e.g., "typedb" or "typedb-3.8.0")
-    const typedbDir = entries.find(
-      (e) =>
-        e.isDirectory() &&
-        (e.name === 'typedb' || e.name.startsWith('typedb-')),
-    )
-
-    const sourceDir = typedbDir ? join(extractDir, typedbDir.name) : extractDir
-
-    // Create bin/ directory
-    const destBinDir = join(binPath, 'bin')
-    await mkdir(destBinDir, { recursive: true })
-
-    // Move launcher script to bin/
-    const launcherName = `typedb${batExt}`
-    const launcherPath = join(sourceDir, launcherName)
-    if (existsSync(launcherPath)) {
-      await moveEntry(launcherPath, join(destBinDir, launcherName))
-    }
-
-    // Move server/ directory into bin/ (preserves bin/server/typedb_server_bin path the launcher expects)
-    const destServerDir = join(destBinDir, 'server')
-    await mkdir(destServerDir, { recursive: true })
-    const serverBinName = `typedb_server_bin${ext}`
-    const serverBinPath = join(sourceDir, 'server', serverBinName)
-    if (existsSync(serverBinPath)) {
-      await moveEntry(serverBinPath, join(destServerDir, serverBinName))
-    }
-
-    // Move console/ directory into bin/ (preserves bin/console/typedb_console_bin path the launcher expects)
-    const destConsoleDir = join(destBinDir, 'console')
-    await mkdir(destConsoleDir, { recursive: true })
-    const consoleBinName = `typedb_console_bin${ext}`
-    const consoleBinPath = join(sourceDir, 'console', consoleBinName)
-    if (existsSync(consoleBinPath)) {
-      await moveEntry(consoleBinPath, join(destConsoleDir, consoleBinName))
-    }
-
-    // Preserve server/config.yml as reference config
-    const configPath = join(sourceDir, 'server', 'config.yml')
-    if (existsSync(configPath)) {
-      const destRefServerDir = join(binPath, 'server')
-      await mkdir(destRefServerDir, { recursive: true })
-      await moveEntry(configPath, join(destRefServerDir, 'config.yml'))
-    }
-
-    // Move LICENSE if present
-    const licensePath = join(sourceDir, 'LICENSE')
-    if (existsSync(licensePath)) {
-      await moveEntry(licensePath, join(binPath, 'LICENSE'))
-    }
-
-    logDebug('TypeDB binaries reorganized to standard bin/ layout')
-  }
-
-  /**
-   * Override verify to handle TypeDB's launcher script.
-   * TypeDB's main binary is a launcher script, not a direct executable.
-   * We verify the actual server binary exists instead of running --version.
-   */
-  async verify(
-    version: string,
-    platform: Platform,
-    arch: Arch,
-  ): Promise<boolean> {
-    const fullVersion = this.getFullVersion(version)
-    const binPath = paths.getBinaryPath({
-      engine: this.config.engineName,
-      version: fullVersion,
-      platform,
-      arch,
-    })
-
-    const ext = platform === Platform.Win32 ? '.exe' : ''
-    const batExt = platform === Platform.Win32 ? '.bat' : ''
-    const launcherPath = join(binPath, 'bin', `typedb${batExt}`)
-    const serverPath = join(binPath, 'bin', 'server', `typedb_server_bin${ext}`)
-    const consolePath = join(
-      binPath,
-      'bin',
-      'console',
-      `typedb_console_bin${ext}`,
-    )
-
-    if (!existsSync(launcherPath)) {
-      throw new Error(`TypeDB launcher not found at ${launcherPath}`)
-    }
-
-    if (!existsSync(serverPath)) {
-      throw new Error(`TypeDB server binary not found at ${serverPath}`)
-    }
-
-    if (!existsSync(consolePath)) {
-      throw new Error(`TypeDB console binary not found at ${consolePath}`)
-    }
-
-    return true
-  }
-}
-
-export const typedbBinaryManager = new TypeDBBinaryManager()

package/engines/typedb/binary-urls.ts

@@ -1,40 +0,0 @@
-/**
- * TypeDB binary URL generation
- *
- * Generates download URLs for TypeDB binaries from the layerbase registry.
- */
-
-import { type Platform, type Arch, Engine } from '../../types'
-import { normalizeVersion } from './version-maps'
-import { buildHostdbUrl } from '../../core/hostdb-client'
-
-/**
- * Get the binary download URL for a specific version and platform
- *
- * URL format: https://registry.layerbase.host/typedb-{version}/typedb-{version}-{platform}-{arch}.{ext}
- *
- * @param version - TypeDB version (e.g., '3.8.0' or '3')
- * @param platform - Target platform (darwin, linux, win32)
- * @param arch - Target architecture (x64, arm64)
- */
-export function getBinaryUrl(
-  version: string,
-  platform: Platform,
-  arch: Arch,
-): string {
-  const fullVersion = normalizeVersion(version)
-  const ext = getArchiveExtension(platform)
-
-  return buildHostdbUrl(Engine.TypeDB, {
-    version: fullVersion,
-    hostdbPlatform: `${platform}-${arch}`,
-    extension: ext,
-  })
-}
-
-/**
- * Get the archive extension for a platform
- */
-export function getArchiveExtension(platform: Platform): 'tar.gz' | 'zip' {
-  return platform === 'win32' ? 'zip' : 'tar.gz'
-}