gRPC & HTTP/2 Streaming

Learning outcomes

• Define typed gRPC services using Protobuf schemas
• Leverage HTTP/2 multiplexing for low-latency RPCs

Mental model

gRPC is a high-performance Remote Procedure Call (RPC) framework that uses Protocol Buffers (compact binary serialization) over HTTP/2 (multiplexed streams over a single TCP connection).

Theory

• Protocol Buffers: Strongly typed binary IDL (Interface Definition Language). Serializes data up to 10x faster and 5x smaller than JSON.
• HTTP/2 Transport: Supports binary framing, header compression (HPACK), and concurrent stream multiplexing over a single TCP socket.

// user_service.proto definition
syntax = "proto3";

package user;

service UserService {
  rpc GetUser (UserRequest) returns (UserResponse);
  rpc StreamLogs (LogRequest) returns (stream LogResponse);
}

message UserRequest {
  string user_id = 1;
}

message UserResponse {
  string user_id = 1;
  string email = 2;
  bool is_active = 3;
}

message LogRequest {
  string service_name = 1;
}

message LogResponse {
  string timestamp = 1;
  string message = 2;
}

# Python gRPC Client Invocation
import grpc
import user_service_pb2
import user_service_pb2_grpc

async def run_client():
    async with grpc.aio.insecure_channel('localhost:50051') as channel:
        stub = user_service_pb2_grpc.UserServiceStub(channel)
        response = await stub.GetUser(user_service_pb2.UserRequest(user_id="usr_100"))
        print(f"User Email: {response.email}")

Alternatives and trade-offs

• REST / JSON over HTTP/1.1: Human-readable, universal browser support; text parsing overhead, HTTP/1.1 head-of-line blocking.
• gRPC / Protobuf over HTTP/2: Ultra-fast binary serialization, bi-directional streaming, strict schema contracts; requires gRPC-Web proxies for direct browser clients.

Failure modes and misconceptions

1. Changing Field Tag Numbers: In Protobuf, changing field tag numbers (string email = 2 to string email = 3) breaks backward and forward compatibility for deployed clients. Field names can change, but tag numbers MUST remain immutable.
2. L4 Load Balancer Connection Sticking: Classic Layer 4 TCP load balancers route an entire HTTP/2 TCP connection to a single backend pod, causing unbalanced server load. Use Layer 7 gRPC load balancing (Envoy / Traefik).

Decision scenario

Use gRPC with Protocol Buffers for internal microservice-to-microservice communication requiring low latency, strict schema validation, and high throughput.

Learning outcomes

• Compile Protocol Buffer (.proto) schemas into strongly typed client and server stubs.
• Leverage HTTP/2 stream multiplexing for concurrent RPC invocations.
• Maintain backward compatibility when updating Protobuf message fields.

Trade-offs

gRPC delivers massive throughput and serialization efficiency for internal microservices, but requires gRPC-Web translation layers for browser clients.

Primary sources

• FastAPI Framework Architecture & Dependency Injection Specification — Tiangolo, verified 2026-07-22