spindb 0.37.2 → 0.38.0

package/dist/engines/couchdb/index.js

@@ -0,0 +1,1043 @@
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { mkdir, writeFile, readFile, unlink } from 'fs/promises';
+import { join, dirname } from 'path';
+import { BaseEngine } from '../base-engine.js';
+import { paths } from '../../config/paths.js';
+import { getEngineDefaults } from '../../config/defaults.js';
+import { platformService, isWindows } from '../../core/platform-service.js';
+import { configManager } from '../../core/config-manager.js';
+import { logDebug, logWarning, assertValidUsername, } from '../../core/error-handler.js';
+import { processManager } from '../../core/process-manager.js';
+import { portManager } from '../../core/port-manager.js';
+import { couchdbBinaryManager } from './binary-manager.js';
+import { getBinaryUrl } from './binary-urls.js';
+import { normalizeVersion, SUPPORTED_MAJOR_VERSIONS, COUCHDB_VERSION_MAP, } from './version-maps.js';
+import { fetchAvailableVersions as fetchHostdbVersions } from './hostdb-releases.js';
+import { detectBackupFormat as detectBackupFormatImpl, restoreBackup, } from './restore.js';
+import { createBackup } from './backup.js';
+import { couchdbApiRequest } from './api-client.js';
+import { parseRESTAPIResult } from '../../core/query-parser.js';
+const ENGINE = 'couchdb';
+const engineDef = getEngineDefaults(ENGINE);
+/**
+ * Get the correct extension for CouchDB binary.
+ * On Windows, CouchDB uses a .cmd batch file, not .exe
+ */
+function getCouchDBExtension() {
+    return isWindows() ? '.cmd' : '';
+}
+/**
+ * Generate CouchDB local.ini configuration content
+ * CouchDB 3.x requires at least one admin account to start
+ */
+function generateCouchDBConfig(options) {
+    const bindAddress = options.bindAddress || '127.0.0.1';
+    return `; SpinDB generated CouchDB configuration
+[couchdb]
+database_dir = ${options.dataDir}
+view_index_dir = ${options.dataDir}
+
+[chttpd]
+port = ${options.port}
+bind_address = ${bindAddress}
+; Allow anonymous access for local development (no login required)
+require_valid_user = false
+
+[chttpd_auth]
+; Allow anonymous access to Fauxton dashboard
+require_valid_user = false
+
+[log]
+file = ${options.logDir}/couchdb.log
+level = info
+
+[admins]
+; CouchDB 3.x requires admin account - credentials available if needed: admin/admin
+admin = admin
+`;
+}
+/**
+ * Generate container-specific vm.args with unique Erlang node name
+ * Each CouchDB instance needs a unique node name to avoid conflicts
+ */
+function generateVmArgs(port, _containerDir) {
+    // Use port in node name to ensure uniqueness
+    const nodeName = `couchdb_${port}@127.0.0.1`;
+    // Read base vm.args and replace the node name
+    return `# SpinDB generated CouchDB vm.args
+# Unique node name based on port to allow multiple instances
+-name ${nodeName}
+
+# All nodes must share the same magic cookie for distributed Erlang to work.
+# -setcookie
+
+# Which interfaces should the node listen on?
+-kernel inet_dist_use_interface {127,0,0,1}
+
+# Tell kernel and SASL not to log anything
+-kernel error_logger silent
+-sasl sasl_error_logger false
+
+# Prevent overlapping partitions
+-kernel prevent_overlapping_partitions false
+
+# Erlang process limit
++P 1048576
+
+# Increase the pool of dirty IO schedulers
++SDio 16
+
+# Increase distribution buffer size
++zdbbl 32768
+
+# Disable interactive shell
++Bd -noinput
+
+# Set maximum SSL session lifetime
+-ssl session_lifetime 300
+
+# OS Mon Settings - disable all monitoring on Windows to avoid win32sysinfo issues
+-os_mon start_cpu_sup false
+-os_mon start_memsup false
+-os_mon start_disksup false
+`;
+}
+/**
+ * Generate Erlang sys.config to disable os_mon features before application starts.
+ * On Windows, os_mon tries to use win32sysinfo which may crash if the port program
+ * is missing or broken. Setting these in sys.config takes effect before os_mon starts.
+ */
+function generateSysConfig() {
+    // Minimal Erlang sys.config - no comments, just config
+    // os_mon settings must be set BEFORE the application starts
+    return `[{os_mon,[{start_cpu_sup,false},{start_disksup,false},{start_memsup,false}]}].
+`;
+}
+/**
+ * Parse a CouchDB connection string for remote operations
+ */
+function parseCouchDBConnectionString(connectionString) {
+    let url;
+    let scheme = 'http';
+    // Handle couchdb:// scheme by converting to http://
+    let normalized = connectionString.trim();
+    if (normalized.startsWith('couchdb://')) {
+        normalized = normalized.replace('couchdb://', 'http://');
+    }
+    // Ensure scheme is present
+    if (!normalized.startsWith('http://') && !normalized.startsWith('https://')) {
+        normalized = `http://${normalized}`;
+    }
+    try {
+        url = new URL(normalized);
+        scheme = url.protocol.replace(':', '');
+    }
+    catch {
+        throw new Error(`Invalid CouchDB connection string: ${connectionString}\n` +
+            'Expected format: http://host:port or couchdb://host:port');
+    }
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    // Handle basic auth if present
+    if (url.username && url.password) {
+        const auth = Buffer.from(`${url.username}:${url.password}`).toString('base64');
+        headers['Authorization'] = `Basic ${auth}`;
+    }
+    // Construct base URL without auth and query params
+    const port = url.port || '5984';
+    const baseUrl = `${scheme}://${url.hostname}:${port}`;
+    // Extract database from pathname
+    const pathname = url.pathname || '';
+    const database = pathname.length > 1 ? pathname.slice(1).split('/')[0] : undefined;
+    return { baseUrl, headers, database };
+}
+/**
+ * Make an HTTP request to a remote CouchDB server
+ */
+async function remoteCouchDBRequest(baseUrl, method, path, headers, body, timeoutMs = 30000) {
+    const url = `${baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const options = {
+        method,
+        headers,
+        signal: controller.signal,
+    };
+    if (body) {
+        options.body = JSON.stringify(body);
+    }
+    try {
+        const response = await fetch(url, options);
+        let data;
+        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(`Remote CouchDB request timed out after ${timeoutMs / 1000}s: ${method} ${path}`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+export class CouchDBEngine extends BaseEngine {
+    name = ENGINE;
+    displayName = 'CouchDB';
+    defaultPort = engineDef.defaultPort;
+    supportedVersions = SUPPORTED_MAJOR_VERSIONS;
+    // Get platform info for binary operations
+    getPlatformInfo() {
+        return platformService.getPlatformInfo();
+    }
+    // Fetch available versions from hostdb
+    async fetchAvailableVersions() {
+        return fetchHostdbVersions();
+    }
+    // Get binary download URL from hostdb
+    getBinaryUrl(version, platform, arch) {
+        return getBinaryUrl(version, platform, arch);
+    }
+    // Resolves version string to full version (e.g., '3' -> '3.5.1')
+    resolveFullVersion(version) {
+        if (/^\d+\.\d+\.\d+$/.test(version)) {
+            return version;
+        }
+        if (COUCHDB_VERSION_MAP[version]) {
+            return COUCHDB_VERSION_MAP[version];
+        }
+        // Normalize to exactly 3 segments (e.g., "3" -> "3.0.0", "3.5" -> "3.5.0")
+        const segments = version.split('.').slice(0, 3);
+        while (segments.length < 3) {
+            segments.push('0');
+        }
+        return segments.join('.');
+    }
+    // Get the path where binaries for a version would be installed
+    getBinaryPath(version) {
+        const fullVersion = this.resolveFullVersion(version);
+        const { platform: p, arch: a } = this.getPlatformInfo();
+        return paths.getBinaryPath({
+            engine: 'couchdb',
+            version: fullVersion,
+            platform: p,
+            arch: a,
+        });
+    }
+    // Verify that CouchDB binaries are available
+    async verifyBinary(binPath) {
+        // CouchDB has a startup script rather than a direct binary
+        // On Windows it's .cmd, on Unix it's just 'couchdb'
+        const serverPath = join(binPath, 'bin', `couchdb${getCouchDBExtension()}`);
+        return existsSync(serverPath);
+    }
+    // Check if a specific CouchDB version is installed
+    async isBinaryInstalled(version) {
+        const { platform, arch } = this.getPlatformInfo();
+        return couchdbBinaryManager.isInstalled(version, platform, arch);
+    }
+    /**
+     * Ensure CouchDB binaries are available for a specific version
+     */
+    async ensureBinaries(version, onProgress) {
+        const { platform, arch } = this.getPlatformInfo();
+        const binPath = await couchdbBinaryManager.ensureInstalled(version, platform, arch, onProgress);
+        // Register binaries in config
+        const toolPath = join(binPath, 'bin', `couchdb${getCouchDBExtension()}`);
+        if (existsSync(toolPath)) {
+            await configManager.setBinaryPath('couchdb', toolPath, 'bundled');
+        }
+        return binPath;
+    }
+    /**
+     * Initialize a new CouchDB data directory
+     */
+    async initDataDir(containerName, _version, options = {}) {
+        const dataDir = paths.getContainerDataPath(containerName, {
+            engine: ENGINE,
+        });
+        const containerDir = paths.getContainerPath(containerName, {
+            engine: ENGINE,
+        });
+        const port = options.port || engineDef.defaultPort;
+        // Create directories
+        if (!existsSync(dataDir)) {
+            await mkdir(dataDir, { recursive: true });
+            logDebug(`Created CouchDB data directory: ${dataDir}`);
+        }
+        const logDir = join(containerDir, 'log');
+        if (!existsSync(logDir)) {
+            await mkdir(logDir, { recursive: true });
+        }
+        // Generate local.ini config
+        const configPath = join(containerDir, 'local.ini');
+        const configContent = generateCouchDBConfig({
+            port,
+            dataDir,
+            logDir,
+        });
+        await writeFile(configPath, configContent);
+        logDebug(`Generated CouchDB config: ${configPath}`);
+        // Generate container-specific vm.args with unique node name
+        const vmArgsPath = join(containerDir, 'vm.args');
+        const vmArgsContent = generateVmArgs(port, containerDir);
+        await writeFile(vmArgsPath, vmArgsContent);
+        logDebug(`Generated CouchDB vm.args: ${vmArgsPath}`);
+        return dataDir;
+    }
+    // Get the path to couchdb server
+    async getCouchDBServerPath(version) {
+        const { platform, arch } = this.getPlatformInfo();
+        const fullVersion = normalizeVersion(version);
+        const binPath = paths.getBinaryPath({
+            engine: 'couchdb',
+            version: fullVersion,
+            platform,
+            arch,
+        });
+        const serverPath = join(binPath, 'bin', `couchdb${getCouchDBExtension()}`);
+        if (existsSync(serverPath)) {
+            return serverPath;
+        }
+        throw new Error(`CouchDB ${version} is not installed. Run: spindb engines download couchdb ${version}`);
+    }
+    // Get the path to couchdb binary
+    async getCouchDBPath(version) {
+        const cached = await configManager.getBinaryPath('couchdb');
+        if (cached && existsSync(cached)) {
+            return cached;
+        }
+        if (version) {
+            const { platform, arch } = this.getPlatformInfo();
+            const fullVersion = normalizeVersion(version);
+            const binPath = paths.getBinaryPath({
+                engine: 'couchdb',
+                version: fullVersion,
+                platform,
+                arch,
+            });
+            const couchdbPath = join(binPath, 'bin', `couchdb${getCouchDBExtension()}`);
+            if (existsSync(couchdbPath)) {
+                return couchdbPath;
+            }
+        }
+        throw new Error('couchdb not found. Run: spindb engines download couchdb <version>');
+    }
+    /**
+     * Start CouchDB server
+     */
+    async start(container, onProgress) {
+        const { name, port, version, binaryPath } = container;
+        // Check if already running
+        const alreadyRunning = await processManager.isRunning(name, {
+            engine: ENGINE,
+        });
+        if (alreadyRunning) {
+            return {
+                port,
+                connectionString: this.getConnectionString(container),
+            };
+        }
+        // Find couchdb binary
+        let couchdbServer = null;
+        if (binaryPath && existsSync(binaryPath)) {
+            const serverPath = join(binaryPath, 'bin', `couchdb${getCouchDBExtension()}`);
+            if (existsSync(serverPath)) {
+                couchdbServer = serverPath;
+                logDebug(`Using stored binary path: ${couchdbServer}`);
+            }
+        }
+        if (!couchdbServer) {
+            try {
+                couchdbServer = await this.getCouchDBServerPath(version);
+            }
+            catch (error) {
+                const originalMessage = error instanceof Error ? error.message : String(error);
+                throw new Error(`CouchDB ${version} is not installed. Run: spindb engines download couchdb ${version}\n` +
+                    `  Original error: ${originalMessage}`);
+            }
+        }
+        logDebug(`Using couchdb for version ${version}: ${couchdbServer}`);
+        const containerDir = paths.getContainerPath(name, { engine: ENGINE });
+        const configPath = join(containerDir, 'local.ini');
+        const dataDir = paths.getContainerDataPath(name, { engine: ENGINE });
+        const logDir = join(containerDir, 'log');
+        const logFile = join(logDir, 'couchdb.log');
+        const pidFile = join(containerDir, 'couchdb.pid');
+        // Check port availability
+        const portWaitTimeout = isWindows() ? 60000 : 0;
+        const portCheckStart = Date.now();
+        const portCheckInterval = 1000;
+        while (!(await portManager.isPortAvailable(port))) {
+            if (Date.now() - portCheckStart >= portWaitTimeout) {
+                throw new Error(`Port ${port} is already in use.`);
+            }
+            logDebug(`Waiting for port ${port} to become available...`);
+            await new Promise((resolve) => setTimeout(resolve, portCheckInterval));
+        }
+        // Regenerate config with current port
+        const configContent = generateCouchDBConfig({
+            port,
+            dataDir,
+            logDir,
+        });
+        await writeFile(configPath, configContent);
+        // Regenerate vm.args with unique node name for this port
+        const vmArgsPath = join(containerDir, 'vm.args');
+        const vmArgsContent = generateVmArgs(port, containerDir);
+        await writeFile(vmArgsPath, vmArgsContent);
+        onProgress?.({ stage: 'starting', message: 'Starting CouchDB...' });
+        logDebug(`Starting couchdb with config: ${configPath}`);
+        // Get the binary directory for default config paths
+        const binDir = dirname(dirname(couchdbServer));
+        const defaultIni = join(binDir, 'etc', 'default.ini');
+        // CouchDB uses COUCHDB_INI_FILES to load config files in order
+        // COUCHDB_ARGS_FILE specifies custom vm.args with unique node name
+        // On Windows, CouchDB may need additional paths set
+        const env = {
+            ...process.env,
+            COUCHDB_INI_FILES: `${defaultIni} ${configPath}`,
+            COUCHDB_ARGS_FILE: vmArgsPath,
+            // Set CouchDB binary directory for Windows
+            COUCHDB_BINDIR: join(binDir, 'bin'),
+            COUCHDB_QUERY_SERVER_JAVASCRIPT: join(binDir, 'bin', 'couchjs'),
+        };
+        // On Windows, use sys.config to disable os_mon before it starts
+        // The vm.args settings are too late - os_mon crashes during init
+        // Erlang reads releases/sys.config at startup, so we modify that file
+        if (isWindows()) {
+            const sysConfigContent = generateSysConfig();
+            // The CRITICAL location - Erlang release reads from releases/sys.config
+            const releasesSysConfig = join(binDir, 'releases', 'sys.config');
+            await writeFile(releasesSysConfig, sysConfigContent);
+            // Copy vm.args to where Windows CouchDB expects it
+            const expectedVmArgs = join(binDir, 'etc', 'vm.args');
+            await writeFile(expectedVmArgs, vmArgsContent);
+            // Also update releases/vm.args
+            const releasesVmArgs = join(binDir, 'releases', 'vm.args');
+            await writeFile(releasesVmArgs, vmArgsContent);
+            // CRITICAL: Write config to binary's etc/local.ini
+            // Windows CouchDB doesn't respect COUCHDB_INI_FILES env var and may not scan local.d/
+            // Write directly to etc/local.ini which CouchDB definitely reads
+            // Note: This means only one container can run per binary install (typical for local dev)
+            const localIniPath = join(binDir, 'etc', 'local.ini');
+            await writeFile(localIniPath, configContent);
+            logDebug(`Wrote config to ${localIniPath}`);
+            // Modify the os_mon.app file directly to disable features
+            // This sets the default env values in the application spec itself
+            const osMonAppPath = join(binDir, 'lib', 'os_mon-2.9.1', 'ebin', 'os_mon.app');
+            try {
+                const osMonApp = await readFile(osMonAppPath, 'utf8');
+                // Replace the default env settings to disable all features
+                const modifiedApp = osMonApp
+                    .replace('{start_cpu_sup, true}', '{start_cpu_sup, false}')
+                    .replace('{start_disksup, true}', '{start_disksup, false}')
+                    .replace('{start_memsup, true}', '{start_memsup, false}');
+                await writeFile(osMonAppPath, modifiedApp);
+                logDebug('Modified os_mon.app to disable features');
+            }
+            catch (err) {
+                logDebug(`Failed to modify os_mon.app: ${err}`);
+            }
+            // Add os_mon priv/bin to PATH so win32sysinfo.exe can be found
+            const osMonPrivBin = join(binDir, 'lib', 'os_mon-2.9.1', 'priv', 'bin');
+            const existingPath = env.PATH || process.env.PATH || '';
+            env.PATH = `${osMonPrivBin};${existingPath}`;
+            logDebug(`Wrote sys.config to ${releasesSysConfig}`);
+            logDebug(`Wrote vm.args to ${releasesVmArgs}`);
+            logDebug(`Added to PATH: ${osMonPrivBin}`);
+        }
+        // Spawn CouchDB process
+        if (isWindows()) {
+            return new Promise((resolve, reject) => {
+                // On Windows, run from the CouchDB installation directory
+                // The Erlang VM expects to find files relative to its installation
+                const spawnOpts = {
+                    cwd: binDir,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    detached: true,
+                    windowsHide: true,
+                    env,
+                };
+                // On Windows, .cmd files must be executed via cmd.exe
+                const proc = spawn('cmd.exe', ['/c', couchdbServer], spawnOpts);
+                let settled = false;
+                let stderrOutput = '';
+                let stdoutOutput = '';
+                proc.on('error', (err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    reject(new Error(`Failed to spawn CouchDB server: ${err.message}`));
+                });
+                proc.on('exit', (code, signal) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    const reason = signal ? `signal ${signal}` : `code ${code}`;
+                    reject(new Error(`CouchDB process exited unexpectedly (${reason}).\n` +
+                        `Stderr: ${stderrOutput || '(none)'}\n` +
+                        `Stdout: ${stdoutOutput || '(none)'}`));
+                });
+                proc.stdout?.on('data', (data) => {
+                    stdoutOutput += data.toString();
+                });
+                proc.stderr?.on('data', (data) => {
+                    stderrOutput += data.toString();
+                });
+                proc.unref();
+                setTimeout(async () => {
+                    if (settled)
+                        return;
+                    if (!proc.pid) {
+                        settled = true;
+                        reject(new Error('CouchDB server process failed to start (no PID)'));
+                        return;
+                    }
+                    try {
+                        await writeFile(pidFile, String(proc.pid));
+                    }
+                    catch {
+                        // Non-fatal
+                    }
+                    const ready = await this.waitForReady(port);
+                    if (settled)
+                        return;
+                    if (ready) {
+                        settled = true;
+                        resolve({
+                            port,
+                            connectionString: this.getConnectionString(container),
+                        });
+                    }
+                    else {
+                        settled = true;
+                        if (proc.pid && platformService.isProcessRunning(proc.pid)) {
+                            try {
+                                await platformService.terminateProcess(proc.pid, true);
+                            }
+                            catch {
+                                // Ignore cleanup errors
+                            }
+                        }
+                        reject(new Error(`CouchDB failed to start within timeout.\n` +
+                            `Binary: ${couchdbServer}\n` +
+                            `Config: ${configPath}\n` +
+                            `Log file: ${logFile}`));
+                    }
+                }, 500);
+            });
+        }
+        // macOS/Linux
+        const proc = spawn(couchdbServer, [], {
+            cwd: containerDir,
+            stdio: ['ignore', 'ignore', 'ignore'],
+            detached: true,
+            env,
+        });
+        proc.unref();
+        if (!proc.pid) {
+            throw new Error('CouchDB server process failed to start (no PID)');
+        }
+        try {
+            await writeFile(pidFile, String(proc.pid));
+        }
+        catch {
+            // Non-fatal
+        }
+        const ready = await this.waitForReady(port);
+        if (ready) {
+            return {
+                port,
+                connectionString: this.getConnectionString(container),
+            };
+        }
+        throw new Error(`CouchDB failed to start within timeout.\n` +
+            `Binary: ${couchdbServer}\n` +
+            `Config: ${configPath}\n` +
+            `Log file: ${logFile}`);
+    }
+    // Wait for CouchDB to be ready
+    async waitForReady(port, timeoutMs = 30000) {
+        const startTime = Date.now();
+        const checkInterval = 500;
+        while (Date.now() - startTime < timeoutMs) {
+            try {
+                const response = await couchdbApiRequest(port, 'GET', '/');
+                if (response.status === 200) {
+                    logDebug(`CouchDB ready on port ${port}`);
+                    return true;
+                }
+            }
+            catch {
+                // Connection failed, wait and retry
+            }
+            await new Promise((resolve) => setTimeout(resolve, checkInterval));
+        }
+        logDebug(`CouchDB did not become ready within ${timeoutMs}ms`);
+        return false;
+    }
+    /**
+     * Stop CouchDB server
+     */
+    async stop(container) {
+        const { name, port } = container;
+        const containerDir = paths.getContainerPath(name, { engine: ENGINE });
+        const pidFile = join(containerDir, 'couchdb.pid');
+        logDebug(`Stopping CouchDB container "${name}" on port ${port}`);
+        let pid = null;
+        if (existsSync(pidFile)) {
+            try {
+                const content = await readFile(pidFile, 'utf8');
+                pid = parseInt(content.trim(), 10);
+            }
+            catch {
+                // Ignore
+            }
+        }
+        if (pid && platformService.isProcessRunning(pid)) {
+            logDebug(`Killing CouchDB process ${pid}`);
+            try {
+                if (isWindows()) {
+                    await platformService.terminateProcess(pid, true);
+                }
+                else {
+                    await platformService.terminateProcess(pid, false);
+                    await new Promise((resolve) => setTimeout(resolve, 2000));
+                    if (platformService.isProcessRunning(pid)) {
+                        logWarning(`Graceful termination failed, force killing ${pid}`);
+                        await platformService.terminateProcess(pid, true);
+                    }
+                }
+            }
+            catch (error) {
+                logDebug(`Process termination error: ${error}`);
+            }
+        }
+        if (isWindows()) {
+            await new Promise((resolve) => setTimeout(resolve, 3000));
+        }
+        // Kill any processes still listening on the port
+        const portPids = await platformService.findProcessByPort(port);
+        for (const portPid of portPids) {
+            if (platformService.isProcessRunning(portPid)) {
+                logDebug(`Killing process ${portPid} still on port ${port}`);
+                try {
+                    await platformService.terminateProcess(portPid, true);
+                }
+                catch {
+                    // Ignore
+                }
+            }
+        }
+        if (isWindows() && portPids.length > 0) {
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+        }
+        // Cleanup PID file
+        if (existsSync(pidFile)) {
+            try {
+                await unlink(pidFile);
+            }
+            catch {
+                // Ignore
+            }
+        }
+        // Note: On Windows, we write to etc/local.ini which gets overwritten on each start
+        // No cleanup needed as the file is shared and will be updated on next container start
+        // Wait for port to be released on Windows
+        if (isWindows()) {
+            logDebug(`Waiting for port ${port} to be released...`);
+            const portWaitStart = Date.now();
+            const portWaitTimeout = 30000;
+            const checkInterval = 500;
+            while (Date.now() - portWaitStart < portWaitTimeout) {
+                if (await portManager.isPortAvailable(port)) {
+                    logDebug('Port released successfully');
+                    break;
+                }
+                await new Promise((resolve) => setTimeout(resolve, checkInterval));
+            }
+        }
+        logDebug('CouchDB stopped');
+    }
+    // Get CouchDB server status
+    async status(container) {
+        const { name, port } = container;
+        const containerDir = paths.getContainerPath(name, { engine: ENGINE });
+        const pidFile = join(containerDir, 'couchdb.pid');
+        // Try health check via REST API
+        try {
+            const response = await couchdbApiRequest(port, 'GET', '/');
+            if (response.status === 200) {
+                return { running: true, message: 'CouchDB is running' };
+            }
+        }
+        catch {
+            // Not responding, check PID
+        }
+        // Check PID file
+        if (existsSync(pidFile)) {
+            try {
+                const content = await readFile(pidFile, 'utf8');
+                const pid = parseInt(content.trim(), 10);
+                if (!isNaN(pid) && pid > 0 && platformService.isProcessRunning(pid)) {
+                    return {
+                        running: true,
+                        message: `CouchDB is running (PID: ${pid})`,
+                    };
+                }
+            }
+            catch {
+                // Ignore
+            }
+        }
+        return { running: false, message: 'CouchDB is not running' };
+    }
+    // Detect backup format
+    async detectBackupFormat(filePath) {
+        return detectBackupFormatImpl(filePath);
+    }
+    /**
+     * Restore a backup
+     * CouchDB can restore while running (uses REST API)
+     */
+    async restore(container, backupPath, options = {}) {
+        const { port } = container;
+        return restoreBackup(backupPath, {
+            port,
+            database: options.database,
+            flush: options.flush,
+        });
+    }
+    /**
+     * Get connection string
+     * Format: http://127.0.0.1:PORT
+     */
+    getConnectionString(container, database) {
+        const { port } = container;
+        const base = `http://127.0.0.1:${port}`;
+        return database ? `${base}/${database}` : base;
+    }
+    // Open Fauxton web UI
+    async connect(container, _database) {
+        const { port } = container;
+        const url = `http://127.0.0.1:${port}/_utils`;
+        console.log(`CouchDB REST API available at: http://127.0.0.1:${port}`);
+        console.log(`CouchDB Fauxton UI: ${url}`);
+        console.log('');
+        console.log('Example commands:');
+        console.log(`  curl http://127.0.0.1:${port}`);
+        console.log(`  curl http://127.0.0.1:${port}/_all_dbs`);
+    }
+    /**
+     * Create a new database
+     */
+    async createDatabase(container, database) {
+        const { port } = container;
+        const response = await couchdbApiRequest(port, 'PUT', `/${encodeURIComponent(database)}`);
+        if (response.status !== 201 && response.status !== 412) {
+            // 412 means database already exists
+            throw new Error(`Failed to create database: ${JSON.stringify(response.data)}`);
+        }
+        logDebug(`Created CouchDB database: ${database}`);
+    }
+    /**
+     * Drop a database
+     */
+    async dropDatabase(container, database) {
+        const { port } = container;
+        const response = await couchdbApiRequest(port, 'DELETE', `/${encodeURIComponent(database)}`);
+        // Accept 200 (OK) or 202 (Accepted) for async deletes
+        if (response.status !== 200 && response.status !== 202) {
+            throw new Error(`Failed to delete database: ${JSON.stringify(response.data)}`);
+        }
+        logDebug(`Deleted CouchDB database: ${database} (status: ${response.status})`);
+    }
+    /**
+     * Get the size of the CouchDB instance
+     */
+    async getDatabaseSize(container) {
+        const { port } = container;
+        try {
+            // CouchDB doesn't directly expose total size, but we can sum up database sizes
+            const dbsResponse = await couchdbApiRequest(port, 'GET', '/_all_dbs');
+            if (dbsResponse.status !== 200) {
+                return null;
+            }
+            const dbs = dbsResponse.data;
+            let totalSize = 0;
+            for (const db of dbs) {
+                if (db.startsWith('_'))
+                    continue; // Skip system dbs
+                const infoResponse = await couchdbApiRequest(port, 'GET', `/${encodeURIComponent(db)}`);
+                if (infoResponse.status === 200) {
+                    const info = infoResponse.data;
+                    totalSize += info.sizes?.file || 0;
+                }
+            }
+            return totalSize > 0 ? totalSize : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Dump from a remote CouchDB connection
+     */
+    async dumpFromConnectionString(connectionString, outputPath) {
+        const { baseUrl, headers, database } = parseCouchDBConnectionString(connectionString);
+        logDebug(`Connecting to remote CouchDB at ${baseUrl}`);
+        // Check connectivity
+        const infoResponse = await remoteCouchDBRequest(baseUrl, 'GET', '/', headers);
+        if (infoResponse.status !== 200) {
+            throw new Error(`Failed to connect to CouchDB at ${baseUrl}: ${JSON.stringify(infoResponse.data)}`);
+        }
+        const serverInfo = infoResponse.data;
+        logDebug(`Connected to CouchDB ${serverInfo?.version || 'unknown'}`);
+        // Get databases to backup
+        let databasesToBackup;
+        if (database) {
+            databasesToBackup = [database];
+        }
+        else {
+            const dbsResponse = await remoteCouchDBRequest(baseUrl, 'GET', '/_all_dbs', headers);
+            if (dbsResponse.status !== 200) {
+                throw new Error(`Failed to list databases: ${JSON.stringify(dbsResponse.data)}`);
+            }
+            const allDbs = dbsResponse.data;
+            databasesToBackup = allDbs.filter((db) => !db.startsWith('_'));
+        }
+        logDebug(`Backing up ${databasesToBackup.length} database(s)`);
+        // Export documents from each database
+        const backup = {
+            version: serverInfo?.version || 'unknown',
+            created: new Date().toISOString(),
+            databases: [],
+        };
+        for (const dbName of databasesToBackup) {
+            logDebug(`Exporting database: ${dbName}`);
+            const docsResponse = await remoteCouchDBRequest(baseUrl, 'GET', `/${encodeURIComponent(dbName)}/_all_docs?include_docs=true`, headers, undefined, 300000);
+            if (docsResponse.status !== 200) {
+                throw new Error(`Failed to export database ${dbName}: ${JSON.stringify(docsResponse.data)}`);
+            }
+            const docsData = docsResponse.data;
+            const docs = docsData.rows
+                ?.map((row) => row.doc)
+                .filter((doc) => doc !== undefined) || [];
+            // Filter out design documents
+            const userDocs = docs.filter((doc) => {
+                const d = doc;
+                return d._id && !d._id.startsWith('_design/');
+            });
+            backup.databases.push({
+                name: dbName,
+                docs: userDocs,
+            });
+        }
+        // Write backup to file
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, JSON.stringify(backup, null, 2));
+        return {
+            filePath: outputPath,
+            warnings: databasesToBackup.length === 0
+                ? ['Remote CouchDB instance has no user databases']
+                : undefined,
+        };
+    }
+    // Create a backup
+    async backup(container, outputPath, options) {
+        return createBackup(container, outputPath, options);
+    }
+    // Run a command - CouchDB uses REST API, not command files
+    async runScript(container, options) {
+        const { port } = container;
+        if (options.file) {
+            throw new Error('CouchDB does not support command files. Use the REST API directly.\n' +
+                `Example: curl http://127.0.0.1:${port}/_all_dbs`);
+        }
+        if (options.sql) {
+            const command = options.sql.trim().toUpperCase();
+            if (command === 'LIST DATABASES' || command === 'SHOW DATABASES') {
+                const response = await couchdbApiRequest(port, 'GET', '/_all_dbs');
+                console.log(JSON.stringify(response.data, null, 2));
+                return;
+            }
+            throw new Error('CouchDB uses REST API for operations. Use curl or the CouchDB client libraries.\n' +
+                `API endpoint: http://127.0.0.1:${port}`);
+        }
+        throw new Error('Either file or sql option must be provided');
+    }
+    /**
+     * Execute a query via REST API
+     *
+     * Query format: METHOD /path [JSON body]
+     * Examples:
+     *   GET /_all_dbs
+     *   GET /mydb/_all_docs
+     *   POST /mydb/_find {"selector": {"type": "user"}}
+     */
+    async executeQuery(container, query, options) {
+        const { port } = container;
+        // Parse the query string: METHOD /path [body]
+        // If options?.method is provided, query can be just the path
+        const trimmed = query.trim();
+        const spaceIdx = trimmed.indexOf(' ');
+        let method;
+        let rest;
+        if (options?.method) {
+            // Method provided via options
+            method = options.method;
+            if (spaceIdx !== -1) {
+                // Check if first token looks like a method (GET, POST, etc.)
+                const firstToken = trimmed.substring(0, spaceIdx).toUpperCase();
+                if (['GET', 'POST', 'PUT', 'DELETE'].includes(firstToken)) {
+                    // Query has method prefix, use rest after it
+                    rest = trimmed.substring(spaceIdx + 1).trim();
+                }
+                else {
+                    // Query is path + body, use entire trimmed
+                    rest = trimmed;
+                }
+            }
+            else {
+                // Query is just the path
+                rest = trimmed;
+            }
+        }
+        else {
+            // No method in options, must parse from query
+            if (spaceIdx === -1) {
+                throw new Error('Invalid query format. Expected: METHOD /path [body]\n' +
+                    'Example: GET /_all_dbs');
+            }
+            method = trimmed.substring(0, spaceIdx).toUpperCase();
+            rest = trimmed.substring(spaceIdx + 1).trim();
+        }
+        // Extract path and optional JSON body
+        let path;
+        let body = options?.body;
+        const bodyStart = rest.indexOf('{');
+        if (bodyStart !== -1 && !body) {
+            path = rest.substring(0, bodyStart).trim();
+            try {
+                body = JSON.parse(rest.substring(bodyStart));
+            }
+            catch {
+                throw new Error('Invalid JSON body in query');
+            }
+        }
+        else {
+            path = rest;
+        }
+        // Ensure path starts with /
+        if (!path.startsWith('/')) {
+            path = '/' + path;
+        }
+        const response = await couchdbApiRequest(port, method, path, body);
+        if (response.status >= 400) {
+            throw new Error(`CouchDB API error (${response.status}): ${JSON.stringify(response.data)}`);
+        }
+        return parseRESTAPIResult(JSON.stringify(response.data));
+    }
+    /**
+     * List all user databases, excluding system databases (_users, _replicator, _global_changes).
+     */
+    async listDatabases(container) {
+        const { port } = container;
+        const response = await couchdbApiRequest(port, 'GET', '/_all_dbs');
+        if (response.status >= 400) {
+            throw new Error(`CouchDB API error (${response.status}): ${JSON.stringify(response.data)}`);
+        }
+        const allDatabases = response.data;
+        const systemDatabases = ['_users', '_replicator', '_global_changes'];
+        const databases = allDatabases.filter((db) => !systemDatabases.includes(db) && !db.startsWith('_'));
+        return databases;
+    }
+    async createUser(container, options) {
+        const { username, password, database } = options;
+        assertValidUsername(username);
+        const { port } = container;
+        const db = database || container.database;
+        if (!db) {
+            throw new Error('No database specified. Use --database or create a database first.');
+        }
+        // Ensure _users system database exists (CouchDB 3.x doesn't auto-create it)
+        const usersDbResponse = await couchdbApiRequest(port, 'PUT', '/_users');
+        if (usersDbResponse.status !== 201 && usersDbResponse.status !== 412) {
+            throw new Error(`Failed to ensure _users database exists: ${JSON.stringify(usersDbResponse.data)}`);
+        }
+        // Create user document in _users database
+        const userDoc = {
+            _id: `org.couchdb.user:${username}`,
+            name: username,
+            type: 'user',
+            roles: [],
+            password,
+        };
+        const createResponse = await couchdbApiRequest(port, 'PUT', `/_users/org.couchdb.user:${encodeURIComponent(username)}`, userDoc);
+        if (createResponse.status !== 201 && createResponse.status !== 409) {
+            throw new Error(`Failed to create user: ${JSON.stringify(createResponse.data)}`);
+        }
+        if (createResponse.status === 409) {
+            // User exists — fetch current doc revision and update password
+            const getResponse = await couchdbApiRequest(port, 'GET', `/_users/org.couchdb.user:${encodeURIComponent(username)}`);
+            if (getResponse.status !== 200 || !getResponse.data) {
+                throw new Error(`Failed to fetch existing user "${username}" (status ${getResponse.status}): ${JSON.stringify(getResponse.data)}`);
+            }
+            const existingDoc = getResponse.data;
+            const rev = existingDoc._rev;
+            if (!rev) {
+                throw new Error(`User "${username}" already exists but document has no _rev field: ${JSON.stringify(getResponse.data)}`);
+            }
+            const updateResponse = await couchdbApiRequest(port, 'PUT', `/_users/org.couchdb.user:${encodeURIComponent(username)}`, { ...existingDoc, password, _rev: rev });
+            if (updateResponse.status !== 201) {
+                throw new Error(`Failed to update user: ${JSON.stringify(updateResponse.data)}`);
+            }
+        }
+        // Ensure the target database exists before setting security
+        const dbCreateResponse = await couchdbApiRequest(port, 'PUT', `/${encodeURIComponent(db)}`);
+        // 201 = created, 412 = already exists — both are fine
+        if (dbCreateResponse.status !== 201 && dbCreateResponse.status !== 412) {
+            throw new Error(`Failed to ensure database "${db}" exists: ${JSON.stringify(dbCreateResponse.data)}`);
+        }
+        // Grant access to the target database via _security document
+        const secResponse = await couchdbApiRequest(port, 'GET', `/${encodeURIComponent(db)}/_security`);
+        if (secResponse.status !== 200) {
+            throw new Error(`Failed to read database security for "${db}": ${JSON.stringify(secResponse.data)}`);
+        }
+        const security = (secResponse.data || {});
+        const members = (security.members || {});
+        const names = (members.names || []).slice();
+        if (!names.includes(username)) {
+            names.push(username);
+        }
+        const secPutResponse = await couchdbApiRequest(port, 'PUT', `/${encodeURIComponent(db)}/_security`, {
+            ...security,
+            members: { ...members, names },
+        });
+        if (secPutResponse.status !== 200 && secPutResponse.status !== 201) {
+            throw new Error(`Failed to update database security for "${db}": ${JSON.stringify(secPutResponse.data)}`);
+        }
+        logDebug(`Created CouchDB user: ${username}`);
+        const connectionString = `http://${encodeURIComponent(username)}:${encodeURIComponent(password)}@127.0.0.1:${port}/${encodeURIComponent(db)}`;
+        return {
+            username,
+            password,
+            connectionString,
+            engine: container.engine,
+            container: container.name,
+            database: db,
+        };
+    }
+}
+export const couchdbEngine = new CouchDBEngine();
+//# sourceMappingURL=index.js.map