gRPC in Microservices: A Worked Case Study
On this page
The problem: services for a ride-hailing app
Try it first. A ride-hailing app has these services:
- Booking: creates rides.
- Pricing: quotes fares.
- Dispatch: matches riders with drivers.
- Driver location: receives GPS updates from driver apps every few seconds.
- Payments: charges riders when rides end.
Rider and driver apps are mobile; there's also a web dashboard. Decide the protocols, call types, contracts, deadlines, error handling, retries, load balancing and security.
Designing the contracts
- One package per service and major version:
booking.v1,pricing.v1,dispatch.v1,location.v1,payments.v1(Days 2 and 23). - Protos in a shared schema repository with
buf lintandbuf breakingon every change; generated Go and Kotlin/Swift packages published per version (Day 4). - Request and response messages per RPC; money as
int64minor units with a currency; times asTimestamp; ride states as enums with..._UNSPECIFIED = 0(Days 3 and 21).
Choosing call types
| Interaction | Call type | Why |
|---|---|---|
| Booking asks Pricing for a quote | Unary | One question, one answer (Day 7) |
| Driver app sends GPS updates | Client streaming (or bidi for acks) | Continuous small messages; one stream per driver session (Day 9) |
| Rider app watches the ride | Server streaming | Status and driver position pushed as they change (Day 8) |
| Dispatch offers a ride to a driver | Bidirectional streaming | Offers out, accept or decline in, independently (Day 10) |
| Booking charges via Payments | Unary with an idempotency key | Must never charge twice (Day 22) |
Deadlines and error handling
The rider's "request ride" call gets a 5-second budget at the edge. Booking passes its context to every call so deadlines propagate (Day 15), and tightens per call:
ctx, cancel := context.WithTimeout(ctx, 1500*time.Millisecond) // leave room for dispatch
defer cancel()
quote, err := pricingClient.GetFareQuote(ctx, &pricingv1.GetFareQuoteRequest{RideId: rideID})
switch status.Code(err) {
case codes.OK:
case codes.Unavailable, codes.DeadlineExceeded:
quote = fallbackQuote(rideID) // degrade: a cached zone price, flagged as an estimate
default:
return nil, status.Errorf(codes.Internal, "pricing failed for ride %s", rideID) // translate, don't forward
}Errors are translated at each boundary, with structured details for validation failures (Day 14). Pricing failures degrade to an estimate rather than failing the booking (see the distributed systems course on graceful degradation).
Retries and idempotency
- Service config retry policies on reads (
GetFareQuote,GetRide) forUNAVAILABLEonly, with backoff and retry throttling (Day 22). ChargeRidecarries an idempotency key derived from the ride ID, so a retried or replayed charge returns the original result. Payments marks its RPCs withidempotency_levelwhere appropriate.
Load balancing and health checks
- Headless Kubernetes Services with client-side
round_robin, or a service mesh, so calls spread across pods (Day 18). MaxConnectionAgeon servers so clients pick up new pods after scaling.- Standard health services with readiness probes; services set
NOT_SERVINGbefore graceful shutdown (Day 20). - Long-lived location and dispatch streams are drained during deploys, and clients reconnect with backoff and resume from their last acknowledged sequence number.
Security and the public edge
- mTLS between all services via the mesh, with per-method authorization by calling service identity (Day 17).
- Mobile apps call the edge over TLS with user tokens; the edge validates them and passes identity downstream in metadata.
- The web dashboard uses Connect or gRPC-Web for the server-streamed ride view; partners get a REST API through transcoding (Days 5 and 19).
Observability and testing
- otelgrpc stats handlers on every client and server; per-method RED metrics; alerts on server-error burn rates and
DEADLINE_EXCEEDEDspikes (Day 24). - bufconn tests for each service's interceptors and status codes; contract tests between teams; game days that kill pricing to check the fallback works (Day 25).
What a strong gRPC design includes
- Call types chosen per interaction, not one style everywhere.
- Deadlines set at the edge and propagated.
- Clear error codes, translated at boundaries, with fallbacks for non-critical dependencies.
- Idempotency wherever money or side effects are involved.
- A plan for load balancing long-lived connections and streams.
- Contracts governed by lint, breaking-change checks and versioning.
Check yourself
It's a continuous sequence of small updates from one driver; streaming avoids per-call overhead and keeps the session on one connection.
Booking catches UNAVAILABLE or DEADLINE_EXCEEDED and falls back to a cached estimate, so the ride can still be booked. The fallback is logged and measured so a long Pricing outage is noticed.
ChargeRide uses an idempotency key derived from the ride id, so any retry, from a timeout or a crash, returns the original charge instead of charging again.
Through an edge gateway that terminates TLS, authenticates users and transcodes or proxies to internal services, which aren't exposed directly.
Clear contracts per service, call types that fit each interaction, deadlines everywhere, correct status codes, idempotent retries, load balancing that spreads calls, TLS and authorization, and observability. Each answers a way distributed calls fail in production.