spindb 0.37.2 → 0.38.0

package/engines/meilisearch/restore.ts

@@ -1,219 +0,0 @@
-/**
- * Meilisearch restore module
- * Supports snapshot-based restore using Meilisearch's snapshot files
- */
-
-import { copyFile, open, mkdir, rm, writeFile } 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
- * Meilisearch uses snapshot files which are compressed 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 - Meilisearch uses single snapshot files',
-      restoreCommand:
-        'Meilisearch requires a single .snapshot file for restore',
-    }
-  }
-
-  // Check file extension for .snapshot files
-  if (filePath.endsWith('.snapshot')) {
-    return {
-      format: 'snapshot',
-      description: 'Meilisearch snapshot file',
-      restoreCommand:
-        'Copy to snapshots directory and restart Meilisearch (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: 'Meilisearch snapshot file (detected by magic bytes)',
-          restoreCommand:
-            'Copy to snapshots directory and restart Meilisearch (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 Meilisearch
-export type RestoreOptions = {
-  containerName: string
-  dataDir?: string
-}
-
-/**
- * Restore from snapshot backup
- *
- * IMPORTANT: Meilisearch should be stopped before snapshot restore.
- * The snapshot file is copied to the snapshots directory, and a marker file
- * is created so that the next start() call will use --import-snapshot flag.
- */
-async function restoreSnapshotBackup(
-  backupPath: string,
-  containerName: string,
-  dataDir?: string,
-): Promise<RestoreResult> {
-  const targetDir =
-    dataDir ||
-    paths.getContainerDataPath(containerName, { engine: 'meilisearch' })
-  // Snapshots directory must be sibling of data, not inside it
-  // IMPORTANT: Meilisearch fails if --snapshot-dir is inside --db-path
-  const containerDir = paths.getContainerPath(containerName, {
-    engine: 'meilisearch',
-  })
-  const snapshotsDir = join(containerDir, '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 indexes after successful copy for clean restore
-  const indexesDir = join(targetDir, 'indexes')
-  if (existsSync(indexesDir)) {
-    logDebug('Removing existing indexes for clean restore')
-    await rm(indexesDir, { recursive: true, force: true })
-  }
-
-  // Also remove tasks database
-  const tasksDir = join(targetDir, 'tasks')
-  if (existsSync(tasksDir)) {
-    logDebug('Removing existing tasks for clean restore')
-    await rm(tasksDir, { recursive: true, force: true })
-  }
-
-  // Write marker file so start() knows to use --import-snapshot
-  // The marker contains the path to the snapshot to import
-  const markerPath = join(containerDir, 'pending-snapshot-import')
-  await writeFile(markerPath, targetPath, 'utf-8')
-  logDebug(`Created pending import marker: ${markerPath}`)
-
-  return {
-    format: 'snapshot',
-    stdout: `Restored snapshot to ${targetPath}. Next start will auto-import the snapshot.`,
-    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 Meilisearch connection string
- * Format: http://host[:port], https://host[:port], or meilisearch://host[:port]
- *
- * The meilisearch:// scheme is an alias for http://
- * Meilisearch uses indexes 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 Meilisearch connection string: expected a non-empty string',
-    )
-  }
-
-  let url: URL
-  try {
-    url = new URL(connectionString)
-  } catch (error) {
-    throw new Error(
-      `Invalid Meilisearch connection string: "${connectionString}". ` +
-        `Expected format: http://host[:port] or meilisearch://host[:port]`,
-      { cause: error },
-    )
-  }
-
-  // Validate protocol (meilisearch:// is an alias for http://)
-  let protocol: 'http' | 'https'
-  if (url.protocol === 'http:' || url.protocol === 'meilisearch:') {
-    protocol = 'http'
-  } else if (url.protocol === 'https:') {
-    protocol = 'https'
-  } else {
-    throw new Error(
-      `Invalid Meilisearch connection string: unsupported protocol "${url.protocol}". ` +
-        `Expected "http://", "https://", or "meilisearch://"`,
-    )
-  }
-
-  const host = url.hostname || '127.0.0.1'
-  const port = parseInt(url.port, 10) || 7700
-
-  return {
-    host,
-    port,
-    protocol,
-  }
-}

package/engines/meilisearch/version-maps.ts

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

package/engines/meilisearch/version-validator.ts

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

@@ -1,162 +0,0 @@
-# MongoDB Engine Implementation
-
-## Overview
-
-MongoDB is a document database with JavaScript-based queries. SpinDB downloads MongoDB binaries from hostdb and manages them with `mongod` server and `mongosh` shell.
-
-## Platform Support
-
-| Platform | Architecture | Status | Notes |
-|----------|--------------|--------|-------|
-| darwin | x64 | Supported | Uses hostdb binaries |
-| darwin | arm64 | Supported | Uses hostdb binaries (Apple Silicon) |
-| linux | x64 | Supported | Uses hostdb binaries |
-| linux | arm64 | Supported | Uses hostdb binaries |
-| win32 | x64 | Supported | Uses hostdb binaries |
-
-## Binary Packaging
-
-### Archive Format
-- **Unix (macOS/Linux)**: `tar.gz`
-- **Windows**: `zip`
-
-### Archive Structure
-```
-mongodb/
-├── bin/
-│   ├── mongod           # Server binary
-│   ├── mongos           # Sharding router
-│   └── mongosh          # Interactive shell
-└── lib/                 # Shared libraries (if any)
-```
-
-### macOS Extended Attributes Recovery
-
-The `BaseDocumentBinaryManager` includes special handling for macOS extended attribute files (`._*` prefix) that may cause tar extraction warnings. The manager recovers from these non-fatal warnings.
-
-### Version Map Sync
-
-```typescript
-export const MONGODB_VERSION_MAP: Record<string, string> = {
-  '7.0': '7.0.28',
-  '8.0': '8.0.x',
-  '8.2': '8.2.x',
-}
-```
-
-## Implementation Details
-
-### Binary Manager
-
-MongoDB uses `BaseDocumentBinaryManager` which extends the base manager with:
-- macOS tar recovery for extended attribute files
-- Major version matching for verification
-
-### Version Parsing
-
-- **Version output format**: `db version v7.0.28` or fallback to semantic version
-- **Parse pattern**: `/db version v(\d+\.\d+\.\d+)/` then fallback to `/(\d+\.\d+\.\d+)/`
-- **Major version matching**: Only major version needs to match for verification
-
-### Default Configuration
-
-- **Default Port**: 27017 (auto-increments on conflict)
-- **Default Database**: Name derived from container name
-- **PID File**: `mongod.pid` in container directory
-
-### Implicit Database Creation
-
-MongoDB/FerretDB don't create databases until data is written. To force immediate creation (so databases appear in tools like TablePlus):
-
-```javascript
-// createDatabase() implementation:
-db.getCollection('_spindb_init').insertOne({})
-db.getCollection('_spindb_init').drop()
-```
-
-This creates and immediately drops a temporary collection, leaving the database visible.
-
-### Connection String Format
-
-```
-mongodb://127.0.0.1:{port}/{database}
-```
-
-## Backup & Restore
-
-### Backup Formats
-
-| Format | Extension | Tool | Notes |
-|--------|-----------|------|-------|
-| bson | (directory) | mongodump | Directory with BSON files |
-| archive | `.archive` | mongodump --archive | Single file archive |
-
-### Restore Methods
-
-- **BSON directory**: Restored via `mongorestore`
-- **Archive format**: Restored via `mongorestore --archive`
-
-## Integration Test Notes
-
-### Reserved Ports
-
-MongoDB integration tests use port ranges to avoid conflicts with default MongoDB installations.
-
-### Test Fixtures
-
-Located in `tests/fixtures/mongodb/seeds/`:
-- Test documents for data operations
-
-### Shell Scripts
-
-MongoDB uses `mongosh` (modern shell) for script execution, not the legacy `mongo` shell.
-
-## Docker E2E Test Notes
-
-MongoDB is tested in Docker E2E with:
-- Container lifecycle
-- Database operations
-- BSON and archive backup/restore
-- Multi-database support
-
-## Known Issues & Gotchas
-
-### 1. mongosh vs mongo
-
-SpinDB uses `mongosh` (the modern MongoDB Shell). The legacy `mongo` shell is deprecated and not bundled.
-
-### 2. macOS Tar Warnings
-
-When extracting MongoDB archives on macOS, tar may emit warnings about `._*` extended attribute files. The `BaseDocumentBinaryManager` handles these warnings gracefully without failing extraction.
-
-### 3. Database Visibility
-
-Databases in MongoDB don't appear in `show dbs` until they contain data. The `createDatabase()` method uses the temp collection trick to force visibility.
-
-### 4. Windows Detached Spawn
-
-On Windows, MongoDB uses detached spawn with `windowsHide: true` for background operation. The process is tracked via PID file.
-
-### 5. Slow Initial Startup
-
-First startup may take longer as MongoDB initializes WiredTiger storage engine.
-
-## CI/CD Notes
-
-### GitHub Actions Cache Step
-
-```yaml
-- name: Cache MongoDB binaries
-  uses: actions/cache@v4
-  with:
-    path: ~/.spindb/bin/mongodb-*
-    key: mongodb-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('engines/mongodb/version-maps.ts') }}
-```
-
-### Docker E2E Alias
-
-```bash
-pnpm test:docker -- mongo
-# or
-pnpm test:docker -- mongodb
-```