og-edopro-server-ts/docs/node-cpp-ipc-performance-testing.md

Node.js ↔ C++ IPC performance testing

This document adds reproducible local benchmarks for the child-process IPC channel.

Included scripts

• npm run perf:protocol
  • Microbenchmark for JSON serialization/parsing and length-prefixed frame encode/decode.
• npm run perf:ipc
  • End-to-end IPC benchmark using a child-process echo worker that mimics current transport:
    • parent writes line-delimited JSON commands,
    • child replies with uint32_le + json frames.

Environment variables

perf:protocol

• BENCH_ITERATIONS (default 200000)
• BENCH_PAYLOAD_BYTES (default 256)

Example:

BENCH_ITERATIONS=500000 BENCH_PAYLOAD_BYTES=512 npm run perf:protocol

perf:ipc

• BENCH_MESSAGES (default 20000)
• BENCH_CONCURRENCY (default 512)
• BENCH_PAYLOAD_BYTES (default 128)

Example:

BENCH_MESSAGES=50000 BENCH_CONCURRENCY=1024 BENCH_PAYLOAD_BYTES=256 npm run perf:ipc

Metrics reported

• Throughput (throughputMsgPerSec)
• End-to-end latency (p50, p95, p99)
• Backpressure stats (drainCount, totalDrainWaitMs)

Suggested baseline workflow

1. Run both scripts on current branch.
2. Save JSON output artifacts.
3. Apply protocol changes (e.g. bidirectional length-prefix framing).
4. Repeat benchmarks with same env vars.
5. Compare p95/p99 latency and throughput deltas.

Production metrics capture

You can enable periodic IPC metrics logs per room by setting:

IPC_METRICS_ENABLED=true

When enabled, each active EDO room logs a structured IPC_METRICS event every 60 seconds with:

• queue depth and max queue depth
• commands enqueued/written and stdin write errors
• drain count and total drain wait time
• stdout chunk/bytes counts
• processed frames, parse errors, and deferred ticks

Use this in production/staging to collect real IPC behavior and share snapshots for analysis.