libSynapx: High-Throughput IPC & Dispatcher Engine
A low-latency, persistent Inter-Process Communication (IPC) and request dispatching engine establishing a bidirectional, memory-pooled bridge between the native XHSC core (Go) and TypeScript, Bun, or Node.js worker runtimes.
argv leakage, and multi-worker port collisions.Architectural Motivation
Hybrid backend architectures combining compiled network listeners with interpreted worker runtimes face four major bottlenecks under legacy IPC models:
1. Subprocess Spawning Latency
Spawning discrete child processes via fork() and exec() incurs 15ms–80ms per invocation due to kernel scheduling and runtime bootstrap overhead.
2. Command-Line Argument (argv) Exposure
Passing metadata or tokens as CLI flags exposes sensitive data in /proc/[pid]/cmdline, ps aux, and system process tables.
3. Multi-Worker Port Collisions
Traditional clustering relies on separate internal TCP ports or unmanaged OS socket sharing, causing uneven balancing and port contention.
4. Buffer Thrashing & GC Stalls
Unstructured streaming and continuous raw-socket JSON serialization fragment memory and trigger frequent Garbage Collector pauses.
System Architecture
libSynapx maintains a persistent, multiplexed binary communication channel backed by pre-allocated multi-tier buffer pools:
Persistent Multiplexed IPC Flow
Go Network Layer / Kernel Epoll & Kqueue Listener
Intelligent Load Balancer / Dynamic Route Synchronizer
Core Architectural Pillars
Persistent Duplex IPC Bridge
Establishes long-lived bidirectional IPC channels at startup. Transactions are multiplexed over a single transport stream with sub-millisecond turnaround.
Multi-Core Request Dispatching (synapx-dispatcher)
The master XHSC process binds the host network interface as the sole external HTTP listener and distributes traffic across worker processes via libSynapx. Child workers never open redundant TCP sockets.
Multi-Tier Buffer Pooling
Uses tiered memory pools (Small, Medium, and Large buffers) with reusable byte slices to eliminate heap fragmentation and GC spikes during sustained high-throughput bursts.
Dynamic Route Table Synchronization
Routing tables are automatically published to the dispatcher on worker startup. Static assets are served directly from native memory while dynamic handlers route immediately to available workers.
Integrated Circuit Breaking & Failover
Tracks worker response times and error rates. If a worker fails or becomes unresponsive, traffic is rerouted immediately to healthy peers while the supervisor initiates automatic process recovery.
Technical Specifications & Metrics
| Architectural Dimension | Traditional Multi-Process Models | XyPriss with libSynapx |
|---|---|---|
| Transaction Turnaround | 15ms – 80ms (subprocess spawn) | < 0.5ms (persistent IPC) |
| Port Management | Multiple internal ports / Proxy layers | Single master port + zero-conflict IPC |
| Process Inspection Security | Arguments visible in /proc and ps | Zero CLI argument leakage |
| Memory Allocation Profile | Continuous per-request heap allocation | Pre-allocated multi-tier buffer pools |
| Failure Recovery | Manual process restart / Proxy timeouts | Autonomous circuit-breaker failover |
Configuration & Implementation
The libSynapx native engine is configured directly inside createServer() via the top-level synapx option (SynapxOptions). It manages zero-copy bidirectional communication buffers, throughput constraints, and high-speed synchronization with the native Go core (XHSC).
import { createServer } from "xypriss";
const app = createServer({
server: {
port: 3000,
},
synapx: {
autoTune: true, // Dynamically tunes limits from maxPayloadSize & fileUpload
maxPayloadSize: "1GB", // Max frame size: "512MB", "1GB", "2GB", or bytes
timeout: "60s", // Execution timeout: ms, "60s", "120s", or "auto"
batchSize: 10000, // Batch buffer queue depth for coalescing writes
},
cluster: {
enabled: true,
workers: "auto", // 1 worker per logical CPU core
strategy: "round-robin", // "round-robin" | "least-connections" | "ip-hash"
autoRespawn: true, // Autonomous worker recovery on abnormal exit
},
});
app.get("/api/v1/metrics", (req, res) => {
res.json({
status: "ok",
engine: "libSynapx",
timestamp: Date.now(),
});
});
app.start();SynapxOptions Reference
| Option | Type | Default | Description |
|---|---|---|---|
| autoTune | boolean | true | Enables automatic calculation and adaptive tuning for timeout, payload limits, and buffer batch size. When enabled or omitted, XyPriss derives optimal engine parameters from maxPayloadSize and fileUpload constraints. |
| maxPayloadSize | number | string | "512MB" | Maximum payload frame size allowed by the Synapx engine (e.g., "512MB", "1GB", "2GB", or bytes). Automatically scales to max(512MB, fileUpload.maxFileSize * 2) when autoTune is active. |
| timeout | number | string | 60000 | Request execution timeout in milliseconds or human-readable duration (e.g., 60000, "60s", "120s", "auto") for Synapx operations before throwing a timeout error. Dynamically derived when autoTune is enabled. |
| batchSize | number | 10000 | Batch buffer queue depth for coalescing write operations across the persistent IPC bridge. |
Security & Process Verification
Validates peer credentials during connection establishment, blocking unauthorized external processes from attaching to the dispatch socket.
Fully compatible with libXESS environment sandboxing so worker processes execute inside protected session boundaries.
Local transport endpoints are restricted with strict 0700 filesystem permissions inside session-scoped directories.
Explore Zero-Trust process confinement, ephemeral secret zeroization, and active honeypot defense.
