spindb 0.37.2 → 0.38.0

package/core/homebrew-version-manager.ts

@@ -1,352 +0,0 @@
-/**
- * PostgreSQL System Version Manager (FALLBACK / DEPRECATED)
- *
- * @deprecated SpinDB now downloads PostgreSQL binaries from hostdb, which include
- * all client tools (psql, pg_dump, pg_restore). This module is a legacy fallback
- * for users who have PostgreSQL installed via system package managers. Consider
- * removing this module once hostdb adoption is complete.
- *
- * FALLBACK USE CASE:
- * Detects PostgreSQL versions installed via system package managers:
- * - macOS: Homebrew (/opt/homebrew/opt/postgresql@17/bin)
- * - Linux: APT/YUM (/usr/lib/postgresql/17/bin)
- *
- * Used when hostdb binaries are unavailable and system tools are needed for
- * dump/restore operations with version compatibility requirements.
- */
-
-import { exec } from 'child_process'
-import { promisify } from 'util'
-import { existsSync } from 'fs'
-import { platformService } from './platform-service'
-import { Platform, Arch } from '../types'
-import { logDebug } from './error-handler'
-
-const execAsync = promisify(exec)
-
-// PostgreSQL versions to detect on system (via Homebrew/apt)
-// NOTE: This is for SYSTEM-INSTALLED PostgreSQL only (fallback path).
-// Primary path uses hostdb binaries. If this module is removed, these
-// versions become irrelevant.
-const SUPPORTED_PG_VERSIONS = ['14', '15', '16', '17', '18']
-
-export type InstalledPostgresVersion = {
-  majorVersion: string // e.g., "14", "17"
-  fullVersion: string // e.g., "14.20", "17.7.0"
-  binPath: string // e.g., "/opt/homebrew/opt/postgresql@17/bin" or "/usr/lib/postgresql/17/bin"
-  isLinked: boolean // Currently linked to system PATH (macOS only)
-  source: 'homebrew' | 'apt' | 'system' | 'unknown'
-}
-
-export type VersionSwitchResult = {
-  success: boolean
-  previousVersion?: string
-  currentVersion?: string
-  error?: string
-}
-
-// Check if Homebrew is available on this system
-export async function isHomebrewAvailable(): Promise<boolean> {
-  const { platform } = platformService.getPlatformInfo()
-  if (platform !== Platform.Darwin) return false
-
-  try {
-    await execAsync('brew --version')
-    return true
-  } catch {
-    return false
-  }
-}
-
-// Get the Homebrew prefix based on architecture
-function getHomebrewPrefix(): string {
-  const { arch } = platformService.getPlatformInfo()
-  return arch === Arch.ARM64 ? '/opt/homebrew' : '/usr/local'
-}
-
-// Get Linux PostgreSQL bin paths (Debian/Ubuntu style)
-function getLinuxPostgresPath(majorVersion: string): string {
-  return `/usr/lib/postgresql/${majorVersion}/bin`
-}
-
-// Get the currently linked PostgreSQL major version (if any)
-export async function getCurrentLinkedVersion(): Promise<string | null> {
-  const prefix = getHomebrewPrefix()
-  const pgDumpPath = `${prefix}/bin/pg_dump`
-
-  if (!existsSync(pgDumpPath)) {
-    return null
-  }
-
-  try {
-    const { stdout } = await execAsync(`"${pgDumpPath}" --version`)
-    const match = stdout.match(/(\d+)\.(\d+)/)
-    return match ? match[1] : null
-  } catch {
-    return null
-  }
-}
-
-/**
- * Detect all PostgreSQL versions installed on the system
- * Works on both macOS (Homebrew) and Linux (APT/YUM)
- */
-export async function detectInstalledPostgres(): Promise<
-  InstalledPostgresVersion[]
-> {
-  const { platform } = platformService.getPlatformInfo()
-  const installed: InstalledPostgresVersion[] = []
-
-  // Get currently linked version (for macOS)
-  const linkedVersion = await getCurrentLinkedVersion()
-
-  if (platform === Platform.Darwin) {
-    // macOS: Check Homebrew installations
-    const prefix = getHomebrewPrefix()
-
-    for (const major of SUPPORTED_PG_VERSIONS) {
-      const binPath = `${prefix}/opt/postgresql@${major}/bin`
-      const pgDumpPath = `${binPath}/pg_dump`
-
-      if (existsSync(pgDumpPath)) {
-        try {
-          const { stdout } = await execAsync(`"${pgDumpPath}" --version`)
-          const match = stdout.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
-          if (match) {
-            installed.push({
-              majorVersion: major,
-              fullVersion: match[0],
-              binPath,
-              isLinked: linkedVersion === major,
-              source: 'homebrew',
-            })
-          }
-        } catch (error) {
-          logDebug(`Could not get version for postgresql@${major}`, {
-            error: error instanceof Error ? error.message : String(error),
-          })
-        }
-      }
-    }
-  } else if (platform === Platform.Linux) {
-    // Linux: Check /usr/lib/postgresql/*/bin (Debian/Ubuntu style)
-    for (const major of SUPPORTED_PG_VERSIONS) {
-      const binPath = getLinuxPostgresPath(major)
-      const pgDumpPath = `${binPath}/pg_dump`
-
-      if (existsSync(pgDumpPath)) {
-        try {
-          const { stdout } = await execAsync(`"${pgDumpPath}" --version`)
-          const match = stdout.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
-          if (match) {
-            installed.push({
-              majorVersion: major,
-              fullVersion: match[0],
-              binPath,
-              isLinked: false, // Linux doesn't use linking like Homebrew
-              source: 'apt',
-            })
-          }
-        } catch (error) {
-          logDebug(`Could not get version for postgresql-${major}`, {
-            error: error instanceof Error ? error.message : String(error),
-          })
-        }
-      }
-    }
-  }
-
-  return installed
-}
-
-/**
- * Get the direct path to a PostgreSQL binary for a specific major version
- * This allows using a specific version without changing system links
- *
- * Works on:
- * - macOS: /opt/homebrew/opt/postgresql@17/bin/pg_dump
- * - Linux: /usr/lib/postgresql/17/bin/pg_dump
- */
-export async function getDirectBinaryPath(
-  tool: 'pg_dump' | 'pg_restore' | 'psql' | 'pg_basebackup',
-  majorVersion: string,
-): Promise<string | null> {
-  const { platform } = platformService.getPlatformInfo()
-
-  if (platform === Platform.Darwin) {
-    // macOS: Homebrew path
-    const prefix = getHomebrewPrefix()
-    const path = `${prefix}/opt/postgresql@${majorVersion}/bin/${tool}`
-    if (existsSync(path)) return path
-  } else if (platform === Platform.Linux) {
-    // Linux: Debian/Ubuntu path
-    const path = `${getLinuxPostgresPath(majorVersion)}/${tool}`
-    if (existsSync(path)) return path
-  }
-
-  return null
-}
-
-/**
- * Find a compatible PostgreSQL version for the target major version
- * Returns the best available version that is >= targetMajor
- */
-export async function findCompatibleVersion(
-  targetMajor: number,
-): Promise<InstalledPostgresVersion | null> {
-  const installed = await detectInstalledPostgres()
-
-  // Filter versions >= target
-  const compatible = installed.filter(
-    (v) => parseInt(v.majorVersion, 10) >= targetMajor,
-  )
-
-  if (compatible.length === 0) {
-    return null
-  }
-
-  // Prefer the currently linked version if it's compatible
-  const linked = compatible.find((v) => v.isLinked)
-  if (linked) {
-    return linked
-  }
-
-  // Otherwise return the lowest compatible version (closest to target)
-  compatible.sort(
-    (a, b) => parseInt(a.majorVersion, 10) - parseInt(b.majorVersion, 10),
-  )
-  return compatible[0]
-}
-
-/**
- * Switch system to use a specific PostgreSQL version
- *
- * - macOS: Uses `brew link` to change symlinks
- * - Linux: Uses `update-alternatives` if available (Debian/Ubuntu)
- *
- * NOTE: Prefer getDirectBinaryPath() when possible to avoid side effects
- */
-export async function switchHomebrewVersion(
-  targetMajor: string,
-): Promise<VersionSwitchResult> {
-  const { platform } = platformService.getPlatformInfo()
-
-  if (platform === Platform.Darwin) {
-    return switchHomebrewVersionMacOS(targetMajor)
-  } else if (platform === Platform.Linux) {
-    return switchVersionLinux(targetMajor)
-  }
-
-  return {
-    success: false,
-    error: 'Version switching not supported on this platform',
-  }
-}
-
-// Switch PostgreSQL version on macOS using Homebrew
-async function switchHomebrewVersionMacOS(
-  targetMajor: string,
-): Promise<VersionSwitchResult> {
-  if (!(await isHomebrewAvailable())) {
-    return { success: false, error: 'Homebrew not available' }
-  }
-
-  const installed = await detectInstalledPostgres()
-  const target = installed.find((v) => v.majorVersion === targetMajor)
-
-  if (!target) {
-    return {
-      success: false,
-      error: `PostgreSQL ${targetMajor} is not installed via Homebrew. Install with: brew install postgresql@${targetMajor}`,
-    }
-  }
-
-  if (target.isLinked) {
-    return {
-      success: true,
-      currentVersion: targetMajor,
-      previousVersion: targetMajor,
-    }
-  }
-
-  const previousLinked = installed.find((v) => v.isLinked)
-
-  try {
-    // Unlink all versions first
-    for (const ver of installed) {
-      await execAsync(
-        `brew unlink postgresql@${ver.majorVersion} 2>/dev/null || true`,
-      )
-    }
-
-    // Link target version
-    await execAsync(`brew link --overwrite postgresql@${targetMajor}`)
-
-    logDebug('Switched Homebrew PostgreSQL version', {
-      from: previousLinked?.majorVersion,
-      to: targetMajor,
-    })
-
-    return {
-      success: true,
-      previousVersion: previousLinked?.majorVersion,
-      currentVersion: targetMajor,
-    }
-  } catch (error) {
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : String(error),
-    }
-  }
-}
-
-/**
- * "Switch" PostgreSQL version on Linux (no-op verification only)
- *
- * Unlike macOS where Homebrew uses symlinks that need switching, Linux installs
- * PostgreSQL versions side-by-side in versioned paths (e.g., /usr/lib/postgresql/17/bin).
- * We access these directly via getDirectBinaryPath(), so no symlink switching is needed.
- * This function just verifies the target version is installed.
- */
-async function switchVersionLinux(
-  targetMajor: string,
-): Promise<VersionSwitchResult> {
-  const installed = await detectInstalledPostgres()
-  const target = installed.find((v) => v.majorVersion === targetMajor)
-
-  if (!target) {
-    return {
-      success: false,
-      error: `PostgreSQL ${targetMajor} is not installed. Install with: sudo apt install postgresql-client-${targetMajor}`,
-    }
-  }
-
-  // No action required - Linux uses versioned paths directly, no symlink switching needed
-  logDebug(
-    'Linux: Version verified, no switching required (using direct path)',
-    {
-      version: targetMajor,
-      binPath: target.binPath,
-    },
-  )
-
-  return {
-    success: true,
-    currentVersion: targetMajor,
-  }
-}
-
-// Get all client tools for a specific PostgreSQL version
-export async function getVersionedToolPaths(majorVersion: string): Promise<{
-  pgDump: string | null
-  pgRestore: string | null
-  psql: string | null
-  pgBasebackup: string | null
-}> {
-  return {
-    pgDump: await getDirectBinaryPath('pg_dump', majorVersion),
-    pgRestore: await getDirectBinaryPath('pg_restore', majorVersion),
-    psql: await getDirectBinaryPath('psql', majorVersion),
-    pgBasebackup: await getDirectBinaryPath('pg_basebackup', majorVersion),
-  }
-}

package/core/hostdb-client.ts

@@ -1,344 +0,0 @@
-/**
- * Shared hostdb Client Module
- *
- * Provides centralized access to pre-built database binaries.
- * Primary registry: registry.layerbase.host
- * Fallback registry: GitHub releases (robertjbass/hostdb)
- *
- * This module handles fetching releases.json with caching to avoid
- * repeated network requests.
- */
-
-import { Platform, type Arch, type Engine } from '../types'
-import { logDebug } from './error-handler'
-
-// Registry base URLs
-export const LAYERBASE_REGISTRY_BASE = 'https://registry.layerbase.host'
-export const GITHUB_REGISTRY_BASE =
-  'https://github.com/robertjbass/hostdb/releases/download'
-
-/**
- * Toggle GitHub fallback for binary downloads and releases.json fetches.
- * Set to `false` to exclusively test the Layerbase registry.
- * Must be re-enabled before release (see PRE_RELEASE_TASKS.md).
- */
-export const ENABLE_GITHUB_FALLBACK = false
-
-// Platform definition in hostdb releases.json
-export type HostdbPlatform = {
-  url: string
-  sha256: string
-  size: number
-}
-
-// Version entry in hostdb releases.json
-export type HostdbRelease = {
-  version: string
-  releaseTag: string
-  releasedAt: string
-  platforms: Record<string, HostdbPlatform>
-}
-
-// Structure of hostdb releases.json
-export type HostdbReleasesData = {
-  repository: string
-  updatedAt: string
-  databases: Record<string, Record<string, HostdbRelease>>
-}
-
-// Supported hostdb platforms
-export const SUPPORTED_PLATFORMS = [
-  'darwin-arm64',
-  'darwin-x64',
-  'linux-arm64',
-  'linux-x64',
-  'win32-x64',
-] as const
-
-export type SupportedPlatform = (typeof SUPPORTED_PLATFORMS)[number]
-
-// Type alias for engines available in hostdb (uses the Engine enum from types)
-export type HostdbEngine = Engine
-
-/**
- * In-memory cache for fetched releases.
- *
- * THREAD-SAFETY NOTE: This cache uses module-level mutable state and is NOT
- * safe for use across Node.js worker threads. Each worker thread will have
- * its own copy of this cache. For SpinDB's single-threaded CLI use case,
- * this is acceptable.
- */
-let cachedReleases: HostdbReleasesData | null = null
-let cacheTimestamp = 0
-const CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
-
-export const LAYERBASE_RELEASES_URL =
-  'https://registry.layerbase.host/releases.json'
-export const GITHUB_RELEASES_URL =
-  'https://raw.githubusercontent.com/robertjbass/hostdb/main/releases.json'
-
-/**
- * Get the list of releases.json URLs to try, respecting ENABLE_GITHUB_FALLBACK.
- * When fallback is disabled, only the Layerbase URL is returned.
- */
-export function getReleasesUrls(): string[] {
-  return ENABLE_GITHUB_FALLBACK
-    ? [LAYERBASE_RELEASES_URL, GITHUB_RELEASES_URL]
-    : [LAYERBASE_RELEASES_URL]
-}
-
-/**
- * Fetch releases.json from hostdb repository with caching.
- *
- * @returns The full releases data from hostdb
- * @throws Error if the fetch fails
- */
-export async function fetchHostdbReleases(): Promise<HostdbReleasesData> {
-  // Return cached releases if still valid
-  if (cachedReleases && Date.now() - cacheTimestamp < CACHE_TTL_MS) {
-    return cachedReleases
-  }
-
-  // Try layerbase registry first, fall back to GitHub (if enabled)
-  const urls = getReleasesUrls()
-  for (let i = 0; i < urls.length; i++) {
-    const url = urls[i]
-    const isLast = i === urls.length - 1
-    try {
-      const response = await fetch(url, {
-        signal: AbortSignal.timeout(5000),
-      })
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`)
-      }
-
-      const data = (await response.json()) as HostdbReleasesData
-
-      // Cache the results
-      cachedReleases = data
-      cacheTimestamp = Date.now()
-
-      return data
-    } catch (error) {
-      const err = error as Error
-      logDebug(`Failed to fetch releases from ${url}: ${err.message}`)
-      // If this was the last URL, rethrow
-      if (isLast) {
-        throw error
-      }
-      // Otherwise try the next URL
-    }
-  }
-
-  // Should be unreachable (loop always throws on last iteration)
-  throw new Error('Failed to fetch hostdb releases from all registries')
-}
-
-/**
- * Get the releases for a specific engine from the hostdb data.
- *
- * @param data - The full hostdb releases data
- * @param engine - The engine (e.g., Engine.PostgreSQL or 'postgresql')
- * @returns The releases for that engine, or undefined if not found
- */
-export function getEngineReleases(
-  data: HostdbReleasesData,
-  engine: Engine | string,
-): Record<string, HostdbRelease> | undefined {
-  return data.databases[engine]
-}
-
-/**
- * Map Node.js platform identifiers to hostdb platform identifiers.
- *
- * @param platform - Node.js platform (e.g., Platform.Darwin)
- * @param arch - Node.js architecture (e.g., Arch.ARM64)
- * @returns The hostdb platform identifier, or undefined if not supported
- */
-export function getHostdbPlatform(
-  platform: Platform,
-  arch: Arch,
-): SupportedPlatform | undefined {
-  const key = `${platform}-${arch}`
-  return SUPPORTED_PLATFORMS.includes(key as SupportedPlatform)
-    ? (key as SupportedPlatform)
-    : undefined
-}
-
-/**
- * Validate that a platform is supported by hostdb.
- *
- * @param platform - Node.js platform (e.g., Platform.Darwin)
- * @param arch - Node.js architecture (e.g., Arch.ARM64)
- * @returns The validated hostdb platform identifier
- * @throws Error if the platform is not supported
- */
-export function validatePlatform(
-  platform: Platform,
-  arch: Arch,
-): SupportedPlatform {
-  const hostdbPlatform = getHostdbPlatform(platform, arch)
-  if (!hostdbPlatform) {
-    const supported = SUPPORTED_PLATFORMS.join(', ')
-    throw new Error(
-      `Unsupported platform: ${platform}-${arch}. ` +
-        `hostdb provides binaries for: ${supported}`,
-    )
-  }
-  return hostdbPlatform
-}
-
-export type BuildHostdbUrlOptions = {
-  version: string
-  hostdbPlatform: string
-  extension?: 'tar.gz' | 'zip'
-}
-
-/**
- * Build a download URL for a hostdb release (low-level, no validation).
- *
- * This is the core URL builder that all engines should use after validating
- * the platform against their own supported platform set.
- *
- * @param engine - The engine name (e.g., 'postgresql', 'mysql')
- * @param options - Version, pre-validated platform string, and optional extension
- * @returns The download URL
- */
-export function buildHostdbUrl(
-  engine: Engine | string,
-  options: BuildHostdbUrlOptions,
-): string {
-  const { version, hostdbPlatform, extension = 'tar.gz' } = options
-  const tag = `${engine}-${version}`
-  const filename = `${engine}-${version}-${hostdbPlatform}.${extension}`
-
-  return `${LAYERBASE_REGISTRY_BASE}/${tag}/${filename}`
-}
-
-/**
- * Build a GitHub fallback URL for a hostdb release (same path scheme as layerbase).
- */
-export function buildGithubFallbackUrl(
-  engine: Engine | string,
-  options: BuildHostdbUrlOptions,
-): string {
-  const { version, hostdbPlatform, extension = 'tar.gz' } = options
-  const tag = `${engine}-${version}`
-  const filename = `${engine}-${version}-${hostdbPlatform}.${extension}`
-
-  return `${GITHUB_REGISTRY_BASE}/${tag}/${filename}`
-}
-
-/**
- * Convert a layerbase registry URL to its GitHub fallback equivalent.
- * Returns null if the URL is not a layerbase URL or if GitHub fallback is disabled.
- */
-export function getRegistryFallbackUrl(url: string): string | null {
-  if (!ENABLE_GITHUB_FALLBACK) return null
-  if (url.startsWith(LAYERBASE_REGISTRY_BASE)) {
-    return url.replace(LAYERBASE_REGISTRY_BASE, GITHUB_REGISTRY_BASE)
-  }
-  return null
-}
-
-/**
- * Fetch wrapper that tries the primary URL first, then falls back to the
- * GitHub registry if the primary is a layerbase URL and the request fails
- * with a 404, 5xx, or network error.
- *
- * AbortError (timeout) is never retried — it propagates immediately.
- */
-export async function fetchWithRegistryFallback(
-  url: string,
-  options?: RequestInit,
-): Promise<Response> {
-  try {
-    const response = await fetch(url, options)
-    if (response.status === 404 || response.status >= 500) {
-      const fallbackUrl = getRegistryFallbackUrl(url)
-      if (fallbackUrl) {
-        logDebug(
-          `Primary registry returned ${response.status}, trying GitHub fallback`,
-        )
-        return await fetch(fallbackUrl, options)
-      }
-    }
-    return response
-  } catch (error) {
-    const err = error as Error
-    // Never retry on timeout (AbortError)
-    if (err.name === 'AbortError') {
-      throw error
-    }
-    const fallbackUrl = getRegistryFallbackUrl(url)
-    if (fallbackUrl) {
-      logDebug(
-        `Primary registry fetch failed (${err.message}), trying GitHub fallback`,
-      )
-      return await fetch(fallbackUrl, options)
-    }
-    throw error
-  }
-}
-
-/**
- * Try fetching from multiple registry URLs in order, returning the first
- * successful (response.ok) Response. Logs per-URL failures via the
- * supplied logger callback.
- *
- * @param urls - URLs to try in order (e.g., layerbase then GitHub)
- * @param logger - Callback for logging per-URL failures
- * @param timeoutMs - Per-request timeout in milliseconds (default: 5000)
- * @returns The first successful Response
- * @throws Error if all URLs fail
- */
-export async function fetchFromRegistryUrls(
-  urls: string[],
-  logger: (message: string) => void,
-  timeoutMs: number = 5000,
-): Promise<Response> {
-  let lastError: Error | null = null
-  for (const url of urls) {
-    try {
-      const response = await fetch(url, {
-        signal: AbortSignal.timeout(timeoutMs),
-      })
-      if (response.ok) return response
-      logger(`Registry fetch from ${url}: HTTP ${response.status}`)
-    } catch (error) {
-      logger(`Registry fetch from ${url} failed: ${error}`)
-      lastError = error as Error
-    }
-  }
-  throw lastError ?? new Error('All release registries failed')
-}
-
-export type BuildDownloadUrlOptions = {
-  version: string
-  platform: Platform
-  arch: Arch
-}
-
-/**
- * Build a download URL for a hostdb release with platform validation.
- *
- * This is a convenience wrapper around buildHostdbUrl that validates
- * the platform against the global SUPPORTED_PLATFORMS list. For engines
- * with different platform support (e.g., ClickHouse doesn't support Windows),
- * use buildHostdbUrl directly after validating against engine-specific platforms.
- *
- * @param engine - The engine name (e.g., 'postgresql', 'mysql')
- * @param options - Version and platform configuration
- * @returns The download URL
- * @throws Error if the platform is not supported by hostdb
- */
-export function buildDownloadUrl(
-  engine: Engine | string,
-  options: BuildDownloadUrlOptions,
-): string {
-  const { version, platform, arch } = options
-  const hostdbPlatform = validatePlatform(platform, arch)
-  const ext = platform === Platform.Win32 ? 'zip' : 'tar.gz'
-
-  return buildHostdbUrl(engine, { version, hostdbPlatform, extension: ext })
-}