spindb 0.37.2 → 0.38.0

package/engines/surrealdb/restore.ts

@@ -1,302 +0,0 @@
-/**
- * SurrealDB restore module
- * Supports SurrealQL-based restores using surreal import
- */
-
-import { spawn } from 'child_process'
-import { open } from 'fs/promises'
-import { existsSync, statSync } from 'fs'
-import { logDebug } from '../../core/error-handler'
-import { requireSurrealPath } from './cli-utils'
-import type { BackupFormat, RestoreResult } from '../../types'
-
-/**
- * SurrealQL keywords that indicate a SurrealDB backup
- */
-const SURREALQL_KEYWORDS = [
-  'DEFINE',
-  'CREATE',
-  'INSERT',
-  'UPDATE',
-  'SELECT',
-  'DELETE',
-  'RELATE',
-  'LET',
-  'BEGIN',
-  'COMMIT',
-  'USE NS',
-  'USE DB',
-  'OPTION IMPORT',
-]
-
-/**
- * Check if file content looks like SurrealQL
- * Only reads first 8KB to avoid loading large files into memory
- */
-async function looksLikeSurql(filePath: string): Promise<boolean> {
-  try {
-    const HEADER_SIZE = 8192
-    const buffer = Buffer.alloc(HEADER_SIZE)
-
-    const fd = await open(filePath, 'r')
-    let bytesRead: number
-    try {
-      const result = await fd.read(buffer, 0, HEADER_SIZE, 0)
-      bytesRead = result.bytesRead
-    } finally {
-      await fd.close()
-    }
-
-    const content = buffer.toString('utf-8', 0, bytesRead)
-    const lines = content.split(/\r?\n/)
-
-    let surqlStatementsFound = 0
-    const linesToCheck = 20
-    let checkedLines = 0
-
-    for (const line of lines) {
-      if (checkedLines >= linesToCheck) break
-
-      const trimmed = line.trim().toUpperCase()
-
-      // Skip empty lines and comments
-      if (!trimmed || trimmed.startsWith('--') || trimmed.startsWith('#'))
-        continue
-
-      checkedLines++
-
-      // Check for SurrealQL keywords
-      for (const keyword of SURREALQL_KEYWORDS) {
-        if (trimmed.startsWith(keyword)) {
-          surqlStatementsFound++
-          break
-        }
-      }
-
-      if (surqlStatementsFound >= 2) {
-        return true
-      }
-    }
-
-    return surqlStatementsFound > 0
-  } catch {
-    return false
-  }
-}
-
-/**
- * Detect backup format from file
- * Supports:
- * - SurrealQL: Schema + data statements
- */
-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 - SurrealDB restore expects a single file',
-      restoreCommand: 'SurrealDB requires a single .surql file for restore',
-    }
-  }
-
-  // Check file extension first for .surql files
-  if (filePath.endsWith('.surql')) {
-    return {
-      format: 'surql',
-      description: 'SurrealDB SurrealQL backup',
-      restoreCommand:
-        'Execute SurrealQL statements via surreal import (spindb restore handles this)',
-    }
-  }
-
-  // Content-based detection
-  if (await looksLikeSurql(filePath)) {
-    return {
-      format: 'surql',
-      description: 'SurrealDB SurrealQL backup (detected by content)',
-      restoreCommand:
-        'Execute SurrealQL statements via surreal import (spindb restore handles this)',
-    }
-  }
-
-  return {
-    format: 'unknown',
-    description: 'Unknown backup format',
-    restoreCommand: 'Use .surql file with SurrealQL statements',
-  }
-}
-
-// Restore options for SurrealDB
-export type RestoreOptions = {
-  containerName: string
-  port: number
-  database?: string
-  version?: string
-}
-
-/**
- * Restore from SurrealQL backup using surreal import
- */
-async function restoreSurqlBackup(
-  backupPath: string,
-  port: number,
-  namespace: string,
-  database: string,
-  version?: string,
-): Promise<RestoreResult> {
-  const surrealPath = await requireSurrealPath(version)
-
-  return new Promise<RestoreResult>((resolve, reject) => {
-    const args = [
-      'import',
-      '--endpoint',
-      `http://127.0.0.1:${port}`,
-      '--user',
-      'root',
-      '--pass',
-      'root',
-      '--ns',
-      namespace,
-      '--db',
-      database,
-      backupPath,
-    ]
-
-    logDebug(`Running: surreal ${args.join(' ')}`)
-
-    const proc = spawn(surrealPath, 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('close', (code) => {
-      if (code === 0) {
-        resolve({
-          format: 'surql',
-          stdout: stdout || 'SurrealQL statements imported successfully',
-          stderr: stderr || undefined,
-          code: 0,
-        })
-      } else {
-        reject(
-          new Error(
-            `surreal import exited with code ${code}${stderr ? `: ${stderr}` : ''}`,
-          ),
-        )
-      }
-    })
-
-    proc.on('error', (error) => {
-      reject(new Error(`Failed to spawn surreal import: ${error.message}`))
-    })
-  })
-}
-
-/**
- * Restore from backup
- * Supports:
- * - SurrealQL: Execute statements via surreal import
- */
-export async function restoreBackup(
-  backupPath: string,
-  options: RestoreOptions,
-): Promise<RestoreResult> {
-  const { containerName, port, database = 'default', version } = options
-  // Use container name as namespace (convert dashes to underscores)
-  const namespace = containerName.replace(/-/g, '_')
-
-  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 === 'surql') {
-    return restoreSurqlBackup(backupPath, port, namespace, database, version)
-  }
-
-  throw new Error(
-    `Invalid backup format: ${format.format}. Use .surql file with SurrealQL statements.`,
-  )
-}
-
-/**
- * Parse SurrealDB connection string
- * Format: surrealdb://[user:password@]host[:port][/namespace/database]
- * Or: ws://host:port or http://host:port
- */
-export function parseConnectionString(connectionString: string): {
-  host: string
-  port: number
-  namespace: string
-  database: string
-  user?: string
-  password?: string
-} {
-  if (!connectionString || typeof connectionString !== 'string') {
-    throw new Error(
-      'Invalid SurrealDB 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 SurrealDB connection string: "${sanitized}". ` +
-        `Expected format: surrealdb://[user:password@]host[:port][/namespace/database]`,
-      { cause: error },
-    )
-  }
-
-  // Validate protocol
-  const validProtocols = ['surrealdb:', 'ws:', 'wss:', 'http:', 'https:']
-  if (!validProtocols.includes(url.protocol)) {
-    throw new Error(
-      `Invalid SurrealDB connection string: unsupported protocol "${url.protocol}". ` +
-        `Expected one of: ${validProtocols.join(', ')}`,
-    )
-  }
-
-  const host = url.hostname || '127.0.0.1'
-  const port = parseInt(url.port, 10) || 8000
-
-  // Parse namespace/database from pathname (e.g., /myns/mydb)
-  const pathParts = url.pathname.split('/').filter(Boolean)
-  const namespace = pathParts[0] || 'test'
-  const database = pathParts[1] || 'test'
-
-  return {
-    host,
-    port,
-    namespace,
-    database,
-    user: url.username || undefined,
-    password: url.password || undefined,
-  }
-}

package/engines/surrealdb/version-maps.ts

@@ -1,41 +0,0 @@
-/**
- * SurrealDB version mapping
- *
- * Maps short version aliases to full versions from hostdb releases.
- * MUST stay in sync with hostdb databases.json
- */
-
-// Full version map for SurrealDB
-export const SURREALDB_VERSION_MAP: Record<string, string> = {
-  '2': '2.3.2',
-  '2.3': '2.3.2',
-  '2.3.2': '2.3.2',
-}
-
-// Supported major versions (for CLI display)
-export const SUPPORTED_MAJOR_VERSIONS = ['2']
-
-// Default version
-export const DEFAULT_VERSION = '2'
-
-/**
- * Normalize a version string to its full version
- * e.g., '2' -> '2.3.2', '2.3' -> '2.3.2'
- */
-export function normalizeVersion(version: string): string {
-  return SURREALDB_VERSION_MAP[version] || version
-}
-
-/**
- * Check if a version is supported
- */
-export function isVersionSupported(version: string): boolean {
-  return version in SURREALDB_VERSION_MAP
-}
-
-/**
- * Get the latest patch version for a major version
- */
-export function getLatestPatch(majorVersion: string): string | undefined {
-  return SURREALDB_VERSION_MAP[majorVersion]
-}

package/engines/tigerbeetle/README.md

@@ -1,61 +0,0 @@
-# TigerBeetle Engine
-
-TigerBeetle is a high-performance financial ledger database written in Zig,
-designed for mission-critical safety and performance.
-
-## Platform Support
-
-All 5 platforms:
-- darwin-arm64
-- darwin-x64
-- linux-arm64
-- linux-x64
-- win32-x64
-
-## Binary Structure
-
-Single binary: `tigerbeetle` (handles both server and REPL client)
-
-## Two-Step Initialization
-
-TigerBeetle requires a format step before starting:
-
-1. **Format**: `tigerbeetle format --cluster=0 --replica=0 --replica-count=1 --development <data-file>`
-2. **Start**: `tigerbeetle start --addresses=127.0.0.1:<port> --development <data-file>`
-
-The `--development` flag is always passed since SpinDB is a local dev tool
-(relaxes Direct I/O requirements).
-
-## REPL Usage
-
-Connect to a running instance:
-```bash
-tigerbeetle repl --cluster=0 --addresses=127.0.0.1:<port>
-```
-
-## Version Grouping
-
-Uses xy-format: `0.16.70` groups as `0.16` (like MariaDB/ClickHouse).
-
-## Backup/Restore
-
-Stop-and-copy of the single `0_0.tigerbeetle` data file.
-The server must be stopped before backup (the file is exclusively locked).
-TigerBeetle is designed for abrupt shutdown (SIGTERM/SIGKILL are safe).
-
-## Key Characteristics
-
-- **Protocol**: Custom binary protocol (not REST, not SQL)
-- **Auth**: None
-- **Multi-database**: No (single ledger per instance)
-- **Health check**: TCP port check + PID (no HTTP endpoint)
-- **License**: Apache-2.0
-- **Default port**: 3000
-
-## Linux / Docker Note
-
-TigerBeetle uses `io_uring` for I/O on Linux. This works on regular Linux systems
-(bare metal, VMs, GitHub Actions runners) but Docker's default seccomp profile blocks
-`io_uring_*` syscalls. When running TigerBeetle inside Docker, the container must be
-started with `--security-opt seccomp=unconfined`. The `pnpm test:docker` wrapper
-handles this automatically. This does not affect macOS or Windows.

package/engines/tigerbeetle/backup.ts

@@ -1,49 +0,0 @@
-/**
- * TigerBeetle backup module
- * Supports stop-and-copy backup of the single data file.
- *
- * TigerBeetle stores all data in a single file (e.g., 0_0.tigerbeetle).
- * Backup requires the server to be stopped first since the data file
- * is exclusively locked by the running process.
- */
-
-import { copyFile, mkdir, stat } from 'fs/promises'
-import { existsSync } from 'fs'
-import { dirname, join } from 'path'
-import { logDebug } from '../../core/error-handler'
-import type { BackupOptions, BackupResult } from '../../types'
-
-/**
- * Create a backup by copying the TigerBeetle data file.
- * The server MUST be stopped before calling this function.
- */
-export async function createBackup(
-  dataDir: string,
-  outputPath: string,
-  _options: BackupOptions,
-): Promise<BackupResult> {
-  const dataFile = join(dataDir, '0_0.tigerbeetle')
-
-  if (!existsSync(dataFile)) {
-    throw new Error(
-      `TigerBeetle data file not found at ${dataFile}. Has the database been initialized?`,
-    )
-  }
-
-  // Ensure output parent directory exists
-  const outputDir = dirname(outputPath)
-  if (!existsSync(outputDir)) {
-    await mkdir(outputDir, { recursive: true })
-  }
-
-  logDebug(`Copying TigerBeetle data file to ${outputPath}`)
-  await copyFile(dataFile, outputPath)
-
-  const stats = await stat(outputPath)
-
-  return {
-    path: outputPath,
-    format: 'binary',
-    size: stats.size,
-  }
-}

package/engines/tigerbeetle/binary-manager.ts

@@ -1,95 +0,0 @@
-/**
- * TigerBeetle Binary Manager
- *
- * Handles downloading, extracting, and managing TigerBeetle binaries from hostdb.
- * Extends BaseBinaryManager for shared download/extraction logic.
- *
- * Note: TigerBeetle uses `tigerbeetle version` (subcommand, not --version flag).
- * We override verify() to use the correct invocation.
- */
-
-import { existsSync } from 'fs'
-import { join } from 'path'
-import {
-  BaseBinaryManager,
-  type BinaryManagerConfig,
-} from '../../core/base-binary-manager'
-import { spawnAsync } from '../../core/spawn-utils'
-import { getBinaryUrl } from './binary-urls'
-import { normalizeVersion } from './version-maps'
-import { Engine, Platform, type Arch } from '../../types'
-import { paths } from '../../config/paths'
-import { logDebug } from '../../core/error-handler'
-
-class TigerBeetleBinaryManager extends BaseBinaryManager {
-  protected readonly config: BinaryManagerConfig = {
-    engine: Engine.TigerBeetle,
-    engineName: 'tigerbeetle',
-    displayName: 'TigerBeetle',
-    serverBinary: 'tigerbeetle',
-  }
-
-  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 {
-    // TigerBeetle outputs: "TigerBeetle v0.16.70" or similar
-    const match = stdout.match(/(?:TigerBeetle\s+)?v?(\d+\.\d+\.\d+)/)
-    return match?.[1] ?? null
-  }
-
-  /**
-   * Override verify to use `tigerbeetle version` subcommand instead of `--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 serverPath = join(binPath, 'bin', `${this.config.serverBinary}${ext}`)
-
-    if (!existsSync(serverPath)) {
-      throw new Error(
-        `${this.config.displayName} binary not found at ${binPath}/bin/`,
-      )
-    }
-
-    // TigerBeetle uses `tigerbeetle version` subcommand (not --version)
-    try {
-      const { stdout } = await spawnAsync(serverPath, ['version'], {
-        timeout: 10000,
-      })
-      const parsedVersion = this.parseVersionFromOutput(stdout)
-      if (parsedVersion) {
-        logDebug(
-          `TigerBeetle binary verified: ${parsedVersion} at ${serverPath}`,
-        )
-      }
-      return true
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : String(error)
-      logDebug(`TigerBeetle version check failed for ${serverPath}: ${msg}`)
-      return false
-    }
-  }
-}
-
-export const tigerbeetleBinaryManager = new TigerBeetleBinaryManager()

package/engines/tigerbeetle/binary-urls.ts

@@ -1,62 +0,0 @@
-import { normalizeVersion } from './version-maps'
-import { buildHostdbUrl } from '../../core/hostdb-client'
-import { Engine, Platform, type Arch } from '../../types'
-
-/**
- * Supported platform identifiers for hostdb downloads.
- * TigerBeetle supports all 5 platforms.
- */
-const SUPPORTED_PLATFORMS = new Set([
-  'darwin-arm64',
-  'darwin-x64',
-  'linux-arm64',
-  'linux-x64',
-  'win32-x64',
-])
-
-/**
- * Get the hostdb platform identifier
- *
- * @param platform - Node.js platform (e.g., 'darwin', 'linux', 'win32')
- * @param arch - Node.js architecture (e.g., 'arm64', 'x64')
- * @returns hostdb platform identifier or null if unsupported
- */
-export function getHostdbPlatform(
-  platform: Platform,
-  arch: Arch,
-): string | null {
-  const key = `${platform}-${arch}`
-  return SUPPORTED_PLATFORMS.has(key) ? key : null
-}
-
-/**
- * Build the download URL for TigerBeetle binaries from hostdb
- *
- * @param version - TigerBeetle version (e.g., '0.16', '0.16.70')
- * @param platform - Platform identifier (e.g., 'darwin', 'linux', 'win32')
- * @param arch - Architecture identifier (e.g., 'arm64', 'x64')
- * @returns Download URL for the binary
- */
-export function getBinaryUrl(
-  version: string,
-  platform: Platform,
-  arch: Arch,
-): string {
-  const platformKey = `${platform}-${arch}`
-  const hostdbPlatform = getHostdbPlatform(platform, arch)
-  if (!hostdbPlatform) {
-    const supported = Array.from(SUPPORTED_PLATFORMS).join(', ')
-    throw new Error(
-      `Unsupported platform: ${platformKey}. Supported platforms: ${supported}`,
-    )
-  }
-
-  const fullVersion = normalizeVersion(version)
-  const ext = platform === Platform.Win32 ? 'zip' : 'tar.gz'
-
-  return buildHostdbUrl(Engine.TigerBeetle, {
-    version: fullVersion,
-    hostdbPlatform,
-    extension: ext,
-  })
-}

package/engines/tigerbeetle/hostdb-releases.ts

@@ -1,26 +0,0 @@
-/**
- * hostdb Releases Module for TigerBeetle
- *
- * Fetches TigerBeetle binary information from the hostdb repository at
- * https://github.com/robertjbass/hostdb
- */
-
-import { createHostdbReleases } from '../../core/hostdb-releases-factory'
-import {
-  TIGERBEETLE_VERSION_MAP,
-  SUPPORTED_MAJOR_VERSIONS,
-} from './version-maps'
-import { tigerbeetleBinaryManager } from './binary-manager'
-import { Engine } from '../../types'
-
-const hostdbReleases = createHostdbReleases({
-  engine: Engine.TigerBeetle,
-  displayName: 'TigerBeetle',
-  versionMap: TIGERBEETLE_VERSION_MAP,
-  supportedMajorVersions: SUPPORTED_MAJOR_VERSIONS,
-  groupingStrategy: 'xy-format',
-  listInstalled: () => tigerbeetleBinaryManager.listInstalled(),
-})
-
-export const fetchAvailableVersions = hostdbReleases.fetchAvailableVersions
-export const getLatestVersion = hostdbReleases.getLatestVersion