Getting Started

Name: stdio Bus
Author: stdio Bus

Build stdio Bus from source and run your first worker in minutes. This guide covers prerequisites, build instructions, configuration, and running stdio Bus in all three operating modes.

Getting Started

Quickstart guide and setup instructions

Integration

Platform integration and usage patterns

Reference

Reference implementation details

Prerequisites

stdio Bus has minimal dependencies. You need a C11 compiler and optionally Node.js for running the included example workers.

C11 Compiler

GCC 4.9+ or Clang 3.4+ with C11 support. The build uses strict flags (-Wall -Wextra -Werror).

Make or CMake

GNU Make for the primary build system, or CMake 3.10+ for IDE integration and out-of-source builds.

Node.js 18+

Optional. Required only for running the included JavaScript example workers and test client.

Platform Support

Platform	I/O Multiplexing	Notes
Linux	`epoll`	Ubuntu 20.04+, Debian 11+, Fedora 35+, Amazon Linux 2
macOS	`kqueue`	macOS 12 (Monterey) or later

Build Instructions

stdio Bus can be built using either Make (recommended) or CMake. Both produce the same executable at build/kernel.

Building with Make

The Makefile is the primary build system and supports both debug and release builds.

Build with Make

# Clone the repository
git clone https://github.com/stdiobus/stdiobus.git
cd kernel
 
# Build with Make (debug build)
make
 
# Or build release version
make BUILD=release
 
# Verify the build
./build/kernel --help

Code block: Build with Make (Bash), 12 lines

Building with CMake

CMake is useful for IDE integration and out-of-source builds.

Build with CMake

# Clone the repository
git clone https://github.com/stdiobus/stdiobus.git
cd kernel
 
# Build with CMake
mkdir build
cd build
cmake ..
make
 
# Verify the build
./kernel --help

Code block: Build with CMake (Bash), 12 lines

Make Targets

Target	Description
`make`	Build debug executable (default)
`make BUILD=release`	Build optimized release executable
`make test`	Build and run the test suite
`make clean`	Remove all build artifacts
`make install`	Install to /usr/local/bin

Configuration

stdio Bus reads configuration from a JSON file specified via --config <path>. The configuration defines worker pools and operational limits.

Minimal Configuration

A minimal configuration defines one worker pool. All limits use defaults when omitted.

config.json

{
  "pools": [
    {
      "id": "echo-worker",
      "command": "/usr/bin/env",
      "args": ["node", "./examples/echo-worker.js"],
      "instances": 2
    }
  ]
}

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

Configuration Fields

Field	Type	Required	Description
`pools[].id`	string	Yes	Unique identifier for the pool
`pools[].command`	string	Yes	Path to executable
`pools[].args`	string[]	No	Command-line arguments
`pools[].instances`	number	Yes	Number of worker instances (≥1)

Operating Modes

stdio Bus supports three operating modes for client connections. Choose based on your deployment scenario.

stdio Mode

Single client via stdin/stdout. Ideal for subprocess embedding where the parent process communicates directly with stdio Bus.

stdio mode

# Send a single request via stdio
echo '{"jsonrpc":"2.0","id":"1","method":"echo","params":{"hello":"world"}}' | ./build/kernel --config config.json --stdio

Code block: stdio mode (Bash), 2 lines

Expected Output

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "echo": {},
    "method": "echo",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Code block in JSON, 9 lines

Unix Socket Mode

Multiple clients via Unix domain socket. Best for local IPC with multiple concurrent clients on the same machine.

Unix socket mode

# Terminal 1: Start stdio Bus with Unix socket
./build/kernel --config config.json --unix /tmp/stdio_bus.sock
 
# Terminal 2: Send test request
node examples/ndjson-client.js --unix /tmp/stdio_bus.sock --method echo --id req-1

Code block: Unix socket mode (Bash), 5 lines

TCP Mode

Multiple clients via TCP socket. Use for network-accessible deployments or when clients run on different machines.

TCP mode

# Terminal 1: Start stdio Bus with TCP listener
./build/kernel --config config.json --tcp 127.0.0.1:9000
 
# Terminal 2: Send test request
node examples/ndjson-client.js --tcp 127.0.0.1:9000 --method echo --id req-1

Code block: TCP mode (Bash), 5 lines

Mode Selection Guide

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

Echo Worker Example

The echo worker demonstrates the NDJSON worker contract. It reads JSON-RPC messages from stdin and writes responses to stdout.

Worker Contract

Input (stdin): NDJSON messages from stdio Bus runtime
Output (stdout): NDJSON responses only
Errors (stderr): Logging and debug output
Shutdown: Handle SIGTERM for graceful exit

Complete Example

echo-worker.js

1#!/usr/bin/env node
2/**
3 * Simple NDJSON echo worker for stdio Bus
4 * Demonstrates the worker-to-daemon contract
5 */
6const readline = require('readline');
7 
8let shuttingDown = false;
9 
10const rl = readline.createInterface({
11    input: process.stdin,
12    output: process.stdout,
13    terminal: false
14});
15 
16function processMessage(line) {
17    if (shuttingDown) return;
18 
19    try {
20        const msg = JSON.parse(line);
21 
22        // Request: has both id and method - send response
23        if (msg.id !== undefined && msg.method !== undefined) {
24            const response = {
25                jsonrpc: '2.0',
26                id: msg.id,
27                result: {
28                    echo: msg.params || {},
29                    method: msg.method,
30                    timestamp: new Date().toISOString()
31                }
32            };
33 
34            // Preserve sessionId for session affinity
35            if (msg.sessionId) {
36                response.sessionId = msg.sessionId;
37            }
38 
39            // Write response as NDJSON
40            console.log(JSON.stringify(response));
41        }
42    } catch (err) {
43        // Log errors to stderr (never stdout)
44        console.error(`[echo-worker] Error: ${err.message}`);
45    }
46}
47 
48// Handle graceful shutdown
49process.on('SIGTERM', () => {
50    shuttingDown = true;
51    rl.close();
52});
53 
54rl.on('line', processMessage);
55rl.on('close', () => process.exit(0));
56 
57console.error('[echo-worker] Started, waiting for messages...');

Code block: echo-worker.js (JavaScript), 57 lines

Testing with NDJSON Client

Use the included NDJSON client to send test requests and verify stdio Bus routing behavior.

Basic Request

node examples/ndjson-client.js --tcp localhost:9000 --method echo --id req-1

Code block in Bash, 1 line

Testing Session Affinity

Send multiple requests with the same sessionId to verify they route to the same worker:

# All requests with same session go to same worker
node examples/ndjson-client.js --tcp localhost:9000 --method test --session sess-123 --id 1
node examples/ndjson-client.js --tcp localhost:9000 --method test --session sess-123 --id 2
node examples/ndjson-client.js --tcp localhost:9000 --method test --session sess-123 --id 3

Code block in Bash, 4 lines

Request with Custom Params

node examples/ndjson-client.js --tcp localhost:9000 \
  --method process \
  --id req-1 \
  --session sess-123 \
  --params '{"data": "test"}'

Code block in Bash, 5 lines

Expected Output

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "sessionId": "sess-123",
  "result": {
    "echo": {"data": "test"},
    "method": "process",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Code block in JSON, 10 lines

Client Options

Option	Description
`--tcp <host:port>`	Connect via TCP
`--unix <path>`	Connect via Unix socket
`--method <name>`	JSON-RPC method name
`--id <value>`	Request ID
`--session <id>`	Session ID for affinity
`--params <json>`	JSON params object
`--interactive`	Interactive mode

Next Steps

Now that you have stdio Bus running with a basic worker, explore these topics:

Protocol Specification: Learn the normative requirements for building conforming implementations
Architecture: Understand the internal runtime model and event loop behavior
Integration Guide: Embed stdio Bus in your IDE, CLI, or agent framework
Configuration Reference: Fine-tune limits, restart policies, and backpressure settings