gRPC & Protobuf

The 30-second version

Big systems are usually split into many small programs, called microservicesMicroserviceA small, separately deployed program that owns one part of a bigger system and talks to the others over the network (HTTP, gRPC, a message queue).: one for products, one for orders, one for payments. They constantly need to ask each other things: "what does product 7 cost?", "is it in stock?". gRPC is one popular way to ask.

Three pieces make gRPC work. You'll meet each one in its own section:

Here's what one call looks like from the outside. On the client it really is just a method call:

// ctx carries the time limit for the call (§08); shopv1 is the package generated from the contract.
// &shopv1.GetProductRequest{Id: 7} builds the request message and passes a pointer to it.
resp, err := client.GetProduct(ctx, &shopv1.GetProductRequest{Id: 7})

But a lot happens between those parentheses:

That middle box, the network, is the reason this topic exists. It's also why §02 starts with a warning: a remote call only looks like a local call. Most of what makes gRPC good in production is about handling that honestly: deadlines (§08), status codes and retries (§09), and load balancing (§11).

What you'll be able to do after this topic

• Write a .proto contract and generate Go and JavaScript code from it.
• Read protobuf bytes by hand, and know which schema changes are safe to deploy.
• Build a gRPC server and client in Go, and call it from Node.
• Use all four call types: one request and one reply, or streams in either direction.
• Set deadlines that travel across services, return proper errors, and retry safely.
• Avoid the classic production traps: load balancers that send everything to one server, giant messages, and schema changes that silently corrupt data.

Calling a function on another machine

The idea: a function call that crosses machines

Inside one program, calling a function is simple. You jump to its code, it runs, it returns. Now imagine GetProduct lives in a different program, on a different machine, maybe written in a different language. To "call" it you have to:

1. turn the arguments into bytes (SerializationSerializationTurning an in-memory object into a flat string of bytes (e.g. JSON) so it can be sent somewhere, and parsing it back on the other side. It costs CPU time proportional to the data size.),
2. send those bytes over the network to the right machine,
3. have that machine turn the bytes back into arguments and run the real function,
4. turn the result into bytes, send them back, and turn them back into a value.

RPC frameworks generate the code for all four steps. The generated pieces are called stubsStub (client / server)Generated code that hides the network. The client stub has a method like GetProduct that turns your call into bytes and sends them; the server stub receives bytes and calls your handler.. You call a method on the client stub; the server stub calls your handler. That's the whole trick, and it dates back to the 1980s. gRPC is Google's modern, open-source version (released in 2015).

Why the illusion is dangerous

A local function call makes three promises the network can't keep:

Here's what that means in practice. Both of these lines look the same; only one of them can hang, half-succeed, or fail with a network error:

p := catalog.Lookup(7)                          // local: nanoseconds, can't "half happen"
resp, err := client.GetProduct(ctx, req)        // remote: ms to ∞, may fail, may have run anyway

So good RPC frameworks don't hide the network completely. gRPC makes you pass a ctx into every call, which can carry a deadline (setting one is your job — §08), returns a typed error code that says what kind of failure happened (§09), and lets you configure retries for only the safe cases.

REST + JSON vs gRPC + protobuf, honestly

You've probably built RESTRESTA style of web API where URLs name things (/products/7) and HTTP methods (GET, POST, DELETE…) say what to do with them, usually with JSON bodies. APIs: URLs like GET /products/7, HTTP methodsHTTP methodThe verb at the start of an HTTP request saying what you want to do: GET (read), POST (create/submit), PUT/PATCH (update), DELETE (remove). as verbs, and JSON bodies. gRPC is not "REST but better". It's a different set of trade-offs:

Protobuf: writing the contract

The .proto file is written in protobuf's interface definition languageInterface definition language (IDL)A small language just for describing data and functions — not for writing logic. A .proto file is written in protobuf's IDL; tools read it and generate real Go or JS code.. It only describes things; there's no logic in it. Here's the whole contract for the product catalog we'll use throughout this topic:

syntax = "proto3";                       // which protobuf version (always proto3 for new code)

package shop.v1;                         // a namespace, so names don't clash with other teams'

option go_package = "example.com/shop/gen/shop/v1;shopv1"; // where the generated Go code lives

message Product {
  int64 id = 1;                          // type, name, FIELD NUMBER
  string name = 2;
  int64 price_cents = 3;                 // 1999 = $19.99 (never use float for money)
  repeated string tags = 4;              // repeated = a list of strings
  Category category = 5;

  oneof discount {                       // at most ONE of these is set
    int32 percent_off = 6;
    int64 cents_off = 7;
  }

  optional string description = 8;       // can tell "not set" apart from ""
}

enum Category {
  CATEGORY_UNSPECIFIED = 0;              // the first value must be 0
  CATEGORY_BOOKS = 1;
  CATEGORY_TOYS = 2;
}

message GetProductRequest  { int64 id = 1; }
message GetProductResponse { Product product = 1; }  // a message inside a message

service CatalogService {
  rpc GetProduct(GetProductRequest) returns (GetProductResponse);
}

Why requests and responses get their own wrapper messages

GetProduct could have returned Product directly. Instead it returns GetProductResponse, which contains a Product. That looks like extra ceremony, but it buys you room to grow. Next year you might want to add bool from_cache = 2; to the response. With a wrapper you just add a field. Without one, you'd have to change the RPC's return type, and that breaks every client. The linter in buf (below) enforces this habit.

The zero-value rule (and why optional exists)

In proto3, every field has a default: 0, "", false, an empty list, or the enum's 0 value. A field holding its default isn't sent at all, and the reader fills the default back in. That keeps messages small, but it means a plain int32 percent_off can't tell "0% off" from "nobody set this".

Mark a field optional when that difference matters. Go then generates a PointerPointer (*T, &v)A value that holds the memory address of another value instead of a copy of it. In Go, &v takes v's address and *T is the type “pointer to T”; changes made through a pointer are seen by everyone holding it. JS objects behave like this automatically. (*string, where nil means "not set"), and JS gets a field that's simply absent. Fields inside a oneof, and fields whose type is another message, already track presence.

Generating code

The .proto file isn't used directly by Go. A code generator reads it and writes ordinary Go files (Code generationCode generation (codegen)A tool that writes source code for you from a description — e.g. protoc turning a .proto file into Go structs and client stubs, or Wire writing your main() wiring. The generated files are checked in or rebuilt, never edited by hand.). The tools you'll meet are protoc or bufprotoc / bufThe tools that read .proto files and run code-generator plugins. protoc is the original compiler from Google; buf is a newer, friendlier tool that also lints and checks for breaking changes., plus two plugins:

• protoc-gen-go writes the message types (Product struct, Category constants).
• protoc-gen-go-grpc writes the client and server stubs for each service.

# run from the project root (the folder with buf.yaml)
# one-time: install buf (e.g. npm install -g @bufbuild/buf) and the two Go plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

buf lint        # style + design checks (e.g. "use wrapper messages")
buf generate    # reads buf.gen.yaml, writes gen/shop/v1/*.pb.go

The modules: path: proto line matters. Without a buf.yaml, buf treats the whole project folder as the root, so the file is called proto/shop/v1/catalog.proto. We tried it: the code lands in gen/proto/shop/v1/ (not where go_package says), and buf lint complains:

proto/shop/v1/catalog.proto:3:1:Files with package "shop.v1" must be within a directory "shop/v1" relative to root but were in directory "proto/shop/v1".

With the buf.yaml above, buf lint prints nothing (that means no problems) and buf generate writes exactly two files: gen/shop/v1/catalog.pb.go and gen/shop/v1/catalog_grpc.pb.go.

What comes out is normal Go. Here's a trimmed view of the generated message type:

type Product struct {
    Id          int64
    Name        string
    PriceCents  int64
    Tags        []string
    Category    Category
    Discount    isProduct_Discount // the oneof: holds a *Product_PercentOff or *Product_CentsOff
    Description *string            // optional → pointer; nil = "not set"
    // …plus hidden internal fields
}

func (x *Product) GetName() string {
    if x != nil {          // ← getters are safe to call on a nil message
        return x.Name
    }
    return ""
}

Here's how each line of the Product message turns up in Go, and in JavaScript (using the Node loader you'll meet at the end of this section):

Setting and reading oneof and optional in Go

These two are where beginners get stuck, because you can't just write Discount: 10 or Description: "x":

p := &shopv1.Product{
    Id:          7,
    Name:        "Go Book",
    Discount:    &shopv1.Product_PercentOff{PercentOff: 10}, // oneof: wrap the value in its "case" type
    Description: proto.String("A book about Go"),            // optional: needs a pointer to a string
}

// Reading a oneof: ask which case is set.
switch d := p.GetDiscount().(type) {
case *shopv1.Product_PercentOff:
    fmt.Println("percent off:", d.PercentOff) // percent off: 10
case *shopv1.Product_CentsOff:
    fmt.Println("cents off:", d.CentsOff)
case nil:
    fmt.Println("no discount")
}
fmt.Println(p.GetCentsOff()) // 0 — getters are safe even when another case is set

// Reading an optional: was it set at all?
if p.Description != nil {
    fmt.Println("description:", p.GetDescription()) // description: A book about Go
}

And in JavaScript?

Node has two styles. The simplest, used in this topic, is dynamic loading with @grpc/proto-loader. It reads the .proto file when your program starts, so there's no build step. The other style is code generation (for example protobuf-es or ts-proto), which gives you TypeScript types. Teams that use TypeScript usually prefer that.

// npm install @grpc/grpc-js @grpc/proto-loader
import * as grpc from "@grpc/grpc-js";
import * as protoLoader from "@grpc/proto-loader";

const def = protoLoader.loadSync("proto/shop/v1/catalog.proto", {
  longs: Number,  // int64 → JS number (see the warning below)
  enums: String,  // "CATEGORY_BOOKS" instead of 1
  defaults: true, // missing fields show up as 0 / "" / []
  oneofs: true,   // adds product.discount = "percentOff" | "centsOff"
});
const shop = grpc.loadPackageDefinition(def).shop.v1; // ← follows "package shop.v1;"

Field names become lowerCamelCase in JS: price_cents becomes priceCents.

On the wire: tags and varints

You won't write these bytes by hand. But knowing what they look like explains almost every rule in the next section: why names don't matter, why numbers are forever, and why old code can skip fields it doesn't know.

Reading bytes in hex

Bytes are usually written in hexadecimalHexadecimal (hex)Base-16 numbers using the digits 0–9 and a–f. One hex digit is exactly 4 bits, so a byte is two hex digits: ff = 255. MAC and IPv6 addresses are written this way.: two characters per ByteByte8 bits — enough to store a number from 0 to 255, or one ASCII character. Network speeds are usually quoted in bits per second, file sizes in bytes., from 00 (0) to ff (255). So 0f = 15 and cf = 207. That's all the notation you need.

One field, three parts

Every encoded field is built the same way:

<< 3 means "shift left by 3 bits", which is the same as multiplying by 8. | wire_type then puts the wire type (0–7) in the 3 low bits that the shift left empty. So the reader can split a tag back apart: tag >> 3 is the field number, and tag & 7 is the wire type.

Varints: small numbers, small bytes

Most numbers in real data are small: IDs, counts, enum values. A varint uses 1 byte for 0–127, 2 bytes up to 16,383, and so on. Each byte holds 7 bits of the number. The 8th (top) bit is a flag: 1 means "another byte follows", 0 means "this is the last one". The lowest 7 bits come first.

A worked example: 1999 in binary is 111 1100 1111 (11 bits). That's more than 7 bits, so it needs two bytes:

• the low 7 bits are 100 1111; there's more to come, so set the top bit: 1100 1111 = cf
• the remaining bits are 1111, and nothing follows: 0000 1111 = 0f

So price_cents = 1999 (field 3) encodes as tag 18 (that's 3 << 3 | 0 = 24 = 0x18), then cf 0f.

Try it

The encoder below produces the same bytes Go's proto.Marshal does. Things to try:

• Set price_cents to 0. The field disappears from the bytes. That's the proto3 zero-value rule from §03.
• Make id bigger than 127, then bigger than 16,383, and watch it grow from 1 to 2 to 3 bytes.
• Set id to -1. It takes 10 bytes. Computers store −1 as all 64 bits set to 1 (two's complementTwo's complementHow computers store negative whole numbers: −1 is stored as all bits set to 1, −2 as all ones except the last bit, and so on. Read as an unsigned number, a small negative value looks enormous.), so read as a varint it looks like the huge number 2⁶⁴ − 1. If negatives are common, use the type sint64. It uses a trick called "ZigZag" so that small negative numbers stay small too.
• Tick "field number 16". The tag now needs 2 bytes (80 01). Field numbers 1–15 cost one tag byte, so give them to your most frequent fields. Notice id also moves to the end: Go writes fields in field-number order, not the order you declared them. (Readers must accept any order, though.)

The default example, byte by byte

Product{id: 7, name: "Go Book", price_cents: 1999, tags: ["go", "book"], category: BOOKS} becomes 26 bytes:

08 07                        field 1 (varint)   = 7
12 07 47 6f 20 42 6f 6f 6b   field 2 (length 7) = "Go Book"
18 cf 0f                     field 3 (varint)   = 1999
22 02 67 6f                  field 4 (length 2) = "go"    ← repeated: one entry per item
22 04 62 6f 6f 6b            field 4 (length 4) = "book"
28 01                        field 5 (varint)   = 1 (CATEGORY_BOOKS)

The same data as compact JSON is 92 bytes, about 3.5× larger. Most of the difference is the key names, "priceCents": and friends, repeated in every single message. Protobuf replaces each name with a one-byte tag.

You can check this yourself in a few lines:

import (
    "fmt"

    shopv1 "example.com/shop/gen/shop/v1"
    "google.golang.org/protobuf/proto"
)

func main() {
    p := &shopv1.Product{Id: 7, Name: "Go Book", PriceCents: 1999,
        Tags: []string{"go", "book"}, Category: shopv1.Category_CATEGORY_BOOKS}

    b, err := proto.Marshal(p) // struct → bytes
    if err != nil {
        panic(err)
    }
    fmt.Printf("% x\n", b) // 08 07 12 07 47 6f 20 42 6f 6f 6b 18 cf 0f 22 02 …
    fmt.Println(len(b))    // 26

    var back shopv1.Product
    _ = proto.Unmarshal(b, &back) // bytes → struct (error ignored only for brevity)
    fmt.Println(back.GetName())   // Go Book
}

Changing the contract safely

Why old and new code always overlap

You can't update every program at the same moment. During a rolling deployRolling deployReplacing the instances of an app a few at a time: start a new one, wait until it's ready, drain and stop an old one, repeat. The service stays up throughout., servers are replaced one by one, so for a few minutes some run v1 and some run v2. Mobile apps are worse: some users never update, so a v1 app may call your servers for years. This overlap is called Version skewVersion skewDifferent versions of the same program (or of a client and its server) running at the same time — normal during deploys, and for months with mobile apps that users don't update..

So every change has to work in two directions (backward and forward compatibilityBackward / forward compatibilityBackward compatible: new code can read data from old code. Forward compatible: old code can read data from new code. During a rolling deploy you need both, because old and new versions run side by side.):

• v2 server → v1 client: old code reads bytes written by new code.
• v1 client → v2 server: new code reads bytes written by old code.

What makes it possible: skipping unknown fields

Recall from §04 that every field starts with a tag: a field number plus a wire type. When a reader sees a field number its schema doesn't know, the wire type still tells it how many bytes to skip. A varint ends at the first byte without the top bit; a length-prefixed field says its length. So the old reader skips the field and carries on. No error, no crash. These skipped fields are called Unknown fieldsUnknown fieldsFields in received protobuf bytes whose numbers the reader's schema doesn't know (usually added in a newer version). The reader skips them without error; Go keeps the raw bytes and writes them back out if the message is re-sent., and Go even keeps their bytes so they survive if the message is passed on.

That one mechanism makes adding fields safe. It also explains why some other changes go badly wrong. Try them:

message Product {
int64 id = 1;
string name = 2;
int64 price_cents = 3;
}

message Product {
int64 id = 1;
string name = 2;
int64 price_cents = 3;
+ string description = 4;
}

The rules, from the simulator

reserved: a tombstone for dead fields

When you delete a field, leave a marker so nobody reuses its number or name by accident later:

message Product {
  reserved 3;                  // price_cents used to live here — never reuse 3
  reserved "price_cents";      // and keep the name free, for the JSON mapping

  int64 id = 1;
  string name = 2;
  int64 price_in_cents = 9;    // the replacement gets a brand-new number
}

Let a machine check it: buf breaking

People forget rules; machines don't. buf breaking compares your .proto files with an older version, for example the main branch in git, and fails if a change would break existing clients. Run it in CICI (continuous integration)A server that builds your code and runs its tests automatically on every push (GitHub Actions, GitLab CI, …), so mistakes are caught minutes after they're made. A flaky test there blocks everyone's merges.:

buf breaking --against '.git#branch=main'

Here's exactly what it printed (buf 1.75, default settings) when we changed line 10 from int64 price_cents = 3; to int64 stock_count = 3;, the reuse from the simulator. The exit code was 100, which fails a CI job:

proto/shop/v1/catalog.proto:10:3:Field "3" with name "stock_count" on message "Product" changed option "json_name" from "priceCents" to "stockCount".
proto/shop/v1/catalog.proto:10:9:Field "3" on message "Product" changed name from "price_cents" to "stock_count".

Notice what it says: "changed name". buf can't know that you meant a brand-new field. To a tool, keeping number 3 and type int64 but changing the name looks like a rename. The rename warnings are what save you here. They come from the default rules, which also protect the JSON mapping and your generated code.

Presence and evolution

Adding a plain int32 percent_off = 6; creates a quiet ambiguity. When a new server reads 0, it might mean "0% off" or it might mean "an old client that's never heard of this field". If that difference matters, declare it optional int32 percent_off = 6;. Go then generates a pointer, and an old client's message shows up as nil ("not sent") rather than 0. That's field presenceField presenceWhether you can tell "this field was set to 0 / empty" from "this field was never set". Plain proto3 scalar fields can't; fields marked optional (and message fields) can., from §03, paying off.

Your first service: server and client

We'll build the simplest kind of call first: a unary RPC, meaning one request in and one response out. GetProduct is unary. Streaming comes in §07.

The project, and how to run it

Here's every file involved, and which one uses which. You write the blue ones; buf generate writes the purple ones; Node reads the .proto file directly:

From an empty folder, these are the steps we ran (Go 1.26, Node 22):

go mod init example.com/shop                              # creates go.mod; the module path matches go_package
go get google.golang.org/grpc google.golang.org/protobuf  # the two Go libraries
# write proto/shop/v1/catalog.proto, buf.yaml, buf.gen.yaml (all from §03)
buf generate                                              # → gen/shop/v1/catalog.pb.go, catalog_grpc.pb.go
# write cmd/server/main.go and cmd/client/main.go (below)

go run ./cmd/server          # terminal 1: prints "listening on :50051" and keeps running
go run ./cmd/client          # terminal 2: prints "Go Book 1999", then the NotFound error

npm install @grpc/grpc-js @grpc/proto-loader
node client.mjs              # the Node client, against the same Go server

The server

The generated code gives you a Go InterfaceInterfaceA list of method names (and their signatures) with no code. Any type that has those methods can be used wherever the interface is expected. In Go this happens automatically, without writing “implements”. called CatalogServiceServer, with one method per rpc in the .proto file. Your job is to write a type that has those methods, then register it.

package main

import (
    "context"
    "log"
    "net"

    shopv1 "example.com/shop/gen/shop/v1"
    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

// catalogServer implements the CatalogServiceServer interface from the generated code.
type catalogServer struct {
    shopv1.UnimplementedCatalogServiceServer // ← embedded: "not implemented" for every RPC we skip
    products map[int64]*shopv1.Product
}

func (s *catalogServer) GetProduct(ctx context.Context, req *shopv1.GetProductRequest) (*shopv1.GetProductResponse, error) {
    p, ok := s.products[req.GetId()]
    if !ok {
        return nil, status.Errorf(codes.NotFound, "product %d not found", req.GetId()) // ← a gRPC error (§09)
    }
    return &shopv1.GetProductResponse{Product: p}, nil
}

func main() {
    lis, err := net.Listen("tcp", ":50051") // accept TCP connections on port 50051
    if err != nil {
        log.Fatal(err)
    }
    s := grpc.NewServer()
    shopv1.RegisterCatalogServiceServer(s, &catalogServer{products: map[int64]*shopv1.Product{
        7: {Id: 7, Name: "Go Book", PriceCents: 1999},
    }})
    log.Println("listening on :50051")
    log.Fatal(s.Serve(lis)) // blocks forever, serving calls
}

Every handler has the same shape: it takes a ctxcontext.ContextA value passed as the first argument through Go calls that carries a deadline and a “stop now” signal. ctx.Done() is a channel you can receive from once it's time to stop. and the request message, and returns the response message or an error. The ctx carries the caller's deadline and cancellation (§08) and its metadataMetadata (gRPC)Key–value pairs sent with a call, outside the message itself — gRPC's name for HTTP headers. Used for auth tokens, request IDs and tracing info., gRPC's version of headers (§10).

The Go client

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    shopv1 "example.com/shop/gen/shop/v1"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure" // ← the "no TLS" option lives in its own package
)

func main() {
    // Create the connection ONCE and reuse it for every call.
    conn, err := grpc.NewClient("localhost:50051",
        grpc.WithTransportCredentials(insecure.NewCredentials())) // no TLS: local demo only
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()
    client := shopv1.NewCatalogServiceClient(conn) // the generated client stub

    ctx, cancel := context.WithTimeout(context.Background(), time.Second) // ← deadline (§08)
    defer cancel()

    resp, err := client.GetProduct(ctx, &shopv1.GetProductRequest{Id: 7})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(resp.GetProduct().GetName(), resp.GetProduct().GetPriceCents()) // Go Book 1999

    _, err = client.GetProduct(ctx, &shopv1.GetProductRequest{Id: 42})
    fmt.Println(err) // rpc error: code = NotFound desc = product 42 not found
}

The Node client

The Node version calls the same Go server. It loads the same .proto file at runtime, as shown in §03:

import * as grpc from "@grpc/grpc-js";
import * as protoLoader from "@grpc/proto-loader";

const def = protoLoader.loadSync("proto/shop/v1/catalog.proto",
  { longs: Number, enums: String, defaults: true, oneofs: true });
const shop = grpc.loadPackageDefinition(def).shop.v1;

// One client object = one connection. Create it once, reuse it.
const client = new shop.CatalogService("localhost:50051", grpc.credentials.createInsecure());

// grpc-js uses callbacks; wrap the call in a Promise so we can await it.
function getProduct(id) {
  return new Promise((resolve, reject) => {
    const deadline = Date.now() + 1000; // ← an absolute time, not a duration
    client.getProduct({ id }, { deadline }, (err, res) => (err ? reject(err) : resolve(res)));
  });
}

const res = await getProduct(7);
console.log(res.product.name, res.product.priceCents); // Go Book 1999

try {
  await getProduct(42);
} catch (err) {
  console.log(err.code === grpc.status.NOT_FOUND, err.details); // true product 42 not found
}
client.close();

HTTP/2 underneath, and the four call types

HTTP/2 in two minutes

gRPC doesn't invent its own network protocol. It runs on top of HTTP/2. The HTTP topic covers HTTP/2 properly; here's the part you need.

With HTTP/1.1, one connection carries one request at a time. A second request has to wait, or open another connection. HTTP/2 instead cuts every request and response into small framesFrame (HTTP/2, HTTP/3)The smallest unit sent on an HTTP/2 connection: a 9-byte header (length, type, flags, stream ID) followed by a payload. HEADERS frames carry headers, DATA frames carry body bytes.. Each frame is labelled with a streamStream (HTTP/2, HTTP/3)One request/response exchange inside a shared connection, identified by a number (stream ID). Every frame carries its stream ID, so the receiver can sort interleaved frames back into separate responses. number, and frames from many streams are interleaved on one connection (MultiplexingMultiplexingSending several independent conversations over one shared channel at the same time, by cutting them into small labelled pieces and interleaving them. HTTP/2 multiplexes many requests over one TCP connection.).

Here's that picture moving. Three calls share one connection; their frames are interleaved on the way in and sorted back into separate calls on the other side. Cancel one and see what happens to the others:

Cancelling sends an RST_STREAMRST_STREAMAn HTTP/2 frame meaning "abandon stream #N". Only that one call stops; the connection and every other stream on it carry on. frame for that one stream number. That's how a cancelled ctx (§08) stops a single call without disturbing anything else on the connection.

What one call looks like on the wire

We pointed the Go client at a server that just prints whatever arrives. Here's the real request for GetProduct(id: 7):

POST /shop.v1.CatalogService/GetProduct      ← :path = /<package>.<Service>/<Method>
content-type: application/grpc
te: trailers                                 ← "I can handle trailers" (required by gRPC)
grpc-timeout: 999042u                        ← the deadline: 999,042 µs left (§08)
authorization: Bearer secret                 ← your metadata (§10)
user-agent: grpc-go/1.85.0

body: 00 00 00 00 02 08 07

A few things stand out:

• Every call is an HTTP POST to a path built from the .proto names. HTTP/2 has no separate "first line" like HTTP/1.1's POST /path HTTP/1.1; it sends the method and path as special headers named :method and :path (pseudo-headersPseudo-header (HTTP/2)A special HTTP/2 header whose name starts with a colon — :method, :path, :status — carrying what HTTP/1.1 put in its first line ("POST /path" or "200 OK").). The capture tool printed them as a familiar first line.
• MetadataMetadata (gRPC)Key–value pairs sent with a call, outside the message itself — gRPC's name for HTTP headers. Used for auth tokens, request IDs and tracing info. is just HTTP headers. Anything you attach in code shows up here as a header.
• The body isn't one bare protobuf message. Each message gets a 5-byte prefix:

The response comes back on the same stream: headers (:status 200), the response message(s) with the same 5-byte prefix, and finally trailersTrailersHTTP headers sent after the body instead of before it. gRPC puts the call's final status (grpc-status, grpc-message) in trailers, because a stream only knows how it ended once it has ended., headers sent after the body:

grpc-status: 5
grpc-message: product 42 not found

Four ways to call

Since a stream can carry any number of messages, gRPC lets each direction be either "one message" or "a stream of messages". You choose per RPC by writing the word stream in the .proto file:

service CatalogService {
  rpc GetProduct(GetProductRequest) returns (GetProductResponse);                   // unary
  rpc ListProducts(ListProductsRequest) returns (stream ListProductsResponse);      // server streaming
  rpc UpdateStock(stream UpdateStockRequest) returns (UpdateStockResponse);         // client streaming
  rpc WatchPrices(stream WatchPricesRequest) returns (stream WatchPricesResponse);  // bidirectional
}

// The new messages used below (Product, Category and GetProduct… are from §03):
message ListProductsRequest  { Category category = 1; }       // CATEGORY_UNSPECIFIED = all
message ListProductsResponse { Product product = 1; }
message UpdateStockRequest   { int64 product_id = 1; int32 delta = 2; } // +5 arrived, -1 sold
message UpdateStockResponse  { int32 updates_applied = 1; }
message WatchPricesRequest   { int64 product_id = 1; }
message WatchPricesResponse  { int64 product_id = 1; int64 price_cents = 2; }

Watch each one on the wire. Blue = headers, purple = messages, green = trailers. When a side marks its last frame with END_STREAM, that's a half-closeHalf-closeTelling the other side "I'm done sending" while still listening for its replies. In gRPC the client half-closes with CloseSend (Go) or end() (JS); on the wire it's the END_STREAM flag.: "I'm done sending, but I'm still listening."

resp, err := client.GetProduct(ctx, &shopv1.GetProductRequest{Id: 7})

The streaming server, in Go

Streaming handlers don't take a request and return a response. Instead they get a stream object to Send and Recv on:

// Server streaming: one request in, Send as many responses as you like.
func (s *catalogServer) ListProducts(req *shopv1.ListProductsRequest,
    stream grpc.ServerStreamingServer[shopv1.ListProductsResponse]) error {
    for _, p := range s.products {
        if err := stream.Send(&shopv1.ListProductsResponse{Product: p}); err != nil {
            return err // the client went away
        }
    }
    return nil // returning ends the stream; status OK goes in the trailers
}

// Client streaming: Recv until io.EOF, then answer once.
func (s *catalogServer) UpdateStock(stream grpc.ClientStreamingServer[shopv1.UpdateStockRequest, shopv1.UpdateStockResponse]) error {
    var n int32
    for {
        _, err := stream.Recv()
        if errors.Is(err, io.EOF) { // the client half-closed: no more messages
            return stream.SendAndClose(&shopv1.UpdateStockResponse{UpdatesApplied: n})
        }
        if err != nil {
            return err
        }
        n++
    }
}

// Bidirectional: Recv and Send independently, in any order.
func (s *catalogServer) WatchPrices(stream grpc.BidiStreamingServer[shopv1.WatchPricesRequest, shopv1.WatchPricesResponse]) error {
    for {
        req, err := stream.Recv()
        if errors.Is(err, io.EOF) {
            return nil
        }
        if err != nil {
            return err
        }
        p := s.products[req.GetProductId()]
        if err := stream.Send(&shopv1.WatchPricesResponse{
            ProductId: req.GetProductId(), PriceCents: p.GetPriceCents(),
        }); err != nil {
            return err
        }
    }
}

Streaming clients, Go and Node

Reading a server stream looks the same in both languages: loop until the stream ends.

stream, err := client.ListProducts(ctx, &shopv1.ListProductsRequest{})
if err != nil {
    return err
}
for {
    msg, err := stream.Recv()
    if errors.Is(err, io.EOF) {
        break // server finished: trailers said OK
    }
    if err != nil {
        return err // a real failure, with a status code
    }
    fmt.Println("listed:", msg.GetProduct().GetName())
}

For a client stream, send several messages, then half-close and wait for the single answer:

up, err := client.UpdateStock(ctx)
if err != nil {
    return err
}
for _, d := range []int32{5, -1, -2} {
    if err := up.Send(&shopv1.UpdateStockRequest{ProductId: 7, Delta: d}); err != nil {
        return err
    }
}
sum, err := up.CloseAndRecv() // half-close + wait for the one response
if err != nil {
    return err
}
fmt.Println("applied:", sum.GetUpdatesApplied()) // applied: 3

For bidirectional streams, sending and receiving must run at the same time. In Go that means a second goroutine; in Node, an event listener:

w, err := client.WatchPrices(ctx)
if err != nil {
    return err
}
go func() { // send in the background…
    for _, id := range []int64{7, 8} {
        if err := w.Send(&shopv1.WatchPricesRequest{ProductId: id}); err != nil {
            return // the stream broke; the Recv loop below will report the real error
        }
    }
    w.CloseSend() // half-close: no more watch requests
}()
for { // …while receiving here
    pc, err := w.Recv()
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return err
    }
    fmt.Println("price:", pc.GetProductId(), pc.GetPriceCents())
}

Deadlines and cancellation across services

Timeout vs deadline

A TimeoutTimeoutA limit on how long to wait for something (a connection, a response) before giving up with an error, so a slow or dead peer can't hang your program forever. is a duration: "wait at most 2 seconds for this step". A deadlineDeadlineA point in time ("by 12:00:01.500") after which a call is abandoned. Unlike a per-step timeout, one deadline is shared by every step and every service working on the same request. is a moment in time: "this whole request must be done by 12:00:01.000". The difference matters as soon as a request passes through several services.

Here's a worked example. A user's app allows 1 second for "show me my order". The gateway spends 200 ms on its own work, then calls orders. Orders spends 300 ms, then calls inventory. If each service set its own fresh 1-second timeout, the total could reach 200 + 300 + 1,000 ms = 1.5 s. The app would have given up at 1.0 s, and the last half second of work would be thrown away. With one shared deadline, each service only gets what's left: orders gets about 800 ms, and inventory about 500 ms.

gRPC carries the deadline for you

You saw this header in §07:

grpc-timeout: 999042u     ← "999,042 microseconds left"

When you call with a ctx that has a deadline, the client converts the remaining time into the grpc-timeout header. The server turns that header back into a deadline on the handler's ctx. If the handler passes that same ctx to its own outgoing calls, the next hop gets a grpc-timeout with whatever time is left, and so on down the chain. That's Deadline propagationDeadline propagationPassing the caller's remaining time along with each call to the next service, so the whole chain gives up together. gRPC sends it in the grpc-timeout header; Go servers turn it back into the handler's ctx..

We measured it with three real Go services and a 1-second client deadline:

gateway:   999ms left
orders:    798ms left      ← gateway used ~200 ms
inventory: 497ms left      ← orders used ~300 ms
client:    rpc error: code = DeadlineExceeded desc = context deadline exceeded
inventory stopped: context canceled

Now try it yourself. Press Send request with the default settings (inventory takes 1500 ms, so it can't fit in the budget). Then flip the toggle to context.Background() per hop and send again, to see what happens when services break the chain:

In code: pass ctx along, always

The rule is short: use the ctx you were given. Don't start a fresh one with context.Background() inside a handler.

func (s *checkoutServer) Checkout(ctx context.Context, req *shopv1.CheckoutRequest) (*shopv1.CheckoutResponse, error) {
    // A brand-new context: forgets the caller's deadline
    // AND won't be cancelled when the caller gives up.
    c, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    resp, err := s.catalog.GetProduct(c, &shopv1.GetProductRequest{Id: req.GetProductId()})
    // …
}

func (s *checkoutServer) Checkout(ctx context.Context, req *shopv1.CheckoutRequest) (*shopv1.CheckoutResponse, error) {
    // ctx already carries the caller's deadline (gRPC read it from grpc-timeout).
    if dl, ok := ctx.Deadline(); ok && time.Until(dl) < 50*time.Millisecond {
        return nil, status.Error(codes.DeadlineExceeded, "not enough time left to try") // fail fast
    }
    resp, err := s.catalog.GetProduct(ctx, &shopv1.GetProductRequest{Id: req.GetProductId()}) // ← pass ctx on
    if err != nil {
        return nil, err
    }
    total := resp.GetProduct().GetPriceCents() * int64(req.GetQuantity())
    return &shopv1.CheckoutResponse{TotalCents: total}, nil
}

You can still tighten the budget for one step. context.WithTimeout(ctx, 200*time.Millisecond) gives a deadline of "200 ms from now or the parent's deadline, whichever comes first". A child context can never outlive its parent, so wrapping the incoming ctx is always safe. Only context.Background() cuts the chain.

Cancellation travels too

A deadline isn't the only way a call ends early. The client might give up: the user closed the page, or another call in a group already failed. When a Go client's ctx is cancelled, gRPC tells the server by sending an RST_STREAMRST_STREAMAn HTTP/2 frame meaning "abandon stream #N". Only that one call stops; the connection and every other stream on it carry on. frame: "abandon stream #N" (you saw it in the multiplexing widget in §07). The server's handler ctx is then cancelled, and so is everything that handler passed that ctx to.

That only helps if your code listens. gRPC calls and well-behaved libraries (database drivers, http.NewRequestWithContext) watch ctx.Done() already. Your own long loops should check it too:

for _, id := range ids {
    if err := ctx.Err(); err != nil { // the caller gave up → stop now
        return status.FromContextError(err).Err() // context error → DEADLINE_EXCEEDED or CANCELLED
    }
    // … expensive work for id …
}

In Node: deadlines are absolute, and parent propagates

In grpc-js you pass deadline as a point in time (§06). To propagate the deadline from inside a Node server handler, pass the incoming call as parent:

server.addService(shop.CheckoutService.service, {
  checkout(call, callback) {
    // call.getDeadline() is the caller's deadline; { parent: call } passes it on,
    // and cancels this downstream call if our caller cancels.
    catalog.getProduct({ id: call.request.productId }, { parent: call }, (err, res) => {
      if (err) return callback(err);
      callback(null, { totalCents: res.product.priceCents * call.request.quantity });
    });
  },
});

We tested this against the Go server: with a 300 ms client deadline, the downstream call ended after about 292 ms with Cancelled by parent call, and the Go server logged context canceled.

Status codes, error details and retries

The codes, with their HTTP cousins

A gRPC status codegRPC status codeOne of 17 standard outcomes every gRPC call ends with: OK (0), CANCELLED, INVALID_ARGUMENT, DEADLINE_EXCEEDED, NOT_FOUND, PERMISSION_DENIED, UNAVAILABLE, INTERNAL and so on. Go uses codes.NotFound; JS uses grpc.status.NOT_FOUND. plays the same role as an HTTP status codeHTTP status codeThe 3-digit number at the start of every HTTP response: 2xx = success (200 OK), 3xx = go elsewhere (301), 4xx = your request was wrong (404 Not Found, 429 Too Many Requests), 5xx = the server failed (500, 503).: a short, standard answer to "how did it go?". gRPC's list is smaller and sharper. Here are the ones you'll actually use:

(The other three are UNKNOWN (2), OUT_OF_RANGE (11) and DATA_LOSS (15).)

Returning and reading errors

import (
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

// Server: return a status error instead of a plain error.
return nil, status.Errorf(codes.NotFound, "product %d not found", id)

// Client: get the code back out.
resp, err := client.GetProduct(ctx, req)
if err != nil {
    switch status.Code(err) {        // codes.OK if err is nil
    case codes.NotFound:
        return showEmptyState()
    case codes.DeadlineExceeded, codes.Unavailable:
        return showTryAgain()
    default:
        return err
    }
}

// Or get code + message together:
if st, ok := status.FromError(err); ok {
    log.Println(st.Code(), st.Message()) // NotFound product 42 not found
}

Rich error details

Sometimes a code and a sentence aren't enough. A form with five bad fields wants to know which five. gRPC lets you attach typed protobuf messages to an error. Google publishes standard ones in the errdetails package (BadRequest, RetryInfo, QuotaFailure, …):

import "google.golang.org/genproto/googleapis/rpc/errdetails"

// Server
// WithDetails only fails if a detail can't be encoded — not a worry with these standard types.
st, _ := status.New(codes.InvalidArgument, "bad request").WithDetails(&errdetails.BadRequest{
    FieldViolations: []*errdetails.BadRequest_FieldViolation{
        {Field: "id", Description: "must be > 0"},
    },
})
return nil, st.Err()

// Client
for _, d := range status.Convert(err).Details() {
    if br, ok := d.(*errdetails.BadRequest); ok {
        for _, v := range br.GetFieldViolations() {
            fmt.Println("bad field:", v.GetField(), v.GetDescription()) // bad field: id must be > 0
        }
    }
}

Retries: let gRPC do it, carefully

Networks drop connections and servers restart, so some calls fail for reasons that a second attempt fixes. The retry rules from Async / Await → Retry with backoff and jitter apply unchanged: back off exponentially, add JitterJitterA small random amount added to a delay or timer — a retry wait, a reconnect, a connection's maximum age — so that many clients don't all act at the same instant and stampede a server., and cap the total. With gRPC, you usually don't write that loop yourself. You declare a retry policy in the Service configService configA JSON document that tells a gRPC client how to call a service: load-balancing policy, default timeouts, and the retry policy. Set in code, or delivered through DNS or a control plane., and the client library runs it for every matching call:

const serviceConfig = `{
  "methodConfig": [{
    "name": [{ "service": "shop.v1.CatalogService" }],
    "retryPolicy": {
      "maxAttempts": 4,
      "initialBackoff": "0.1s",
      "maxBackoff": "1s",
      "backoffMultiplier": 2,
      "retryableStatusCodes": ["UNAVAILABLE"]
    }
  }],
  "retryThrottling": { "maxTokens": 10, "tokenRatio": 0.1 }
}`

conn, err := grpc.NewClient(target,
    grpc.WithTransportCredentials(insecure.NewCredentials()), // local demo; use TLS in production (§11)
    grpc.WithDefaultServiceConfig(serviceConfig))

We ran this against a server that answers UNAVAILABLE twice and then succeeds. The client's call simply returned the product, and the server logged 3 attempts. grpc-js (1.14) accepts the same JSON through the channel option "grpc.service_config".

Interceptors: middleware for RPCs

If you've read Structural patterns → HTTP middleware, this is the same idea with a different function signature. An interceptor gets the request and a handler function (the "rest of the chain"). It can do something before, call handler, do something after, or refuse to call it at all.

Two server interceptors: logging and auth

// Logging: runs around every unary call.
func logging(ctx context.Context, req any, info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler) (any, error) {
    start := time.Now()
    resp, err := handler(ctx, req) // ← call the next layer (eventually, your method)
    slog.Info("rpc", "method", info.FullMethod, "code", status.Code(err), "took", time.Since(start))
    return resp, err
}

// Auth: checks a token in the metadata, and stops the call if it's wrong.
func auth(ctx context.Context, req any, info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler) (any, error) {
    md, _ := metadata.FromIncomingContext(ctx)
    if vals := md.Get("authorization"); len(vals) == 0 || vals[0] != "Bearer secret" {
        return nil, status.Error(codes.Unauthenticated, "missing or bad token") // handler never runs
    }
    return handler(ctx, req)
}

s := grpc.NewServer(grpc.ChainUnaryInterceptor(logging, auth)) // first listed = outermost

Running the client from §06 against this server logs:

INFO rpc method=/shop.v1.CatalogService/GetProduct code=OK took=9.211µs
INFO rpc method=/shop.v1.CatalogService/GetProduct code=NotFound took=34.427µs
INFO rpc method=/shop.v1.CatalogService/GetProduct code=Unauthenticated took=4.709µs

Order matters. ChainUnaryInterceptor(logging, auth) makes logging the outer layer. So the rejected call above still got logged, with its Unauthenticated code and how long it took. Swap the order, and rejected calls would vanish from your logs.

Streaming RPCs use a second kind, grpc.StreamServerInterceptor, installed with grpc.ChainStreamInterceptor(…). It wraps the whole stream instead of one request/response pair. A unary interceptor does nothing for streaming methods, so if you write auth, write both. The stream version has a different signature, but the same idea:

func authStream(srv any, ss grpc.ServerStream, info *grpc.StreamServerInfo,
    handler grpc.StreamHandler) error {
    md, _ := metadata.FromIncomingContext(ss.Context()) // a stream's ctx comes from ss.Context()
    if vals := md.Get("authorization"); len(vals) == 0 || vals[0] != "Bearer secret" {
        return status.Error(codes.Unauthenticated, "missing or bad token") // the stream never starts
    }
    return handler(srv, ss)
}

s := grpc.NewServer(
    grpc.ChainUnaryInterceptor(logging, auth),
    grpc.ChainStreamInterceptor(authStream),
)

We tested it: ListProducts without a token now fails with Unauthenticated, and with the token it streams as before. It also caught us out once more. Server reflection (§11) is a streaming service, so grpcurl … list failed with Unauthenticated too. Exempt /grpc.reflection. methods as well as the health check (see the warning below), or serve them only on an internal port.

Sending metadata from the client

The client attaches metadata to the outgoing ctx:

ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer secret")
resp, err := client.GetProduct(ctx, req) // sent as an HTTP/2 header

Clients can have interceptors too. Use them to add the token to every call, record client-side LatencyLatencyHow long one request or job takes from the moment it arrives until it's finished — including any time spent waiting in a queue., or start a tracing spanTracing / spanDistributed tracing records the path of one request through your code and services. Each timed step (one middleware, one DB query) is a span, so you can see where the time went.. Here's the Node version (tested against our Go server):

const authInterceptor = (options, nextCall) =>
  new grpc.InterceptingCall(nextCall(options), {
    start(metadata, listener, next) {
      metadata.set("authorization", "Bearer secret"); // added to every call
      next(metadata, listener);
    },
  });

const client = new shop.CatalogService("localhost:50051", grpc.credentials.createInsecure(),
  { interceptors: [authInterceptor] });

In Go, the equivalent is grpc.WithChainUnaryInterceptor(…) on NewClient. For auth tokens specifically there's a purpose-built option, grpc.WithPerRPCCredentials(…). Its credentials can insist on an encrypted connection (the standard OAuth ones do), so a token is never sent in plain text by accident.

Running gRPC in production

1 · Load balancing: the connection is the problem

A Load balancerLoad balancerA component that spreads incoming requests or connections across several servers, so no single one is overloaded and a dead one can be skipped. spreads work across servers. The classic, cheap kind is a Layer 4 (L4) balancerLayer 4 (L4) load balancerA load balancer that works at the TCP/UDP level. It only sees IP addresses and ports, picks a backend once per connection, and copies bytes back and forth without understanding them. Examples: AWS NLB, Linux IPVS.: it picks a backend once per TCP connection, then just copies bytes. That worked for HTTP/1.1, where clients open many short connections. But a gRPC client opens one HTTP/2 connection and sends every RPC down it for hours. So an L4 balancer sends 100% of that client's traffic to one backend, and a backend you add later gets nothing. (The Load Balancing topic covers L4 vs L7 in depth.)

There are three standard fixes. They're often combined:

The simplest client-side setup in Go is DNS plus round_robin. In KubernetesKubernetesA system that runs your containers across many machines: it decides where each one runs, restarts them when they crash, rolls out new versions, and gives each group a stable name other services can call., point it at a headless serviceHeadless Service (Kubernetes)A Kubernetes Service with no virtual IP (clusterIP: None). Its DNS name returns the IPs of every ready pod directly, so the client chooses which one to call., whose DNS name returns every podPod (Kubernetes)The unit Kubernetes runs and restarts: one or a few containers that live and die together. Stopping a pod is how Kubernetes stops your process during a deploy.'s address instead of one shared virtual address:

conn, err := grpc.NewClient("dns:///catalog.shop.svc.cluster.local:50051",
    grpc.WithTransportCredentials(creds), // TLS credentials: see part 4 below
    grpc.WithDefaultServiceConfig(`{"loadBalancingConfig": [{"round_robin": {}}]}`))

2 · Keepalive: noticing dead connections

A long-lived connection can die silently. A NATNATNetwork Address Translation: a router rewrites private addresses (like 192.168.1.20) to its one public address on the way out, and back on the way in. Why your laptop isn't directly reachable from the internet. router or FirewallFirewallA filter that allows or blocks network traffic by rules — e.g. “only port 443 from the internet”. in between forgets it after a few idle minutes, or a server machine disappears without closing anything. The client only finds out when a request times out. HTTP/2 keepalive pingsKeepalive ping (HTTP/2)A tiny PING frame sent on an idle connection to check the other side is still there, so a silently dead connection is noticed in seconds instead of minutes. Servers limit how often clients may ping. detect this early. Servers enforce a minimum ping interval, so the two sides must agree:

// Server
grpc.NewServer(
    grpc.KeepaliveParams(keepalive.ServerParameters{
        MaxConnectionAge:      5 * time.Minute,  // re-balance (fix 3 above)
        MaxConnectionAgeGrace: 30 * time.Second, // let in-flight calls finish first
    }),
    grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
        MinTime:             10 * time.Second, // clients may ping at most every 10 s
        PermitWithoutStream: true,
    }),
)

// Client
grpc.WithKeepaliveParams(keepalive.ClientParameters{
    Time:                30 * time.Second, // ping after 30 s of silence
    Timeout:             10 * time.Second, // no answer in 10 s → treat the connection as dead
    PermitWithoutStream: true,
})

3 · Message size limits

By default a grpc-go server and client refuse to receive any message larger than 4 MiB (4 × 1,048,576 = 4,194,304 bytes; a MiB is 1,024 × 1,024 bytes). We sent a 5 MiB response and got:

rpc error: code = ResourceExhausted desc = grpc: received message larger than max (5242890 vs. 4194304)

You can raise the limit (grpc.MaxRecvMsgSize(…) on the server, grpc.MaxCallRecvMsgSize(…) per call on the client). But usually the error is telling you something. A whole message is held in memory, on both sides, before your code sees any of it. For big results, stream them in pages (§07). For files, stream chunks of ~64 KB, or upload to object storageObject storageA service for storing big files by name, like Amazon S3 or Google Cloud Storage. Programs upload and download whole files over HTTP instead of sending them through their own APIs. and pass a URL.

4 · Encryption and identity: TLS and mTLS

Between machines, always use TLSTLSTransport Layer Security: the encryption layer that makes HTTPS secure. It proves the server is who it claims to be and scrambles everything so nobody in between can read or change it.. Inside a company it's common to go further with mutual TLSmTLS (mutual TLS)TLS where both sides show a certificate: the server proves who it is to the client, and the client proves who it is to the server. Common for service-to-service calls inside a company.: the client also presents a CertificateCertificate (TLS)A small signed file that says “this public key belongs to example.com”, vouched for by a trusted certificate authority. Browsers check it so they know they're talking to the real site., so the server knows which service is calling. The TLS topic explains certificates and handshakes. In gRPC it's a few lines of config. Every service's certificate is signed by your company's own certificate authority (CA)Certificate authority (CA)An organization trusted to check that you really control a domain and then sign a certificate saying so. Let's Encrypt, DigiCert and Google Trust Services are CAs. Companies also run private CAs for internal services., and each side trusts certificates signed by it:

cert, err := tls.LoadX509KeyPair("server.crt", "server.key") // this server's certificate + private key
// … handle err …
caPEM, err := os.ReadFile("ca.crt") // the company CA (certificate authority) that signs every service's certificate
// … handle err …
pool := x509.NewCertPool()
if !pool.AppendCertsFromPEM(caPEM) { // false = no valid certificate in the file
    log.Fatal("ca.crt: no certificates found")
}

creds := credentials.NewTLS(&tls.Config{
    Certificates: []tls.Certificate{cert},
    ClientCAs:    pool,
    ClientAuth:   tls.RequireAndVerifyClientCert, // ← the "m" in mTLS: clients must show a cert too
    MinVersion:   tls.VersionTLS13,
})
s := grpc.NewServer(grpc.Creds(creds))
// Client side: grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{
//     Certificates: []tls.Certificate{clientCert}, RootCAs: pool }))

In a service mesh, the sidecars usually do mTLS for you, and your app speaks plain gRPC to its local sidecar.

5 · Browsers: gRPC-Web and Connect

Browser JavaScript can't read HTTP/2 trailers, and gRPC puts its status there (§07). So browsers can't speak gRPC directly. There are two common answers:

• gRPC-WebgRPC-WebA variant of the gRPC protocol that browsers can use (browsers can't read HTTP/2 trailers from JavaScript). Usually needs a proxy such as Envoy to translate to real gRPC.: a browser-friendly variant that moves the trailers into the body. Usually a proxy (Envoy) translates it to real gRPC for your servers.
• ConnectConnect (protocol)A protocol and set of libraries from the makers of buf that serve the same .proto services over plain HTTP — JSON or binary — so browsers and curl can call them, while also speaking gRPC and gRPC-Web.: libraries (Go, TypeScript and more) whose servers speak gRPC, gRPC-Web and a simple HTTP+JSON protocol on the same port. From the browser you can fetch a method with a JSON body, no proxy needed, while your backend services still use gRPC with each other.

Either way, the .proto file stays the single source of truth.

6 · Debugging: reflection and grpcurl

Protobuf bytes are unreadable without the schema (§04), so curl is no help. grpcurl is curl for gRPC. It needs the .proto files, or a server with server reflectionServer reflectionAn optional built-in gRPC service that answers "which services and messages do you have?", so debugging tools like grpcurl can call your server without a copy of the .proto files. turned on (reflection.Register(s) in Go). Real output from our server:

$ grpcurl -plaintext localhost:50051 list
grpc.health.v1.Health
grpc.reflection.v1.ServerReflection
grpc.reflection.v1alpha.ServerReflection
shop.v1.CatalogService

$ grpcurl -plaintext -H 'authorization: Bearer secret' -d '{"id": 7}' \
    localhost:50051 shop.v1.CatalogService/GetProduct
{
  "product": {
    "id": "7",
    "name": "Go Book",
    "priceCents": "1999",
    "tags": ["go", "book"],
    "category": "CATEGORY_BOOKS"
  }
}

grpcurl shows messages in the protobuf JSON mappingProtobuf JSON mappingAn official way to write any protobuf message as JSON (field names become lowerCamelCase keys). Used by tools like grpcurl and by HTTP/JSON gateways. Unlike the binary format, it does depend on field names., which is why the int64 values appear as strings ("7"). -plaintext means no TLS, and -d is the request as JSON. Many teams enable reflection only on internal ports, since it hands your whole API description to anyone who can connect. For a GUI, Postman and similar tools speak gRPC too.

7 · Health checking

Load balancers and Kubernetes need to ask "can you take traffic?". gRPC has a standard answer, the gRPC health checking protocolgRPC health checking protocolA standard service (grpc.health.v1.Health) with a Check method that returns SERVING or NOT_SERVING. Load balancers and Kubernetes call it to decide whether to send traffic., and grpc-go ships an implementation:

hs := health.NewServer()
healthpb.RegisterHealthServer(s, hs)
hs.SetServingStatus("shop.v1.CatalogService", healthpb.HealthCheckResponse_SERVING)
// during shutdown: hs.Shutdown() → reports NOT_SERVING, so balancers drain you first

Kubernetes can probe it natively (a grpc: probe, in Kubernetes 1.24+), and so can Envoy and cloud balancers. Remember the warning from §10: keep your auth interceptor away from the health service.

Pitfalls gallery

Each of these has caused real outages. Each one points back to the section that explains it.

func getProduct(id int64) (*shopv1.Product, error) {
    conn, _ := grpc.NewClient(addr, opts...) // ✕ a new connection pool per call (and the error is ignored)
    defer conn.Close()
    // …
}

Check yourself

Predict the answer before you click. Each question names the section that covers it: Q1 and Q6 come from §03–§04, Q2 from §05, Q3 from §08, Q4 from §09, and Q5 from §11.

message Item { int64 id = 1; }
// Encode Item{id: 150}. 150 in binary is 1001 0110.

// v1:  int64 price_cents = 3;
// v2:  (price_cents deleted)  int64 stock_count = 3;
// A v2 server sends stock_count = 42 to a v1 app.

// client: ctx with a 1 s timeout → gateway.
// gateway handler:
func (s *gw) GetOrder(ctx context.Context, r *Req) (*Resp, error) {
    c, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    return s.inventory.Check(c, r) // inventory needs 3 s today
}

// 1 client app, 1 gRPC connection, 1,000 RPC/s
//   → L4 (TCP) load balancer → backends A, B, C
// You add backend D.

b, _ := proto.Marshal(&shopv1.Product{
    Id: 0, Name: "", PriceCents: 0,
})
fmt.Println(len(b))

Cheat sheet