spindb 0.32.2 → 0.33.1

package/engines/influxdb/README.md

@@ -0,0 +1,180 @@
+# InfluxDB Engine Implementation
+
+## Overview
+
+InfluxDB 3.x is a time-series database rewritten in Rust. It uses a REST API for all operations (no CLI client). InfluxDB 3.x supports SQL queries via its HTTP API, unlike earlier versions which used InfluxQL/Flux.
+
+## 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
+```text
+influxdb/
+├── influxdb3           # Server binary
+├── python/             # Bundled Python runtime
+│   └── lib/
+│       └── libpython3.13.dylib
+├── LICENSE-APACHE
+└── LICENSE-MIT
+```
+
+### Binary + Python Runtime
+InfluxDB 3.x ships as a single `influxdb3` binary that acts as the server, bundled with a Python runtime. The binary uses `@executable_path/python/lib/libpython3.13.dylib`, so the `python/` directory must be co-located with the binary. The custom `moveExtractedEntries` override ensures both end up in `bin/`. There is no separate CLI client — all interactions use the REST API.
+
+### Version Map Sync
+
+```typescript
+export const INFLUXDB_VERSION_MAP: Record<string, string> = {
+  '3': '3.8.0',
+}
+```
+
+## Implementation Details
+
+### Binary Manager
+
+InfluxDB uses `BaseBinaryManager` since it's a server-based engine with single-digit major versions:
+
+```typescript
+class InfluxDBBinaryManager extends BaseBinaryManager {
+  protected readonly config = {
+    engine: Engine.InfluxDB,
+    engineName: 'influxdb',
+    displayName: 'InfluxDB',
+    serverBinary: 'influxdb3',
+  }
+}
+```
+
+### REST API Engine
+
+InfluxDB is a **REST API engine**:
+- `spindb run` is **NOT applicable** (scriptFileLabel is `null`)
+- `spindb connect` opens the health endpoint info in terminal
+- All operations use HTTP REST API
+
+### Default Configuration
+
+- **Default Port**: 8086
+- **Health Endpoint**: `GET /health`
+- **SQL Query Endpoint**: `POST /api/v3/query_sql`
+- **Write Endpoint**: `POST /api/v3/write_lp`
+- **No Authentication**: InfluxDB 3.x local dev has no auth by default
+- **PID File**: `influxdb.pid` in container directory
+
+### Database Creation
+
+InfluxDB 3.x creates databases **implicitly on first write**. There is no explicit `CREATE DATABASE` command. When you write data with a database name, it's auto-created.
+
+### Connection String Format
+
+```text
+http://127.0.0.1:{port}
+```
+
+## Backup & Restore
+
+### Backup Formats
+
+| Format | Extension | Method | Notes |
+|--------|-----------|--------|-------|
+| sql | `.sql` | REST API | SQL dump with CREATE TABLE + INSERT statements |
+
+### Backup Method
+
+Uses InfluxDB's SQL query API to export data:
+1. `SHOW TABLES` — lists all tables/measurements
+2. `SELECT * FROM {table}` — exports all data per table
+3. Generates SQL INSERT statements for restore
+
+### Restore Method
+
+Parses SQL dump file and executes statements via `POST /api/v3/query_sql`.
+
+## Integration Test Notes
+
+### REST API Testing
+
+Integration tests use `fetch()` to interact with InfluxDB REST API.
+
+### Test Fixtures
+
+Located in `tests/fixtures/influxdb/seeds/`:
+- `README.md` documenting the API-based approach
+
+## Known Issues & Gotchas
+
+### 1. No CLI Client
+
+InfluxDB 3.x has no bundled CLI client. All operations use the HTTP REST API. The `clientTools` array in engine-defaults is empty.
+
+### 2. Implicit Database Creation
+
+Databases are created on first write, not via explicit commands. `createDatabase()` verifies server health but doesn't create anything.
+
+### 3. SQL Query Support
+
+InfluxDB 3.x supports SQL queries (not InfluxQL or Flux from v1/v2). Query via:
+```bash
+curl -X POST http://localhost:8086/api/v3/query_sql \
+  -H "Content-Type: application/json" \
+  -d '{"db":"mydb","q":"SELECT * FROM measurement","format":"json"}'
+```
+
+### 4. Write via Line Protocol
+
+Data writes use InfluxDB line protocol format:
+```bash
+curl -X POST "http://localhost:8086/api/v3/write_lp?db=mydb" \
+  -H "Content-Type: text/plain" \
+  -d 'measurement,tag=value field=123'
+```
+
+### 5. Windows PID Handling
+
+On Windows, uses `platformService.findProcessByPort(port)` after startup to find the real PID, similar to QuestDB/TypeDB pattern.
+
+## REST API Quick Reference
+
+### Health
+```bash
+GET /health
+```
+
+### Query (SQL)
+```bash
+POST /api/v3/query_sql
+Content-Type: application/json
+{"db":"mydb","q":"SELECT 1","format":"json"}
+```
+
+### Write (Line Protocol)
+```bash
+POST /api/v3/write_lp?db=mydb
+Content-Type: text/plain
+measurement,tag=value field=123
+```
+
+### Show Tables
+```bash
+POST /api/v3/query_sql
+{"db":"mydb","q":"SHOW TABLES","format":"json"}
+```
+
+### List Databases
+```bash
+GET /api/v3/configure/database?format=json
+```

package/engines/influxdb/api-client.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared InfluxDB REST API client utilities
+ */
+
+/**
+ * Make an HTTP request to InfluxDB REST API
+ *
+ * @param port - The HTTP port InfluxDB is listening on
+ * @param method - HTTP method (GET, POST, PUT, DELETE)
+ * @param path - API path (e.g., '/health', '/api/v3/query_sql')
+ * @param body - Optional body: object for JSON, string for text/plain (line protocol)
+ * @param timeoutMs - Request timeout in milliseconds (default: 30s)
+ */
+export async function influxdbApiRequest(
+  port: number,
+  method: string,
+  path: string,
+  body?: Record<string, unknown> | string,
+  timeoutMs = 30000,
+): 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 options: RequestInit = {
+    method,
+    signal: controller.signal,
+  }
+
+  if (body !== undefined) {
+    if (typeof body === 'string') {
+      options.headers = { 'Content-Type': 'text/plain' }
+      options.body = body
+    } else {
+      options.headers = { 'Content-Type': 'application/json' }
+      options.body = JSON.stringify(body)
+    }
+  }
+
+  try {
+    const response = await fetch(url, options)
+
+    // Try to parse as JSON, fall back to text for endpoints like /health
+    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(
+        `InfluxDB API request timed out after ${timeoutMs / 1000}s: ${method} ${path}`,
+      )
+    }
+    throw error
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}

package/engines/influxdb/backup.ts

@@ -0,0 +1,160 @@
+/**
+ * InfluxDB backup module
+ * Supports SQL-based backup using InfluxDB's REST API to export data
+ */
+
+import { mkdir, stat, writeFile } from 'fs/promises'
+import { existsSync } from 'fs'
+import { dirname } from 'path'
+import { logDebug } from '../../core/error-handler'
+import { influxdbApiRequest } from './api-client'
+import type { ContainerConfig, BackupOptions, BackupResult } from '../../types'
+
+/**
+ * Create an SQL backup using InfluxDB's REST API
+ * Queries all tables and exports data as SQL INSERT statements
+ */
+export async function createBackup(
+  container: ContainerConfig,
+  outputPath: string,
+  options: BackupOptions,
+): Promise<BackupResult> {
+  const { port } = container
+  const database = options.database || container.database
+
+  // Ensure output directory exists
+  const outputDir = dirname(outputPath)
+  if (!existsSync(outputDir)) {
+    await mkdir(outputDir, { recursive: true })
+  }
+
+  logDebug(
+    `Creating InfluxDB SQL backup via REST API on port ${port} for database "${database}"`,
+  )
+
+  // Get list of tables in the database
+  const tablesResponse = await influxdbApiRequest(
+    port,
+    'POST',
+    '/api/v3/query_sql',
+    {
+      db: database,
+      q: 'SHOW TABLES',
+      format: 'json',
+    },
+  )
+
+  if (tablesResponse.status !== 200) {
+    throw new Error(
+      `Failed to list tables: ${JSON.stringify(tablesResponse.data)}`,
+    )
+  }
+
+  const tablesData = tablesResponse.data as Array<Record<string, unknown>>
+  const tables: string[] = []
+
+  // Extract user table names: include rows with 'iox' schema or no schema field,
+  // skip system schemas (information_schema, system, etc.)
+  if (Array.isArray(tablesData)) {
+    for (const row of tablesData) {
+      const schema = row.table_schema as string | undefined
+      if (schema && schema !== 'iox') continue
+      const tableName =
+        (row.table_name as string) ||
+        (row.name as string) ||
+        (Object.values(row)[0] as string)
+      if (tableName) {
+        tables.push(tableName)
+      }
+    }
+  }
+
+  logDebug(`Found ${tables.length} tables: ${tables.join(', ')}`)
+
+  // Build SQL dump
+  let sqlContent = `-- InfluxDB SQL Backup\n`
+  sqlContent += `-- Database: ${database}\n`
+  sqlContent += `-- Created: ${new Date().toISOString()}\n\n`
+
+  for (const table of tables) {
+    logDebug(`Exporting table: ${table}`)
+
+    // Query column metadata to identify tag columns
+    // Tags use Dictionary(Int32, Utf8) type in InfluxDB 3.x
+    const tagColumns: string[] = []
+    try {
+      const colResponse = await influxdbApiRequest(
+        port,
+        'POST',
+        '/api/v3/query_sql',
+        {
+          db: database,
+          q: `SELECT column_name, data_type FROM information_schema.columns WHERE table_name = '${table.replace(/'/g, "''")}'`,
+          format: 'json',
+        },
+      )
+      if (colResponse.status === 200 && Array.isArray(colResponse.data)) {
+        for (const col of colResponse.data as Array<Record<string, unknown>>) {
+          const dataType = String(col.data_type || '')
+          if (dataType.includes('Dictionary')) {
+            tagColumns.push(String(col.column_name))
+          }
+        }
+      }
+    } catch {
+      logDebug(`Warning: Could not query column metadata for ${table}`)
+    }
+
+    // Query all data from the table
+    const dataResponse = await influxdbApiRequest(
+      port,
+      'POST',
+      '/api/v3/query_sql',
+      {
+        db: database,
+        q: `SELECT * FROM "${table.replace(/"/g, '""')}"`,
+        format: 'json',
+      },
+    )
+
+    if (dataResponse.status !== 200) {
+      logDebug(
+        `Warning: Failed to export table ${table}: ${JSON.stringify(dataResponse.data)}`,
+      )
+      continue
+    }
+
+    const rows = dataResponse.data as Array<Record<string, unknown>>
+
+    if (Array.isArray(rows) && rows.length > 0) {
+      sqlContent += `-- Table: ${table}\n`
+      if (tagColumns.length > 0) {
+        sqlContent += `-- Tags: ${tagColumns.join(', ')}\n`
+      }
+
+      for (const row of rows) {
+        const columns = Object.keys(row)
+        const values = columns.map((col) => {
+          const val = row[col]
+          if (val === null || val === undefined) return 'NULL'
+          if (typeof val === 'number') return String(val)
+          if (typeof val === 'boolean') return val ? 'true' : 'false'
+          return `'${String(val).replace(/'/g, "''")}'`
+        })
+        sqlContent += `INSERT INTO "${table.replace(/"/g, '""')}" (${columns.map((c) => `"${c.replace(/"/g, '""')}"`).join(', ')}) VALUES (${values.join(', ')});\n`
+      }
+      sqlContent += '\n'
+    }
+  }
+
+  // Write SQL content to file
+  await writeFile(outputPath, sqlContent, 'utf-8')
+
+  const stats = await stat(outputPath)
+
+  return {
+    path: outputPath,
+    format: 'sql',
+    size: stats.size,
+  }
+}

package/engines/influxdb/binary-manager.ts

@@ -0,0 +1,110 @@
+/**
+ * InfluxDB Binary Manager
+ *
+ * Handles downloading, extracting, and managing InfluxDB binaries from hostdb.
+ * Extends BaseBinaryManager for shared download/extraction logic.
+ *
+ * InfluxDB 3.x archives extract to a flat `influxdb/` directory:
+ *   influxdb/
+ *   ├── influxdb3           (server binary)
+ *   ├── python/             (bundled Python runtime)
+ *   │   └── lib/
+ *   │       └── libpython3.13.dylib
+ *   ├── LICENSE-APACHE
+ *   └── LICENSE-MIT
+ *
+ * The binary uses @executable_path/python/lib/libpython3.13.dylib, so python/
+ * must be in the same directory as the binary. We reorganize to:
+ *   bin/
+ *   ├── influxdb3
+ *   └── python/             (co-located for @executable_path resolution)
+ */
+
+import { mkdir, readdir } from 'fs/promises'
+import { join } from 'path'
+import {
+  BaseBinaryManager,
+  type BinaryManagerConfig,
+} from '../../core/base-binary-manager'
+import { moveEntry } from '../../core/fs-error-utils'
+import { logDebug } from '../../core/error-handler'
+import { getBinaryUrl } from './binary-urls'
+import { normalizeVersion } from './version-maps'
+import { Engine, type Platform, type Arch } from '../../types'
+
+class InfluxDBBinaryManager extends BaseBinaryManager {
+  protected readonly config: BinaryManagerConfig = {
+    engine: Engine.InfluxDB,
+    engineName: 'influxdb',
+    displayName: 'InfluxDB',
+    serverBinary: 'influxdb3',
+  }
+
+  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 "influxdb3 3.8.0" or "InfluxDB 3 Edge v3.8.0"
+    const match = stdout.match(/v?(\d+\.\d+\.\d+)/)
+    return match?.[1] ?? null
+  }
+
+  /**
+   * Override moveExtractedEntries to co-locate python/ with the binary.
+   *
+   * The influxdb3 binary references @executable_path/python/lib/libpython3.13.dylib,
+   * so the python/ directory must be inside bin/ alongside the binary.
+   * The default flat-structure handler would put python/ at binPath/python/ instead
+   * of binPath/bin/python/, causing a dylib load failure.
+   */
+  protected override async moveExtractedEntries(
+    extractDir: string,
+    binPath: string,
+  ): Promise<void> {
+    const entries = await readdir(extractDir, { withFileTypes: true })
+
+    // Find the influxdb directory (e.g., "influxdb" or "influxdb-3.8.0")
+    const influxDir = entries.find(
+      (e) =>
+        e.isDirectory() &&
+        (e.name === 'influxdb' || e.name.startsWith('influxdb-')),
+    )
+
+    const sourceDir = influxDir ? join(extractDir, influxDir.name) : extractDir
+    const sourceEntries = influxDir
+      ? await readdir(sourceDir, { withFileTypes: true })
+      : entries
+
+    // Create bin/ directory
+    const destBinDir = join(binPath, 'bin')
+    await mkdir(destBinDir, { recursive: true })
+
+    for (const entry of sourceEntries) {
+      const sourcePath = join(sourceDir, entry.name)
+
+      if (entry.name === 'influxdb3' || entry.name === 'influxdb3.exe') {
+        // Server binary → bin/
+        await moveEntry(sourcePath, join(destBinDir, entry.name))
+      } else if (entry.name === 'python') {
+        // Python runtime → bin/python/ (must be co-located with binary for @executable_path)
+        await moveEntry(sourcePath, join(destBinDir, 'python'))
+      } else {
+        // Licenses, metadata, etc. → binPath root
+        await moveEntry(sourcePath, join(binPath, entry.name))
+      }
+    }
+
+    logDebug('InfluxDB binaries reorganized with python/ co-located in bin/')
+  }
+}
+
+export const influxdbBinaryManager = new InfluxDBBinaryManager()

package/engines/influxdb/binary-urls.ts

@@ -0,0 +1,69 @@
+import { normalizeVersion } from './version-maps'
+import { buildHostdbUrl } from '../../core/hostdb-client'
+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 InfluxDB binaries from hostdb
+ *
+ * Format: https://github.com/robertjbass/hostdb/releases/download/influxdb-{version}/influxdb-{version}-{platform}-{arch}.{ext}
+ *
+ * @param version - InfluxDB version (e.g., '3', '3.8.0')
+ * @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)
+  const ext = platform === Platform.Win32 ? 'zip' : 'tar.gz'
+
+  return buildHostdbUrl(Engine.InfluxDB, {
+    version: fullVersion,
+    hostdbPlatform,
+    extension: ext,
+  })
+}

package/engines/influxdb/hostdb-releases.ts

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