gRPC

Protocol Buffers: the contract

A gRPC service starts with a .proto file. Messages describe the data (typed fields with stable numbers); services describe the callable methods. This file is the single source of truth, shared by every language.

syntax = "proto3";

package todo.v1;
option go_package = "example.com/todo/gen/todov1";

message GetTodoRequest {
  int64 id = 1;
}

message Todo {
  int64 id = 1;
  string title = 2;
  bool done = 3;
}

service TodoService {
  // unary: one request in, one response out
  rpc GetTodo(GetTodoRequest) returns (Todo);
  // server streaming: one request, a stream of responses
  rpc ListTodos(ListTodosRequest) returns (stream Todo);
}

The numbers (= 1, = 2) are field tags — they identify fields on the wire, so you can rename a field freely but must never reuse a tag. That tag-based encoding is what makes protobuf compact and forward/backward compatible.

Code generation with protoc

You don’t write the wire format by hand. The protoc compiler plus two Go plugins turn the .proto into typed Go: structs for the messages, a client stub, and a server interface you implement.

# install the Go plugins once
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# generate todo.pb.go (messages) and todo_grpc.pb.go (stubs)
protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       todo.proto

The generated server side is an interface; you supply the logic. The generated client side is a struct with typed methods.

package main

import (
	"context"
	"log"
	"net"

	"google.golang.org/grpc"
	todov1 "example.com/todo/gen/todov1"
)

// implement the generated server interface
type server struct {
	todov1.UnimplementedTodoServiceServer
}

func (s *server) GetTodo(ctx context.Context, req *todov1.GetTodoRequest) (*todov1.Todo, error) {
	// look the todo up, return a typed message
	return &todov1.Todo{Id: req.Id, Title: "write Go", Done: false}, nil
}

func main() {
	lis, err := net.Listen("tcp", ":50051") // needs a network — run locally, not in the sandbox
	if err != nil {
		log.Fatal(err)
	}
	s := grpc.NewServer()
	todov1.RegisterTodoServiceServer(s, &server{})
	log.Fatal(s.Serve(lis)) // serves gRPC over HTTP/2
}

Calling it from a client is just a typed method call — the stub handles connection, framing, and serialization:

conn, err := grpc.NewClient("localhost:50051",
	grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
	log.Fatal(err)
}
defer conn.Close()

client := todov1.NewTodoServiceClient(conn)
todo, err := client.GetTodo(context.Background(), &todov1.GetTodoRequest{Id: 1})
// todo is a *todov1.Todo — fully typed, no manual JSON parsing

The four RPC kinds

gRPC runs over HTTP/2, whose multiplexed, long-lived streams unlock four call shapes. REST over HTTP/1.1 effectively only gives you the first.

In Go, streaming methods hand you a stream object: you loop calling stream.Send(msg) and stream.Recv() instead of returning a single value.

sequenceDiagram
participant C as Client stub<br/>(generated)
participant S as Server impl<br/>(your code)
Note over C,S: single HTTP/2 connection, multiplexed
C->>S: GetTodo(req)  [unary]
S-->>C: Todo
C->>S: ListTodos(req)  [server stream]
S-->>C: Todo (frame 1)
S-->>C: Todo (frame 2)
S-->>C: Todo (frame 3)

gRPC vs REST

Reach for gRPC for internal, service-to-service traffic where both sides are yours: you get a strongly-typed contract, compact binary payloads, and first-class streaming, all multiplexed over one HTTP/2 connection. Reach for REST/JSON when the audience is a browser or a third party — it’s human-readable, curl-friendly, cacheable by intermediaries, and needs no special client. (Browsers can’t speak raw gRPC without a gRPC-Web proxy.)

See also

• RPC & serialization — net/rpc and the protobuf-vs-gob-vs-JSON trade-off.
• REST APIs — the JSON/HTTP alternative for public, browser-facing APIs.
• framing & protocols — the length-prefix/binary ideas protobuf builds on.
• WebSockets — browser-friendly bidirectional streaming.

Next: real-time, full-duplex connections with WebSockets.

Related topics