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:

Dimension	JSON-RPC 2.0 (HTTP Loopback)	gRPC / HTTP/2	Unix Domain Sockets (Raw)
Serialization Format	UTF-8 JSON text	Binary Protocol Buffers	Custom binary / JSON frames
Client Compatibility	Any language with HTTP (`curl`, Python, JS)	Requires compiled protobuf stubs	Requires POSIX socket bindings
Round-Trip Overhead	0.8ms - 1.8ms	0.4ms - 0.9ms	0.2ms - 0.5ms
Inspectability	Plain text; inspectable with standard tools	Binary inspection required	Hex dumps or framing decoders
Cross-Platform Support	POSIX and Windows platforms uniform	Universal with compiler toolchain	Windows 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)")