Examples
Every runnable example in this repo, mapped to the chapter it supports.
Every hands-on chapter in this site has a matching runnable example under
examples/
in the repo. Each hands-on example ships both a Quarkus and a Python
implementation, generated from the same Protobuf contract, and a verify.sh that
calls the running service and asserts response semantics against the proto — not
just a status. The code tabs and example layout are built to admit Go and C++ later.
More examples land here as new chapters ship.
| Example | What it shows | Stacks | Chapter |
|---|---|---|---|
| 00-prerequisites | Lab skeleton — both stacks boot from one proto, answer reflection, return a canned GetQuote |
Both | Ch0 |
| 03-protobuf | Protobuf round-trip — buf build + a Python serialize→parse proving a Booking/Money survives the wire |
Python (docker-free) | Ch3 |
| 04-well-known-types | Well-known types & JSON mapping — FindOptimalRoute renders Timestamp→RFC 3339 and Money→decimal string identically on both stacks |
Both | Ch4 |
| 05-contract-first | Contract-first anchor — RoutingService.GetQuote (unary), traced end to end |
Both | Ch5 |
| 06-http2-foundation | Measured: protobuf vs proto3-JSON payload size (122B vs 363B) + a wire-byte decode | Python (docker-free) | Ch6 |
| 07-unary-rpcs | Unary GetQuote + channel/stub reuse (one channel, repeated calls) |
Both | Ch7 |
| 08-server-streaming | TrackingService.WatchShipment — an ordered 4-event stream, count + order asserted |
Both | Ch8 |
| 09-client-and-bidi-streaming | ReportPositions (client-stream fold) + Sync (bidi), both stacks |
Both | Ch9 |
| 10-deadlines-cancellation | Deadline propagation — RoutingService→QuoteService; tight deadline → DEADLINE_EXCEEDED, generous → OK | Both | Ch10 |
| 11-error-handling | Canonical status codes + google.rpc.Status details (BadRequest / ErrorInfo / RetryInfo) |
Both | Ch11 |
| 12-interceptors | Server interceptor — logging/timing + an auth hook rejecting un-credentialed calls | Both | Ch12 |
| 13-schema-design | RoutingService.ListRoutes — page-token pagination (no overlap, empty token at end) + FieldMask projection, byte-identical on both stacks |
Both | Ch13 |
| 14-evolution | The buf breaking gate — safe change passes, delete/renumber/retype (even when reserved) fails, a new package path sidesteps it |
buf (tooling) | Ch14 |
| 15-backend-io-concurrency | FindOptimalRoute over simulated blocking I/O — 8 concurrent calls overlap on the correct model (@Blocking/virtual threads, grpc.aio+asyncio.to_thread) and starve on the event loop |
Both | Ch15 |
| 16-async-long-running-jobs | The server-owned Operation pattern — RecomputeRoutes starts work; GetOperation polls, WatchOperation streams progress, CancelOperation stops it; rerunnable reconcile |
Both | Ch16 |
| 17-streaming-at-scale | Backpressure on WatchShipment — a slow consumer paces a demand-driven producer (server-stamped timestamps spread out) vs an eager one; keepalive holds a quiet stream open |
Both | Ch17 |
| 18-performance-tuning | The channel-reuse footgun (reused channel beats channel-per-call), max-message-size, gzip, keepalive, and a pinned ghz benchmark with loose bounds |
Both | Ch18 |
| 19-tls-mtls | GetQuote over TLS then mTLS — self-generated certs (correct SANs), plaintext refused, a client cert required; the Quarkus JKS-truststore gotcha |
Both | Ch19 |
| 20-authn-authz | JWT in call metadata + an auth interceptor — valid token passes, missing/invalid/expired → UNAUTHENTICATED, insufficient scope → PERMISSION_DENIED |
Both | Ch20 |
| 21-observability | OTel trace spanning REST→gRPC→QuoteService (trace-id continuity), Prometheus metrics, and grpc.health.v1 — the LGTM stack wired in |
Both | Ch21 |
| 22-mesh-loadbalancing | The L4 single-connection pin on minikube — plain Service pins to one pod; headless+round_robin and Istio each fan out across 3 replicas (run on minikube, not CI) |
Cluster | Ch22 |
| 23-grpc-web-transcoding | One GetQuote, four doors — native gRPC, a REST shim, Envoy JSON/HTTP transcoding (auto_mapping), and a grpc-web framed client — all reaching the same RPC |
Both | Ch23 |
| 24-cross-protocol-http3 | GetQuote over HTTP/2 (gated + a ghz baseline) alongside a real HTTP/3 transport demo (Caddy + aioquic QUIC) — the transport, not gRPC-over-HTTP/3 |
Both | Ch24 |
| 25-testing-and-cli | Reflection probes (grpcurl), @QuarkusTest+@GrpcClient and pytest in-process suites gated at image-build, and a pinned ghz smoke |
Both | Ch25 |
| 26-debugging | Reproduce UNIMPLEMENTED / DEADLINE_EXCEEDED / UNAVAILABLE / TLS-handshake failures and diagnose them with reflection, channelz, and GRPC_TRACE |
Both | Ch26 |
| 27-complete-project | The final project — all three services, all four RPC modes, mTLS + JWT + OTel + ghz in one CI-gated Compose stack; a run-by-hand minikube tier solves the LB problem | Both | Ch27 |
| 99-appendix-a-openshift-crc | OpenShift Local (CRC) — gRPC over Routes (only passthrough carries native gRPC), OSSM STRICT mTLS + a weighted canary, in-cluster build (run on CRC, not CI) | Cluster | App. A |
Running an example
Each directory is self-contained — a README.md, a compose.yaml, and a
verify.sh that calls the running service and asserts response semantics
against the shared Protobuf contract under contracts/proto/, not just a status
code. The cluster-tier examples ship k8s/ or helm/ instead and run on
minikube or CRC.
cd examples/05-contract-first
./verify.sh
See Prerequisites & the Lab for the full toolchain setup.