spindb 0.36.1 → 0.36.2

package/core/library-env.ts

@@ -0,0 +1,120 @@
+/**
+ * Library environment utilities for dynamically-linked engine binaries.
+ *
+ * MariaDB, Redis, and Valkey hostdb binaries are linked against Homebrew's
+ * OpenSSL at absolute paths (e.g. /opt/homebrew/opt/openssl@3/lib/libssl.3.dylib).
+ * On systems without that library, they fail with cryptic dyld errors.
+ *
+ * This module provides:
+ * - getLibraryEnv(): sets DYLD_FALLBACK_LIBRARY_PATH / LD_LIBRARY_PATH so
+ *   the dynamic linker checks {binPath}/lib first (preparing for when hostdb
+ *   bundles dylibs alongside binaries).
+ * - detectLibraryError(): scans process output for library-loading patterns
+ *   and returns an actionable error message.
+ */
+
+import { platform as osPlatform } from 'os'
+import { join } from 'path'
+
+/**
+ * Returns env vars that point the dynamic linker at {binPath}/lib.
+ * On macOS: DYLD_FALLBACK_LIBRARY_PATH
+ * On Linux: LD_LIBRARY_PATH
+ * On Windows: returns undefined (not applicable).
+ *
+ * Usage: spread into spawn env: `{ ...process.env, ...getLibraryEnv(binPath) }`
+ */
+export function getLibraryEnv(
+  binPath: string,
+): Record<string, string> | undefined {
+  const plat = osPlatform()
+  const libDir = join(binPath, 'lib')
+
+  if (plat === 'darwin') {
+    return { DYLD_FALLBACK_LIBRARY_PATH: libDir }
+  }
+  if (plat === 'linux') {
+    return { LD_LIBRARY_PATH: libDir }
+  }
+  return undefined
+}
+
+/**
+ * Scans stderr/log output for dynamic library loading errors and returns
+ * an actionable message, or null if no library error was detected.
+ */
+export function detectLibraryError(
+  output: string,
+  engineName: string,
+): string | null {
+  if (!output) return null
+
+  const plat = osPlatform()
+  const lower = output.toLowerCase()
+
+  // macOS dyld errors
+  if (
+    lower.includes('library not loaded') ||
+    lower.includes('dyld:') ||
+    lower.includes('dyld[')
+  ) {
+    const needsOpenssl =
+      lower.includes('libssl') || lower.includes('libcrypto')
+
+    if (needsOpenssl && plat === 'darwin') {
+      return (
+        `${engineName} failed to start: missing OpenSSL libraries.\n` +
+        `The downloaded binary requires OpenSSL 3 which is not installed.\n` +
+        `Fix: brew install openssl@3\n` +
+        `Alternatively, re-download binaries after hostdb ships relocatable builds.`
+      )
+    }
+
+    return (
+      `${engineName} failed to start: a required dynamic library could not be loaded.\n` +
+      `This typically means the hostdb binary was built against libraries not present on this system.\n` +
+      (plat === 'darwin'
+        ? `Try: brew install openssl@3\n`
+        : `Try: sudo apt-get install libssl-dev  (or the equivalent for your distro)\n`) +
+      `See: https://github.com/robertjbass/hostdb/issues`
+    )
+  }
+
+  // Linux GLIBC version errors
+  if (lower.includes('glibc') || lower.includes('libc.so')) {
+    return (
+      `${engineName} failed to start: incompatible system C library (GLIBC).\n` +
+      `The downloaded binary requires a newer GLIBC version than is installed.\n` +
+      `Options:\n` +
+      `  - Upgrade your OS to a newer version\n` +
+      `  - Use Docker: spindb can run inside containers with newer GLIBC\n` +
+      `See: https://github.com/robertjbass/hostdb/issues`
+    )
+  }
+
+  // Generic shared library errors on Linux
+  if (
+    lower.includes('error while loading shared libraries') ||
+    lower.includes('cannot open shared object file')
+  ) {
+    const needsOpenssl =
+      lower.includes('libssl') || lower.includes('libcrypto')
+
+    if (needsOpenssl) {
+      return (
+        `${engineName} failed to start: missing OpenSSL libraries.\n` +
+        `Fix: sudo apt-get install libssl-dev  (Debian/Ubuntu)\n` +
+        `     sudo dnf install openssl-devel   (Fedora/RHEL)\n` +
+        `See: https://github.com/robertjbass/hostdb/issues`
+      )
+    }
+
+    return (
+      `${engineName} failed to start: a required shared library is missing.\n` +
+      `Check the error output above for the specific library name and install it.\n` +
+      `See: https://github.com/robertjbass/hostdb/issues`
+    )
+  }
+
+  return null
+}

package/engines/mariadb/index.ts

@@ -52,6 +52,7 @@ import {
   type UserCredentials,
 } from '../../types'
 import { parseTSVToQueryResult } from '../../core/query-parser'
+import { getLibraryEnv, detectLibraryError } from '../../core/library-env'
 
 const execAsync = promisify(exec)
 
@@ -256,18 +257,27 @@ export class MariaDBEngine extends BaseEngine {
       const cmd = `"${installDb}" --datadir="${dataDir}"`
 
       return new Promise((resolve, reject) => {
-        exec(cmd, { timeout: 120000 }, async (error, stdout, stderr) => {
-          if (error) {
-            await cleanupOnFailure()
-            reject(
-              new Error(
-                `MariaDB initialization failed with code ${error.code}: ${stderr || stdout || error.message}`,
-              ),
-            )
-          } else {
-            resolve(dataDir)
-          }
-        })
+        exec(
+          cmd,
+          { timeout: 120000, env: { ...process.env, ...getLibraryEnv(binPath) } },
+          async (error, stdout, stderr) => {
+            if (error) {
+              await cleanupOnFailure()
+              const libError = detectLibraryError(
+                stderr || stdout || error.message,
+                'MariaDB',
+              )
+              reject(
+                new Error(
+                  libError ||
+                    `MariaDB initialization failed with code ${error.code}: ${stderr || stdout || error.message}`,
+                ),
+              )
+            } else {
+              resolve(dataDir)
+            }
+          },
+        )
       })
     }
 
@@ -293,6 +303,7 @@ export class MariaDBEngine extends BaseEngine {
     return new Promise((resolve, reject) => {
       const proc = spawn(installDb, args, {
         stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, ...getLibraryEnv(binPath) },
       })
 
       let stdout = ''
@@ -310,9 +321,11 @@ export class MariaDBEngine extends BaseEngine {
           resolve(dataDir)
         } else {
           await cleanupOnFailure()
+          const libError = detectLibraryError(stderr || stdout, 'MariaDB')
           reject(
             new Error(
-              `MariaDB initialization failed with code ${code}: ${stderr || stdout}`,
+              libError ||
+                `MariaDB initialization failed with code ${code}: ${stderr || stdout}`,
             ),
           )
         }
@@ -384,11 +397,14 @@ export class MariaDBEngine extends BaseEngine {
 
     let proc: ReturnType<typeof spawn> | null = null
 
+    const libraryEnv = getLibraryEnv(binPath)
+
     if (isWindows()) {
       proc = spawn(mysqld, args, {
         stdio: ['ignore', 'pipe', 'pipe'],
         detached: true,
         windowsHide: true,
+        env: { ...process.env, ...libraryEnv },
       })
 
       proc.stdout?.on('data', (data: Buffer) => {
@@ -403,6 +419,7 @@ export class MariaDBEngine extends BaseEngine {
       proc = spawn(mysqld, args, {
         stdio: ['ignore', 'ignore', 'ignore'],
         detached: true,
+        env: { ...process.env, ...libraryEnv },
       })
       proc.unref()
     }
@@ -465,7 +482,21 @@ export class MariaDBEngine extends BaseEngine {
               if (proc) {
                 proc.removeListener('error', errorHandler)
               }
-              reject(new Error('MariaDB failed to start within timeout'))
+
+              // Check log file for library errors
+              let libError: string | null = null
+              try {
+                const logContent = await readFile(logFile, 'utf-8')
+                libError = detectLibraryError(logContent, 'MariaDB')
+              } catch {
+                // Log file might not exist
+              }
+
+              reject(
+                new Error(
+                  libError || 'MariaDB failed to start within timeout',
+                ),
+              )
             }
           }
         }

package/engines/redis/index.ts

@@ -45,6 +45,7 @@ import {
   type UserCredentials,
 } from '../../types'
 import { parseRedisResult } from '../../core/query-parser'
+import { getLibraryEnv, detectLibraryError } from '../../core/library-env'
 
 const execAsync = promisify(exec)
 
@@ -477,6 +478,12 @@ export class RedisEngine extends BaseEngine {
 
     logDebug(`Using redis-server for version ${version}: ${redisServer}`)
 
+    // Compute library fallback paths from the binary directory
+    // redisServer is e.g. /path/to/redis-8.4.0-darwin-arm64/bin/redis-server
+    // We need the parent directory (without /bin/redis-server)
+    const binBaseDir = binaryPath || this.getBinaryPath(version)
+    const libraryEnv = getLibraryEnv(binBaseDir)
+
     const containerDir = paths.getContainerPath(name, { engine: ENGINE })
     const configPath = join(containerDir, 'redis.conf')
     const dataDir = paths.getContainerDataPath(name, { engine: ENGINE })
@@ -533,6 +540,7 @@ export class RedisEngine extends BaseEngine {
           stdio: ['ignore', 'pipe', 'pipe'],
           detached: true,
           windowsHide: true,
+          env: { ...process.env, ...libraryEnv },
         }
 
         // Convert Windows path to Cygwin format for MSYS2/Cygwin-built binaries
@@ -603,6 +611,16 @@ export class RedisEngine extends BaseEngine {
               logContent = '(log file not found or empty)'
             }
 
+            // Check for library loading errors first
+            const libError = detectLibraryError(
+              stderrOutput + logContent,
+              'Redis',
+            )
+            if (libError) {
+              reject(new Error(libError))
+              return
+            }
+
             const errorDetails = [
               portError || 'Redis failed to start within timeout.',
               `Binary: ${redisServer}`,
@@ -625,6 +643,7 @@ export class RedisEngine extends BaseEngine {
     return new Promise((resolve, reject) => {
       const proc = spawn(redisServer, [configPath], {
         stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, ...libraryEnv },
       })
 
       let stdout = ''
@@ -678,6 +697,16 @@ export class RedisEngine extends BaseEngine {
               logContent = '(log file not found or empty)'
             }
 
+            // Check for library loading errors
+            const libError = detectLibraryError(
+              stderr + logContent,
+              'Redis',
+            )
+            if (libError) {
+              reject(new Error(libError))
+              return
+            }
+
             const errorDetails = [
               'Redis failed to start within timeout.',
               `Binary: ${redisServer}`,
@@ -700,6 +729,16 @@ export class RedisEngine extends BaseEngine {
             logContent = ''
           }
 
+          // Check for library loading errors on non-zero exit
+          const libError = detectLibraryError(
+            stderr + stdout + logContent,
+            'Redis',
+          )
+          if (libError) {
+            reject(new Error(libError))
+            return
+          }
+
           const errorDetails = [
             stderr || stdout || `redis-server exited with code ${code}`,
             logContent ? `Log content:\n${logContent}` : '',

package/engines/valkey/index.ts

@@ -45,6 +45,7 @@ import {
   type UserCredentials,
 } from '../../types'
 import { parseRedisResult } from '../../core/query-parser'
+import { getLibraryEnv, detectLibraryError } from '../../core/library-env'
 
 const execAsync = promisify(exec)
 
@@ -486,6 +487,10 @@ export class ValkeyEngine extends BaseEngine {
 
     logDebug(`Using valkey-server for version ${version}: ${valkeyServer}`)
 
+    // Compute library fallback paths from the binary directory
+    const binBaseDir = binaryPath || this.getBinaryPath(version)
+    const libraryEnv = getLibraryEnv(binBaseDir)
+
     const containerDir = paths.getContainerPath(name, { engine: ENGINE })
     const configPath = join(containerDir, 'valkey.conf')
     const dataDir = paths.getContainerDataPath(name, { engine: ENGINE })
@@ -542,6 +547,7 @@ export class ValkeyEngine extends BaseEngine {
           stdio: ['ignore', 'pipe', 'pipe'],
           detached: true,
           windowsHide: true,
+          env: { ...process.env, ...libraryEnv },
         }
 
         // Convert Windows path to Cygwin format for Cygwin-built binaries
@@ -612,6 +618,16 @@ export class ValkeyEngine extends BaseEngine {
               logContent = '(log file not found or empty)'
             }
 
+            // Check for library loading errors first
+            const libError = detectLibraryError(
+              stderrOutput + logContent,
+              'Valkey',
+            )
+            if (libError) {
+              reject(new Error(libError))
+              return
+            }
+
             const errorDetails = [
               portError || 'Valkey failed to start within timeout.',
               `Binary: ${valkeyServer}`,
@@ -634,6 +650,7 @@ export class ValkeyEngine extends BaseEngine {
     return new Promise((resolve, reject) => {
       const proc = spawn(valkeyServer, [configPath], {
         stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, ...libraryEnv },
       })
 
       let stdout = ''
@@ -678,6 +695,23 @@ export class ValkeyEngine extends BaseEngine {
               reject(new Error(portError))
               return
             }
+
+            // Check for library loading errors
+            let logContent = ''
+            try {
+              logContent = await readFile(logFile, 'utf-8')
+            } catch {
+              logContent = ''
+            }
+            const libError = detectLibraryError(
+              stderr + logContent,
+              'Valkey',
+            )
+            if (libError) {
+              reject(new Error(libError))
+              return
+            }
+
             reject(
               new Error(
                 `Valkey failed to start within timeout. Check logs at: ${logFile}`,
@@ -685,6 +719,12 @@ export class ValkeyEngine extends BaseEngine {
             )
           }
         } else {
+          // Check for library loading errors on non-zero exit
+          const libError = detectLibraryError(stderr || stdout, 'Valkey')
+          if (libError) {
+            reject(new Error(libError))
+            return
+          }
           reject(
             new Error(
               stderr || stdout || `valkey-server exited with code ${code}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.36.1",
+  "version": "0.36.2",
   "author": "Bob Bass <bob@bbass.co>",
   "license": "PolyForm-Noncommercial-1.0.0",
   "description": "Zero-config Docker-free local database containers. Create, backup, and clone a variety of popular databases.",