gRPC Server Streaming Explained
On this page
Server streaming: updates without polling
A customer watches their order: paid, shipped, delivered. Polling GetOrder every few seconds wastes calls and still lags. With server streaming, the client makes one call and the server pushes each change as it happens.
rpc WatchOrder(WatchOrderRequest) returns (stream WatchOrderResponse);Writing a server-streaming handler in Go
The handler sends as many messages as it wants, then returns to end the stream:
func (s *server) WatchOrder(req *shopv1.WatchOrderRequest,
stream grpc.ServerStreamingServer[shopv1.WatchOrderResponse]) error {
for _, st := range []shopv1.Order_Status{
shopv1.Order_STATUS_PAID, shopv1.Order_STATUS_SHIPPED, shopv1.Order_STATUS_DELIVERED} {
select {
case <-stream.Context().Done(): // client cancelled or deadline passed
return status.FromContextError(stream.Context().Err()).Err()
case <-time.After(200 * time.Millisecond): // stand-in for waiting on a real event
}
if err := stream.Send(&shopv1.WatchOrderResponse{Status: st, At: timestamppb.Now()}); err != nil {
return err
}
}
return nil // ends the stream with status OK
}Run with grpcurl, the updates arrive 200 ms apart:
{"status":"STATUS_PAID","at":"2026-10-15T02:53:45.227352Z"}
{"status":"STATUS_SHIPPED","at":"2026-10-15T02:53:45.428447Z"}
{"status":"STATUS_DELIVERED","at":"2026-10-15T02:53:45.629527Z"}Reading a server stream in the client
stream, err := client.WatchOrder(ctx, &shopv1.WatchOrderRequest{OrderId: "ord_42"})
if err != nil {
return err
}
for {
update, err := stream.Recv()
if err == io.EOF {
break // server finished normally
}
if err != nil {
return err // the stream failed: check status.Code(err)
}
fmt.Println(update.GetStatus())
}Stopping a stream early with cancellation
The client stops a stream by cancelling its context. In the lab, the client read the first update and then cancelled:
stream first: STATUS_PAID
after cancel: code=CanceledThe server notices through stream.Context().Done() and stops working, which is why the handler checks it on every iteration. A handler that ignores cancellation keeps sending into a dead stream and holding resources.
Server streaming in production
- Deadlines on long streams: a 2-second deadline would cut off a stream meant to last an hour. Use long deadlines (or none) for watch-style streams, with application-level heartbeats and keepalive settings so dead connections are detected.
- Reconnection: connections drop (deploys, load balancer timeouts, mobile networks). Clients must reconnect with backoff and resume. Include a cursor or version in each message (
last_event_id) and accept it in the request, so the server can resend what was missed. - Flow control: HTTP/2 flow control slows
Sendwhen the client reads slowly, so a fast server can't overwhelm a slow client's memory. Don't buffer unbounded data on the server either. - Load balancing: one long stream stays on one backend; plan capacity per stream, and drain streams gracefully during deploys (Day 18).
Check yourself
The handler returns nil, which sends status OK in the trailers; the client's Recv then returns io.EOF. Returning an error instead ends the stream with that status.
The client may cancel or its deadline may pass; checking lets the server stop work instead of sending into a dead stream.
Reconnect with exponential backoff and jitter, and send the last event id or version it saw, so the server can replay anything missed. Without a resume point, events during the gap are lost.
Proxies, load balancers and NAT devices silently drop connections that look idle. gRPC keepalive pings keep the connection active and detect dead peers, so clients notice a broken stream and reconnect instead of waiting forever.
HTTP/2 flow control stops the server's sends once the client's window is full, so a slow reader applies backpressure instead of growing memory.