spindb 0.37.2 → 0.38.0

package/engines/couchdb/README.md

@@ -1,257 +0,0 @@
-# CouchDB Engine Implementation
-
-## Overview
-
-CouchDB is a document-oriented database with a REST API. Like Qdrant and Meilisearch, it uses HTTP for all operations. CouchDB includes the Fauxton web dashboard.
-
-## 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 `.cmd` batch file (see below) |
-
-### Windows Binary - .cmd Not .exe
-
-**Critical**: CouchDB on Windows uses a **batch file** (`couchdb.cmd`), not an executable:
-
-```text
-couchdb/bin/couchdb.cmd    # NOT couchdb.exe
-```
-
-The binary manager has a helper `getCouchDBExtension()` that returns `.cmd` on Windows.
-
-## Binary Packaging
-
-### Archive Format
-- **Unix (macOS/Linux)**: `tar.gz`
-- **Windows**: `zip`
-
-### Archive Structure
-```text
-couchdb/
-├── bin/
-│   ├── couchdb           # Unix: shell script
-│   └── couchdb.cmd       # Windows: batch file
-├── lib/                  # Erlang libraries
-├── etc/                  # Configuration
-└── share/               # Data files
-```
-
-### CouchDB is an Erlang Application
-
-CouchDB is written in Erlang. This has implications:
-- No `--version` flag (Erlang tries to start on any arguments)
-- Binary verification only checks file existence
-- Startup involves the Erlang runtime
-
-### Version Map Sync
-
-```typescript
-export const COUCHDB_VERSION_MAP: Record<string, string> = {
-  '3': '3.5.1',
-}
-```
-
-## Implementation Details
-
-### Binary Manager
-
-CouchDB uses `BaseBinaryManager` with a custom `verify()` override:
-
-```typescript
-// CouchDB doesn't support --version (tries to start)
-// Verification just checks binary existence
-async verify(): Promise<boolean> {
-  return existsSync(binaryPath)
-}
-```
-
-### REST API Engine
-
-CouchDB is a **REST API engine**:
-- `spindb run` is **NOT applicable**
-- `spindb connect` opens Fauxton dashboard in browser
-- All operations use HTTP REST API
-
-### Default Configuration
-
-- **Default Port**: 5984 (auto-increments on conflict)
-- **Health Endpoint**: `/` (root - returns JSON with version)
-- **Dashboard (Fauxton)**: `/_utils`
-- **Default Credentials**: `admin` / `admin`
-- **PID File**: `couchdb.pid` in container directory
-
-### Fauxton Authentication
-
-CouchDB 3.x requires an admin account. Even with `require_valid_user = false`:
-- Fauxton's session-based auth still shows a login screen
-- Default credentials: `admin` / `admin`
-- The shell handler shows credentials before opening browser
-
-### Connection String Format
-
-```text
-http://127.0.0.1:{port}/{database}
-```
-
-### Web Dashboard (Fauxton)
-
-Fauxton dashboard is at:
-```text
-http://localhost:{port}/_utils
-```
-
-## Backup & Restore
-
-### Backup Formats
-
-| Format | Extension | Tool | Notes |
-|--------|-----------|------|-------|
-| json | `.json` | REST API | JSON documents |
-
-### Backup Method
-
-Uses CouchDB's bulk document APIs:
-- `GET /{db}/_all_docs?include_docs=true` - Export all documents
-- `POST /{db}/_bulk_docs` - Import documents
-
-### No Native Snapshot
-
-Unlike Qdrant/Meilisearch, CouchDB doesn't have a native snapshot format. Backup is JSON export.
-
-## Integration Test Notes
-
-### REST API Testing
-
-Integration tests use `fetch()` or `curl`.
-
-### Test Fixtures
-
-Located in `tests/fixtures/couchdb/seeds/`:
-- `README.md` documenting the API-based approach
-
-## Docker E2E Test Notes
-
-CouchDB Docker E2E uses `curl`:
-
-```bash
-# Health check
-curl http://localhost:5984/
-
-# Create database
-curl -X PUT http://admin:admin@localhost:5984/mydb
-
-# Add document
-curl -X POST http://admin:admin@localhost:5984/mydb \
-  -H 'Content-Type: application/json' \
-  -d '{"name":"test"}'
-```
-
-### Backup/Restore Skipped in Docker E2E
-
-CouchDB backup/restore tests are skipped in Docker E2E (covered by integration tests).
-
-## Known Issues & Gotchas
-
-### 1. No --version Flag
-
-CouchDB is an Erlang application that tries to start when run with any arguments. You cannot run `couchdb --version`. Binary verification only checks file existence.
-
-### 2. Windows Uses .cmd
-
-On Windows, the binary is `couchdb.cmd` (batch file), NOT `couchdb.exe`. This is handled by `getCouchDBExtension()`.
-
-### 3. No CLI Shell
-
-`spindb run` does nothing for CouchDB. Use the REST API or Fauxton.
-
-### 4. Authentication Required
-
-Fauxton requires authentication even for local development:
-- Username: `admin`
-- Password: `admin`
-
-### 5. Database Creation is Explicit
-
-Unlike MongoDB, databases must be explicitly created via PUT request:
-```bash
-curl -X PUT http://admin:admin@localhost:5984/newdb
-```
-
-### 6. Health Check at Root
-
-The root path `/` returns health/version info:
-```json
-{"couchdb":"Welcome","version":"3.5.1","features":[...]}
-```
-
-## CI/CD Notes
-
-### curl-Based Testing
-
-CI tests use `curl` commands.
-
-### GitHub Actions Cache Step
-
-```yaml
-- name: Cache CouchDB binaries
-  uses: actions/cache@v4
-  with:
-    path: ~/.spindb/bin/couchdb-*
-    key: couchdb-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('engines/couchdb/version-maps.ts') }}
-```
-
-## REST API Quick Reference
-
-### Databases
-```bash
-# List databases
-GET /_all_dbs
-
-# Create database
-PUT /{db}
-
-# Delete database
-DELETE /{db}
-
-# Get database info
-GET /{db}
-```
-
-### Documents
-```bash
-# Create document (server-generated ID)
-POST /{db}
-
-# Create/update document (specified ID)
-PUT /{db}/{id}
-
-# Get document
-GET /{db}/{id}
-
-# Delete document
-DELETE /{db}/{id}?rev={rev}
-```
-
-### Bulk Operations
-```bash
-# Get all documents
-GET /{db}/_all_docs?include_docs=true
-
-# Bulk insert
-POST /{db}/_bulk_docs
-{"docs": [...]}
-```
-
-### Admin
-```bash
-# Server info/health
-GET /
-
-# Session info
-GET /_session
-```

package/engines/couchdb/api-client.ts

@@ -1,81 +0,0 @@
-/**
- * Shared CouchDB REST API client utilities
- */
-
-// Default admin credentials for local development
-// CouchDB 3.x requires admin account to start
-export const DEFAULT_ADMIN_USER = 'admin'
-export const DEFAULT_ADMIN_PASSWORD = 'admin'
-
-/**
- * Make an HTTP request to CouchDB REST API
- *
- * @param port - The HTTP port CouchDB is listening on
- * @param method - HTTP method (GET, POST, PUT, DELETE)
- * @param path - API path (e.g., '/', '/_all_dbs', '/mydb')
- * @param body - Optional JSON body for POST/PUT requests
- * @param timeoutMs - Request timeout in milliseconds (default: 30s)
- * @param auth - Optional authentication credentials (defaults to admin:admin)
- */
-export async function couchdbApiRequest(
-  port: number,
-  method: string,
-  path: string,
-  body?: Record<string, unknown>,
-  timeoutMs = 30000,
-  auth: { username: string; password: string } | null = {
-    username: DEFAULT_ADMIN_USER,
-    password: DEFAULT_ADMIN_PASSWORD,
-  },
-): Promise<{ status: number; data: unknown }> {
-  const url = `http://127.0.0.1:${port}${path}`
-
-  const controller = new AbortController()
-  const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
-
-  const headers: Record<string, string> = {
-    'Content-Type': 'application/json',
-  }
-
-  // Add basic auth header if credentials provided
-  if (auth) {
-    const credentials = Buffer.from(
-      `${auth.username}:${auth.password}`,
-    ).toString('base64')
-    headers['Authorization'] = `Basic ${credentials}`
-  }
-
-  const options: RequestInit = {
-    method,
-    headers,
-    signal: controller.signal,
-  }
-
-  if (body) {
-    options.body = JSON.stringify(body)
-  }
-
-  try {
-    const response = await fetch(url, options)
-
-    // Try to parse as JSON, CouchDB always returns JSON
-    let data: unknown
-    const contentType = response.headers.get('content-type') || ''
-    if (contentType.includes('application/json')) {
-      data = await response.json()
-    } else {
-      data = await response.text()
-    }
-
-    return { status: response.status, data }
-  } catch (error) {
-    if (error instanceof Error && error.name === 'AbortError') {
-      throw new Error(
-        `CouchDB API request timed out after ${timeoutMs / 1000}s: ${method} ${path}`,
-      )
-    }
-    throw error
-  } finally {
-    clearTimeout(timeoutId)
-  }
-}

package/engines/couchdb/backup.ts

@@ -1,137 +0,0 @@
-/**
- * CouchDB backup module
- * Supports JSON-based backup using CouchDB's REST API
- *
- * CouchDB backup strategy:
- * - Export all documents from each database using _all_docs?include_docs=true
- * - Store as a JSON file with metadata about databases and their documents
- */
-
-import { mkdir, stat, writeFile } from 'fs/promises'
-import { existsSync } from 'fs'
-import { dirname } from 'path'
-import { logDebug } from '../../core/error-handler'
-import { couchdbApiRequest } from './api-client'
-import type { ContainerConfig, BackupOptions, BackupResult } from '../../types'
-
-// Backup operations may take longer than the default timeout
-const BACKUP_TIMEOUT_MS = 600000 // 10 minutes
-
-type CouchDBBackup = {
-  version: string
-  created: string
-  databases: Array<{
-    name: string
-    docs: unknown[]
-  }>
-}
-
-/**
- * Create a JSON backup of all databases using CouchDB's REST API
- */
-export async function createBackup(
-  container: ContainerConfig,
-  outputPath: string,
-  options: BackupOptions,
-): Promise<BackupResult> {
-  const { port } = container
-  const targetDatabase = options.database
-
-  // Ensure output directory exists
-  const outputDir = dirname(outputPath)
-  if (!existsSync(outputDir)) {
-    await mkdir(outputDir, { recursive: true })
-  }
-
-  // Get CouchDB version info
-  const infoResponse = await couchdbApiRequest(port, 'GET', '/')
-  const serverInfo = infoResponse.data as { version?: string }
-  const serverVersion = serverInfo?.version || 'unknown'
-
-  // Get list of databases to backup
-  let databasesToBackup: string[]
-
-  if (targetDatabase) {
-    // Backup specific database
-    databasesToBackup = [targetDatabase]
-  } else {
-    // Backup all user databases (excluding system databases)
-    const dbsResponse = await couchdbApiRequest(port, 'GET', '/_all_dbs')
-    if (dbsResponse.status !== 200) {
-      throw new Error(
-        `Failed to list databases: ${JSON.stringify(dbsResponse.data)}`,
-      )
-    }
-    const allDbs = dbsResponse.data as string[]
-    // Filter out system databases (starting with _)
-    databasesToBackup = allDbs.filter((db) => !db.startsWith('_'))
-  }
-
-  logDebug(`Backing up ${databasesToBackup.length} database(s)`)
-
-  // Export documents from each database
-  const backup: CouchDBBackup = {
-    version: serverVersion,
-    created: new Date().toISOString(),
-    databases: [],
-  }
-
-  for (const dbName of databasesToBackup) {
-    logDebug(`Exporting database: ${dbName}`)
-
-    const docsResponse = await couchdbApiRequest(
-      port,
-      'GET',
-      `/${encodeURIComponent(dbName)}/_all_docs?include_docs=true`,
-      undefined,
-      BACKUP_TIMEOUT_MS,
-    )
-
-    if (docsResponse.status !== 200) {
-      throw new Error(
-        `Failed to export database ${dbName}: ${JSON.stringify(docsResponse.data)}`,
-      )
-    }
-
-    const docsData = docsResponse.data as {
-      rows?: Array<{ doc?: unknown }>
-    }
-    const docs =
-      docsData.rows
-        ?.map((row) => row.doc)
-        .filter((doc): doc is unknown => doc !== undefined) || []
-
-    // Filter out design documents for cleaner backup (they start with _design/)
-    const userDocs = docs.filter((doc) => {
-      const d = doc as { _id?: string }
-      return d._id && !d._id.startsWith('_design/')
-    })
-
-    backup.databases.push({
-      name: dbName,
-      docs: userDocs,
-    })
-  }
-
-  // Write backup to file
-  await writeFile(outputPath, JSON.stringify(backup, null, 2))
-
-  const stats = await stat(outputPath)
-
-  return {
-    path: outputPath,
-    format: 'json',
-    size: stats.size,
-  }
-}
-
-/**
- * Create a backup for cloning purposes
- */
-export async function createCloneBackup(
-  container: ContainerConfig,
-  outputPath: string,
-): Promise<BackupResult> {
-  // Backup all databases for cloning
-  return createBackup(container, outputPath, { database: '' })
-}

package/engines/couchdb/binary-manager.ts

@@ -1,86 +0,0 @@
-/**
- * CouchDB Binary Manager
- *
- * Handles downloading, extracting, and managing CouchDB binaries from hostdb.
- * Extends BaseBinaryManager for shared download/extraction logic.
- *
- * Note: CouchDB doesn't support --version flag. It's an Erlang application that
- * tries to start the server when run, so we override verify() to just check
- * binary existence instead of running it.
- */
-
-import { existsSync } from 'fs'
-import { join } from 'path'
-import {
-  BaseBinaryManager,
-  type BinaryManagerConfig,
-} from '../../core/base-binary-manager'
-import { getBinaryUrl } from './binary-urls'
-import { normalizeVersion } from './version-maps'
-import { Engine, Platform, type Arch } from '../../types'
-import { paths } from '../../config/paths'
-
-class CouchDBBinaryManager extends BaseBinaryManager {
-  protected readonly config: BinaryManagerConfig = {
-    engine: Engine.CouchDB,
-    engineName: 'couchdb',
-    displayName: 'CouchDB',
-    serverBinary: 'couchdb',
-  }
-
-  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 {
-    // Extract version from output like "couchdb 3.5.1" or "Apache CouchDB 3.5.1"
-    const match = stdout.match(
-      /(?:couchdb\s+)?(?:Apache CouchDB\s+)?v?(\d+\.\d+\.\d+)/i,
-    )
-    return match?.[1] ?? null
-  }
-
-  /**
-   * Override verify to just check binary existence.
-   * CouchDB doesn't support --version flag - it's an Erlang application that
-   * tries to start the server when run with any arguments.
-   *
-   * Note: On Windows, CouchDB uses a .cmd batch file, not .exe
-   */
-  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,
-    })
-
-    // CouchDB on Windows uses .cmd batch file, not .exe
-    const ext = platform === Platform.Win32 ? '.cmd' : ''
-    const serverPath = join(binPath, 'bin', `${this.config.serverBinary}${ext}`)
-
-    if (!existsSync(serverPath)) {
-      throw new Error(
-        `${this.config.displayName} binary not found at ${binPath}/bin/`,
-      )
-    }
-
-    // Just verify the binary exists - we can't run --version on CouchDB
-    return true
-  }
-}
-
-export const couchdbBinaryManager = new CouchDBBinaryManager()

package/engines/couchdb/binary-urls.ts

@@ -1,115 +0,0 @@
-import { COUCHDB_VERSION_MAP } from './version-maps'
-import { buildHostdbUrl } from '../../core/hostdb-client'
-import { logDebug } from '../../core/error-handler'
-import { Engine, Platform, type Arch } from '../../types'
-
-/**
- * Supported platform identifiers for hostdb downloads.
- * hostdb uses standard Node.js platform naming - this set validates
- * that a platform/arch combination is supported, not transforms it.
- */
-const SUPPORTED_PLATFORMS = new Set([
-  'darwin-arm64',
-  'darwin-x64',
-  'linux-arm64',
-  'linux-x64',
-  'win32-x64',
-])
-
-/**
- * Get the hostdb platform identifier
- *
- * hostdb uses standard platform naming that matches Node.js identifiers directly.
- * This function validates the platform/arch combination is supported.
- *
- * @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 CouchDB binaries from hostdb
- *
- * Format: https://registry.layerbase.host/couchdb-{version}/couchdb-{version}-{platform}-{arch}.{ext}
- *
- * @param version - CouchDB version (e.g., '3', '3.5.1')
- * @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}`,
-    )
-  }
-
-  // Normalize version (handles major version lookup and X.Y -> X.Y.Z conversion)
-  const fullVersion = normalizeVersion(version, COUCHDB_VERSION_MAP)
-  const ext = platform === Platform.Win32 ? 'zip' : 'tar.gz'
-
-  return buildHostdbUrl(Engine.CouchDB, {
-    version: fullVersion,
-    hostdbPlatform,
-    extension: ext,
-  })
-}
-
-/**
- * Normalize version string to X.Y.Z format
- *
- * @param version - Version string (e.g., '3', '3.5', '3.5.1')
- * @param versionMap - Optional version map for major version lookup
- * @returns Normalized version (e.g., '3.5.1')
- */
-function normalizeVersion(
-  version: string,
-  versionMap: Record<string, string> = COUCHDB_VERSION_MAP,
-): string {
-  // Check if it's an exact key in the map (handles "3", "3.5", etc.)
-  if (versionMap[version]) {
-    return versionMap[version]
-  }
-
-  const parts = version.split('.')
-
-  // If it's already a full version (X.Y.Z), return as-is
-  if (parts.length === 3) {
-    return version
-  }
-
-  // For two-part versions (e.g., "3.5"), first try exact two-part key, then fall back to major
-  if (parts.length === 2) {
-    const twoPart = `${parts[0]}.${parts[1]}`
-    if (versionMap[twoPart]) {
-      return versionMap[twoPart]
-    }
-    // Fall back to major version for latest patch
-    const major = parts[0]
-    const mapped = versionMap[major]
-    if (mapped) {
-      return mapped
-    }
-  }
-
-  // Unknown version format - log and return as-is
-  // This may cause download failures if the version doesn't exist in hostdb
-  logDebug(
-    `CouchDB version '${version}' not in version map, may not be available in hostdb`,
-  )
-  return version
-}

package/engines/couchdb/hostdb-releases.ts

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