Stax Digital Garden

HBM-1009 - The Trade-Offs of Loopback JSON-RPC

2 min read

Living Document Notice Published 2026-09-18. The evolving architecture and revisions for this dispatch live in the Stax Digital Garden.

The Trade-Offs of Loopback JSON-RPC

The Trade-Offs of Loopback JSON-RPC: Monochromatic ice blue phosphor P7 vector CRT macro showing an architectural balance scale comparing serialization latency against process isolation barriers

Designing inter-process communication for local personal tools requires balancing developer ergonomic accessibility against execution latency. While binary protocols such as Protocol Buffers and gRPC offer compact wire representations, their compilation dependencies and rigid tooling pipelines add friction for small extension developers.

Harbormaster adopts JSON-RPC 2.0 over loopback HTTP as its primary transport contract. This dispatch quantifies the engineering trade-offs of this decision, benchmarking payload parsing latency, socket connection reuse, and transport debugging ergonomics on typical developer machines.

Protocol Comparison Matrix

Evaluating transport protocols for local desktop module integration:

DimensionJSON-RPC 2.0 (HTTP Loopback)gRPC / HTTP/2Unix Domain Sockets (Raw)
Serialization FormatUTF-8 JSON textBinary Protocol BuffersCustom binary / JSON frames
Client CompatibilityAny language with HTTP (curl, Python, JS)Requires compiled protobuf stubsRequires POSIX socket bindings
Round-Trip Overhead0.8ms – 1.8ms0.4ms – 0.9ms0.2ms – 0.5ms
InspectabilityPlain text; inspectable with standard toolsBinary inspection requiredHex dumps or framing decoders
Cross-Platform SupportPOSIX and Windows platforms uniformUniversal with compiler toolchainWindows named pipes differ

Latency Breakdown: 1,000 Local Invocations

Benchmarking note relationship queries across 1,000 iterations on a local loopback interface:

Total Elapsed Time: 1,240ms (Average: 1.24ms per request)
├─ 0.15ms : Loopback TCP connection negotiation (reused via keepalive)
├─ 0.22ms : HTTP header parsing and Host header check
├─ 0.28ms : JSON-RPC schema validation and token lookup
├─ 0.35ms : In-memory graph query execution
└─ 0.24ms : JSON serialization and socket write

While binary protocols save fractions of a millisecond, JSON-RPC 2.0 delivers transparent inspectability without requiring complex stub compilation.

Benchmarking Script

Execute local throughput benchmarks using Python urllib3:

import time
import json
import urllib.request
 
url = "http://127.0.0.1:8765/protocol/v1/rpc"
payload = json.dumps({
    "jsonrpc": "2.0",
    "id": 1,
    "method": "kpp.system.ping",
    "params": {}
}).encode("utf-8")
 
start = time.perf_counter()
for _ in range(500):
    req = urllib.request.Request(url, data=payload, headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req) as resp:
        _ = resp.read()
 
elapsed = time.perf_counter() - start
print(f"Completed 500 requests in {elapsed:.3f}s ({elapsed/500*1000:.2f}ms/req)")
  • Directus Target: harbormaster
  • Garden Source Reference: MOC - Harbormaster Protocol, MOC - Bosun PKM Tools
  • Garden Source Reference: [HBM-1009 - The Trade-Offs of Loopback JSON-RPC](HBM-1009 - The Trade-Offs of Loopback JSON-RPC)

Graph View