Platform Integration Guide

Name: stdio Bus
Author: stdio Bus

This guide describes how to embed stdio Bus in an IDE, platform, or infrastructure system. It covers operating mode selection, configuration, worker implementation, error handling, and graceful shutdown.

Getting Started

Integration

Reference

Deployment Options

stdio Bus can be embedded in your platform in several ways, depending on your architecture and requirements.

Subprocess

Spawn cos as a child process. Ideal for IDE extensions and desktop applications where stdio Bus runs alongside your main process.

Sidecar

Run cos alongside your service in containerized deployments. Connect via Unix socket or TCP for multi-process architectures.

Embedded (TBD)

Link stdio Bus as a library for deep integration. This mode is planned for future releases and not yet supported.

Subprocess Embedding

The most common approach is spawning stdio Bus as a subprocess. This provides process isolation while maintaining simple communication via stdin/stdout.

Node.js Example

subprocess-embedding.js

1const { spawn } = require('child_process');
2const readline = require('readline');
3 
4// Spawn stdio Bus as a subprocess
5const kernel = spawn('./build/kernel', [
6    '--config', './config.json',
7    '--stdio'
8], {
9    stdio: ['pipe', 'pipe', 'inherit']  // stdin, stdout, stderr
10});
11 
12// Send messages to stdio Bus via stdin
13cos.stdin.write(JSON.stringify({
14    jsonrpc: '2.0',
15    id: '1',
16    method: 'initialize',
17    params: {},
18    sessionId: 'session-001'
19}) + '\n');
20 
21// Read responses from stdio Bus via stdout
22const rl = readline.createInterface({ input: cos.stdout });
23rl.on('line', (line) => {
24    const response = JSON.parse(line);
25    console.log('Response:', response);
26});

Code block: subprocess-embedding.js (JavaScript), 26 lines

Key Points

When using subprocess embedding, stdio Bus reads from its stdin and writes to its stdout. Your platform sends NDJSON messages to stdio Bus's stdin and reads responses from its stdout. Diagnostic output goes to stderr.

Socket-Based Integration

For multi-client scenarios, use Unix socket or TCP mode. This allows multiple processes to connect to a single stdio Bus instance.

Unix Socket Connection

unix-socket-client.js

1const net = require('net');
2 
3// Connect to stdio Bus via Unix socket
4const client = net.createConnection('/tmp/stdio_bus.sock', () => {
5    console.log('Connected to stdio Bus');
6    
7    // Send a request
8    client.write(JSON.stringify({
9        jsonrpc: '2.0',
10        id: '1',
11        method: 'test',
12        params: {},
13        sessionId: 'session-001'
14    }) + '\n');
15});
16 
17// Handle responses with NDJSON parsing
18let buffer = '';
19client.on('data', (data) => {
20    buffer += data.toString();
21    let newlineIndex;
22    while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
23        const line = buffer.slice(0, newlineIndex);
24        buffer = buffer.slice(newlineIndex + 1);
25        const response = JSON.parse(line);
26        console.log('Response:', response);
27    }
28});

Code block: unix-socket-client.js (JavaScript), 28 lines

TCP Connection

tcp-client.js

const net = require('net');
 
// Connect to stdio Bus via TCP
const client = net.createConnection({ host: '127.0.0.1', port: 9000 }, () => {
    console.log('Connected to stdio Bus via TCP');
    
    client.write(JSON.stringify({
        jsonrpc: '2.0',
        id: '1',
        method: 'process',
        params: { data: 'test' },
        sessionId: 'session-001'
    }) + '\n');
});
 
client.on('data', (data) => {
    // Handle NDJSON responses
    const lines = data.toString().split('\n').filter(Boolean);
    lines.forEach(line => {
        const response = JSON.parse(line);
        console.log('Response:', response);
    });
});

Code block: tcp-client.js (JavaScript), 23 lines

Mode Selection Guide

stdio Bus supports three operating modes, each suited to different integration scenarios. Choose based on your deployment requirements.

Mode	Flag	Use Case
stdio	`--stdio`	Subprocess embedding, single client, IDE extensions
Unix socket	`--unix <path>`	Local IPC, multiple clients, security-sensitive deployments
TCP	`--tcp <host:port>`	Network access, remote clients, distributed systems

Mode Characteristics

Requirement	Recommended Mode
Single client, subprocess embedding	stdio
Multiple local clients, security-sensitive	Unix socket
Multiple clients, network access needed	TCP
IDE extension	stdio
Containerized microservice	Unix socket or TCP
Development/testing	Any (TCP is easiest to debug)

Configuration Options

stdio Bus reads configuration from a JSON file specified via --config <path>. Configure worker pools and operational limits based on your requirements.

Pool Configuration

Field	Required	Description
`pools[].id`	Yes	Unique identifier for the pool (used in logs)
`pools[].command`	Yes	Path to the worker executable
`pools[].args`	No	Array of command-line arguments
`pools[].instances`	Yes	Number of worker processes to spawn (≥1)

Limits Configuration

Field	Default	Description
`max_input_buffer`	1 MB	Maximum bytes buffered per input connection
`max_output_queue`	4 MB	Maximum bytes queued per output connection
`max_restarts`	5	Maximum worker restarts within time window
`restart_window_sec`	60	Time window for counting restarts
`drain_timeout_sec`	30	Graceful shutdown timeout before SIGKILL
`backpressure_timeout_sec`	60	Backpressure timeout before closing connection

Configuration Examples

Minimal Configuration — Single worker, default limits:

config-minimal.json

{
  "pools": [
    {
      "id": "worker",
      "command": "/usr/bin/node",
      "args": ["./worker.js"],
      "instances": 1
    }
  ]
}

Code block: config-minimal.json (JSON), 10 lines

High-Throughput Configuration — Multiple workers, increased buffers:

config-high-throughput.json

{
  "pools": [
    {
      "id": "worker",
      "command": "/usr/bin/node",
      "args": ["./worker.js"],
      "instances": 8
    }
  ],
  "limits": {
    "max_input_buffer": 4194304,
    "max_output_queue": 16777216,
    "backpressure_timeout_sec": 120
  }
}

Code block: config-high-throughput.json (JSON), 15 lines

Fault-Tolerant Configuration — Aggressive restart policy:

config-fault-tolerant.json

{
  "pools": [
    {
      "id": "worker",
      "command": "/usr/bin/node",
      "args": ["./worker.js"],
      "instances": 4
    }
  ],
  "limits": {
    "max_restarts": 10,
    "restart_window_sec": 300,
    "drain_timeout_sec": 60
  }
}

Code block: config-fault-tolerant.json (JSON), 15 lines

Worker Implementation Templates

Workers are child processes that communicate with stdio Bus via stdin/stdout pipes using NDJSON format. A compliant worker must:

Read NDJSON from stdin (one JSON object per line)
Write NDJSON responses to stdout
Write diagnostics to stderr (never stdout)
Handle SIGTERM for graceful shutdown
Preserve id and sessionId in responses

JavaScript Worker Template

worker.js

1#!/usr/bin/env node
2const readline = require('readline');
3 
4const rl = readline.createInterface({
5    input: process.stdin,
6    output: process.stdout,
7    terminal: false
8});
9 
10rl.on('line', (line) => {
11    try {
12        const msg = JSON.parse(line);
13        
14        // Only respond to requests (messages with id and method)
15        if (msg.id !== undefined && msg.method !== undefined) {
16            const response = {
17                jsonrpc: '2.0',
18                id: msg.id,
19                result: handleMethod(msg.method, msg.params)
20            };
21            
22            // Preserve sessionId if present
23            if (msg.sessionId) {
24                response.sessionId = msg.sessionId;
25            }
26            
27            console.log(JSON.stringify(response));
28        }
29    } catch (err) {
30        console.error(`Parse error: ${err.message}`);
31    }
32});
33 
34function handleMethod(method, params) {
35    switch (method) {
36        case 'initialize':
37            return { capabilities: {} };
38        case 'echo':
39            return { echo: params };
40        default:
41            return { error: `Unknown method: ${method}` };
42    }
43}
44 
45// Graceful shutdown on SIGTERM
46process.on('SIGTERM', () => {
47    console.error('Received SIGTERM, shutting down');
48    process.exit(0);
49});

Code block: worker.js (JavaScript), 49 lines

Python Worker Template

worker.py

1#!/usr/bin/env python3
2import sys
3import json
4import signal
5 
6def handle_method(method, params):
7    """Implement your method handlers here."""
8    if method == 'initialize':
9        return {'capabilities': {}}
10    elif method == 'echo':
11        return {'echo': params}
12    else:
13        return {'error': f'Unknown method: {method}'}
14 
15def process_message(line):
16    """Process a single NDJSON message."""
17    try:
18        msg = json.loads(line)
19        
20        # Only respond to requests (messages with id and method)
21        if 'id' in msg and 'method' in msg:
22            response = {
23                'jsonrpc': '2.0',
24                'id': msg['id'],
25                'result': handle_method(msg['method'], msg.get('params', {}))
26            }
27            
28            # Preserve sessionId if present
29            if 'sessionId' in msg:
30                response['sessionId'] = msg['sessionId']
31            
32            print(json.dumps(response), flush=True)
33    except json.JSONDecodeError as e:
34        print(f'Parse error: {e}', file=sys.stderr)
35 
36def main():
37    # Graceful shutdown on SIGTERM
38    signal.signal(signal.SIGTERM, lambda sig, frame: sys.exit(0))
39    
40    for line in sys.stdin:
41        process_message(line.strip())
42 
43if __name__ == '__main__':
44    main()

Code block: worker.py (Python), 44 lines

Error Handling Patterns

Platform integrators should handle connection errors, message errors, and worker failures gracefully.

Connection Errors

Error	Cause	Platform Action
Connection refused	stdio Bus not running or wrong address	Retry with backoff, check stdio Bus status
Connection reset	stdio Bus closed connection	Check for malformed messages, reconnect
Timeout	stdio Bus or worker unresponsive	Implement client-side timeouts

stdio Bus Exit Codes

Exit Code	Meaning	Platform Action
0	Graceful shutdown	Normal termination
1	Configuration or startup error	Check config file and logs
Non-zero	Unexpected error	Check stderr, restart

Request Timeout Pattern

error-handling.js

1const pendingRequests = new Map();
2 
3function sendRequest(client, request, timeoutMs = 30000) {
4    return new Promise((resolve, reject) => {
5        const timer = setTimeout(() => {
6            pendingRequests.delete(request.id);
7            reject(new Error('Request timeout'));
8        }, timeoutMs);
9        
10        // Store pending request
11        pendingRequests.set(request.id, { resolve, reject, timer });
12        
13        // Send request
14        client.write(JSON.stringify(request) + '\n');
15    });
16}
17 
18function handleResponse(response) {
19    const pending = pendingRequests.get(response.id);
20    if (pending) {
21        clearTimeout(pending.timer);
22        pendingRequests.delete(response.id);
23        if (response.error) {
24            pending.reject(new Error(response.error.message));
25        } else {
26            pending.resolve(response.result);
27        }
28    }
29}

Code block: error-handling.js (JavaScript), 29 lines

Graceful Shutdown Procedures

Proper shutdown handling ensures no data loss and clean resource cleanup.

stdio Bus Shutdown Sequence

When stdio Bus receives SIGTERM or SIGINT:

Stop accepting connections: Close listening socket (socket modes)
Signal workers: Send SIGTERM to all running workers
Drain period: Wait up to drain_timeout_sec for workers to exit
Force termination: Send SIGKILL to remaining workers
Cleanup: Close all file descriptors, free memory
Exit: Exit with code 0

Platform Shutdown Procedure

graceful-shutdown.js

1const { spawn } = require('child_process');
2 
3const kernel = spawn('./build/kernel', ['--config', 'config.json', '--stdio']);
4 
5// Graceful shutdown function
6function shutdown() {
7    return new Promise((resolve) => {
8        cos.on('exit', (code) => {
9            console.log(`stdio Bus exited with code ${code}`);
10            resolve(code);
11        });
12        
13        // Send SIGTERM for graceful shutdown
14        cos.kill('SIGTERM');
15        
16        // Force kill after timeout (drain_timeout_sec + buffer)
17        setTimeout(() => {
18            if (!cos.killed) {
19                console.warn('stdio Bus did not exit, sending SIGKILL');
20                cos.kill('SIGKILL');
21            }
22        }, 35000);
23    });
24}
25 
26// Handle process signals
27process.on('SIGTERM', async () => {
28    await shutdown();
29    process.exit(0);
30});

Code block: graceful-shutdown.js (JavaScript), 30 lines

⏱️ Timeout Recommendation

Set your platform timeout slightly higher than drain_timeout_sec (default: 30s) to allow stdio Bus to complete its shutdown sequence. A platform timeout of 35 seconds is recommended.

Common Integration Patterns

The following code snippets demonstrate common patterns for integrating with stdio Bus in production environments.

Session Management

Sessions provide worker affinity for related messages. All messages with the same sessionId route to the same worker.

session-management.js

// Generate unique session IDs
function generateSessionId() {
    return `session-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
}
 
// Track sessions per user/context
const userSessions = new Map();
 
function getOrCreateSession(userId) {
    if (!userSessions.has(userId)) {
        userSessions.set(userId, generateSessionId());
    }
    return userSessions.get(userId);
}
 
// Send request with session affinity
function sendRequest(client, userId, method, params) {
    const sessionId = getOrCreateSession(userId);
    const request = {
        jsonrpc: '2.0',
        id: generateRequestId(),
        method,
        params,
        sessionId
    };
    client.write(JSON.stringify(request) + '\n');
}

Code block: session-management.js (JavaScript), 27 lines

Request-Response Correlation

Track pending requests for response matching using the request id field.

request-correlation.js

const pendingRequests = new Map();
let requestCounter = 0;
 
function generateRequestId() {
    return `req-${++requestCounter}`;
}
 
function sendRequest(client, method, params, sessionId) {
    return new Promise((resolve, reject) => {
        const id = generateRequestId();
        const request = { jsonrpc: '2.0', id, method, params };
        if (sessionId) request.sessionId = sessionId;
        
        pendingRequests.set(id, { resolve, reject });
        client.write(JSON.stringify(request) + '\n');
    });
}
 
function handleResponse(response) {
    const pending = pendingRequests.get(response.id);
    if (pending) {
        pendingRequests.delete(response.id);
        if (response.error) {
            pending.reject(new Error(response.error.message));
        } else {
            pending.resolve(response.result);
        }
    }
}

Code block: request-correlation.js (JavaScript), 29 lines

Connection Pooling

Manage multiple connections for high throughput in TCP or Unix socket mode.

connection-pool.js

1const net = require('net');
2 
3class ConnectionPool {
4    constructor(socketPath, poolSize = 4) {
5        this.socketPath = socketPath;
6        this.connections = [];
7        this.nextIndex = 0;
8        
9        for (let i = 0; i < poolSize; i++) {
10            this.connections.push(this.createConnection());
11        }
12    }
13    
14    createConnection() {
15        const conn = net.createConnection(this.socketPath);
16        conn.buffer = '';
17        conn.on('data', (data) => {
18            conn.buffer += data.toString();
19            this.processBuffer(conn);
20        });
21        return conn;
22    }
23    
24    processBuffer(conn) {
25        let newlineIndex;
26        while ((newlineIndex = conn.buffer.indexOf('\n')) !== -1) {
27            const line = conn.buffer.slice(0, newlineIndex);
28            conn.buffer = conn.buffer.slice(newlineIndex + 1);
29            this.handleResponse(JSON.parse(line));
30        }
31    }
32    
33    getConnection() {
34        const conn = this.connections[this.nextIndex];
35        this.nextIndex = (this.nextIndex + 1) % this.connections.length;
36        return conn;
37    }
38    
39    send(message) {
40        const conn = this.getConnection();
41        conn.write(JSON.stringify(message) + '\n');
42    }
43    
44    close() {
45        this.connections.forEach(conn => conn.end());
46    }
47}

Code block: connection-pool.js (JavaScript), 47 lines

Health Monitoring

Monitor stdio Bus process health and implement automatic restart on failure.

health-monitoring.js

1const { spawn } = require('child_process');
2 
3class COSManager {
4    constructor(configPath, mode = 'stdio') {
5        this.configPath = configPath;
6        this.mode = mode;
7        this.process = null;
8        this.restartCount = 0;
9        this.maxRestarts = 5;
10    }
11    
12    start() {
13        const args = ['--config', this.configPath, `--${this.mode}`];
14        this.process = spawn('./build/kernel', args, {
15            stdio: ['pipe', 'pipe', 'inherit']
16        });
17        
18        this.process.on('exit', (code, signal) => {
19            console.error(`stdio Bus exited: code=${code}, signal=${signal}`);
20            this.handleExit(code, signal);
21        });
22        
23        this.process.on('error', (err) => {
24            console.error(`stdio Bus error: ${err.message}`);
25        });
26        
27        return this.process;
28    }
29    
30    handleExit(code, signal) {
31        if (signal === 'SIGTERM' || signal === 'SIGINT') {
32            return; // Intentional shutdown
33        }
34        
35        // Unexpected exit - attempt restart
36        if (this.restartCount < this.maxRestarts) {
37            this.restartCount++;
38            console.log(`Restarting stdio Bus (attempt ${this.restartCount})`);
39            setTimeout(() => this.start(), 1000 * this.restartCount);
40        } else {
41            console.error('Max restarts exceeded, giving up');
42        }
43    }
44    
45    stop() {
46        if (this.process) {
47            this.process.kill('SIGTERM');
48        }
49    }
50}

Code block: health-monitoring.js (JavaScript), 50 lines

Logging Integration

Capture stdio Bus stderr output and forward to your logging system.

logging-integration.js

const { spawn } = require('child_process');
const readline = require('readline');
 
const kernel = spawn('./build/kernel', ['--config', 'config.json', '--stdio'], {
    stdio: ['pipe', 'pipe', 'pipe']  // Capture stderr
});
 
// Forward stdio Bus logs to your logging system
const stderrReader = readline.createInterface({ input: cos.stderr });
 
stderrReader.on('line', (line) => {
    // Parse stdio Bus log format: [TIMESTAMP] [LEVEL] message
    const match = line.match(/^\[([^\]]+)\] \[([^\]]+)\] (.*)$/);
    if (match) {
        const [, timestamp, level, message] = match;
        yourLogger.log(level.toLowerCase(), message, { 
            timestamp, 
            source: 'stdio Bus' 
        });
    } else {
        yourLogger.info(line, { source: 'stdio Bus' });
    }
});

Code block: logging-integration.js (JavaScript), 23 lines

stdio Bus