Core Architecture

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.

Generation 5 (G5) Foundation
libSynapx is a core pillar of the XHSC G5 (Zero-Trust Synapx) architecture, eliminating subprocess spawning latency, command-line 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:

XHSC G5 Data Plane

Persistent Multiplexed IPC Flow

Native XHSC CoreGo Engine

Go Network Layer / Kernel Epoll & Kqueue Listener

Zero-Copy Socket
Persistent Multiplexed IPC
Binary Wire FramingAdaptive Backpressure & Circuit Breaking
libSynapx DispatcherCore Router

Intelligent Load Balancer / Dynamic Route Synchronizer

Pooled Memory Arena

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 DimensionTraditional Multi-Process ModelsXyPriss with libSynapx
Transaction Turnaround15ms – 80ms (subprocess spawn)< 0.5ms (persistent IPC)
Port ManagementMultiple internal ports / Proxy layersSingle master port + zero-conflict IPC
Process Inspection SecurityArguments visible in /proc and psZero CLI argument leakage
Memory Allocation ProfileContinuous per-request heap allocationPre-allocated multi-tier buffer pools
Failure RecoveryManual process restart / Proxy timeoutsAutonomous 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).

typescript
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

OptionTypeDefaultDescription
autoTunebooleantrueEnables 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.
maxPayloadSizenumber | 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.
timeoutnumber | string60000Request 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.
batchSizenumber10000Batch buffer queue depth for coalescing write operations across the persistent IPC bridge.

Security & Process Verification

Mutual Session Auth

Validates peer credentials during connection establishment, blocking unauthorized external processes from attaching to the dispatch socket.

libXESS Interoperability

Fully compatible with libXESS environment sandboxing so worker processes execute inside protected session boundaries.

0700 Transport Bounds

Local transport endpoints are restricted with strict 0700 filesystem permissions inside session-scoped directories.

Environment Security Shield (libXESS)

Explore Zero-Trust process confinement, ephemeral secret zeroization, and active honeypot defense.