🔌 gRPC 101

What gRPC Actually Is

gRPC is not one new thing — it's an assembly of parts that each have their own guide on this site:

• Payloads: Protocol Buffers serialize your messages to a compact binary wire format.
• Transport: HTTP/2 carries every call as a multiplexed stream over one long-lived connection.
• Contract → code: the protoc compiler reads your .proto and generates client stubs and server base classes in your language.

The Layer Cake

Reading top to bottom, this is what a gRPC call is made of:

Each layer only knows about the one below it. Your business code sees a method; the wire sees TCP bytes. That separation is exactly why the same .proto generates working clients in Go, Python, Java, and Rust with no hand-written wire code.

The Contract: a .proto File

Everything starts from an interface definition. You declare messages (the data) and a service (the callable methods):

syntax = "proto3";

package users.v1;

message GetUserRequest {
  string user_id = 1;
}

message User {
  string user_id = 1;
  string display_name = 2;
  string email = 3;
}

service UserService {
  // A plain request/response method (unary).
  rpc GetUser(GetUserRequest) returns (User);
}

Codegen: Stubs and Servicers

Run the compiler and you get two generated artifacts per language:

# Generate Python code from the contract
# python -m grpc_tools.protoc -I. \
#     --python_out=. --grpc_python_out=. users/v1/user.proto

# -> user_pb2.py       (the message classes: GetUserRequest, User)
# -> user_pb2_grpc.py  (UserServiceStub + UserServiceServicer)

• Stub (client side): has one method per rpc. You call it; it does the marshalling and networking.
• Servicer (server side): a base class you subclass and fill in with your logic.

Channels vs Stubs

The channel owns the HTTP/2 connection(s), name resolution, load-balancing, and connection state. Create it once and reuse it:

import grpc
from users.v1 import user_pb2, user_pb2_grpc

# One channel, long-lived, shared across the process.
channel = grpc.insecure_channel("users.internal:50051")
stub = user_pb2_grpc.UserServiceStub(channel)   # cheap wrapper

resp = stub.GetUser(user_pb2.GetUserRequest(user_id="u_123"))
print(resp.display_name)

The Server Side

Subclass the generated servicer, implement each method, and register it:

import grpc
from concurrent import futures
from users.v1 import user_pb2, user_pb2_grpc

class UserService(user_pb2_grpc.UserServiceServicer):
    def GetUser(self, request, context):
        user = db.load(request.user_id)          # your logic
        return user_pb2.User(
            user_id=user.id,
            display_name=user.name,
            email=user.email,
        )

server = grpc.server(futures.ThreadPoolExecutor(max_workers=16))
user_pb2_grpc.add_UserServiceServicer_to_server(UserService(), server)
server.add_insecure_port("[::]:50051")
server.start()
server.wait_for_termination()

Every handler receives a context — the door to deadlines, cancellation, metadata, and status codes. It shows up in every other guide in this collection.

How One Call Maps to HTTP/2

A gRPC call is a perfectly ordinary HTTP/2 request/response — with conventions:

• The method name becomes the :path: /package.Service/Method.
• Each message on the wire is a 5-byte prefix (1 compression flag + 4-byte big-endian length) followed by the Protobuf bytes.
• The real result code arrives in trailers (grpc-status), not the HTTP :status — HTTP is almost always 200 even for failures. More in Status Codes.

Key Takeaways