Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 39 ยท Streaming

gRPC Bidirectional Streaming RPCs

Learn bidirectional streaming in gRPC: both sides send independently on one call. See ping-pong and fully concurrent patterns, closing rules, and a chat-room design in runnable Go stand-ins.

In bidirectional streaming both the client and the server send sequences of messages on the same call, and the two directions are independent. Either side can send whenever it likes, in any order, until it half-closes its sending side. This powers chat systems, collaborative editors, real-time games, live translation, sync protocols and long-running control channels.

The real gRPC library cannot run here, so real code is read-only. Go stand-ins with channels reproduce the patterns, and they are runnable.

The contract

stream appears on both sides:

PROTO
service Chat {
  rpc Join(stream ChatMessage) returns (stream ChatMessage);
}

message ChatMessage {
  string user = 1;
  string text = 2;
}

On the HTTP/2 stream, requests and responses travel as two independent flows of length-prefixed messages (see how gRPC uses HTTP/2). The server's trailing status ends the call.

Two patterns

  1. Ping-pong. One side sends, the other answers, strictly in turn. Easy to reason about, effectively a request-response loop inside a single call, and it avoids per-call setup costs.
  2. Fully concurrent. Both sides send at will. The receive loop and the send loop run in separate goroutines. This is what chat and real-time sync need.

The order of messages within one direction is preserved. There is no ordering guarantee between directions.

The server (Go, read-only)

Go
func (s *chatServer) Join(stream pb.Chat_JoinServer) error {
	id := s.hub.add(stream)         // register for broadcasts
	defer s.hub.remove(id)

	for {
		msg, err := stream.Recv()
		if err == io.EOF {
			return nil // client closed its side
		}
		if err != nil {
			return err
		}
		s.hub.broadcast(msg) // calls Send on every connected stream
	}
}

A critical rule: Send on one stream must not be called concurrently from several goroutines. A hub that broadcasts to many streams from many handlers must give each stream its own writer goroutine and queue, or guard each stream with a mutex.

The client (Go, read-only)

Go
stream, err := client.Join(ctx)
if err != nil {
	return err
}

done := make(chan struct{})
go func() { // receive loop
	defer close(done)
	for {
		msg, err := stream.Recv()
		if err != nil { // io.EOF or a status error
			return
		}
		fmt.Printf("%s: %s\n", msg.GetUser(), msg.GetText())
	}
}()

for _, line := range lines { // send loop
	if err := stream.Send(&pb.ChatMessage{User: "ada", Text: line}); err != nil {
		break
	}
}
stream.CloseSend() // half-close: "I have nothing more to say"
<-done

CloseSend ends only the client-to-server direction. The server may still be sending, and the client keeps receiving until the server returns.

Stand-in 1: ping-pong with running totals

The client sends numbers one at a time; the server answers each with the running total. Because the exchange is strictly alternating, the output is deterministic.

Go Stand-in: ping-pong stream

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: a chat room with a hub

Here three users join a room. The hub gives each member a queue (channel) drained by a dedicated writer goroutine, so one slow listener cannot block the others and each stream has exactly one sender. Messages are collected and sorted at the end so that the output does not depend on goroutine scheduling.

Go Stand-in: chat hub with per-stream writers

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.

If a member's queue is full because the client is slow, a real hub must decide what to do: drop the member, drop old messages, or block (which stalls everyone). That decision is a design choice you make explicitly; see flow control and streaming patterns.

Termination rules

  • Either side may end its direction first. The client uses CloseSend; the server ends by returning from the handler (with nil for OK or an error status).
  • Once the server returns, the call is over. The client's Recv yields io.EOF (or the error), and further Send calls fail.
  • Cancelling the context aborts both directions immediately.
  • If the client's context deadline expires, both sides see DEADLINE_EXCEEDED.

Heartbeats and idle streams

Long-lived streams can sit silent for hours. Intermediaries such as load balancers often close idle connections after 30 to 60 seconds. Two remedies:

  1. HTTP/2 keepalive pings, configured on the client and server.
  2. Application heartbeats: a oneof member such as Heartbeat sent every N seconds, letting both sides detect a dead peer quickly.

When to avoid bidirectional streams

Streams are stateful, harder to load balance (one stream sticks to one backend for its lifetime), harder to retry and harder to observe. If your interaction is naturally request-response, unary calls are simpler and scale better. Use bidirectional streams when you need low latency in both directions or want to avoid reconnecting for each message.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does CloseSend do on the client of a bidirectional stream?

    It is a half-close: the server sees io.EOF on Recv, but may keep sending.
  2. 2. Which ordering guarantee holds on a stream?

    Each direction is an ordered sequence. The two are independent.
  3. 3. Why give each stream its own writer goroutine in a chat hub?

    One concurrent sender per stream; queues isolate slow consumers.
  4. 4. How does the server end a bidirectional call successfully?

    Returning from the handler finishes the call with the returned status; nil means OK.
  5. 5. Why send heartbeats on idle streams?

    Keepalive traffic proves the connection is alive.

Summary

  • Bidirectional streaming declares stream on both request and response; each direction is an independent ordered flow.
  • Use ping-pong for simple alternating protocols and concurrent loops for real-time systems.
  • Only one goroutine may send on a stream at a time; use per-stream queues in hubs.
  • Half-close with CloseSend; the server ends the call by returning.
  • Add heartbeats for long-lived streams and prefer unary calls when a stream is not needed.

Next: Flow Control and Streaming Patterns