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 isRequest-Headers *Length-Prefixed-Message EOS; the headers include:method POST,:path "/" Service-Name "/" {method name}, an optionalgrpc-timeout(the deadline, for examplegrpc-timeout = 1S),content-type "application/grpc", and Custom-Metadata (your own headers; binary ones end in-bin). The status is sent asgrpc-statusin 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.httpannotations 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
protocuse with a fast compiler, module-aware workspaces, formatting, linting, breaking-change detection, code generation, dependency management ..."; its quick start listsbuf format -w,buf lint,buf breaking --against '.git#branch=main'andbuf generate. google.golang.org/grpc/codes(v1.80.0,codes.go): the 17 codes fromOK(0) toUnauthenticated(16) and their doc comments, quoted in the status-code table.google.golang.org/protobuf/encoding/protowire(v1.36.11,wire.go): wire typesVarintType = 0,Fixed64Type = 1,BytesType = 2,Fixed32Type = 5(3 and 4 are the old "group" types);EncodeTagisuint64(num)<<3 | uint64(typ&7); valid field numbers run from 1 to1<<29 - 1, and 19000-19999 are reserved by protobuf itself;AppendVarintstores 7 bits per byte.- The generated
orders_grpc.pb.goitself: "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
errisnilandQtyis 0.encoding/jsonignores 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
- 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. - 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.
- 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, likeshop.OrderV1, and in gRPC part of the method path (/shop.OrderService/PlaceOrder).option go_package = "shop/orders;main";: tellsprotoc-gen-gothe 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.OrderV2is the "after the cleanup" version:qtyrenamed toquantitybut kept number 2, and a newnotefield 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 fieldsItem,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 ajsontag; - getters (
GetItem(),GetQty(),GetQuantity(),GetNote()): they checkx != nil, so they are safe to call on a nil message and return the zero value; - methods
Reset,String,ProtoReflectand 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,StartGroupTypeandEndGroupType, 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,notenever travel. Only numbers do. Names stay in the.protoand the generated code.
And the three compatibility experiments:
- V1 reads V2:
qty=2. The renameqty→quantitywas 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 andqtystays 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
streamdecides 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 (:0lets the OS pick);grpc.NewServer()makes a server;RegisterOrderServiceServerattaches ourorderServer;srv.Serve(lis)accepts connections (in a goroutine, somaincan 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.Statuswith.Code()and.Message(). CancelOrder:rpc error: code = Unimplemented desc = method CancelOrder not implemented. That text is exactly thestatus.Errorin the generatedUnimplementedOrderServiceServer: 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 callsstream.Sendfour times; returning from the method ends the stream.AddItems(client streaming) callsstream.Recv()until it returnsio.EOF, which means "the client said that's all", then answers once withSendAndClose. The replyNotecarries the item count as text and the total inN.
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
Recvuntilio.EOF, and collected the bill withCloseAndRecv. - 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 bymainand 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 withcontext.WithTimeout(actx, a context, carries a deadline and a "stop" signal through every call). - Metadata: the client adds an
x-request-id, like an HTTP header, withmetadata.AppendToOutgoingContext; the server reads it withmetadata.FromIncomingContext. - Interceptor:
logCallsis a function that wraps every unary call: it logs the method, the request id, the code and the time, and callsnextto 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 idreq-1.info.FullMethodis the path that travels:/shop.OrderService/PlaceOrder. - Biryani: the client got
DeadlineExceededafter 100 ms. - The deadline travels with the call (the gRPC spec sends it as the
grpc-timeoutheader), so the server'sctxwas cancelled at 100 ms too: it loggedCanceled 100msand 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
ctxon. If the order service calls the kitchen with thectxit 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'sHeader-Namerule). - 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 plaincurland 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
.proto= the contract → protoc / buf generate code → implement the Server interface (embedUnimplemented...) and Register it → call it with the typed Client.- Numbers travel, names don't: never reuse or renumber a field, never change its type;
reservedthe old ones. - unary · server stream · client stream · bidi;
io.EOFends a stream. - Errors:
status.Error(codes.X, ...)on the server,status.Code(err)on the client. - A deadline on every call, metadata for headers, interceptors around every call.
- gRPC inside, REST / Connect / grpc-gateway at the edge.
Mini project: the kitchen service
Build a kitchen service:
kitchen.protowithCook(unary) andStatus(server streaming).NotFoundfor unknown dishes,InvalidArgumentforqty < 1.- A logging + request-id interceptor (unary and stream).
- The order service calls
Cookwith a 500 ms deadline. - v2: add a
spice_levelfield, 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:NotFoundandInvalidArgument, with our messages.r4: dum biryani takes 800 ms, the deadline is 500 ms: the client getsDeadlineExceeded, and the kitchen sees itsctxcancelled 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 logsOK (stream)with request idr5.- The v1 proof:
conn.Invokesends a raw call toKitchen_Cook_FullMethodNamewith aCookRequestV1, the message v1 clients were built with (no field 3). The v2 server read it fine:spice_levelwas 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. ticketsis anatomic.Int32because a gRPC server runs each call in its own goroutine, so twoCookcalls 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
- A teammate wants to change
int32 qty = 2;tostring qty = 2;because "quantities like '2 large' are nicer". What happens to old services, and what should they do instead? - Decode these bytes by hand:
08 96 01 12 03 74 65 61. Then check withprotowire. - Write a client interceptor that adds an
x-request-idto every call and gives calls without a deadline a default 1-second deadline (homework from the video). - Your
AddItemsserver loop isfor { it, _ := stream.Recv(); ... }. What goes wrong? - 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
.protofor 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
- What are Protocol Buffers? A schema language (
.proto) plus a compact binary encoding; code for each language is generated byprotocand plugins. - 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.
- What does
reserveddo? Stops anyone from reusing a deleted field's number or name; protoc refuses the.proto. - 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.
- 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. - Name the four RPC types. Unary, server streaming, client streaming, bidirectional streaming.
- Why embed
UnimplementedXServer? The generated interface requires it; it makes methods you haven't written returnUnimplemented, and lets the server keep compiling when new RPCs are added to the.proto. - 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 becomesUnknown. - 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'sctxis cancelled when it passes, and passingctxon carries it downstream. - 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.
- protoc vs buf? protoc is the compiler that runs plugins; buf is a toolchain that also lints, formats, manages dependencies and detects breaking changes.
- 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
.protocontract, 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 letbuf breakingcheck every change. - gRPC turns a
servicein the.protointo a typed server interface and client (protoc-gen-go-grpc): unary, server streaming, client streaming and bidirectional streaming, whereio.EOFmeans "done". - Errors carry status codes (
status.Error(codes.NotFound, ...)); a plain error becomesUnknown. - 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
.protowith 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).