Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 39 ยท Streaming

gRPC Server Streaming RPCs

Learn server-streaming RPCs: define the stream in proto, send many messages from the server, read until EOF on the client, cancel early, and when to stream instead of paginate.

In a unary call, the client sends one request and gets one response. In a server-streaming call, the client sends one request and the server answers with a sequence of messages over time. The call ends when the server finishes sending and returns a status. This is a natural fit for large result sets, progress updates, live feeds and anything where the data arrives gradually.

Real gRPC code is read-only on this site (no gRPC library here). The Go stand-ins model streams with channels and with real loopback TCP, and they are runnable.

Declaring a server stream

The only change in the contract is the stream keyword before the response type:

PROTO
service Stock {
  rpc Subscribe(SubscribeRequest) returns (stream PriceUpdate);
}

message SubscribeRequest {
  repeated string symbols = 1;
}

message PriceUpdate {
  string symbol = 1;
  double price = 2;
  google.protobuf.Timestamp at = 3;
}

On the wire it is the same HTTP/2 stream as a unary call, but with multiple length-prefixed messages in the response (see how gRPC uses HTTP/2). The status arrives in the trailers after the last message.

The server side (Go, read-only)

Go
func (s *stockServer) Subscribe(req *pb.SubscribeRequest, stream pb.Stock_SubscribeServer) error {
	ctx := stream.Context()
	ticker := time.NewTicker(time.Second)
	defer ticker.Stop()

	for {
		select {
		case <-ctx.Done():
			return ctx.Err() // client went away or deadline hit
		case <-ticker.C:
			for _, sym := range req.GetSymbols() {
				update := &pb.PriceUpdate{Symbol: sym, Price: s.quote(sym)}
				if err := stream.Send(update); err != nil {
					return err // connection broke
				}
			}
		}
	}
}

Notes:

  • The handler receives the request and a stream object; it returns only an error. Returning nil ends the stream with status OK.
  • stream.Send blocks when the client is slow, because of HTTP/2 flow control (more in flow control and streaming patterns).
  • Always watch stream.Context(); an endless stream is only stopped by cancellation.
  • Do not call Send from several goroutines at once. A stream supports one concurrent sender and one concurrent receiver.

The client side (Go, read-only)

Go
stream, err := client.Subscribe(ctx, &pb.SubscribeRequest{Symbols: []string{"ACME", "INIT"}})
if err != nil {
	log.Fatal(err)
}
for {
	update, err := stream.Recv()
	if err == io.EOF {
		break // server finished normally
	}
	if err != nil {
		log.Fatal(err) // a real error status
	}
	log.Printf("%s = %.2f", update.GetSymbol(), update.GetPrice())
}

Recv returns io.EOF when the server finished with OK. Any other error carries the gRPC status. To stop early, cancel the context.

Stand-in 1: a stream built on a channel

A Go channel models a stream well: the server sends values, the client ranges over them, and closing the channel means EOF. This runnable stand-in also shows the client cancelling early.

Go Stand-in: server stream over a channel

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Stand-in 2: streaming over real TCP

This stand-in sends a stream of length-prefixed messages over loopback TCP, then closes the connection to signal the end. It reuses the framing idea from the HTTP/2 lesson. Messages are JSON, and the transport is TCP, so it is not gRPC; but the read-until-EOF loop is the same one you write against a real stream.

Go Stand-in: framed stream over loopback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

When to stream instead of paginate

Situation Better choice
Small to medium result, user clicks "next page" Paginated unary (see defining services)
Large export processed in a pipeline Server streaming
Live updates, notifications, progress Server streaming
Client may need random access to pages Pagination
Results must be consistent snapshots Streaming from one transaction, or pagination with a snapshot token

Streaming keeps one connection and one call open, so it consumes server resources for its whole life. Pagination lets the server forget the client between pages.

Error handling in streams

A stream can fail after some messages were sent. The error arrives from Recv as a status, and everything received before it is valid. Design your client to handle partial results: either use them, or restart (with a resume token, such as the last id received).

Go
if err != nil && err != io.EOF {
	st, _ := status.FromError(err)
	log.Printf("stream broke after %d messages: %s", count, st.Code())
	// reconnect with resume_after = lastID
}

Long-lived streams also face idle timeouts from proxies and load balancers; the remedies are keepalive pings and application-level heartbeats.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where does the stream keyword go for a server-streaming method?

    rpc Subscribe(Req) returns (stream Resp) means the server sends many responses.
  2. 2. What does the client get from Recv when the server finishes successfully?

    EOF means a clean end. Any other error carries a failure status.
  3. 3. How can a client stop a server stream early?

    Cancelling the context ends the call; the server sees its context cancelled.
  4. 4. Is it safe to call Send on one stream from many goroutines at once?

    Streams allow one concurrent sender and one concurrent receiver; serialize sends yourself.
  5. 5. When is pagination better than server streaming?

    Pagination is stateless between pages; streams hold a call open.

Summary

  • Server streaming: one request, many responses, declared with returns (stream T).
  • The handler loops on stream.Send, and returns an error or nil to finish.
  • Clients call Recv until io.EOF; cancel the context to stop early.
  • Check the stream context, and design for partial failure.
  • Choose streaming for feeds and exports, pagination for browsing.

Next: Client Streaming