tywrap 0.1.2 → 0.2.0

package/dist/runtime/node.js

@@ -1,16 +1,26 @@
 /**
- * Node.js runtime bridge (minimal MVP)
+ * Node.js Runtime Bridge with Optional Connection Pooling
+ *
+ * NodeBridge is the unified Node.js runtime bridge that supports both single-process
+ * (correctness-first) and multi-process (pooled) configurations. By default, it runs
+ * in single-process mode for maximum compatibility with the original NodeBridge behavior.
+ *
+ * For high-throughput workloads, configure pooling via minProcesses/maxProcesses options.
  */
 import { existsSync } from 'node:fs';
 import { delimiter, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
+import { EventEmitter } from 'events';
+import { globalCache } from '../utils/cache.js';
 import { autoRegisterArrowDecoder, decodeValueAsync } from '../utils/codec.js';
 import { getDefaultPythonPath } from '../utils/python.js';
 import { getVenvBinDir, getVenvPythonExe } from '../utils/runtime.js';
 import { RuntimeBridge } from './base.js';
 import { BridgeDisposedError, BridgeProtocolError } from './errors.js';
 import { BridgeCore, ensureJsonFallback, ensurePythonEncoding, getMaxLineLengthFromEnv, getPathKey, normalizeEnv, validateBridgeInfo, } from './bridge-core.js';
+import { getComponentLogger } from '../utils/logger.js';
+const log = getComponentLogger('NodeBridge');
 function resolveDefaultScriptPath() {
     try {
         return fileURLToPath(new URL('../../runtime/python_bridge.py', import.meta.url));
@@ -25,13 +35,47 @@ function resolveVirtualEnv(virtualEnv, cwd) {
     const pythonPath = join(binDir, getVenvPythonExe());
     return { venvPath, binDir, pythonPath };
 }
+/**
+ * Node.js runtime bridge for executing Python code.
+ *
+ * By default, runs in single-process mode for correctness-first behavior.
+ * Configure minProcesses/maxProcesses for process pooling in high-throughput scenarios.
+ *
+ * @example
+ * ```typescript
+ * // Single-process mode (default)
+ * const bridge = new NodeBridge();
+ *
+ * // Multi-process pooling for high throughput
+ * const pooledBridge = new NodeBridge({
+ *   minProcesses: 2,
+ *   maxProcesses: 8,
+ *   enableCache: true,
+ * });
+ * ```
+ */
 export class NodeBridge extends RuntimeBridge {
-    child;
-    core;
+    processPool = [];
+    roundRobinIndex = 0;
+    cleanupTimer;
     options;
+    emitter = new EventEmitter();
     disposed = false;
-    initPromise;
     bridgeInfo;
+    initPromise;
+    // Performance monitoring
+    stats = {
+        totalRequests: 0,
+        totalTime: 0,
+        cacheHits: 0,
+        poolHits: 0,
+        poolMisses: 0,
+        processSpawns: 0,
+        processDeaths: 0,
+        memoryPeak: 0,
+        averageTime: 0,
+        cacheHitRate: 0,
+    };
     constructor(options = {}) {
         super();
         const cwd = options.cwd ?? process.cwd();
@@ -40,6 +84,11 @@ export class NodeBridge extends RuntimeBridge {
         const scriptPath = options.scriptPath ?? resolveDefaultScriptPath();
         const resolvedScriptPath = isAbsolute(scriptPath) ? scriptPath : resolve(cwd, scriptPath);
         this.options = {
+            // Default to single-process mode for backward compatibility
+            minProcesses: options.minProcesses ?? 1,
+            maxProcesses: options.maxProcesses ?? 1,
+            maxIdleTime: options.maxIdleTime ?? 300000, // 5 minutes
+            maxRequestsPerProcess: options.maxRequestsPerProcess ?? 1000,
             pythonPath: options.pythonPath ?? venv?.pythonPath ?? getDefaultPythonPath(),
             scriptPath: resolvedScriptPath,
             virtualEnv,
@@ -48,25 +97,45 @@ export class NodeBridge extends RuntimeBridge {
             maxLineLength: options.maxLineLength,
             inheritProcessEnv: options.inheritProcessEnv ?? false,
             enableJsonFallback: options.enableJsonFallback ?? false,
+            enableCache: options.enableCache ?? false,
             env: options.env ?? {},
+            warmupCommands: options.warmupCommands ?? [],
         };
+        // Start cleanup scheduler for pooled mode
+        this.startCleanupScheduler();
     }
     async init() {
         if (this.disposed) {
             throw new BridgeDisposedError('Bridge has been disposed');
         }
-        if (this.child) {
-            return;
+        if (this.processPool.length >= this.options.minProcesses) {
+            return; // Already initialized
         }
         if (this.initPromise) {
             return this.initPromise;
         }
+        this.initPromise = this.doInit();
+        return this.initPromise;
+    }
+    async doInit() {
         // eslint-disable-next-line security/detect-non-literal-fs-filename -- script path is user-configured
         if (!existsSync(this.options.scriptPath)) {
             throw new BridgeProtocolError(`Python bridge script not found at ${this.options.scriptPath}`);
         }
-        this.initPromise = this.startProcess();
-        return this.initPromise;
+        const require = createRequire(import.meta.url);
+        await autoRegisterArrowDecoder({
+            loader: () => require('apache-arrow'),
+        });
+        // Ensure minimum processes are available
+        while (this.processPool.length < this.options.minProcesses) {
+            await this.spawnProcess();
+        }
+        // Validate protocol version
+        await this.refreshBridgeInfo();
+        // Warm up processes if configured
+        if (this.options.warmupCommands.length > 0) {
+            await this.warmupProcesses();
+        }
     }
     async getBridgeInfo(options = {}) {
         await this.init();
@@ -80,94 +149,458 @@ export class NodeBridge extends RuntimeBridge {
     }
     async call(module, functionName, args, kwargs) {
         await this.init();
-        return this.send({ method: 'call', params: { module, functionName, args, kwargs } });
+        const startTime = performance.now();
+        const cacheKey = this.options.enableCache
+            ? this.safeCacheKey('runtime_call', module, functionName, args, kwargs)
+            : null;
+        if (cacheKey) {
+            const cached = await globalCache.get(cacheKey);
+            if (cached !== null) {
+                this.stats.cacheHits++;
+                this.updateStats(performance.now() - startTime);
+                return cached;
+            }
+        }
+        try {
+            const result = await this.executeRequest({
+                method: 'call',
+                params: { module, functionName, args, kwargs },
+            });
+            const duration = performance.now() - startTime;
+            // Cache result for pure functions (simple heuristic)
+            if (cacheKey && this.isPureFunctionCandidate(functionName, args)) {
+                await globalCache.set(cacheKey, result, {
+                    computeTime: duration,
+                    dependencies: [module],
+                });
+            }
+            this.updateStats(duration);
+            return result;
+        }
+        catch (error) {
+            this.updateStats(performance.now() - startTime, true);
+            throw error;
+        }
     }
     async instantiate(module, className, args, kwargs) {
         await this.init();
-        return this.send({ method: 'instantiate', params: { module, className, args, kwargs } });
+        const startTime = performance.now();
+        try {
+            const result = await this.executeRequest({
+                method: 'instantiate',
+                params: { module, className, args, kwargs },
+            });
+            this.updateStats(performance.now() - startTime);
+            return result;
+        }
+        catch (error) {
+            this.updateStats(performance.now() - startTime, true);
+            throw error;
+        }
     }
     async callMethod(handle, methodName, args, kwargs) {
         await this.init();
-        return this.send({ method: 'call_method', params: { handle, methodName, args, kwargs } });
+        const startTime = performance.now();
+        try {
+            const result = await this.executeRequest({
+                method: 'call_method',
+                params: { handle, methodName, args, kwargs },
+            });
+            this.updateStats(performance.now() - startTime);
+            return result;
+        }
+        catch (error) {
+            this.updateStats(performance.now() - startTime, true);
+            throw error;
+        }
     }
     async disposeInstance(handle) {
         await this.init();
-        await this.send({ method: 'dispose_instance', params: { handle } });
+        await this.executeRequest({
+            method: 'dispose_instance',
+            params: { handle },
+        });
     }
-    async dispose() {
-        this.disposed = true;
-        this.core?.handleProcessExit();
-        this.resetProcess();
+    /**
+     * Execute request with intelligent process selection
+     */
+    async executeRequest(payload) {
+        let worker = this.selectOptimalWorker();
+        // Spawn new process if none available and under limit
+        if (!worker && this.processPool.length < this.options.maxProcesses) {
+            try {
+                worker = await this.spawnProcess();
+                this.stats.poolMisses++;
+            }
+            catch (error) {
+                throw new Error(`Failed to spawn worker process: ${error}`);
+            }
+        }
+        // Wait for worker if all are busy
+        worker ??= await this.waitForAvailableWorker();
+        this.stats.poolHits++;
+        return this.sendToWorker(worker, payload);
     }
-    async send(payload) {
-        if (this.disposed) {
-            throw new BridgeDisposedError('Bridge has been disposed');
+    /**
+     * Select optimal worker based on load and performance
+     */
+    selectOptimalWorker() {
+        // For single-process mode, allow concurrent requests to the same worker.
+        // BridgeCore handles request ID multiplexing, so multiple in-flight requests are safe.
+        // This preserves original NodeBridge behavior where concurrent calls were allowed.
+        if (this.options.maxProcesses === 1 && this.processPool.length === 1) {
+            const worker = this.processPool[0];
+            if (worker && !worker.quarantined && worker.process.exitCode === null) {
+                return worker;
+            }
+            return null;
         }
-        if (!this.core) {
-            throw new BridgeProtocolError('Python process not available');
+        // For multi-worker pools, use busy status for load balancing
+        const availableWorkers = this.processPool.filter(w => !w.busy && !w.quarantined && w.process.exitCode === null);
+        if (availableWorkers.length === 0) {
+            return null;
         }
-        return this.core.send(payload);
+        // Simple round-robin for now, could be enhanced with load-based selection
+        const worker = availableWorkers[this.roundRobinIndex % availableWorkers.length];
+        this.roundRobinIndex = (this.roundRobinIndex + 1) % availableWorkers.length;
+        return worker ?? null;
+    }
+    /**
+     * Wait for any worker to become available
+     */
+    async waitForAvailableWorker(timeoutMs = 5000) {
+        return new Promise((resolvePromise, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error('Timeout waiting for available worker'));
+            }, timeoutMs);
+            const checkWorker = () => {
+                const worker = this.selectOptimalWorker();
+                if (worker) {
+                    clearTimeout(timeout);
+                    resolvePromise(worker);
+                }
+                else {
+                    // Check again in 10ms
+                    setTimeout(checkWorker, 10);
+                }
+            };
+            checkWorker();
+        });
     }
-    async startProcess() {
+    /**
+     * Send request to specific worker
+     */
+    async sendToWorker(worker, payload) {
+        worker.busy = true;
+        worker.requestCount++;
+        worker.lastUsed = Date.now();
+        const startTime = performance.now();
         try {
-            const require = createRequire(import.meta.url);
-            await autoRegisterArrowDecoder({
-                loader: () => require('apache-arrow'),
-            });
-            const { spawn } = await import('child_process');
-            const env = this.buildEnv();
-            const maxLineLength = this.options.maxLineLength ?? getMaxLineLengthFromEnv(env);
-            let child;
-            try {
-                child = spawn(this.options.pythonPath, [this.options.scriptPath], {
-                    cwd: this.options.cwd,
-                    stdio: ['pipe', 'pipe', 'pipe'],
-                    env,
+            const result = await worker.core.send(payload);
+            const duration = performance.now() - startTime;
+            worker.stats.totalTime += duration;
+            worker.stats.totalRequests++;
+            worker.stats.averageTime = worker.stats.totalTime / worker.stats.totalRequests;
+            return result;
+        }
+        catch (error) {
+            worker.stats.errorCount++;
+            throw error;
+        }
+        finally {
+            worker.busy = false;
+        }
+    }
+    quarantineWorker(worker, error) {
+        if (worker.quarantined) {
+            return;
+        }
+        worker.quarantined = true;
+        log.warn('Quarantining worker', { workerId: worker.id, error: String(error) });
+        this.terminateWorker(worker, { force: true })
+            .then(() => {
+            if (!this.disposed && this.processPool.length < this.options.minProcesses) {
+                this.spawnProcess().catch(spawnError => {
+                    log.error('Failed to spawn replacement worker after quarantine', {
+                        error: String(spawnError),
+                    });
                 });
             }
-            catch (err) {
-                throw new BridgeProtocolError(`Failed to start Python process: ${err.message}`);
+        })
+            .catch(terminateError => {
+            log.warn('Failed to terminate quarantined worker', {
+                workerId: worker.id,
+                error: String(terminateError),
+            });
+        });
+    }
+    /**
+     * Spawn new worker process with optimizations
+     */
+    async spawnProcess() {
+        const { spawn } = await import('child_process');
+        const workerId = `worker_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        const env = this.buildEnv();
+        env.PYTHONUNBUFFERED = '1'; // Ensure immediate output
+        env.PYTHONDONTWRITEBYTECODE = '1'; // Skip .pyc files for faster startup
+        const maxLineLength = this.options.maxLineLength ?? getMaxLineLengthFromEnv(env);
+        const childProcess = spawn(this.options.pythonPath, [this.options.scriptPath], {
+            cwd: this.options.cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env,
+        });
+        const worker = {
+            process: childProcess,
+            id: workerId,
+            requestCount: 0,
+            lastUsed: Date.now(),
+            busy: false,
+            quarantined: false,
+            core: null,
+            stats: {
+                totalRequests: 0,
+                totalTime: 0,
+                averageTime: 0,
+                errorCount: 0,
+            },
+        };
+        worker.core = new BridgeCore({
+            write: (data) => {
+                if (!worker.process.stdin?.writable) {
+                    throw new BridgeProtocolError('Worker process stdin not writable');
+                }
+                worker.process.stdin.write(data);
+            },
+        }, {
+            timeoutMs: this.options.timeoutMs,
+            maxLineLength,
+            decodeValue: decodeValueAsync,
+            onFatalError: (error) => this.quarantineWorker(worker, error),
+            onTimeout: (error) => this.quarantineWorker(worker, error),
+        });
+        // Setup process event handlers
+        this.setupProcessHandlers(worker);
+        this.processPool.push(worker);
+        this.stats.processSpawns++;
+        return worker;
+    }
+    /**
+     * Setup event handlers for worker process
+     */
+    setupProcessHandlers(worker) {
+        const childProcess = worker.process;
+        childProcess.stdout?.on('data', (chunk) => {
+            worker.core.handleStdoutData(chunk);
+        });
+        childProcess.stderr?.on('data', (chunk) => {
+            worker.core.handleStderrData(chunk);
+            const errorText = chunk.toString().trim();
+            if (errorText) {
+                log.warn('Worker stderr', { workerId: worker.id, output: errorText });
             }
-            const startupError = await new Promise(done => {
-                child.once('error', e => done(e));
-                child.once('spawn', () => done(null));
+        });
+        // Handle process exit
+        childProcess.on('exit', code => {
+            log.warn('Worker exited', { workerId: worker.id, code });
+            worker.core.handleProcessExit();
+            this.handleWorkerExit(worker, code);
+        });
+        // Handle process errors
+        childProcess.on('error', error => {
+            log.error('Worker error', { workerId: worker.id, error: String(error) });
+            worker.core.handleProcessError(error);
+            this.handleWorkerExit(worker, -1);
+        });
+    }
+    /**
+     * Handle worker process exit
+     */
+    handleWorkerExit(worker, _code) {
+        if (!this.processPool.includes(worker)) {
+            return;
+        }
+        worker.core.clear();
+        // Remove from pool
+        const index = this.processPool.indexOf(worker);
+        if (index >= 0) {
+            this.processPool.splice(index, 1);
+            this.stats.processDeaths++;
+        }
+        // Spawn replacement if needed and not disposing
+        if (!this.disposed && this.processPool.length < this.options.minProcesses) {
+            this.spawnProcess().catch(error => {
+                log.error('Failed to spawn replacement worker', { error: String(error) });
             });
-            if (startupError) {
-                throw new BridgeProtocolError(`Failed to start Python process: ${startupError.message}`);
+        }
+    }
+    /**
+     * Warm up processes with configured commands
+     */
+    async warmupProcesses() {
+        const warmupPromises = this.processPool.map(async (worker) => {
+            for (const cmd of this.options.warmupCommands) {
+                try {
+                    await this.sendToWorker(worker, {
+                        method: cmd.method,
+                        params: cmd.params,
+                    });
+                }
+                catch (error) {
+                    log.warn('Warmup command failed', { workerId: worker.id, error: String(error) });
+                }
+            }
+        });
+        await Promise.all(warmupPromises);
+    }
+    safeCacheKey(prefix, ...inputs) {
+        try {
+            return globalCache.generateKey(prefix, ...inputs);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Heuristic to determine if function result should be cached
+     */
+    isPureFunctionCandidate(functionName, args) {
+        // Simple heuristics - could be made more sophisticated
+        const pureFunctionPatterns = [
+            /^(get|fetch|read|load|find|search|query|select)_/i,
+            /^(compute|calculate|process|transform|convert)_/i,
+            /^(encode|decode|serialize|deserialize)_/i,
+        ];
+        const impureFunctionPatterns = [
+            /^(set|save|write|update|insert|delete|create|modify)_/i,
+            /^(send|post|put|patch)_/i,
+            /random|uuid|timestamp|now|current/i,
+        ];
+        // Don't cache if function name suggests mutation
+        if (impureFunctionPatterns.some(pattern => pattern.test(functionName))) {
+            return false;
+        }
+        // Cache if function name suggests pure computation
+        if (pureFunctionPatterns.some(pattern => pattern.test(functionName))) {
+            return true;
+        }
+        // Don't cache if args contain mutable objects (very basic check)
+        const hasComplexArgs = args.some(arg => arg !== null && typeof arg === 'object' && !(arg instanceof Date));
+        return !hasComplexArgs && args.length <= 3; // Cache simple calls with few args
+    }
+    /**
+     * Update performance statistics
+     */
+    updateStats(duration, _error = false) {
+        this.stats.totalRequests++;
+        this.stats.totalTime += duration;
+        const currentMemory = process.memoryUsage().heapUsed;
+        if (currentMemory > this.stats.memoryPeak) {
+            this.stats.memoryPeak = currentMemory;
+        }
+    }
+    /**
+     * Get performance statistics
+     */
+    getStats() {
+        const avgTime = this.stats.totalRequests > 0 ? this.stats.totalTime / this.stats.totalRequests : 0;
+        const hitRate = this.stats.totalRequests > 0 ? this.stats.cacheHits / this.stats.totalRequests : 0;
+        return {
+            ...this.stats,
+            averageTime: avgTime,
+            cacheHitRate: hitRate,
+            poolSize: this.processPool.length,
+            busyWorkers: this.processPool.filter(w => w.busy).length,
+            memoryUsage: process.memoryUsage(),
+            workerStats: this.processPool.map(w => ({
+                id: w.id,
+                requestCount: w.requestCount,
+                averageTime: w.stats.averageTime,
+                errorCount: w.stats.errorCount,
+                busy: w.busy,
+                pendingRequests: w.core.getPendingCount(),
+            })),
+        };
+    }
+    /**
+     * Cleanup idle processes
+     */
+    async cleanup() {
+        const now = Date.now();
+        const idleWorkers = this.processPool.filter(w => !w.busy &&
+            now - w.lastUsed > this.options.maxIdleTime &&
+            this.processPool.length > this.options.minProcesses);
+        for (const worker of idleWorkers) {
+            await this.terminateWorker(worker);
+        }
+        // Restart workers that have handled too many requests
+        const overusedWorkers = this.processPool.filter(w => !w.busy && w.requestCount >= this.options.maxRequestsPerProcess);
+        for (const worker of overusedWorkers) {
+            await this.terminateWorker(worker);
+            if (this.processPool.length < this.options.minProcesses) {
+                await this.spawnProcess();
             }
-            this.child = child;
-            this.core = new BridgeCore({
-                write: (data) => {
-                    if (!this.child?.stdin) {
-                        throw new BridgeProtocolError('Python process not available');
+        }
+    }
+    /**
+     * Gracefully terminate a worker
+     */
+    async terminateWorker(worker, options = {}) {
+        if (worker.busy && !options.force) {
+            return;
+        }
+        const index = this.processPool.indexOf(worker);
+        if (index >= 0) {
+            this.processPool.splice(index, 1);
+            this.stats.processDeaths++;
+        }
+        worker.core.handleProcessExit();
+        worker.core.clear();
+        // Graceful termination
+        try {
+            if (worker.process.exitCode === null) {
+                worker.process.kill('SIGTERM');
+                // Force kill if not terminated in 5 seconds
+                setTimeout(() => {
+                    if (worker.process.exitCode === null) {
+                        worker.process.kill('SIGKILL');
                     }
-                    this.child.stdin.write(data);
-                },
-            }, {
-                timeoutMs: this.options.timeoutMs,
-                maxLineLength,
-                decodeValue: decodeValueAsync,
-                onFatalError: () => this.resetProcess(),
-            });
-            this.child.stdout?.on('data', chunk => {
-                this.core?.handleStdoutData(chunk);
-            });
-            this.child.stderr?.on('data', chunk => {
-                this.core?.handleStderrData(chunk);
-            });
-            this.child.on('error', err => {
-                this.core?.handleProcessError(err);
-            });
-            this.child.on('exit', () => {
-                this.core?.handleProcessExit();
-                this.resetProcess();
-            });
-            await this.refreshBridgeInfo();
+                }, 5000);
+            }
+        }
+        catch (error) {
+            log.warn('Error terminating worker', { workerId: worker.id, error: String(error) });
+        }
+    }
+    /**
+     * Start cleanup scheduler
+     */
+    startCleanupScheduler() {
+        this.cleanupTimer = setInterval(async () => {
+            try {
+                await this.cleanup();
+            }
+            catch (error) {
+                log.error('Cleanup error', { error: String(error) });
+            }
+        }, 60000); // Cleanup every minute
+    }
+    /**
+     * Dispose all resources
+     */
+    async dispose() {
+        if (this.disposed) {
+            return;
         }
-        catch (err) {
-            this.resetProcess();
-            throw err;
+        this.disposed = true;
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
         }
+        // Terminate all workers
+        const terminationPromises = this.processPool.map(worker => this.terminateWorker(worker, { force: true }));
+        await Promise.all(terminationPromises);
+        this.processPool.length = 0;
+        this.emitter.removeAllListeners();
     }
     buildEnv() {
         const allowedPrefixes = ['TYWRAP_'];
@@ -199,32 +632,19 @@ export class NodeBridge extends RuntimeBridge {
             env[pathKey] = `${venv.binDir}${delimiter}${currentPath}`;
         }
         ensurePythonEncoding(env);
-        // Respect explicit request for JSON fallback only; otherwise fast-fail by default
         ensureJsonFallback(env, this.options.enableJsonFallback);
         env = normalizeEnv(env, {});
         return env;
     }
-    resetProcess() {
-        this.core?.clear();
-        this.core = undefined;
-        if (this.child) {
-            try {
-                if (this.child.exitCode === null) {
-                    this.child.kill('SIGTERM');
-                }
-            }
-            catch {
-                // ignore
-            }
-        }
-        this.child = undefined;
-        this.initPromise = undefined;
-        this.bridgeInfo = undefined;
-    }
     async refreshBridgeInfo() {
-        const info = await this.send({ method: 'meta', params: {} });
+        const info = await this.executeRequest({ method: 'meta', params: {} });
         validateBridgeInfo(info);
         this.bridgeInfo = info;
     }
 }
+/**
+ * @deprecated Use NodeBridge with minProcesses/maxProcesses options instead.
+ * This alias is provided for backward compatibility.
+ */
+export { NodeBridge as OptimizedNodeBridge };
 //# sourceMappingURL=node.js.map