/**
* postgres-mcp - Sandbox Factory
*
* Factory functions for creating sandbox instances with configurable isolation modes.
* Allows runtime selection between vm-based and worker-based sandboxes.
*/
import { CodeModeSandbox, SandboxPool } from './sandbox.js';
import { WorkerSandbox, WorkerSandboxPool } from './worker-sandbox.js';
import { logger } from '../utils/logger.js';
import type {
SandboxOptions,
PoolOptions,
SandboxResult
} from './types.js';
/**
* Sandbox isolation mode
*/
export type SandboxMode = 'vm' | 'worker';
/**
* Unified sandbox interface
*/
export interface ISandbox {
execute(code: string, apiBindings: Record<string, unknown>): Promise<SandboxResult>;
isHealthy(): boolean;
dispose(): void;
}
/**
* Unified sandbox pool interface
*/
export interface ISandboxPool {
initialize(): void;
execute(code: string, apiBindings: Record<string, unknown>): Promise<SandboxResult>;
getStats(): { available: number; inUse: number; max: number };
dispose(): void;
}
/**
* Mode info for documentation/selection
*/
export interface SandboxModeInfo {
name: string;
isolation: string;
performance: string;
security: string;
requirements: string;
}
// Default mode (module-level state)
let defaultMode: SandboxMode = 'vm';
/**
* Set the default sandbox mode
*/
export function setDefaultSandboxMode(mode: SandboxMode): void {
defaultMode = mode;
logger.info(`Sandbox default mode set to: ${mode}`, {
module: 'CODEMODE' as const
});
}
/**
* Get the current default mode
*/
export function getDefaultSandboxMode(): SandboxMode {
return defaultMode;
}
/**
* Get available sandbox modes
*/
export function getAvailableSandboxModes(): SandboxMode[] {
return ['vm', 'worker'];
}
/**
* Create a sandbox instance
* @param mode - Isolation mode ('vm' or 'worker')
* @param options - Sandbox options
*/
export function createSandbox(mode?: SandboxMode, options?: SandboxOptions): ISandbox {
const selectedMode = mode ?? defaultMode;
switch (selectedMode) {
case 'worker':
return WorkerSandbox.create(options);
case 'vm':
default:
return CodeModeSandbox.create(options);
}
}
/**
* Create a sandbox pool
* @param mode - Isolation mode ('vm' or 'worker')
* @param poolOptions - Pool configuration
* @param sandboxOptions - Sandbox configuration
*/
export function createSandboxPool(
mode?: SandboxMode,
poolOptions?: PoolOptions,
sandboxOptions?: SandboxOptions
): ISandboxPool {
const selectedMode = mode ?? defaultMode;
switch (selectedMode) {
case 'worker':
return new WorkerSandboxPool(poolOptions, sandboxOptions);
case 'vm':
default:
return new SandboxPool(poolOptions, sandboxOptions);
}
}
/**
* Get mode characteristics for documentation/selection
*/
export function getSandboxModeInfo(mode: SandboxMode): SandboxModeInfo {
switch (mode) {
case 'worker':
return {
name: 'Worker Thread',
isolation: 'Separate V8 instance per worker',
performance: 'Higher overhead (thread spawn per execution)',
security: 'Enhanced - isolated memory, hard timeouts',
requirements: 'Node.js worker_threads (built-in)'
};
case 'vm':
default:
return {
name: 'VM Context',
isolation: 'Script isolation within same process',
performance: 'Low overhead (reusable contexts)',
security: 'Standard - script isolation, blocked globals',
requirements: 'Node.js vm module (built-in)'
};
}
}
