A small lab to measure the performance cost of introducing a gRPC gateway boundary in front of a backend service.

It compares two request paths:

• Direct: Client → Backend
• With gateway: Client → Gateway → Backend

The goal is to quantify:

• Throughput degradation
• Tail-latency amplification (p95 / p99)
• Saturation behavior under load
• Protocol Overhead: Direct comparisons between gRPC and REST proxies.

• cmd/backend/ – gRPC & REST backend service
• cmd/gateway/ – Gateway proxy that translates or forwards requests
• cmd/loadgen/ – Load generator with percentile latency tracking (HdrHistogram) capable of sweeping gRPC and REST.
• frontend/ – React/Vite Dashboard UI to visualize metrics directly.
• gateway/ – Gateway proxy routing logic.
• internal/proto/ – Protobuf definitions and generated code.
• docker-compose.yml – Local network orchestration.
• docs/ + mkdocs.yml – Documentation site.
• Makefile – one-command workflows

• Go 1.26
• make

Optional:

• Docker (for controlled benchmark environments)
• Python (for docs tooling)

The fastest way to test the lab locally is using our master Makefile orchestrator. It uses Docker Compose to start the Backend, the Gateway, and a React-based Dashboard UI:

make all

Once running, navigate to http://localhost/ in your browser to access the interactive dashboard. You can toggle between tracking gRPC proxy latency and standard REST proxies.

Alternatively, you can run isolated load tests via the CLI:

make sweep REQUESTS=50000 CONCURRENCY="1 16 64"

Suggested quick iteration:

REQUESTS=20000 CONCURRENCY="1 2 4 8 16 32 64" 

Adjust concurrency levels to observe saturation and latency amplification.

Using the newly implemented transport switches, you can generate a matrix of performance results covering REST and gRPC with or without TLS.

make bench-matrix

Example result:

Mode RPS p50 p95 p99 --------------------------------------------- REST 7.0k 3ms 9ms 13ms REST + TLS 2.3k 12ms 27ms 35ms gRPC 23.5k 1ms 2ms 2ms gRPC + TLS 21.6k 1ms 2ms 2ms 

When introducing a gateway hop, expect overhead from:

• Additional scheduling and queuing
• Serialization/deserialization
• Extra transport hop
• Goroutine contention

Key indicators:

• Where p99 latency rises sharply
• Where throughput plateaus
• How the gateway shifts the latency knee
• The performance differences between gRPC Multiplexing and traditional HTTP Keep-Alive connection limits.

Online: https://null-pointer-sch.github.io/grpc-boundary-lab/

Local:

make docs 

Then open the local MkDocs URL printed in the terminal.

• Gateway forwarding via gRPC client
• Automated load generator with percentile latency tracking
• Integration tests and CI
• MkDocs-based documentation site

MIT