@mhingston5/conduit 1.0.0

package/src/index.ts

@@ -0,0 +1,92 @@
+import { ConfigService } from './core/config.service.js';
+import { createLogger, loggerStorage } from './core/logger.js';
+import { SocketTransport } from './transport/socket.transport.js';
+import { OpsServer } from './core/ops.server.js';
+import { ConcurrencyService } from './core/concurrency.service.js';
+import { RequestController } from './core/request.controller.js';
+import { GatewayService } from './gateway/gateway.service.js';
+import { SecurityService } from './core/security.service.js';
+import { OtelService } from './core/otel.service.js';
+import { DenoExecutor } from './executors/deno.executor.js';
+import { PyodideExecutor } from './executors/pyodide.executor.js';
+import { IsolateExecutor } from './executors/isolate.executor.js';
+import { ExecutorRegistry } from './core/registries/executor.registry.js';
+import { ExecutionService } from './core/execution.service.js';
+import { buildDefaultMiddleware } from './core/middleware/middleware.builder.js';
+async function main() {
+    const configService = new ConfigService();
+    const logger = createLogger(configService);
+
+    const otelService = new OtelService(logger);
+    await otelService.start();
+
+    await loggerStorage.run({ correlationId: 'system' }, async () => {
+        const securityService = new SecurityService(logger, configService.get('ipcBearerToken'));
+
+        const gatewayService = new GatewayService(logger, securityService);
+        const upstreams = configService.get('upstreams') || [];
+        for (const upstream of upstreams) {
+            gatewayService.registerUpstream(upstream);
+        }
+
+        const executorRegistry = new ExecutorRegistry();
+        executorRegistry.register('deno', new DenoExecutor(configService.get('denoMaxPoolSize')));
+        executorRegistry.register('python', new PyodideExecutor(configService.get('pyodideMaxPoolSize')));
+
+        // IsolateExecutor needs gatewayService
+        const isolateExecutor = new IsolateExecutor(logger, gatewayService);
+        executorRegistry.register('isolate', isolateExecutor);
+
+        const executionService = new ExecutionService(
+            logger,
+            configService.get('resourceLimits'),
+            gatewayService,
+            securityService,
+            executorRegistry
+        );
+
+        const requestController = new RequestController(
+            logger,
+            executionService,
+            gatewayService,
+            buildDefaultMiddleware(securityService)
+        );
+
+        const opsServer = new OpsServer(logger, configService.all, gatewayService, requestController);
+        await opsServer.listen();
+
+        const concurrencyService = new ConcurrencyService(logger, {
+            maxConcurrent: configService.get('maxConcurrent')
+        });
+
+        const transport = new SocketTransport(logger, requestController, concurrencyService);
+        const port = configService.get('port');
+        const address = await transport.listen({ port });
+        executionService.ipcAddress = address; // Update IPC address on ExecutionService instead of RequestController
+
+        // Pre-warm workers
+        await requestController.warmup();
+
+        logger.info('Conduit server started');
+
+        // Handle graceful shutdown
+        const shutdown = async () => {
+            logger.info('Shutting down...');
+            await Promise.all([
+                transport.close(),
+                opsServer.close(),
+                requestController.shutdown(),
+                otelService.shutdown(),
+            ]);
+            process.exit(0);
+        };
+
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    });
+}
+
+main().catch((err) => {
+    console.error('Failed to start Conduit:', err);
+    process.exit(1);
+});

package/src/sdk/index.ts

@@ -0,0 +1,2 @@
+export { ToolBinding, SDKGeneratorOptions, toToolBinding, groupByNamespace } from './tool-binding.js';
+export { SDKGenerator } from './sdk-generator.js';

package/src/sdk/sdk-generator.ts

@@ -0,0 +1,245 @@
+import { ToolBinding, groupByNamespace } from './tool-binding.js';
+
+/**
+ * Generates in-memory SDK code from discovered tool bindings.
+ * The generated code creates a nested object structure where
+ * tools.namespace.method(args) => callTool("namespace__method", args)
+ */
+export class SDKGenerator {
+    /**
+     * Convert camelCase to snake_case for Python
+     */
+    private toSnakeCase(str: string): string {
+        return str.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
+    }
+
+    /**
+     * Escape a string for use in generated code
+     */
+    private escapeString(str: string): string {
+        return str.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n');
+    }
+
+    /**
+     * Generate TypeScript SDK code to be injected into Deno sandbox.
+     * Creates: tools.namespace.method(args) => __internalCallTool("namespace__method", args)
+     * @param bindings Tool bindings to generate SDK for
+     * @param allowedTools Optional allowlist for $raw() enforcement
+     * @param enableRawFallback Enable $raw() escape hatch (default: true)
+     */
+    generateTypeScript(bindings: ToolBinding[], allowedTools?: string[], enableRawFallback = true): string {
+        const grouped = groupByNamespace(bindings);
+        const lines: string[] = [];
+
+        lines.push('// Generated SDK - Do not edit');
+
+        // Inject allowlist for SDK-level enforcement
+        if (allowedTools && allowedTools.length > 0) {
+            const normalizedList = allowedTools.map(t => t.replace(/\./g, '__'));
+            lines.push(`const __allowedTools = ${JSON.stringify(normalizedList)};`);
+        } else {
+            lines.push('const __allowedTools = null;');
+        }
+
+        lines.push('const tools = {');
+
+        for (const [namespace, tools] of grouped.entries()) {
+            // Validate namespace is a valid identifier
+            const safeNamespace = this.isValidIdentifier(namespace) ? namespace : `["${this.escapeString(namespace)}"]`;
+
+            if (this.isValidIdentifier(namespace)) {
+                lines.push(`  ${namespace}: {`);
+            } else {
+                lines.push(`  "${this.escapeString(namespace)}": {`);
+            }
+
+            for (const tool of tools) {
+                const methodName = this.isValidIdentifier(tool.methodName)
+                    ? tool.methodName
+                    : `["${this.escapeString(tool.methodName)}"]`;
+
+                // Add JSDoc if description available
+                if (tool.description) {
+                    lines.push(`    /** ${this.escapeString(tool.description)} */`);
+                }
+
+                if (this.isValidIdentifier(tool.methodName)) {
+                    lines.push(`    async ${tool.methodName}(args) {`);
+                } else {
+                    lines.push(`    "${this.escapeString(tool.methodName)}": async function(args) {`);
+                }
+                lines.push(`      return await __internalCallTool("${this.escapeString(tool.name)}", args);`);
+                lines.push(`    },`);
+            }
+
+            lines.push(`  },`);
+        }
+
+        // Add $raw escape hatch with allowlist validation
+        if (enableRawFallback) {
+            lines.push(`  /** Call a tool by its full name (escape hatch for dynamic/unknown tools) */`);
+            lines.push(`  async $raw(name, args) {`);
+            lines.push(`    const normalized = name.replace(/\\./g, '__');`);
+            lines.push(`    if (__allowedTools) {`);
+            lines.push(`      const allowed = __allowedTools.some(p => {`);
+            lines.push(`        if (p.endsWith('__*')) return normalized.startsWith(p.slice(0, -1));`);
+            lines.push(`        return normalized === p;`);
+            lines.push(`      });`);
+            lines.push(`      if (!allowed) throw new Error(\`Tool \${name} is not in the allowlist\`);`);
+            lines.push(`    }`);
+            lines.push(`    return await __internalCallTool(normalized, args);`);
+            lines.push(`  },`);
+        }
+
+        lines.push('};');
+        lines.push('(globalThis as any).tools = tools;');
+
+        return lines.join('\n');
+    }
+
+    /**
+     * Generate Python SDK code to be injected into Pyodide sandbox.
+     * Creates: tools.namespace.method(args) => _internal_call_tool("namespace__method", args)
+     * @param bindings Tool bindings to generate SDK for
+     * @param allowedTools Optional allowlist for raw() enforcement
+     * @param enableRawFallback Enable raw() escape hatch (default: true)
+     */
+    generatePython(bindings: ToolBinding[], allowedTools?: string[], enableRawFallback = true): string {
+        const grouped = groupByNamespace(bindings);
+        const lines: string[] = [];
+
+        lines.push('# Generated SDK - Do not edit');
+
+        // Inject allowlist for SDK-level enforcement
+        if (allowedTools && allowedTools.length > 0) {
+            const normalizedList = allowedTools.map(t => t.replace(/\./g, '__'));
+            lines.push(`_allowed_tools = ${JSON.stringify(normalizedList)}`);
+        } else {
+            lines.push('_allowed_tools = None');
+        }
+
+        lines.push('');
+        lines.push('class _ToolNamespace:');
+        lines.push('    def __init__(self, methods):');
+        lines.push('        for name, fn in methods.items():');
+        lines.push('            setattr(self, name, fn)');
+        lines.push('');
+        lines.push('class _Tools:');
+        lines.push('    def __init__(self):');
+
+        for (const [namespace, tools] of grouped.entries()) {
+            const safeNamespace = this.toSnakeCase(namespace);
+            const methodsDict: string[] = [];
+
+            for (const tool of tools) {
+                const methodName = this.toSnakeCase(tool.methodName);
+                const fullName = tool.name;
+                // Use async lambda - Python doesn't have async lambdas natively,
+                // so we define methods that return awaitable coroutines
+                methodsDict.push(`            "${methodName}": lambda args, n="${this.escapeString(fullName)}": _internal_call_tool(n, args)`);
+            }
+
+            lines.push(`        self.${safeNamespace} = _ToolNamespace({`);
+            lines.push(methodsDict.join(',\n'));
+            lines.push(`        })`);
+        }
+
+        // Add raw escape hatch with allowlist validation
+        if (enableRawFallback) {
+            lines.push('');
+            lines.push('    async def raw(self, name, args):');
+            lines.push('        """Call a tool by its full name (escape hatch for dynamic/unknown tools)"""');
+            lines.push('        normalized = name.replace(".", "__")');
+            lines.push('        if _allowed_tools is not None:');
+            lines.push('            allowed = any(');
+            lines.push('                normalized.startswith(p[:-1]) if p.endswith("__*") else normalized == p');
+            lines.push('                for p in _allowed_tools');
+            lines.push('            )');
+            lines.push('            if not allowed:');
+            lines.push('                raise PermissionError(f"Tool {name} is not in the allowlist")');
+            lines.push('        return await _internal_call_tool(normalized, args)');
+        }
+
+        lines.push('');
+        lines.push('tools = _Tools()');
+
+        return lines.join('\n');
+    }
+
+    /**
+     * Generate JavaScript SDK code for isolated-vm (V8 Isolate).
+     * Creates: tools.namespace.method(args) => __callToolSync("namespace__method", JSON.stringify(args))
+     * @param bindings Tool bindings to generate SDK for
+     * @param allowedTools Optional allowlist for $raw() enforcement
+     * @param enableRawFallback Enable $raw() escape hatch (default: true)
+     */
+    generateIsolateSDK(bindings: ToolBinding[], allowedTools?: string[], enableRawFallback = true): string {
+        const grouped = groupByNamespace(bindings);
+        const lines: string[] = [];
+
+        lines.push('// Generated SDK for isolated-vm');
+
+        // Inject allowlist for SDK-level enforcement (optional, as Gateway also enforces)
+        if (allowedTools && allowedTools.length > 0) {
+            const normalizedList = allowedTools.map(t => t.replace(/\./g, '__'));
+            lines.push(`const __allowedTools = ${JSON.stringify(normalizedList)};`);
+        } else {
+            lines.push('const __allowedTools = null;');
+        }
+
+        lines.push('const tools = {');
+
+        for (const [namespace, tools] of grouped.entries()) {
+            const safeNamespace = this.isValidIdentifier(namespace) ? namespace : `["${this.escapeString(namespace)}"]`;
+
+            if (this.isValidIdentifier(namespace)) {
+                lines.push(`  ${namespace}: {`);
+            } else {
+                lines.push(`  "${this.escapeString(namespace)}": {`);
+            }
+
+            for (const tool of tools) {
+                const methodName = this.isValidIdentifier(tool.methodName) ? tool.methodName : `["${this.escapeString(tool.methodName)}"]`;
+
+                if (this.isValidIdentifier(tool.methodName)) {
+                    lines.push(`    async ${methodName}(args) {`);
+                } else {
+                    lines.push(`    "${this.escapeString(tool.methodName)}": async function(args) {`);
+                }
+
+                lines.push(`      const resStr = await __callTool("${this.escapeString(tool.name)}", JSON.stringify(args || {}));`);
+                lines.push(`      return JSON.parse(resStr);`);
+                lines.push(`    },`);
+            }
+
+            lines.push(`  },`);
+        }
+
+        // Add $raw escape hatch
+        if (enableRawFallback) {
+            lines.push(`  async $raw(name, args) {`);
+            lines.push(`    const normalized = name.replace(/\\./g, '__');`);
+            lines.push(`    if (__allowedTools) {`);
+            lines.push(`      const allowed = __allowedTools.some(p => {`);
+            lines.push(`        if (p.endsWith('__*')) return normalized.startsWith(p.slice(0, -1));`);
+            lines.push(`        return normalized === p;`);
+            lines.push(`      });`);
+            lines.push(`      if (!allowed) throw new Error(\`Tool \${name} is not in the allowlist\`);`);
+            lines.push(`    }`);
+            lines.push(`    const resStr = await __callTool(normalized, JSON.stringify(args || {}));`);
+            lines.push(`    return JSON.parse(resStr);`);
+            lines.push(`  },`);
+        }
+
+        lines.push('};');
+
+        return lines.join('\n');
+    }
+
+    /**
+     * Check if a string is a valid JavaScript/Python identifier
+     */
+    private isValidIdentifier(str: string): boolean {
+        return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(str);
+    }
+}

package/src/sdk/tool-binding.ts

@@ -0,0 +1,86 @@
+/**
+ * Language-agnostic interface for tool bindings.
+ * Used to generate typed SDK code for sandbox injection.
+ */
+export interface ToolBinding {
+    /** Full qualified name: "github__createIssue" */
+    name: string;
+    /** Upstream ID / namespace: "github" */
+    namespace: string;
+    /** Tool method name: "createIssue" */
+    methodName: string;
+    /** JSON Schema for input validation */
+    inputSchema?: object;
+    /** Human-readable description */
+    description?: string;
+}
+
+export interface SDKGeneratorOptions {
+    /** Tool bindings to include in SDK */
+    tools: ToolBinding[];
+    /** Allow $raw escape hatch for dynamic calls (default: true) */
+    enableRawFallback?: boolean;
+}
+
+// Inline parsing to avoid circular dependency with PolicyService
+function parseToolName(qualifiedName: string): { namespace: string; name: string } {
+    const separatorIndex = qualifiedName.indexOf('__');
+    if (separatorIndex === -1) {
+        return { namespace: '', name: qualifiedName };
+    }
+    return {
+        namespace: qualifiedName.substring(0, separatorIndex),
+        name: qualifiedName.substring(separatorIndex + 2)
+    };
+}
+
+/**
+ * Convert a prefixed tool name to a ToolBinding.
+ * @param name Full tool name in format "namespace__methodName"
+ * @param inputSchema Optional JSON Schema
+ * @param description Optional description
+ */
+export function toToolBinding(
+    name: string,
+    inputSchema?: object,
+    description?: string
+): ToolBinding {
+    const toolId = parseToolName(name);
+
+    return {
+        name,
+        namespace: toolId.namespace || 'default',
+        methodName: toolId.name || name,
+        inputSchema,
+        description,
+    };
+}
+
+/**
+ * Convert a ToolStub to a ToolBinding.
+ * @param stub ToolStub from GatewayService
+ */
+export function fromToolStub(stub: { id: string; name: string; description?: string }): ToolBinding {
+    const toolId = parseToolName(stub.id);
+    return {
+        name: stub.id,
+        namespace: toolId.namespace || 'default',
+        methodName: stub.name, // stub.name is already the method name (e.g. "create_issue")
+        description: stub.description,
+    };
+}
+
+/**
+ * Group tool bindings by namespace for SDK generation.
+ */
+export function groupByNamespace(bindings: ToolBinding[]): Map<string, ToolBinding[]> {
+    const groups = new Map<string, ToolBinding[]>();
+
+    for (const binding of bindings) {
+        const existing = groups.get(binding.namespace) || [];
+        existing.push(binding);
+        groups.set(binding.namespace, existing);
+    }
+
+    return groups;
+}

package/src/transport/socket.transport.ts

@@ -0,0 +1,203 @@
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { Logger } from 'pino';
+import { RequestController } from '../core/request.controller.js';
+import { JSONRPCRequest, ConduitError } from '../core/types.js';
+import { ExecutionContext } from '../core/execution.context.js';
+import { ConcurrencyService } from '../core/concurrency.service.js';
+import { loggerStorage } from '../core/logger.js';
+
+export interface TransportOptions {
+    path?: string; // For Unix Socket or Named Pipe
+    port?: number; // For TCP (development)
+    host?: string;
+}
+
+export class SocketTransport {
+    private server: net.Server;
+    private logger: Logger;
+    private requestController: RequestController;
+    private concurrencyService: ConcurrencyService;
+
+    constructor(
+        logger: Logger,
+        requestController: RequestController,
+        concurrencyService: ConcurrencyService
+    ) {
+        this.logger = logger;
+        this.requestController = requestController;
+        this.concurrencyService = concurrencyService;
+        this.server = net.createServer((socket) => {
+            this.handleConnection(socket);
+        });
+
+        this.server.on('error', (err) => {
+            this.logger.error({ err }, 'Server error');
+        });
+    }
+
+    async listen(options: TransportOptions): Promise<string> {
+        return new Promise((resolve, reject) => {
+            if (options.path) {
+                // Strict IPC mode
+                const socketPath = this.formatSocketPath(options.path);
+                this.logger.info({ socketPath }, 'Binding to IPC socket');
+
+                // Cleanup existing socket if needed (unlikely on Windows, but good for Unix)
+                if (os.platform() !== 'win32' && path.isAbsolute(socketPath)) {
+                    // We rely on caller or deployment to clean up, or error out. 
+                    // Trying to unlink here might be dangerous if we don't own it.
+                    // But strictly, we should just listen.
+                }
+
+                this.server.listen(socketPath, () => {
+                    this.resolveAddress(resolve);
+                });
+            } else if (options.port !== undefined) {
+                // Strict TCP mode
+                this.logger.info({ port: options.port, host: options.host }, 'Binding to TCP port');
+                this.server.listen(options.port, options.host || '127.0.0.1', () => {
+                    this.resolveAddress(resolve);
+                });
+            } else {
+                reject(new Error('Invalid transport configuration: neither path nor port provided'));
+                return;
+            }
+
+            this.server.on('error', reject);
+        });
+    }
+
+    private resolveAddress(resolve: (value: string) => void) {
+        const address = this.server.address();
+        const addressStr = typeof address === 'string' ? address : `${address?.address}:${address?.port}`;
+        this.logger.info({ address: addressStr }, 'Transport server listening');
+        resolve(addressStr);
+    }
+
+    private formatSocketPath(inputPath: string): string {
+        if (os.platform() === 'win32') {
+            // Windows Named Pipe format: \\.\pipe\conduit-[id]
+            if (!inputPath.startsWith('\\\\.\\pipe\\')) {
+                return `\\\\.\\pipe\\${inputPath}`;
+            }
+            return inputPath;
+        } else {
+            // Unix Socket path
+            return path.isAbsolute(inputPath) ? inputPath : path.join(os.tmpdir(), inputPath);
+        }
+    }
+
+    private handleConnection(socket: net.Socket) {
+        const remoteAddress = socket.remoteAddress || 'pipe';
+        this.logger.debug({ remoteAddress }, 'New connection established');
+
+        socket.setEncoding('utf8');
+        let buffer = '';
+        const MAX_BUFFER_SIZE = 10 * 1024 * 1024; // 10MB limit
+
+        socket.on('data', async (chunk) => {
+            buffer += chunk;
+
+            if (buffer.length > MAX_BUFFER_SIZE) {
+                this.logger.error({ remoteAddress }, 'Connection exceeded max buffer size, closing');
+                socket.destroy();
+                return;
+            }
+
+            // Backpressure: pause processing new chunks until this buffer is handled
+            socket.pause();
+
+            try {
+                let pos: number;
+                while ((pos = buffer.indexOf('\n')) >= 0) {
+                    const line = buffer.substring(0, pos).trim();
+                    buffer = buffer.substring(pos + 1);
+
+                    if (!line) continue;
+
+                    let request: JSONRPCRequest;
+                    try {
+                        request = JSON.parse(line) as JSONRPCRequest;
+                    } catch (err) {
+                        this.logger.error({ err, line }, 'Failed to parse JSON-RPC request');
+                        const errorResponse = {
+                            jsonrpc: '2.0',
+                            id: null,
+                            error: {
+                                code: -32700,
+                                message: 'Parse error',
+                            },
+                        };
+                        socket.write(JSON.stringify(errorResponse) + '\n');
+                        continue;
+                    }
+
+                    const context = new ExecutionContext({
+                        logger: this.logger,
+                        remoteAddress: remoteAddress,
+                    });
+
+                    await loggerStorage.run({ correlationId: context.correlationId }, async () => {
+                        try {
+                            const response = await this.concurrencyService.run(() =>
+                                this.requestController.handleRequest(request, context)
+                            );
+                            socket.write(JSON.stringify(response) + '\n');
+                        } catch (err: any) {
+                            if (err.name === 'QueueFullError') {
+                                socket.write(JSON.stringify({
+                                    jsonrpc: '2.0',
+                                    id: request.id,
+                                    error: {
+                                        code: ConduitError.ServerBusy,
+                                        message: 'Server busy'
+                                    }
+                                }) + '\n');
+                            } else {
+                                this.logger.error({ err, requestId: request.id }, 'Request handling failed');
+                                // Internal error handling usually done by Middleware/RequestController return
+                                // But if something crashed outside standard flow:
+                                socket.write(JSON.stringify({
+                                    jsonrpc: '2.0',
+                                    id: request.id,
+                                    error: {
+                                        code: ConduitError.InternalError,
+                                        message: 'Internal server error'
+                                    }
+                                }) + '\n');
+                            }
+                        }
+                    });
+                }
+            } catch (err) {
+                this.logger.error({ err }, 'Unexpected error in socket data handler');
+                socket.destroy();
+            } finally {
+                socket.resume();
+            }
+        });
+
+        socket.on('close', () => {
+            this.logger.debug({ remoteAddress }, 'Connection closed');
+        });
+
+        socket.on('error', (err) => {
+            this.logger.error({ err, remoteAddress }, 'Socket error');
+        });
+    }
+
+    async close(): Promise<void> {
+        return new Promise((resolve) => {
+            if (this.server.listening) {
+                this.server.close(() => {
+                    this.logger.info('Transport server closed');
+                    resolve();
+                });
+            } else {
+                resolve();
+            }
+        });
+    }
+}