SyntaxPilot
Courses/Go Programming/Lesson 69
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Go Programming · Lesson 69 of 89

gRPC and Protocol Buffers

Protocol Buffers.proto filesmessagesfields and numberingbackward compatibilityprotoc and bufprotoc-gen-go and protoc-gen-go-grpcgRPC service definitionsunary RPCserver streamingclient streamingbidirectional streaminggRPC status codesdeadlines

These are the notes for Go episode 69. Raju's shop is now several Go services that talk to each other all day: an order service, a kitchen service, a billing service. They talk JSON, and one day a harmless rename makes the kitchen cook zero cups of chai with no error anywhere. We fix that by inventing a contract both sides compile from: Protocol Buffers. We look at the real bytes that travel, learn the rules for changing a schema without breaking anyone, and then use gRPC to turn that contract into typed function calls between services: one-shot calls with real status codes, three kinds of streaming, deadlines, metadata and interceptors. We finish with when to pick gRPC and when to stay with REST.

All outputs are from real runs (Go 1.24.7, linux/amd64) with google.golang.org/grpc v1.80.0 and google.golang.org/protobuf v1.36.11, served by the local module proxy from tools/goproxy_x.sh. Code was generated in this run with protoc 3.21.12 (libprotoc 3.21.12), protoc-gen-go v1.36.11 and protoc-gen-go-grpc v1.6.1 (tools/protoc_go.sh). Timings and the order of log lines printed by different goroutines can change between runs.

Facts and sources

Read in this run:

  • grpc/grpc README: "gRPC is a modern, open source, high-performance remote procedure call (RPC) framework that can run anywhere".
  • grpc/grpc-go README: "A high performance, open source, general RPC framework that puts mobile and HTTP/2 first".
  • grpc/grpc doc/PROTOCOL-HTTP2.md ("gRPC over HTTP2"): a request is Request-Headers *Length-Prefixed-Message EOS; the headers include :method POST, :path "/" Service-Name "/" {method name}, an optional grpc-timeout (the deadline, for example grpc-timeout = 1S), content-type "application/grpc", and Custom-Metadata (your own headers; binary ones end in -bin). The status is sent as grpc-status in the Trailers "even if the status code is OK".
  • grpc-gateway README: "a plugin of the Google protocol buffers compiler protoc. It reads protobuf service definitions and generates a reverse-proxy server which translates a RESTful HTTP API into gRPC. This server is generated according to the google.api.http annotations in your service definitions." Its example annotation is shown below.
  • connect-go README: "Connect is a slim library for building browser and gRPC-compatible HTTP APIs ... Handlers and clients support three protocols: gRPC, gRPC-Web, and Connect's own protocol." and "The Connect protocol is a simple protocol that works over HTTP/1.1 or HTTP/2 ... Calling a Connect API is as easy as using curl."
  • bufbuild/buf README: "Buf is the modern toolchain for Protobuf. It replaces day-to-day protoc use with a fast compiler, module-aware workspaces, formatting, linting, breaking-change detection, code generation, dependency management ..."; its quick start lists buf format -w, buf lint, buf breaking --against '.git#branch=main' and buf generate.
  • google.golang.org/grpc/codes (v1.80.0, codes.go): the 17 codes from OK (0) to Unauthenticated (16) and their doc comments, quoted in the status-code table.
  • google.golang.org/protobuf/encoding/protowire (v1.36.11, wire.go): wire types VarintType = 0, Fixed64Type = 1, BytesType = 2, Fixed32Type = 5 (3 and 4 are the old "group" types); EncodeTag is uint64(num)<<3 | uint64(typ&7); valid field numbers run from 1 to 1<<29 - 1, and 19000-19999 are reserved by protobuf itself; AppendVarint stores 7 bits per byte.
  • The generated orders_grpc.pb.go itself: "All implementations must embed UnimplementedOrderServiceServer for forward compatibility" and "Requires gRPC-Go v1.64.0 or later".
  • status.FromContextError (grpc v1.80.0): "converts a context error or wrapped context error into a Status".
  • The episode script (episodes/go_ep69.py): the compiler's editor holds at most 16,000 characters, which is why each gRPC demo uses a smaller .proto.
  • Everything else is from the real runs below (protoc error messages included).

The problem: a JSON rename that breaks silently

Real-life example: the counter writes order slips for the kitchen: item, qty. One day the counter staff print new slips that say quantity instead of qty. The cook looks for qty, finds nothing, and makes 0 cups. Nobody shouts; the customer just never gets the chai.

Raju's order service sends each order to the kitchen service as JSON. The order team does a "small cleanup" and renames qty to quantity; their tests pass. The kitchen team still has the old struct.

go.mod:

module shop

go 1.24

main.go:

package main

import (
    "encoding/json"
    "fmt"
)

// the orders team, after a "small cleanup": qty is now quantity
type OrderV2 struct {
    Item     string `json:"item"`
    Quantity int    `json:"quantity"`
}

// the kitchen team still has the old struct
type OrderV1 struct {
    Item string `json:"item"`
    Qty  int    `json:"qty"`
}

func main() {
    body, _ := json.Marshal(OrderV2{Item: "chai", Quantity: 2})
    fmt.Println("sent:    ", string(body), "-", len(body), "bytes")

    var got OrderV1
    err := json.Unmarshal(body, &got)
    fmt.Printf("kitchen: %+v err=%v\n", got, err)
    fmt.Println("cups of chai to make:", got.Qty)
}
sent:     {"item":"chai","quantity":2} - 28 bytes
kitchen: {Item:chai Qty:0} err=<nil>
cups of chai to make: 0
  • err is nil and Qty is 0. encoding/json ignores keys it doesn't know (quantity) and leaves fields it didn't find (Qty) at their zero value. Nothing failed, but the data is wrong: a silent bug.
  • The message is 28 bytes, and most of them are the field names "item" and "quantity", sent again in every single message.

What services really need

  1. RPC, a remote procedure call: call a function on another machine as if it were local. reply, err := kitchen.PlaceOrder(ctx, req) looks like a normal call, but the request travels over the network and the reply comes back as the return value.
  2. A contract: one schema file that describes every message, with code generated for both sides, so a rename can't silently break the other team.
  3. Compact binary messages, fast to encode and decode, instead of repeating names as text.

Protocol Buffers give us the contract and the binary format. gRPC gives us the calls.

Protocol Buffers: the .proto file

Real-life example: a railway reservation form. It is the same printed form for every passenger, and the boxes are numbered: box 1 name, box 2 age. The clerk reads box numbers, not your handwriting of the labels. And someone has to print the forms.

Reservation form Protocol Buffers
the printed form, same for everyone the .proto file: the schema
numbered boxes: 1 name, 2 age field numbers: string item = 1; int32 qty = 2;
the printing press protoc (+ the protoc-gen-go plugin): generates Go code

Protocol Buffers (protobuf) is a language for describing structured data (the schema) plus a compact binary format for sending it. A schema describes the shape of the data: each message and its fields with their types.

order.proto (from the video):

syntax = "proto3";

package shop;

option go_package = "shop/orders;main";

// version 1, used by the kitchen service
message OrderV1 {
  string item = 1;
  int32 qty = 2;
}

// version 2: qty renamed, a new field added
message OrderV2 {
  string item = 1;
  int32 quantity = 2; // same number 2, new name
  string note = 3;    // new field, new number
}

Line by line:

  • syntax = "proto3";: the version of the protobuf language; proto3 is the current one.
  • package shop;: the protobuf package name. It becomes part of full names, like shop.OrderV1, and in gRPC part of the method path (/shop.OrderService/PlaceOrder).
  • option go_package = "shop/orders;main";: tells protoc-gen-go the Go import path (shop/orders) and, after the ;, the Go package name (main). The import path must contain a / or . (we hit that error below).
  • message OrderV1 { ... }: a message is a record type, like a Go struct.
  • string item = 1;: a field: a type (string), a name (item), and a field number (1). The number, not the name, is what travels.
  • OrderV2 is the "after the cleanup" version: qty renamed to quantity but kept number 2, and a new note field got a new number, 3.
  • // comments are copied into the generated Go code.

Field types used in this episode: string (text), int32 (a whole number, Go int32). Field names are written in snake_case (order_id, total_rupees); the Go code turns them into OrderId, TotalRupees and GetOrderId().

protoc and protoc-gen-go: printing the forms

protoc is the protocol buffer compiler: it reads .proto files. It doesn't know Go itself; a plugin does the writing. protoc-gen-go is the official Go plugin for messages. --go_out=. means "run protoc-gen-go and write into ."; --go_opt=paths=source_relative means "put the output next to the .proto file" instead of in folders named after the import path. The plugins must be on your PATH:

$ export PATH=/tmp/protobin:$PATH          # where protoc-gen-go and protoc-gen-go-grpc were installed
$ protoc --version
libprotoc 3.21.12
$ protoc --go_out=. --go_opt=paths=source_relative order.proto
$ wc -l order.pb.go
198 order.pb.go

The real run wrote order.pb.go, 198 lines we never edit by hand (it is byte-for-byte the file in episodes/go_gen/ep69/). Its first lines and the parts we use:

// Code generated by protoc-gen-go. DO NOT EDIT.
// versions:
//  protoc-gen-go v1.36.11
//  protoc        v3.21.12
// source: order.proto

package main
...
// version 2: qty renamed, a new field added
type OrderV2 struct {
    state         protoimpl.MessageState `protogen:"open.v1"`
    Item          string                 `protobuf:"bytes,1,opt,name=item,proto3" json:"item,omitempty"`
    Quantity      int32                  `protobuf:"varint,2,opt,name=quantity,proto3" json:"quantity,omitempty"` // same number 2, new name
    Note          string                 `protobuf:"bytes,3,opt,name=note,proto3" json:"note,omitempty"`          // new field, new number
    unknownFields protoimpl.UnknownFields
    sizeCache     protoimpl.SizeCache
}
...
func (x *OrderV2) GetQuantity() int32 {
    if x != nil {
        return x.Quantity
    }
    return 0
}

What the generated file contains:

  • a Go struct per message (OrderV1, OrderV2) with exported fields Item, Qty, Quantity, Note, plus a few private fields the library uses;
  • a struct tag per field that records the field number and wire type (protobuf:"varint,2,..."), and also a json tag;
  • getters (GetItem(), GetQty(), GetQuantity(), GetNote()): they check x != nil, so they are safe to call on a nil message and return the zero value;
  • methods Reset, String, ProtoReflect and a compressed copy of the schema (the "descriptor") that the protobuf library uses to encode and decode.

The header says DO NOT EDIT: the next protoc run overwrites the file. To change it, change the .proto and regenerate.

Programs that only use messages need just the protobuf module:

module shop

go 1.24

require google.golang.org/protobuf v1.36.11

Field numbers on the wire

Now the same order as protobuf. proto.Marshal turns a message into bytes (marshal = encode to bytes; unmarshal = decode back). We compare with JSON, then walk the bytes with the low-level protowire package to see what's inside. Then the old V1 reads a new V2 message, the new V2 reads an old V1 message, and finally someone reuses number 2 for a text field. The program is compiled together with order.proto and the generated order.pb.go above.

main.go:

package main

import (
    "encoding/json"
    "fmt"

    "google.golang.org/protobuf/encoding/protowire"
    "google.golang.org/protobuf/proto"
)

func main() {
    msg := &OrderV2{Item: "chai", Quantity: 2, Note: "less sugar"}
    b, _ := proto.Marshal(msg)
    j, _ := json.Marshal(msg)
    fmt.Printf("protobuf: %d bytes % x\n", len(b), b)
    fmt.Printf("JSON:     %d bytes %s\n", len(j), j)

    // what actually travels: field NUMBERS, never names
    for rest := b; len(rest) > 0; {
        num, typ, n := protowire.ConsumeTag(rest)
        rest = rest[n:]
        n = protowire.ConsumeFieldValue(num, typ, rest)
        fmt.Printf("  field %d, wire type %d, %d value bytes\n", num, typ, n)
        rest = rest[n:]
    }

    // the old kitchen service reads the NEW message
    var old OrderV1
    err := proto.Unmarshal(b, &old)
    fmt.Printf("V1 reads V2: item=%q qty=%d err=%v\n", old.GetItem(), old.GetQty(), err)

    // the new service reads an OLD message: the missing field is its zero value
    b1, _ := proto.Marshal(&OrderV1{Item: "samosa", Qty: 3})
    var v2 OrderV2
    proto.Unmarshal(b1, &v2)
    fmt.Printf("V2 reads V1: item=%q quantity=%d note=%q\n", v2.GetItem(), v2.GetQuantity(), v2.GetNote())

    // breaking change: someone reuses number 2 for a TEXT field
    bad := protowire.AppendTag(nil, 2, protowire.BytesType)
    bad = protowire.AppendString(bad, "two")
    err = proto.Unmarshal(bad, &old)
    fmt.Printf("number 2 reused as text: qty=%d err=%v\n", old.GetQty(), err)
}
protobuf: 20 bytes 0a 04 63 68 61 69 10 02 1a 0a 6c 65 73 73 20 73 75 67 61 72
JSON:     48 bytes {"item":"chai","quantity":2,"note":"less sugar"}
  field 1, wire type 2, 5 value bytes
  field 2, wire type 0, 1 value bytes
  field 3, wire type 2, 11 value bytes
V1 reads V2: item="chai" qty=2 err=<nil>
V2 reads V1: item="samosa" quantity=3 note=""
number 2 reused as text: qty=0 err=<nil>

20 bytes vs 48 bytes for the same order. (json.Marshal works on the generated struct because of its json tags.) Here are the 20 bytes, one field at a time:

Bytes Meaning
0a the tag: field number 1, wire type 2. A tag is number << 3 + wire type: 1×8 + 2 = 10 = 0x0a
04 length: 4 bytes follow
63 68 61 69 c h a i
10 tag: field 2, wire type 0 (varint): 2×8 + 0 = 16 = 0x10
02 the value 2, as a varint
1a tag: field 3, wire type 2: 3×8 + 2 = 26 = 0x1a
0a length: 10 bytes follow
6c 65 73 73 20 73 75 67 61 72 less sugar
  • A wire type tells the reader how to find the end of the value, even for a field it doesn't know: 0 = varint (numbers like int32), 2 = length-delimited (a length, then that many bytes: strings, bytes, nested messages); 1 and 5 are fixed 8-byte and 4-byte values (3 and 4, StartGroupType and EndGroupType, don't appear in this episode).
  • A varint ("variable-length integer") stores small numbers in fewer bytes: 7 bits of the number per byte, and the top bit says "another byte follows". 2 is the single byte 02; 150 needs two bytes, 96 01 (practice question 2 runs this).
  • The names item, quantity, note never travel. Only numbers do. Names stay in the .proto and the generated code.

And the three compatibility experiments:

  • V1 reads V2: qty=2. The rename qty → quantity was safe, because both versions call it number 2. Field 3 (note) is unknown to V1, so V1 simply skips it.
  • V2 reads V1: note="". A field that isn't in the bytes gets its zero value. New code must treat "empty" as "not sent".
  • Number 2 reused as text: qty=0 err=<nil>. The bytes say "field 2, length-delimited", but V1 expects field 2 to be a varint, so it can't use it and qty stays 0. The same silent bug as JSON. Field numbers are forever.

Backward compatibility

Backward compatible means new code still understands old messages, and (often called forward compatible) old code still understands new ones. During a deploy, old and new versions of services run at the same time, and old messages may sit in queues or databases, so both directions matter.

Change to a .proto Safe? Why
add a field with a new number yes old readers skip it; new readers see the zero value in old messages
rename a field, keep its number yes names don't travel (but JSON forms of the message do use names)
delete a field and reserve its number and name yes nobody can reuse them
change a field's number no old and new readers look in different places
change a field's type (e.g. int32 → string) no the wire type no longer matches: silently 0, as we saw
reuse a deleted field's number no old data is read as the new field

reserved

When you delete a field, mark its number and name as reserved, and protoc refuses any future field that uses them. Real runs:

syntax = "proto3";
package shop;
option go_package = "shop/orders;main";
message Order {
  reserved 2;
  reserved "qty";
  string item = 1;
  string note = 2;
}
$ protoc --go_out=. reserved.proto
reserved.proto: Field "note" uses reserved number 2.
reserved.proto: Suggested field numbers for shop.Order: 3

The same message with int32 qty = 3; instead of string note = 2;:

$ protoc --go_out=. reserved2.proto
reserved2.proto:8:9: Field name "qty" is reserved.

And two fields with the same number in one message:

dup.proto:6:15: Field number 1 has already been used in "shop.Order" by field "item".

buf

Long protoc commands get tedious, and protoc can't tell you that today's schema breaks yesterday's. buf is a toolchain for protobuf: it formats and lints .proto files (checks style rules), generates code, and has breaking-change detection, which compares your schema with an earlier version and fails if you broke a rule. From its README:

buf format -w
buf lint
buf breaking --against '.git#branch=main'
buf generate

buf breaking in CI (the automatic checks that run on every pull request) catches "changed a number" or "changed a type" before it is merged. (buf was not installed in this sandbox; these commands are from its README, not a real run.)

gRPC service definitions

gRPC is an open source, high-performance RPC framework built on HTTP/2 and Protocol Buffers. HTTP/2 is the second major version of HTTP, the protocol the web uses; per the gRPC-over-HTTP2 spec, every gRPC call is an HTTP/2 POST to the path /package.Service/Method, with the protobuf message as the body.

A service block in the .proto lists the functions other programs can call, each with a request message and a response message. orders.proto (from the video) is the whole service, all four kinds of call; keep it as the reference:

syntax = "proto3";

package shop;

option go_package = "shop/orders;main";

message OrderRequest {
  string item = 1;
  int32 qty = 2;
}

message OrderReply {
  string order_id = 1;
  int32 total_rupees = 2;
}

message TrackRequest { string order_id = 1; }
message TrackUpdate { string status = 1; int32 step = 2; }
message Item { string name = 1; int32 qty = 2; }
message Bill { int32 items = 1; int32 total_rupees = 2; }
message ChatMsg { string text = 1; }

service OrderService {
  rpc PlaceOrder(OrderRequest) returns (OrderReply);        // unary
  rpc TrackOrder(TrackRequest) returns (stream TrackUpdate); // server streaming
  rpc AddItems(stream Item) returns (Bill);                  // client streaming
  rpc KitchenChat(stream ChatMsg) returns (stream ChatMsg);  // bidirectional streaming
}
  • rpc PlaceOrder(OrderRequest) returns (OrderReply);: one method: its name, the request message type, the reply message type.
  • The word stream decides the kind of call (next section).

The second plugin, protoc-gen-go-grpc, writes the gRPC code; --go-grpc_out runs it:

$ protoc --go_out=. --go_opt=paths=source_relative \
         --go-grpc_out=. --go-grpc_opt=paths=source_relative orders.proto
$ wc -l orders.pb.go orders_grpc.pb.go
  467 orders.pb.go
  226 orders_grpc.pb.go

orders.pb.go has the seven message structs (same shape as before). orders_grpc.pb.go (226 lines, also byte-for-byte the episode's file) has:

const (
    OrderService_PlaceOrder_FullMethodName  = "/shop.OrderService/PlaceOrder"
    OrderService_TrackOrder_FullMethodName  = "/shop.OrderService/TrackOrder"
    ...
)

type OrderServiceClient interface {
    PlaceOrder(ctx context.Context, in *OrderRequest, opts ...grpc.CallOption) (*OrderReply, error)
    TrackOrder(ctx context.Context, in *TrackRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[TrackUpdate], error)
    AddItems(ctx context.Context, opts ...grpc.CallOption) (grpc.ClientStreamingClient[Item, Bill], error)
    KitchenChat(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[ChatMsg, ChatMsg], error)
}

func NewOrderServiceClient(cc grpc.ClientConnInterface) OrderServiceClient { ... }

type OrderServiceServer interface {
    PlaceOrder(context.Context, *OrderRequest) (*OrderReply, error)
    TrackOrder(*TrackRequest, grpc.ServerStreamingServer[TrackUpdate]) error
    AddItems(grpc.ClientStreamingServer[Item, Bill]) error
    KitchenChat(grpc.BidiStreamingServer[ChatMsg, ChatMsg]) error
    mustEmbedUnimplementedOrderServiceServer()
}

func (UnimplementedOrderServiceServer) TrackOrder(*TrackRequest, grpc.ServerStreamingServer[TrackUpdate]) error {
    return status.Error(codes.Unimplemented, "method TrackOrder not implemented")
}

func RegisterOrderServiceServer(s grpc.ServiceRegistrar, srv OrderServiceServer) { ... }
Generated name What it is Who uses it
OrderServiceServer an interface: the methods your server must have the server
UnimplementedOrderServiceServer a struct whose methods all answer Unimplemented; you embed it the server
RegisterOrderServiceServer attaches your implementation to a *grpc.Server the server
OrderServiceClient + NewOrderServiceClient a typed client with one Go method per RPC the client
..._FullMethodName the method path that travels in the request both, and interceptors

Why the demos use smaller protos

The SyntaxPilot compiler's editor holds at most 16,000 characters per program, and the two files generated from the whole orders.proto are already 22,439 characters (orders.pb.go 12,804 + orders_grpc.pb.go 9,635). So each gRPC demo below is compiled with a smaller .proto that keeps only the calls that demo uses, generated with the same protoc command:

Demo .proto (in episodes/go_gen/ep69/) Calls Generated lines (.pb.go + _grpc.pb.go)
unary, deadlines place/orders.proto PlaceOrder, CancelOrder 196 + 159
server + client streaming stream/orders.proto TrackOrder, AddItems 199 + 155
bidirectional streaming chat/orders.proto Kitchen.Chat 126 + 115

Re-running protoc on each of the three in this run produced files byte-for-byte equal to the episode's. The Go code you write against them is the same as against the whole service; only the message and method names are smaller.

Four ways to talk to the shop

Real life gRPC call type In the .proto
"Price of chai?" "15." One question, one answer unary rpc PlaceOrder(OrderRequest) returns (OrderReply);
live delivery tracking: one order, many updates server streaming returns (stream TrackUpdate)
reading your whole list to the cashier, then one bill client streaming (stream Item) returns (Bill)
a phone call with the kitchen: both talk any time bidirectional streaming (stream ChatMsg) returns (stream ChatMsg)

Unary RPC and status codes

A unary RPC is one request, one reply: exactly like calling a function. The server embeds UnimplementedOrderServiceServer, so every method we don't write answers Unimplemented. PlaceOrder looks up the price; an unknown item returns a status error with code NotFound, quantity 0 returns InvalidArgument. main starts the server on a free port, connects a client, places three orders, then calls CancelOrder, which we never wrote.

The demo's contract, place/orders.proto:

syntax = "proto3";

package shop;

option go_package = "shop/orders;main";

message OrderRequest {
  string item = 1;
  int32 qty = 2;
}

message OrderReply {
  string order_id = 1;
  int32 total_rupees = 2;
}

service OrderService {
  rpc PlaceOrder(OrderRequest) returns (OrderReply);
  rpc CancelOrder(OrderRequest) returns (OrderReply);
}

Every gRPC program in these notes uses this go.mod:

module shop

go 1.24

require (
    google.golang.org/grpc v1.80.0
    google.golang.org/protobuf v1.36.11
)

and is compiled together with a .proto and the two files protoc generated from it (orders.pb.go, orders_grpc.pb.go). The video's demos use the small protos above; the extra programs in Common mistakes and Practice use the whole orders.proto.

main.go:

package main

import (
    "context"
    "fmt"
    "log"
    "net"

    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/status"
)

var prices = map[string]int32{"chai": 15, "samosa": 20}

// the server: implement the methods of OrderServiceServer
type orderServer struct {
    UnimplementedOrderServiceServer // methods we don't write answer "Unimplemented"
}

func (s *orderServer) PlaceOrder(ctx context.Context, req *OrderRequest) (*OrderReply, error) {
    price, ok := prices[req.GetItem()]
    if !ok {
        return nil, status.Errorf(codes.NotFound, "no item %q on the menu", req.GetItem())
    }
    if req.GetQty() <= 0 {
        return nil, status.Error(codes.InvalidArgument, "qty must be at least 1")
    }
    return &OrderReply{OrderId: "ORD-1", TotalRupees: price * req.GetQty()}, nil
}

func main() {
    lis, err := net.Listen("tcp", "127.0.0.1:0") // any free port
    if err != nil {
        log.Fatal(err)
    }
    srv := grpc.NewServer()
    RegisterOrderServiceServer(srv, &orderServer{})
    go srv.Serve(lis)
    defer srv.Stop()

    // the client: a connection plus generated, typed methods
    conn, err := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()
    client := NewOrderServiceClient(conn)

    for _, req := range []*OrderRequest{{Item: "chai", Qty: 2}, {Item: "pizza", Qty: 1}, {Item: "samosa", Qty: 0}} {
        reply, err := client.PlaceOrder(context.Background(), req)
        if err != nil {
            st := status.Convert(err)
            fmt.Printf("%-7s -> error, code=%s, message=%q\n", req.GetItem(), st.Code(), st.Message())
            continue
        }
        fmt.Printf("%-7s -> %s, total %d rupees\n", req.GetItem(), reply.GetOrderId(), reply.GetTotalRupees())
    }
    _, err = client.CancelOrder(context.Background(), &OrderRequest{Item: "chai", Qty: 2}) // never written
    fmt.Println("CancelOrder:", err)
}
chai    -> ORD-1, total 30 rupees
pizza   -> error, code=NotFound, message="no item \"pizza\" on the menu"
samosa  -> error, code=InvalidArgument, message="qty must be at least 1"
CancelOrder: rpc error: code = Unimplemented desc = method CancelOrder not implemented
  • Server side: net.Listen("tcp", "127.0.0.1:0") opens a listener on any free port (:0 lets the OS pick); grpc.NewServer() makes a server; RegisterOrderServiceServer attaches our orderServer; srv.Serve(lis) accepts connections (in a goroutine, so main can go on).
  • Client side: grpc.NewClient(address, ...) creates a client connection (*grpc.ClientConn). insecure.NewCredentials() means no encryption: fine for one machine, never for real networks (real servers use TLS, episode 66). NewOrderServiceClient(conn) wraps it in the typed client.
  • client.PlaceOrder(ctx, req) returns (*OrderReply, error), like a local function. Chai: ORD-1, 2 × 15 = 30 rupees.
  • Pizza and samosa: the error carries a code and a message. status.Convert(err) turns any error into a *status.Status with .Code() and .Message().
  • CancelOrder: rpc error: code = Unimplemented desc = method CancelOrder not implemented. That text is exactly the status.Error in the generated UnimplementedOrderServiceServer: the embedded struct answered for us. Without embedding it, the program doesn't even compile (see Common mistakes).

gRPC status codes

Instead of HTTP's 400/404/503, gRPC has 17 status codes, the same for every language and transport. A real run that prints them all:

main.go (go.mod as above; no generated files needed):

package main

import (
    "fmt"

    "google.golang.org/grpc/codes"
)

func main() {
    for c := codes.OK; c <= codes.Unauthenticated; c++ {
        fmt.Printf("%2d %s\n", uint32(c), c)
    }
}
 0 OK
 1 Canceled
 2 Unknown
 3 InvalidArgument
 4 DeadlineExceeded
 5 NotFound
 6 AlreadyExists
 7 PermissionDenied
 8 ResourceExhausted
 9 FailedPrecondition
10 Aborted
11 OutOfRange
12 Unimplemented
13 Internal
14 Unavailable
15 DataLoss
16 Unauthenticated
Code Use it when (from the codes package docs)
0 OK "returned on success"
1 Canceled "the operation was canceled (typically by the caller)"
2 Unknown unknown error; also "errors raised by APIs that do not return enough error information" (a plain Go error!)
3 InvalidArgument "client specified an invalid argument" (bad input whatever the state)
4 DeadlineExceeded "operation expired before completion"
5 NotFound "some requested entity ... was not found"
6 AlreadyExists creating something that "already exists"
7 PermissionDenied "the caller does not have permission" (known, but not allowed)
8 ResourceExhausted "some resource has been exhausted, perhaps a per-user quota"
9 FailedPrecondition "the system is not in a state required for the operation"
10 Aborted aborted, "typically due to a concurrency issue"
11 OutOfRange "attempted past the valid range"
12 Unimplemented "not implemented or not supported/enabled in this service"
13 Internal "some invariants expected by underlying system has been broken" (our bug)
14 Unavailable "currently unavailable ... may be corrected by retrying with a backoff"
15 DataLoss "unrecoverable data loss or corruption"
16 Unauthenticated "does not have valid authentication credentials" (not logged in)

The video compares the common ones to HTTP's 400 (InvalidArgument), 404 (NotFound), 401 (Unauthenticated) and 503 (Unavailable). The functions:

Function Side What it does
status.Error(codes.NotFound, "msg") server an error with a code
status.Errorf(codes.NotFound, "no item %q", x) server the same, with fmt formatting
status.Code(err) client just the code (OK for nil)
status.Convert(err) client a *Status with .Code() and .Message()
status.FromContextError(ctx.Err()) server turns a context error into Canceled/DeadlineExceeded

Streaming RPCs

Server and client streaming

This contract, stream/orders.proto, has one server-streaming and one client-streaming call, with two small messages, Item and Note:

syntax = "proto3";

package shop;

option go_package = "shop/orders;main";

message Item {
  string name = 1;
  int32 qty = 2;
}

message Note {
  string text = 1;
  int32 n = 2;
}

service OrderService {
  rpc TrackOrder(Item) returns (stream Note); // server streaming
  rpc AddItems(stream Item) returns (Note);   // client streaming
}
  • TrackOrder (server streaming) gets one request and calls stream.Send four times; returning from the method ends the stream.
  • AddItems (client streaming) calls stream.Recv() until it returns io.EOF, which means "the client said that's all", then answers once with SendAndClose. The reply Note carries the item count as text and the total in N.

main.go:

package main

import (
    "context"
    "fmt"
    "io"
    "log"
    "net"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

var prices = map[string]int32{"chai": 15, "samosa": 20, "vada pav": 25}

type orderServer struct{ UnimplementedOrderServiceServer }

// server streaming: one request, many replies
func (s *orderServer) TrackOrder(it *Item, stream grpc.ServerStreamingServer[Note]) error {
    for i, st := range []string{"cooking", "packed", "out for delivery", "delivered"} {
        stream.Send(&Note{Text: st, N: int32(i + 1)})
        time.Sleep(50 * time.Millisecond)
    }
    return nil // returning ends the stream
}

// client streaming: many requests, one reply
func (s *orderServer) AddItems(stream grpc.ClientStreamingServer[Item, Note]) error {
    var count, total int32
    for {
        it, err := stream.Recv()
        if err == io.EOF { // the client said "that's all"
            return stream.SendAndClose(&Note{Text: fmt.Sprint(count, " items"), N: total})
        }
        if err != nil {
            return err
        }
        count += it.GetQty()
        total += prices[it.GetName()] * it.GetQty()
    }
}

func main() {
    lis, err := net.Listen("tcp", "127.0.0.1:0")
    if err != nil {
        log.Fatal(err)
    }
    srv := grpc.NewServer()
    RegisterOrderServiceServer(srv, &orderServer{})
    go srv.Serve(lis)
    defer srv.Stop()
    conn, _ := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
    defer conn.Close()
    c, ctx := NewOrderServiceClient(conn), context.Background()

    track, _ := c.TrackOrder(ctx, &Item{Name: "chai", Qty: 2})
    for {
        u, err := track.Recv()
        if err == io.EOF { // the server finished the stream
            break
        }
        fmt.Printf("track: step %d %s\n", u.GetN(), u.GetText())
    }

    add, _ := c.AddItems(ctx)
    add.Send(&Item{Name: "chai", Qty: 2})
    add.Send(&Item{Name: "samosa", Qty: 3})
    add.Send(&Item{Name: "vada pav", Qty: 1})
    bill, err := add.CloseAndRecv()
    fmt.Printf("bill: %s, %d rupees, err=%v\n", bill.GetText(), bill.GetN(), err)
}
track: step 1 cooking
track: step 2 packed
track: step 3 out for delivery
track: step 4 delivered
bill: 6 items, 115 rupees, err=<nil>
  • Track: four updates arrive one by one over one call.
  • Bill: 2×15 + 3×20 + 1×25 = 115 rupees, 6 items: one reply for three sent items.
  • The client read the updates with Recv until io.EOF, and collected the bill with CloseAndRecv.
  • Both calls used the same conn: HTTP/2 carries many calls (streams) over one connection.

Bidirectional streaming

A Kitchen service with one call, Chat, a stream in both directions (chat/orders.proto):

syntax = "proto3";

package shop;

option go_package = "shop/orders;main";

message ChatMsg {
  string text = 1;
}

service Kitchen {
  rpc Chat(stream ChatMsg) returns (stream ChatMsg); // bidirectional streaming
}

The server receives a message and answers it, and for a rush order it sends a second message nobody asked for. The client receives in a background goroutine while main keeps sending, then CloseSend says "that's all from me"; the server's Recv then returns io.EOF, it returns, and the client's Recv gets an error, which closes done.

main.go:

package main

import (
    "context"
    "fmt"
    "io"
    "log"
    "net"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

type kitchen struct{ UnimplementedKitchenServer }

// bidirectional streaming: both sides send whenever they like
func (k *kitchen) Chat(stream grpc.BidiStreamingServer[ChatMsg, ChatMsg]) error {
    for {
        m, err := stream.Recv()
        if err == io.EOF { // the counter hung up
            return nil
        }
        if err != nil {
            return err
        }
        stream.Send(&ChatMsg{Text: "kitchen: ok, " + m.GetText()})
        if m.GetText() == "rush order for table 7" {
            stream.Send(&ChatMsg{Text: "kitchen: table 7 first, 5 minutes"}) // a second reply, unasked
        }
    }
}

func main() {
    lis, err := net.Listen("tcp", "127.0.0.1:0")
    if err != nil {
        log.Fatal(err)
    }
    srv := grpc.NewServer()
    RegisterKitchenServer(srv, &kitchen{})
    go srv.Serve(lis)
    defer srv.Stop()
    conn, _ := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
    defer conn.Close()

    chat, _ := NewKitchenClient(conn).Chat(context.Background())
    done := make(chan struct{})
    go func() { // receive in the background, while main keeps sending
        for {
            m, err := chat.Recv()
            if err != nil {
                close(done)
                return
            }
            fmt.Println("  <-", m.GetText())
        }
    }()
    for _, t := range []string{"table 4 wants extra chutney", "rush order for table 7", "make table 2's chai strong"} {
        fmt.Println("->", t)
        chat.Send(&ChatMsg{Text: t})
    }
    chat.CloseSend() // "that's all from me"
    <-done
}
-> table 4 wants extra chutney
-> rush order for table 7
-> make table 2's chai strong
  <- kitchen: ok, table 4 wants extra chutney
  <- kitchen: ok, rush order for table 7
  <- kitchen: table 7 first, 5 minutes
  <- kitchen: ok, make table 2's chai strong
  • The three messages went out without waiting for answers, and the kitchen's replies came back as it sent them, including the extra one about table 7. Neither side waits for the other: a conversation, not question and answer.
  • The line order can vary between runs: the -> lines are printed by main and the <- lines by the receiving goroutine, so they can interleave differently (in this run, and in a second run, all three -> lines came first). The order of the <- lines themselves is fixed, because one stream delivers messages in the order they were sent.
Kind Server method gets Server calls Client calls
unary (ctx, *Req) return reply, err c.PlaceOrder(ctx, req)
server streaming (*Req, grpc.ServerStreamingServer[Resp]) Send(...) many times, return nil Recv() until io.EOF
client streaming (grpc.ClientStreamingServer[Req, Resp]) Recv() until io.EOF, then SendAndClose(reply) Send(...) many times, then CloseAndRecv()
bidirectional (grpc.BidiStreamingServer[Req, Resp]) Recv() and Send() in any order Send, Recv, finally CloseSend()

io.EOF means "the other side is done", not an error. Any other error from Recv is a real failure and should be returned.

Deadlines, metadata, interceptors

Three production features in one program (compiled with place/orders.proto, like the unary demo):

  • Deadline: biryani is slow (300 ms), but the server watches ctx.Done(). The client gives every call a deadline of 100 ms with context.WithTimeout (a ctx, a context, carries a deadline and a "stop" signal through every call).
  • Metadata: the client adds an x-request-id, like an HTTP header, with metadata.AppendToOutgoingContext; the server reads it with metadata.FromIncomingContext.
  • Interceptor: logCalls is a function that wraps every unary call: it logs the method, the request id, the code and the time, and calls next to run the real method.

main.go:

package main

import (
    "context"
    "fmt"
    "net"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/metadata"
    "google.golang.org/grpc/status"
)

type orderServer struct{ UnimplementedOrderServiceServer }

func (s *orderServer) PlaceOrder(ctx context.Context, req *OrderRequest) (*OrderReply, error) {
    if req.GetItem() == "biryani" { // a slow dish
        select {
        case <-time.After(300 * time.Millisecond):
        case <-ctx.Done(): // the client gave up: stop working
            return nil, status.FromContextError(ctx.Err()).Err()
        }
    }
    return &OrderReply{OrderId: "ORD-7", TotalRupees: 15 * req.GetQty()}, nil
}

// an interceptor runs around EVERY call: logging, auth, metrics, in one place
func logCalls(ctx context.Context, req any, info *grpc.UnaryServerInfo, next grpc.UnaryHandler) (any, error) {
    start := time.Now()
    md, _ := metadata.FromIncomingContext(ctx) // the call's headers
    resp, err := next(ctx, req)                // run the real method
    fmt.Printf("  [server] %s request-id=%v code=%s %v\n",
        info.FullMethod, md.Get("x-request-id"), status.Code(err), time.Since(start).Round(10*time.Millisecond))
    return resp, err
}

func main() {
    lis, _ := net.Listen("tcp", "127.0.0.1:0")
    srv := grpc.NewServer(grpc.UnaryInterceptor(logCalls))
    RegisterOrderServiceServer(srv, &orderServer{})
    go srv.Serve(lis)
    defer srv.Stop()
    conn, _ := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
    defer conn.Close()
    c := NewOrderServiceClient(conn)

    for i, item := range []string{"chai", "biryani"} {
        // a deadline: this call may take at most 100ms, end to end
        ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
        ctx = metadata.AppendToOutgoingContext(ctx, "x-request-id", fmt.Sprint("req-", i+1))
        reply, err := c.PlaceOrder(ctx, &OrderRequest{Item: item, Qty: 2})
        cancel()
        fmt.Printf("%-8s reply=%v code=%s\n", item, reply.GetOrderId(), status.Code(err))
    }
    time.Sleep(50 * time.Millisecond) // let the server finish its log line
}
  [server] /shop.OrderService/PlaceOrder request-id=[req-1] code=OK 0s
chai     reply=ORD-7 code=OK
  [server] /shop.OrderService/PlaceOrder request-id=[req-2] code=Canceled 100ms
biryani  reply= code=DeadlineExceeded
  • Chai: OK, logged by the interceptor with request id req-1. info.FullMethod is the path that travels: /shop.OrderService/PlaceOrder.
  • Biryani: the client got DeadlineExceeded after 100 ms.
  • The deadline travels with the call (the gRPC spec sends it as the grpc-timeout header), so the server's ctx was cancelled at 100 ms too: it logged Canceled 100ms and stopped cooking instead of working 300 ms for nobody. status.FromContextError(ctx.Err()) turned the context error into the code.
  • md.Get("x-request-id") returns a []string ([req-1]), because a header may appear more than once.
  • The server's log line and the client's line for biryani can come in either order: they are printed by different goroutines (in this run the server's came first; in an earlier run it came after).

Production gRPC habits

  • A deadline on every call. Without one, a client waits as long as the server takes (Common mistakes shows a real 1-second wait).
  • Pass ctx on. If the order service calls the kitchen with the ctx it received, the deadline flows to every service further down the chain.
  • Metadata = headers: request ids, auth tokens. Header names use lowercase letters, digits, _, - and . (the gRPC spec's Header-Name rule).
  • Interceptors = middleware (episode 64): there are unary and stream versions, for servers and clients:
Interceptor Install with Signature (short)
unary server grpc.NewServer(grpc.UnaryInterceptor(f)) f(ctx, req, info, next) (any, error)
stream server grpc.NewServer(grpc.StreamInterceptor(f)) f(srv, ss, info, next) error
unary client grpc.NewClient(addr, grpc.WithUnaryInterceptor(f)) f(ctx, method, req, reply, cc, invoker, opts...) error
several in order grpc.ChainUnaryInterceptor(recoverer, auth, logCalls) runs them in order around the call
  • Real servers use TLS credentials, not insecure (episode 66).

gRPC vs REST

gRPC REST + JSON
message format binary Protocol Buffers, small text JSON, bigger, readable
schema required: .proto, generated code optional (OpenAPI)
transport HTTP/2, streaming both ways HTTP/1.1 or HTTP/2
errors 17 status codes, deadlines built in HTTP status codes
browsers need a proxy (gRPC-Web) work everywhere
debugging not human-readable with plain curl curl it, cache it, easy to read
best for between your own services browsers and public APIs

A common choice: gRPC inside (service to service), REST at the edge for browsers and partners. OpenAPI is a standard way to write a schema for a REST API.

grpc-gateway: REST in front of gRPC

grpc-gateway is a protoc plugin that reads your service definitions and generates a reverse proxy (a server that receives requests and forwards them to another server) which translates a RESTful JSON API into gRPC calls. You add google.api.http annotations in the .proto. The example from its README (not run here; it needs the googleapis .proto files):

import "google/api/annotations.proto";

service YourService {
  rpc Echo(StringMessage) returns (StringMessage) {
    option (google.api.http) = {
      post: "/v1/example/echo"
      body: "*"
    };
  }
}

A browser then sends POST /v1/example/echo with JSON, and the gateway calls the gRPC Echo method.

gRPC-Web and Connect RPC

  • gRPC-Web lets browser code call gRPC services through a proxy.
  • Connect RPC (connect-go) is a slim library whose handlers and clients speak three protocols: gRPC, gRPC-Web and Connect's own protocol. The Connect protocol works over HTTP/1.1 or HTTP/2, and you can call it with plain curl and JSON. Its README's example (not run here):
curl \
    --header "Content-Type: application/json" \
    --data '{"sentence": "I feel happy."}' \
    https://demo.connectrpc.com/connectrpc.eliza.v1.ElizaService/Say

Same .proto, same generated types; one server reachable by gRPC clients, browsers and curl.

gRPC and Protocol Buffers in one page

  1. .proto = the contract → protoc / buf generate code → implement the Server interface (embed Unimplemented...) and Register it → call it with the typed Client.
  2. Numbers travel, names don't: never reuse or renumber a field, never change its type; reserved the old ones.
  3. unary · server stream · client stream · bidi; io.EOF ends a stream.
  4. Errors: status.Error(codes.X, ...) on the server, status.Code(err) on the client.
  5. A deadline on every call, metadata for headers, interceptors around every call.
  6. gRPC inside, REST / Connect / grpc-gateway at the edge.

Mini project: the kitchen service

Build a kitchen service:

  1. kitchen.proto with Cook (unary) and Status (server streaming).
  2. NotFound for unknown dishes, InvalidArgument for qty < 1.
  3. A logging + request-id interceptor (unary and stream).
  4. The order service calls Cook with a 500 ms deadline.
  5. v2: add a spice_level field, and prove v1 clients still work.
Full solution

Version 1 of the contract, kitchen.proto, is the v2 file below without the spice_level line:

$ protoc --go_out=. --go_opt=paths=source_relative \
         --go-grpc_out=. --go-grpc_opt=paths=source_relative kitchen.proto
$ wc -l kitchen.pb.go kitchen_grpc.pb.go
  297 kitchen.pb.go
  163 kitchen_grpc.pb.go

Version 2 adds one field with a new number; nothing else changes:

syntax = "proto3";

package kitchen;

option go_package = "shop/kitchen;main";

message CookRequest {
  string dish = 1;
  int32 qty = 2;
  string spice_level = 3; // v2: a new field with a NEW number
}

message CookReply {
  string ticket_id = 1;
  int32 cook_ms = 2;
}

message StatusRequest { string ticket_id = 1; }
message StatusUpdate { string stage = 1; int32 percent = 2; }

service Kitchen {
  rpc Cook(CookRequest) returns (CookReply);                // unary
  rpc Status(StatusRequest) returns (stream StatusUpdate);  // server streaming
}

To prove that v1 clients still work inside one program, we keep a copy of the v1 request message under another name, kitchen_v1.proto (exactly the fields v1 clients were compiled with):

syntax = "proto3";

package kitchen;

option go_package = "shop/kitchen;main";

// exactly what version 1 clients were compiled with (no spice_level)
message CookRequestV1 {
  string dish = 1;
  int32 qty = 2;
}
$ protoc --go_out=. --go_opt=paths=source_relative \
         --go-grpc_out=. --go-grpc_opt=paths=source_relative kitchen.proto kitchen_v1.proto
$ wc -l kitchen.pb.go kitchen_grpc.pb.go kitchen_v1.pb.go
  307 kitchen.pb.go
  163 kitchen_grpc.pb.go
  132 kitchen_v1.pb.go

The new field in the generated struct:

type CookRequest struct {
    state         protoimpl.MessageState `protogen:"open.v1"`
    Dish          string                 `protobuf:"bytes,1,opt,name=dish,proto3" json:"dish,omitempty"`
    Qty           int32                  `protobuf:"varint,2,opt,name=qty,proto3" json:"qty,omitempty"`
    SpiceLevel    string                 `protobuf:"bytes,3,opt,name=spice_level,json=spiceLevel,proto3" json:"spice_level,omitempty"` // v2: a new field with a NEW number
    unknownFields protoimpl.UnknownFields
    sizeCache     protoimpl.SizeCache
}

main.go (the gRPC go.mod above; compiled with kitchen.proto, kitchen_v1.proto and the three generated files):

package main

import (
    "context"
    "fmt"
    "io"
    "log"
    "net"
    "sync/atomic"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/metadata"
    "google.golang.org/grpc/status"
)

// ---------- the kitchen service (server) ----------

var menu = map[string]time.Duration{ // dish -> cooking time
    "chai":        20 * time.Millisecond,
    "masala dosa": 60 * time.Millisecond,
    "dum biryani": 800 * time.Millisecond, // slower than any sensible deadline
}

type kitchen struct {
    UnimplementedKitchenServer
    tickets atomic.Int32 // many calls can run at once: count safely
}

func (k *kitchen) Cook(ctx context.Context, req *CookRequest) (*CookReply, error) {
    cookTime, ok := menu[req.GetDish()]
    if !ok {
        return nil, status.Errorf(codes.NotFound, "no dish %q on the menu", req.GetDish())
    }
    if req.GetQty() < 1 {
        return nil, status.Errorf(codes.InvalidArgument, "qty must be at least 1, got %d", req.GetQty())
    }
    spice := req.GetSpiceLevel()
    if spice == "" { // a v1 client never sends it: "" is the zero value
        spice = "medium"
    }
    select {
    case <-time.After(cookTime):
    case <-ctx.Done(): // the caller's deadline passed: stop cooking
        return nil, status.FromContextError(ctx.Err()).Err()
    }
    id := fmt.Sprintf("T-%d", k.tickets.Add(1))
    fmt.Printf("  [kitchen] cooked %d x %s (%s)\n", req.GetQty(), req.GetDish(), spice)
    return &CookReply{TicketId: id, CookMs: int32(cookTime / time.Millisecond)}, nil
}

func (k *kitchen) Status(req *StatusRequest, stream grpc.ServerStreamingServer[StatusUpdate]) error {
    for i, stage := range []string{"chopping", "cooking", "plating"} {
        if err := stream.Send(&StatusUpdate{Stage: stage, Percent: int32((i + 1) * 100 / 3)}); err != nil {
            return err
        }
        time.Sleep(20 * time.Millisecond)
    }
    return nil
}

// ---------- interceptors: logging + request id ----------

func requestID(ctx context.Context) string {
    md, _ := metadata.FromIncomingContext(ctx)
    if ids := md.Get("x-request-id"); len(ids) > 0 {
        return ids[0]
    }
    return "(none)"
}

func logUnary(ctx context.Context, req any, info *grpc.UnaryServerInfo, next grpc.UnaryHandler) (any, error) {
    start := time.Now()
    resp, err := next(ctx, req)
    fmt.Printf("  [log] %s id=%s code=%s %v\n", info.FullMethod, requestID(ctx), status.Code(err),
        time.Since(start).Round(100*time.Millisecond))
    return resp, err
}

func logStream(srv any, ss grpc.ServerStream, info *grpc.StreamServerInfo, next grpc.StreamHandler) error {
    err := next(srv, ss)
    fmt.Printf("  [log] %s id=%s code=%s (stream)\n", info.FullMethod, requestID(ss.Context()), status.Code(err))
    return err
}

// ---------- the order service (client) ----------

func order(c KitchenClient, reqID, dish string, qty int32, spice string) {
    ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond) // the deadline
    defer cancel()
    ctx = metadata.AppendToOutgoingContext(ctx, "x-request-id", reqID)
    r, err := c.Cook(ctx, &CookRequest{Dish: dish, Qty: qty, SpiceLevel: spice})
    if err != nil {
        st := status.Convert(err)
        fmt.Printf("%s %-12s -> %s: %s\n", reqID, dish, st.Code(), st.Message())
        return
    }
    fmt.Printf("%s %-12s -> ticket %s, cooked in %dms\n", reqID, dish, r.GetTicketId(), r.GetCookMs())
}

func main() {
    lis, err := net.Listen("tcp", "127.0.0.1:0")
    if err != nil {
        log.Fatal(err)
    }
    srv := grpc.NewServer(grpc.UnaryInterceptor(logUnary), grpc.StreamInterceptor(logStream))
    RegisterKitchenServer(srv, &kitchen{})
    go srv.Serve(lis)
    defer srv.Stop()

    conn, err := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()
    c := NewKitchenClient(conn)

    fmt.Println("--- v2 order service ---")
    order(c, "r1", "masala dosa", 2, "hot")
    order(c, "r2", "pizza", 1, "")
    order(c, "r3", "chai", 0, "")
    order(c, "r4", "dum biryani", 1, "mild")
    time.Sleep(400 * time.Millisecond) // let the kitchen log the cancelled call

    fmt.Println("--- status stream ---")
    ctx := metadata.AppendToOutgoingContext(context.Background(), "x-request-id", "r5")
    st, _ := c.Status(ctx, &StatusRequest{TicketId: "T-1"})
    for {
        u, err := st.Recv()
        if err == io.EOF { // the kitchen finished the stream
            break
        }
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("T-1 %-9s %3d%%\n", u.GetStage(), u.GetPercent())
    }

    fmt.Println("--- an old v1 client (no spice_level field) ---")
    v1ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
    defer cancel()
    v1ctx = metadata.AppendToOutgoingContext(v1ctx, "x-request-id", "old-1")
    var reply CookReply
    err = conn.Invoke(v1ctx, Kitchen_Cook_FullMethodName, &CookRequestV1{Dish: "chai", Qty: 3}, &reply)
    fmt.Printf("old-1 chai -> ticket %s err=%v\n", reply.GetTicketId(), err)
}
--- v2 order service ---
  [kitchen] cooked 2 x masala dosa (hot)
  [log] /kitchen.Kitchen/Cook id=r1 code=OK 100ms
r1 masala dosa  -> ticket T-1, cooked in 60ms
  [log] /kitchen.Kitchen/Cook id=r2 code=NotFound 0s
r2 pizza        -> NotFound: no dish "pizza" on the menu
  [log] /kitchen.Kitchen/Cook id=r3 code=InvalidArgument 0s
r3 chai         -> InvalidArgument: qty must be at least 1, got 0
  [log] /kitchen.Kitchen/Cook id=r4 code=Canceled 500ms
r4 dum biryani  -> DeadlineExceeded: context deadline exceeded
--- status stream ---
T-1 chopping   33%
T-1 cooking    66%
T-1 plating   100%
  [log] /kitchen.Kitchen/Status id=r5 code=OK (stream)
--- an old v1 client (no spice_level field) ---
  [kitchen] cooked 3 x chai (medium)
  [log] /kitchen.Kitchen/Cook id=old-1 code=OK 0s
old-1 chai -> ticket T-2 err=<nil>
  • r1: OK through the interceptor, which logged the method, request id and code.
  • r2/r3: NotFound and InvalidArgument, with our messages.
  • r4: dum biryani takes 800 ms, the deadline is 500 ms: the client gets DeadlineExceeded, and the kitchen sees its ctx cancelled at 500 ms (Canceled 500ms) and stops. (In another run the [log] line for r4 came after the client's line: two goroutines print at the same time.)
  • Status: three updates, then the stream interceptor logs OK (stream) with request id r5.
  • The v1 proof: conn.Invoke sends a raw call to Kitchen_Cook_FullMethodName with a CookRequestV1, the message v1 clients were built with (no field 3). The v2 server read it fine: spice_level was missing, so it was "" (the zero value) and the kitchen used its default, medium. Adding a field with a new number did not break old clients.
  • tickets is an atomic.Int32 because a gRPC server runs each call in its own goroutine, so two Cook calls can update it at the same time.

Common mistakes (and the real messages)

The plain-error, no-deadline and server-down rows come from one real run:

main.go:

package main

import (
    "context"
    "errors"
    "fmt"
    "net"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/status"
)

type orderServer struct{ UnimplementedOrderServiceServer }

func (s *orderServer) PlaceOrder(ctx context.Context, req *OrderRequest) (*OrderReply, error) {
    switch req.GetItem() {
    case "lassi":
        return nil, errors.New("lassi is out of stock") // a plain Go error, no code
    case "biryani":
        time.Sleep(time.Second) // slow, and nobody set a deadline
    }
    return &OrderReply{OrderId: "ORD-9"}, nil
}

func main() {
    lis, _ := net.Listen("tcp", "127.0.0.1:0")
    srv := grpc.NewServer()
    RegisterOrderServiceServer(srv, &orderServer{})
    go srv.Serve(lis)
    defer srv.Stop()
    conn, _ := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
    defer conn.Close()
    c := NewOrderServiceClient(conn)

    // 1. a plain error from the server
    _, err := c.PlaceOrder(context.Background(), &OrderRequest{Item: "lassi", Qty: 1})
    fmt.Println("plain error:", err)

    // 2. no deadline: the client waits as long as the server takes
    start := time.Now()
    _, err = c.PlaceOrder(context.Background(), &OrderRequest{Item: "biryani", Qty: 1})
    fmt.Println("no deadline: waited", time.Since(start).Round(100*time.Millisecond), "err:", err)

    // 3. a server that isn't running
    dead, _ := net.Listen("tcp", "127.0.0.1:0")
    addr := dead.Addr().String()
    dead.Close() // nothing listens here any more
    conn2, _ := grpc.NewClient(addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
    defer conn2.Close()
    _, err = NewOrderServiceClient(conn2).PlaceOrder(context.Background(), &OrderRequest{Item: "chai", Qty: 1})
    fmt.Println("server down: code =", status.Code(err))
}
plain error: rpc error: code = Unknown desc = lassi is out of stock
no deadline: waited 1s err: <nil>
server down: code = Unavailable

Forgetting to embed UnimplementedOrderServiceServer (a server with only PlaceOrder):

package main

import (
    "context"

    "google.golang.org/grpc"
)

type orderServer struct{} // forgot UnimplementedOrderServiceServer

func (s *orderServer) PlaceOrder(ctx context.Context, req *OrderRequest) (*OrderReply, error) {
    return &OrderReply{OrderId: "ORD-1"}, nil
}

func main() {
    srv := grpc.NewServer()
    RegisterOrderServiceServer(srv, &orderServer{})
}
# shop
./main.go:17:37: cannot use &orderServer{} (value of type *orderServer) as OrderServiceServer value in argument to RegisterOrderServiceServer: *orderServer does not implement OrderServiceServer (missing method AddItems)
Mistake What you see Why Fix
renaming JSON fields between services kitchen: {Item:chai Qty:0} err=<nil> no shared contract a .proto both sides generate from
reusing a field number for a new type number 2 reused as text: qty=0 err=<nil> old data read as the new field a new number; reserved 2;
using a reserved number Field "note" uses reserved number 2. protoc protects you pick the suggested new number
two fields with one number Field number 1 has already been used in "shop.Order" by field "item". numbers must be unique unique numbers
forgetting a method on the server rpc error: code = Unimplemented desc = method CancelOrder not implemented the embedded Unimplemented...Server answered implement it
not embedding Unimplemented...Server *orderServer does not implement OrderServiceServer (missing method AddItems) the interface needs every method embed UnimplementedOrderServiceServer (by value)
returning errors.New from a handler rpc error: code = Unknown desc = lassi is out of stock a plain error has no code status.Error(codes.NotFound, ...)
calls without a deadline no deadline: waited 1s (or forever) default: no deadline context.WithTimeout on every call
server not running code = Unavailable nothing listening retry with backoff; check the address
no go_package protoc-gen-go: unable to determine Go import path for "nogopkg.proto" the plugin needs a Go import path option go_package = "shop/orders;main";
go_package = "main" invalid Go import path "main" for "nos.proto" ... must contain at least one period ('.') or forward slash ('/') not an import path "shop/orders;main"
plugin not on PATH protoc-gen-go: program not found or is not executable protoc looks for protoc-gen-go on PATH install it; export PATH=...
missing ; in the .proto semi.proto:4:48: Expected ";". syntax error add it
editing *.pb.go files your change is gone after the next protoc generated code (DO NOT EDIT) change the .proto, regenerate
ignoring the error from Recv the server spins on EOF; the client gets code: Internal and no bill (practice 4) io.EOF = the other side is done if err == io.EOF { return stream.SendAndClose(bill) }, then if err != nil { return err }

Practice

  1. A teammate wants to change int32 qty = 2; to string qty = 2; because "quantities like '2 large' are nicer". What happens to old services, and what should they do instead?
  2. Decode these bytes by hand: 08 96 01 12 03 74 65 61. Then check with protowire.
  3. Write a client interceptor that adds an x-request-id to every call and gives calls without a deadline a default 1-second deadline (homework from the video).
  4. Your AddItems server loop is for { it, _ := stream.Recv(); ... }. What goes wrong?
  5. For each, pick gRPC or REST: (a) the order service calling the kitchen service 2,000 times a second; (b) a public API for partner restaurants; (c) a browser dashboard of live orders, if you want one .proto for everything.
Solutions

1. Changing a field's type breaks compatibility: the number 2 now has wire type 2 (length-delimited) instead of 0 (varint). Old services read new messages as qty=0, err=<nil>, exactly the "number 2 reused as text" run above. Instead: add a new field, string qty_note = 3;, and keep int32 qty = 2;. If qty is ever removed, write reserved 2; reserved "qty";.

2. 08 = tag 8 = field 1 (8 >> 3), wire type 0 (8 & 7): a varint follows. 96 01: 0x96 has the top bit set, so another byte follows; the value is (0x96 & 0x7f) + 0x01 × 128 = 22 + 128 = 150. 12 = 18 = field 2, wire type 2; 03 = length 3; 74 65 61 = tea. Check:

main.go (go.mod with only google.golang.org/protobuf v1.36.11):

package main

import (
    "fmt"

    "google.golang.org/protobuf/encoding/protowire"
)

func main() {
    b := []byte{0x08, 0x96, 0x01, 0x12, 0x03, 0x74, 0x65, 0x61}
    for rest := b; len(rest) > 0; {
        num, typ, n := protowire.ConsumeTag(rest)
        rest = rest[n:]
        switch typ {
        case protowire.VarintType:
            v, m := protowire.ConsumeVarint(rest)
            fmt.Printf("field %d, wire type %d (varint): %d\n", num, typ, v)
            rest = rest[m:]
        case protowire.BytesType:
            v, m := protowire.ConsumeBytes(rest)
            fmt.Printf("field %d, wire type %d (length-delimited): %q\n", num, typ, v)
            rest = rest[m:]
        }
    }
    fmt.Printf("150 as a varint: % x\n", protowire.AppendVarint(nil, 150))
    fmt.Printf("2 as a varint:   % x\n", protowire.AppendVarint(nil, 2))
}
field 1, wire type 0 (varint): 150
field 2, wire type 2 (length-delimited): "tea"
150 as a varint: 96 01
2 as a varint:   02

3.

main.go:

package main

import (
    "context"
    "fmt"
    "net"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/metadata"
    "google.golang.org/grpc/status"
)

type orderServer struct{ UnimplementedOrderServiceServer }

func (s *orderServer) PlaceOrder(ctx context.Context, req *OrderRequest) (*OrderReply, error) {
    md, _ := metadata.FromIncomingContext(ctx)
    return &OrderReply{OrderId: "ORD-for-" + md.Get("x-request-id")[0], TotalRupees: 15 * req.GetQty()}, nil
}

// a CLIENT interceptor: runs around every call this client makes
func withRequestID() grpc.UnaryClientInterceptor {
    n := 0
    return func(ctx context.Context, method string, req, reply any, cc *grpc.ClientConn,
        invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
        n++
        ctx = metadata.AppendToOutgoingContext(ctx, "x-request-id", fmt.Sprint("auto-", n))
        if _, ok := ctx.Deadline(); !ok { // no deadline? add a default one
            var cancel context.CancelFunc
            ctx, cancel = context.WithTimeout(ctx, time.Second)
            defer cancel()
        }
        err := invoker(ctx, method, req, reply, cc, opts...) // make the real call
        fmt.Printf("  [client] %s code=%s\n", method, status.Code(err))
        return err
    }
}

func main() {
    lis, _ := net.Listen("tcp", "127.0.0.1:0")
    srv := grpc.NewServer()
    RegisterOrderServiceServer(srv, &orderServer{})
    go srv.Serve(lis)
    defer srv.Stop()
    conn, _ := grpc.NewClient(lis.Addr().String(),
        grpc.WithTransportCredentials(insecure.NewCredentials()),
        grpc.WithUnaryInterceptor(withRequestID()))
    defer conn.Close()
    c := NewOrderServiceClient(conn)
    for _, item := range []string{"chai", "chai"} {
        r, err := c.PlaceOrder(context.Background(), &OrderRequest{Item: item, Qty: 2})
        fmt.Println(r.GetOrderId(), r.GetTotalRupees(), err)
    }
}
  [client] /shop.OrderService/PlaceOrder code=OK
ORD-for-auto-1 30 <nil>
  [client] /shop.OrderService/PlaceOrder code=OK
ORD-for-auto-2 30 <nil>

The server never had to know about the interceptor; the request id arrived as ordinary metadata. grpc.WithUnaryInterceptor installs it on the connection, so every call through conn gets it.

4. It ignores the error. After the client's last item, Recv returns nil and io.EOF, and keeps doing so; it.GetQty() on a nil item is 0 (getters are nil-safe), so the loop spins and never sends the bill. A real run with a loop that gives up after 1000 calls and returns without SendAndClose:

main.go:

package main

import (
    "context"
    "fmt"
    "net"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    "google.golang.org/grpc/status"
)

type orderServer struct{ UnimplementedOrderServiceServer }

func (s *orderServer) AddItems(stream grpc.ClientStreamingServer[Item, Bill]) error {
    bill := &Bill{}
    for i := 0; ; i++ {
        it, err := stream.Recv() // the bug: the real code ignores err
        bill.Items += it.GetQty()
        if i == 1000 {
            fmt.Printf("  [server] still looping after %d Recv calls, last err=%v, item=%v\n", i, err, it)
            return nil
        }
    }
}

func main() {
    lis, _ := net.Listen("tcp", "127.0.0.1:0")
    srv := grpc.NewServer()
    RegisterOrderServiceServer(srv, &orderServer{})
    go srv.Serve(lis)
    defer srv.Stop()
    conn, _ := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
    defer conn.Close()
    ctx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()
    add, _ := NewOrderServiceClient(conn).AddItems(ctx)
    add.Send(&Item{Name: "chai", Qty: 2})
    bill, err := add.CloseAndRecv()
    fmt.Println("bill:", bill, "code:", status.Code(err))
}
  [server] still looping after 1000 Recv calls, last err=EOF, item=<nil>
bill: <nil> code: Internal

The server spun on EOF, and because it returned without SendAndClose, the client got code Internal and no bill. Fix: if err == io.EOF { return stream.SendAndClose(bill) }, then if err != nil { return err }, as in the streaming program.

5. (a) gRPC: your own services, high volume, small binary messages, deadlines and codes. (b) REST + JSON (or a grpc-gateway in front of the gRPC service): partners expect curl-able HTTP and JSON. (c) Connect RPC, or gRPC-Web through a proxy: browser-friendly, still from the same .proto.

Quick quiz

1. (From the video.) Which change to this message is safe for clients that still use the old version?

message Order {
  string item = 1;
  int32 qty = 2;
}
// A: rename qty to quantity, keep = 2
// B: change qty to string, keep = 2
// C: delete qty, add string note = 2
// D: renumber item to 5
Answer

A. Only field numbers travel, so renaming is safe. Changing the type (B), reusing number 2 (C) or renumbering (D) make old and new programs misread each other's data, silently.

2. A handler returns errors.New("out of stock"). What does status.Code(err) say on the client?

Answer

Unknown. The real run printed rpc error: code = Unknown desc = lassi is out of stock. Use status.Error(codes.NotFound, ...) or another fitting code.

3. The client's deadline is 100 ms and the server needs 300 ms. What code does the client get, and what does a well-written server do?

Answer

The client gets DeadlineExceeded. The server's ctx is cancelled too (the deadline travels with the call), so it should watch ctx.Done() and stop; the real run logged code=Canceled 100ms on the server.

4. In a client-streaming RPC, how does the server know the client has sent its last item?

Answer

stream.Recv() returns io.EOF (after the client calls CloseAndRecv()); the server then replies once with SendAndClose.

Interview questions

  1. What are Protocol Buffers? A schema language (.proto) plus a compact binary encoding; code for each language is generated by protoc and plugins.
  2. Why do field numbers matter more than names? Only numbers (with a wire type) are encoded; names exist only in the schema and code. Renaming is safe; renumbering or reusing a number is not.
  3. What does reserved do? Stops anyone from reusing a deleted field's number or name; protoc refuses the .proto.
  4. Which schema changes are backward compatible? Adding fields with new numbers, renaming fields, deleting fields while reserving them. Not: changing numbers or types, reusing numbers.
  5. What is gRPC? An open source, high-performance RPC framework: services defined in .proto, generated typed clients and servers, Protocol Buffers over HTTP/2, status codes, deadlines, metadata and streaming.
  6. Name the four RPC types. Unary, server streaming, client streaming, bidirectional streaming.
  7. Why embed UnimplementedXServer? The generated interface requires it; it makes methods you haven't written return Unimplemented, and lets the server keep compiling when new RPCs are added to the .proto.
  8. How do you return and read errors? status.Error(codes.X, msg) on the server; status.Code(err) / status.Convert(err) on the client. A plain error becomes Unknown.
  9. Why must every call have a deadline, and how does it propagate? Without one a call can wait forever; the deadline is sent with the call (grpc-timeout), the server's ctx is cancelled when it passes, and passing ctx on carries it downstream.
  10. What are metadata and interceptors? Metadata is key/value headers on a call (request ids, auth tokens). Interceptors are middleware around every call (unary/stream, server/client), used for logging, auth, metrics, panic recovery.
  11. protoc vs buf? protoc is the compiler that runs plugins; buf is a toolchain that also lints, formats, manages dependencies and detects breaking changes.
  12. When would you choose REST over gRPC, and how can you offer both? Browsers and public APIs; offer both with grpc-gateway (REST proxy from annotations) or Connect RPC (gRPC, gRPC-Web and Connect protocols from one handler).

Glossary

Term Meaning Example
Service (microservice) a separate program that does one job and talks to others over the network the order service, the kitchen service
JSON a text format for data, with names and values {"item":"chai","qty":2}
Marshal / unmarshal encode a value to bytes / decode bytes back to a value proto.Marshal(msg), json.Unmarshal(b, &v)
Zero value Go's default for a type: 0, "", false, nil missing qty reads as 0
Silent bug wrong data with no error qty=0 err=<nil>
RPC (remote procedure call) calling a function that runs on another machine client.PlaceOrder(ctx, req)
Contract an agreement both sides must follow, checked by tools the .proto file
Schema a description of the shape of data: messages, fields, types message OrderV1 { ... }
Protocol Buffers (protobuf) a schema language plus a compact binary format order.proto → 20 bytes
.proto file a file written in the protobuf language orders.proto
syntax = "proto3" which protobuf language version the file uses first line of every file here
package (protobuf) the namespace for names in the .proto package shop; → shop.OrderService
go_package the Go import path and package name for generated code "shop/orders;main"
Import path the name Go uses to import a package; must contain / or . for protoc-gen-go shop/orders
Message a record type in protobuf, like a Go struct message OrderReply
Field one named, typed, numbered part of a message int32 qty = 2;
Field number the number that identifies a field on the wire; 1 to 1<<29 - 1, never 19000-19999 = 2
Scalar types basic field types string, int32
snake_case words joined by _, the protobuf naming style; Go code uses OrderId order_id
Binary format data as raw bytes, not readable text 0a 04 63 68 61 69 ...
Wire / on the wire the bytes as they travel over the network "names never go on the wire"
Wire format how protobuf lays out the bytes: tag, then value tag 0x10, value 02
Tag field number and wire type packed in one varint: number << 3 plus the type 0x0a = field 1, type 2
Wire type tells the reader how long the value is 0 = varint, 2 = length-delimited
Varint variable-length integer: 7 bits per byte, top bit = "more bytes" 2 → 02, 150 → 96 01
Length-delimited a length, then that many bytes 04 63 68 61 69 = "chai"
protowire Go package for reading and writing raw protobuf bytes protowire.ConsumeTag(b)
proto.Marshal / proto.Unmarshal encode / decode a whole message proto.Marshal(&OrderV1{...})
Backward compatibility new code reads old data (and old code reads new data) V2 reads V1, V1 reads V2
Breaking change a change that makes old and new versions misread each other changing qty's type
reserved marks deleted field numbers/names so they're never reused reserved 2; reserved "qty";
protoc the protocol buffer compiler; runs plugins protoc --go_out=. order.proto
Plugin a separate program protoc runs to write code for one language protoc-gen-go
protoc-gen-go the plugin that writes Go structs for messages (*.pb.go) --go_out=.
protoc-gen-go-grpc the plugin that writes the gRPC server interface and client (*_grpc.pb.go) --go-grpc_out=.
paths=source_relative put generated files next to the .proto --go_opt=paths=source_relative
PATH the list of folders where the shell looks for programs export PATH=/tmp/protobin:$PATH
Generated code code written by a tool; never edit it by hand // Code generated ... DO NOT EDIT.
Getter generated method that returns a field, nil-safe req.GetQty()
Struct tag metadata on a Go struct field protobuf:"varint,2,..."
buf a protobuf toolchain: format, lint, generate, breaking-change detection buf breaking --against '.git#branch=main'
Lint automatic check of style rules buf lint
Breaking-change detection comparing a schema with an older version to find breaking changes buf breaking
CI automatic checks on every pull request runs buf breaking
gRPC an open source, high-performance RPC framework on HTTP/2 + protobuf grpc.NewServer()
HTTP/2 the second major version of HTTP; one connection carries many streams; gRPC calls are HTTP/2 POSTs all calls on one conn
Service definition a service block listing the RPC methods service OrderService { ... }
rpc one method in a service rpc PlaceOrder(OrderRequest) returns (OrderReply);
Full method name the path a call travels on: /package.Service/Method /shop.OrderService/PlaceOrder
Server interface the methods your server must implement OrderServiceServer
UnimplementedOrderServiceServer struct to embed; unwritten methods answer Unimplemented struct{ UnimplementedOrderServiceServer }
Embedding putting a type inside a struct so its methods become the struct's type orderServer struct{ UnimplementedOrderServiceServer }
Register...Server attaches your implementation to a gRPC server RegisterOrderServiceServer(srv, &orderServer{})
Typed client generated client with one Go method per RPC NewOrderServiceClient(conn)
Listener / port an open network door / its number net.Listen("tcp", "127.0.0.1:0")
grpc.NewClient creates a client connection to a server address grpc.NewClient(addr, ...)
*grpc.ClientConn a client connection, shared by many calls conn
insecure.NewCredentials() no encryption; for local demos only grpc.WithTransportCredentials(...)
TLS encryption for network connections (episode 66) real servers use TLS credentials
conn.Invoke a raw unary call by method name the v1-client proof
Unary RPC one request, one reply PlaceOrder
Stream a sequence of messages within one call stream TrackUpdate
Server streaming one request, many replies TrackOrder
Client streaming many requests, one reply AddItems
Bidirectional streaming both sides send many messages, in any order Kitchen.Chat
Send / Recv send / receive one message on a stream stream.Send(&TrackUpdate{...})
io.EOF "the other side is done sending" ends a Recv loop
SendAndClose client streaming: the server's one reply stream.SendAndClose(bill)
CloseAndRecv client streaming: the client says "done" and waits for the reply add.CloseAndRecv()
CloseSend client says "no more messages" on a bidi stream chat.CloseSend()
Status code gRPC's error category, 0-16 codes.NotFound
status.Error / Errorf build an error with a code status.Error(codes.InvalidArgument, "...")
status.Code / status.Convert read the code / code and message from an error status.Code(err)
Unknown the code a plain Go error becomes errors.New(...) on the server
Unavailable server can't be reached; retry with backoff server down
Backoff waiting longer between each retry 100 ms, 200 ms, 400 ms ...
Context (ctx) carries deadlines and cancellation through calls context.Background()
Deadline the latest time a call may finish context.WithTimeout(ctx, 100*time.Millisecond)
DeadlineExceeded the client's deadline passed biryani
Canceled the call was cancelled (e.g. the caller gave up) the server side of biryani
ctx.Done() a channel closed when the call is cancelled case <-ctx.Done():
grpc-timeout the header that carries the deadline to the server grpc-timeout = 1S
Metadata key/value headers on a gRPC call x-request-id: req-1
Request id a unique id per request, to follow it through logs req-1, r4
AppendToOutgoingContext / FromIncomingContext add metadata on the client / read it on the server md.Get("x-request-id")
Interceptor a function that wraps every call (gRPC's middleware) grpc.UnaryInterceptor(logCalls)
Middleware code that runs before and after every request (episode 64) logging, auth
ChainUnaryInterceptor run several unary interceptors in order (recoverer, auth, logCalls)
REST HTTP APIs built on URLs, methods and (usually) JSON GET /v1/orders/7
OpenAPI a standard schema format for REST APIs optional for REST
curl a command-line tool for sending HTTP requests curl --data '{...}' URL
Reverse proxy a server that receives requests and forwards them to another server grpc-gateway
grpc-gateway protoc plugin that generates a REST/JSON reverse proxy in front of gRPC option (google.api.http) = { post: "/v1/example/echo" ... }
Annotation an option in the .proto that adds extra information for a tool google.api.http
gRPC-Web a way for browsers to call gRPC, through a proxy browser dashboards
Connect RPC library whose handlers speak gRPC, gRPC-Web and the Connect protocol (HTTP/1.1 or HTTP/2, curl-able) connect-go
atomic.Int32 a counter that is safe to update from many goroutines k.tickets.Add(1)

Summary

  • JSON between services can break silently when one side renames a field: qty=0, err=<nil>.
  • Protocol Buffers are the fix: a .proto contract, code generated for both sides by protoc + protoc-gen-go (or buf), and compact binary messages: 20 bytes vs 48.
  • Field numbers travel, names don't: renaming is safe; changing a number or type, or reusing a number, is a silent bug. Use reserved, and let buf breaking check every change.
  • gRPC turns a service in the .proto into a typed server interface and client (protoc-gen-go-grpc): unary, server streaming, client streaming and bidirectional streaming, where io.EOF means "done".
  • Errors carry status codes (status.Error(codes.NotFound, ...)); a plain error becomes Unknown.
  • Put a deadline on every call (it travels to the server), carry headers in metadata, and wrap every call with interceptors.
  • gRPC inside, REST at the edge, or both from one .proto with grpc-gateway or Connect RPC.

Next episode: Observability: logs, metrics and traces (structured logs with slog, Prometheus metrics, RED and USE, OpenTelemetry traces and spans, traceparent, health checks, expvar).