@grafema/core 0.2.10 → 0.2.12-beta

package/src/storage/backends/RFDBServerBackend.ts

@@ -18,15 +18,14 @@
  *   await backend.flush();
  */
 
-import { RFDBClient } from '@grafema/rfdb-client';
-import { existsSync, unlinkSync } from 'fs';
-import { spawn, type ChildProcess } from 'child_process';
+import { RFDBClient, type BatchHandle } from '@grafema/rfdb-client';
+import type { ChildProcess } from 'child_process';
 import { join, dirname } from 'path';
-import { setTimeout as sleep } from 'timers/promises';
 
 import type { WireNode, WireEdge, FieldDeclaration, CommitDelta, AttrQuery as RFDBAttrQuery } from '@grafema/types';
 import type { NodeType, EdgeType } from '@grafema/types';
-import { findRfdbBinary } from '../../utils/findRfdbBinary.js';
+import { startRfdbServer } from '../../utils/startRfdbServer.js';
+import { GRAFEMA_VERSION, getSchemaVersion } from '../../version.js';
 import type { BaseNodeRecord, EdgeRecord, AnyBrandedNode } from '@grafema/types';
 import { brandNodeInternal } from '../../core/brandNodeInternal.js';
 import type { AttrQuery, GraphStats, GraphExport } from '../../core/GraphBackend.js';
@@ -201,66 +200,19 @@ export class RFDBServerBackend {
   }
 
   /**
-   * Find RFDB server binary using shared utility.
-   * Delegates to findRfdbBinary() for consistent search across all entry points.
-   */
-  private _findServerBinary(): string | null {
-    const binaryPath = findRfdbBinary();
-    if (binaryPath) {
-      this.log(`[RFDBServerBackend] Found binary: ${binaryPath}`);
-    }
-    return binaryPath;
-  }
-
-  /**
-   * Start RFDB server process
+   * Start RFDB server process using shared utility.
    */
   private async _startServer(): Promise<void> {
     if (!this.dbPath) {
       throw new Error('dbPath required to start RFDB server');
     }
 
-    // Find server binary - check multiple locations
-    const binaryPath = this._findServerBinary();
-    if (!binaryPath) {
-      throw new Error(
-        'RFDB server binary not found.\n' +
-        'Install @grafema/rfdb: npm install @grafema/rfdb\n' +
-        'Or build from source: cargo build --release --bin rfdb-server'
-      );
-    }
-
-    // Remove stale socket
-    if (existsSync(this.socketPath)) {
-      unlinkSync(this.socketPath);
-    }
-
-    this.log(`[RFDBServerBackend] Starting: ${binaryPath} ${this.dbPath} --socket ${this.socketPath}`);
-
-    this.serverProcess = spawn(binaryPath, [this.dbPath, '--socket', this.socketPath], {
-      stdio: ['ignore', 'ignore', 'inherit'], // stdin/stdout ignored, stderr inherited
-      detached: true, // Allow server to outlive this process
-    });
-
-    // Don't let server process prevent parent from exiting
-    this.serverProcess.unref();
-
-    this.serverProcess.on('error', (err: Error) => {
-      this.logError(`[RFDBServerBackend] Server process error:`, err);
+    await startRfdbServer({
+      dbPath: this.dbPath,
+      socketPath: this.socketPath,
+      waitTimeoutMs: 5000,
+      logger: this.silent ? undefined : { debug: (m: string) => this.log(m) },
     });
-
-    // Wait for socket to appear
-    let attempts = 0;
-    while (!existsSync(this.socketPath) && attempts < 50) {
-      await sleep(100);
-      attempts++;
-    }
-
-    if (!existsSync(this.socketPath)) {
-      throw new Error(`RFDB server failed to start (socket not created after ${attempts * 100}ms)`);
-    }
-
-    this.log(`[RFDBServerBackend] Server started on ${this.socketPath}`);
   }
 
   /**
@@ -274,9 +226,28 @@ export class RFDBServerBackend {
     try {
       const hello = await this.client.hello(3);
       this.protocolVersion = hello.protocolVersion;
+      this._checkServerVersion(hello.serverVersion);
     } catch {
       // Server predates hello command or doesn't support v3 — safe v2 fallback
       this.protocolVersion = 2;
+      this.log('[RFDBServerBackend] WARNING: Server does not support version negotiation. Consider updating rfdb-server.');
+    }
+  }
+
+  /**
+   * Validate server version against expected client version.
+   * Warns on mismatch but never fails — version differences are informational.
+   */
+  private _checkServerVersion(serverVersion: string): void {
+    if (!serverVersion) return;
+    const expected = getSchemaVersion(GRAFEMA_VERSION);
+    const actual = getSchemaVersion(serverVersion);
+    if (actual !== expected) {
+      this.log(
+        `[RFDBServerBackend] WARNING: rfdb-server version mismatch — ` +
+        `server v${serverVersion}, expected v${GRAFEMA_VERSION}. ` +
+        `Update with: grafema server restart`
+      );
     }
   }
 
@@ -769,10 +740,13 @@ export class RFDBServerBackend {
   /**
    * Commit the current batch to the server atomically.
    * Returns a CommitDelta describing what changed.
+   *
+   * @param tags - Optional tags for the commit
+   * @param deferIndex - When true, server writes data but skips index rebuild.
    */
-  async commitBatch(tags?: string[]): Promise<CommitDelta> {
+  async commitBatch(tags?: string[], deferIndex?: boolean, protectedTypes?: string[]): Promise<CommitDelta> {
     if (!this.client) throw new Error('Not connected to RFDB server');
-    return this.client.commitBatch(tags);
+    return this.client.commitBatch(tags, deferIndex, protectedTypes);
   }
 
   /**
@@ -822,6 +796,24 @@ export class RFDBServerBackend {
     this.client.abortBatch();
   }
 
+  /**
+   * Rebuild all secondary indexes after deferred-index commits (REG-487).
+   * Call this once after a series of commitBatch(tags, true) calls.
+   */
+  async rebuildIndexes(): Promise<void> {
+    if (!this.client) throw new Error('Not connected to RFDB server');
+    await this.client.rebuildIndexes();
+  }
+
+  /**
+   * Create an isolated batch handle for concurrent-safe batching (REG-487).
+   * Each handle has its own buffers — safe for parallel workers.
+   */
+  createBatch(): BatchHandle {
+    if (!this.client) throw new Error('Not connected to RFDB server');
+    return this.client.createBatch();
+  }
+
   // ===========================================================================
   // Export/Import
   // ===========================================================================

package/src/utils/startRfdbServer.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared utility for starting rfdb-server
+ *
+ * Single authoritative function for spawning rfdb-server. All spawn sites
+ * (RFDBServerBackend, CLI server command, ParallelAnalysisRunner) delegate here.
+ *
+ * Callers are responsible for checking if a server is already running before
+ * calling this function. This function always spawns a new server process.
+ */
+
+import { existsSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import { spawn, type ChildProcess } from 'child_process';
+import { setTimeout as sleep } from 'timers/promises';
+import { findRfdbBinary } from './findRfdbBinary.js';
+
+export interface StartRfdbServerOptions {
+  dbPath: string;
+  socketPath: string;
+  /** Override binary path; if absent, findRfdbBinary() is called */
+  binaryPath?: string;
+  /** If provided, PID file is written after spawn */
+  pidPath?: string;
+  /** Socket poll timeout in ms (default: 5000) */
+  waitTimeoutMs?: number;
+  /** Optional logger for debug messages */
+  logger?: { debug(msg: string): void };
+  /** Internal: dependency injection for testing */
+  _deps?: {
+    spawn?: typeof spawn;
+    findRfdbBinary?: () => string | null;
+    existsSync?: (path: string) => boolean;
+    unlinkSync?: (path: string) => void;
+    writeFileSync?: (path: string, data: string) => void;
+  };
+}
+
+/**
+ * Start an rfdb-server process.
+ *
+ * 1. Resolve binary (explicit or via findRfdbBinary)
+ * 2. Remove stale socket
+ * 3. Spawn detached process
+ * 4. Write PID file (if pidPath provided)
+ * 5. Poll for socket file up to waitTimeoutMs
+ * 6. Return ChildProcess (caller decides whether to kill later)
+ */
+export async function startRfdbServer(options: StartRfdbServerOptions): Promise<ChildProcess> {
+  const {
+    dbPath,
+    socketPath,
+    pidPath,
+    waitTimeoutMs = 5000,
+    logger,
+    _deps,
+  } = options;
+
+  const _spawn = _deps?.spawn ?? spawn;
+  const _findRfdbBinary = _deps?.findRfdbBinary ?? findRfdbBinary;
+  const _existsSync = _deps?.existsSync ?? existsSync;
+  const _unlinkSync = _deps?.unlinkSync ?? unlinkSync;
+  const _writeFileSync = _deps?.writeFileSync ?? writeFileSync;
+
+  // 1. Resolve binary
+  const binaryPath = options.binaryPath || _findRfdbBinary();
+  if (!binaryPath) {
+    throw new Error(
+      'RFDB server binary not found.\n' +
+      'Install @grafema/rfdb: npm install @grafema/rfdb\n' +
+      'Or build from source: cargo build --release --bin rfdb-server'
+    );
+  }
+
+  // 2. Remove stale socket
+  if (_existsSync(socketPath)) {
+    _unlinkSync(socketPath);
+  }
+
+  const dataDir = dirname(socketPath);
+  logger?.debug(`Starting rfdb-server: ${binaryPath} ${dbPath} --socket ${socketPath} --data-dir ${dataDir}`);
+
+  // 3. Spawn server (detached, survives parent exit)
+  // Mutable container to capture async spawn errors (Dijkstra amendment B)
+  const state = { spawnError: null as Error | null };
+
+  const serverProcess = _spawn(binaryPath, [dbPath, '--socket', socketPath, '--data-dir', dataDir], {
+    stdio: ['ignore', 'ignore', 'inherit'],
+    detached: true,
+  });
+
+  serverProcess.unref();
+
+  // Wire error handler to capture ENOENT and other spawn failures
+  serverProcess.on('error', (err: Error) => {
+    state.spawnError = err;
+  });
+
+  // 4. Write PID file if requested and pid is available
+  if (pidPath && serverProcess.pid) {
+    _writeFileSync(pidPath, String(serverProcess.pid));
+  }
+
+  // 5. Poll for socket file
+  const maxAttempts = Math.ceil(waitTimeoutMs / 100);
+  let attempts = 0;
+  while (!_existsSync(socketPath) && attempts < maxAttempts) {
+    if (state.spawnError) {
+      throw new Error(
+        `RFDB server failed to start: ${state.spawnError.message} — check binary: ${binaryPath}`
+      );
+    }
+    await sleep(100);
+    attempts++;
+  }
+
+  // 6. Final check
+  if (!_existsSync(socketPath)) {
+    const detail = state.spawnError ? `: ${state.spawnError.message}` : '';
+    throw new Error(
+      `RFDB server failed to start after ${waitTimeoutMs}ms${detail} — check binary: ${binaryPath}`
+    );
+  }
+
+  logger?.debug(`rfdb-server started on ${socketPath}`);
+  return serverProcess;
+}