Catalog My learning Blog
gRPC and Protobuf Tutorial: Fast Microservice APIs · Phase 2 · Lesson 10 · 3 min read

gRPC Bidirectional Streaming Explained

On this page
  1. Bidirectional streaming: two independent streams
  2. Writing a bidirectional streaming server in Go
  3. The client: receiving on its own goroutine
  4. Concurrency rules for gRPC streams
  5. Designing bidirectional protocols
  6. Check yourself

Bidirectional streaming: two independent streams

In a support chat, the customer sends messages whenever they like and the agent replies whenever they like. Neither side waits for the other. Bidirectional streaming gives each side its own stream of messages over one call:

Code
rpc SupportChat(stream SupportChatRequest) returns (stream SupportChatResponse);

The two directions are independent: the server can reply to every message, batch replies, or send messages nobody asked for.

Writing a bidirectional streaming server in Go

Go
func (s *server) SupportChat(stream grpc.BidiStreamingServer[shopv1.SupportChatRequest, shopv1.SupportChatResponse]) error {
	for {
		req, err := stream.Recv()
		if errors.Is(err, io.EOF) {
			return nil                         // client finished; end the call
		}
		if err != nil {
			return err
		}
		reply := "Thanks, looking into it."
		if strings.Contains(strings.ToLower(req.GetText()), "where") {
			reply = "Your order shipped this morning."
		}
		if err := stream.Send(&shopv1.SupportChatResponse{From: "agent", Text: reply}); err != nil {
			return err
		}
	}
}

The client: receiving on its own goroutine

Because messages can arrive at any time, the client reads in a separate goroutine while the main one sends:

Code
chat, err := client.SupportChat(ctx)
if err != nil {
	return err
}
done := make(chan struct{})
go func() {
	defer close(done)
	for {
		msg, err := chat.Recv()
		if err == io.EOF {
			return
		}
		if err != nil {
			log.Println("chat ended:", status.Code(err))
			return
		}
		fmt.Printf("%s: %s\n", msg.GetFrom(), msg.GetText())
	}
}()
for _, text := range []string{"Hi, about order ord_42", "Where is it?"} {
	chat.Send(&shopv1.SupportChatRequest{Text: text})
}
chat.CloseSend()     // "I'm done sending"; still receiving
<-done

The lab run:

Code
bidi received:  agent: Thanks, looking into it.
bidi received:  agent: Your order shipped this morning.
Client and server each send and receive independently on one stream; either side can half-close its sending direction, and the call ends with a status from the server.
Client and server each send and receive independently on one stream; either side can half-close its sending direction, and the call ends with a status from the server.

Concurrency rules for gRPC streams

In grpc-go (and similar in other languages):

  • One goroutine may call Send at a time, and one may call Recv at a time. Sending and receiving concurrently is fine; two goroutines sending at once is not. Funnel sends through one goroutine or a mutex.
  • CloseSend half-closes: the client stops sending but keeps receiving until the server ends the call.
  • The server ends the call by returning from the handler; its return value becomes the status.
  • Cancel the context to abort everything immediately.

Designing bidirectional protocols

Bidirectional streams are powerful and easy to get wrong:

  • Define message types for each kind of event with a oneof (join, message, typing, ack), instead of overloading one text field.
  • Add acknowledgments and sequence numbers if delivery matters; a dropped connection loses whatever was in flight.
  • Plan reconnection and resume, as with server streams (Day 8).
  • Long-lived streams pin to one backend, so capacity, draining during deploys and keepalives need thought (Day 18).

Use bidi when both sides really need to send independently. For "send a request, get many responses", server streaming is simpler; for "upload many, get one answer", client streaming.

Check yourself

Messages can arrive at any time, independently of what the client is sending, so receiving can't wait for sends to finish.

It half-closes the client's sending direction, telling the server no more messages are coming. The client can still receive until the server ends the call with a status.

No. Only one goroutine may call Send at a time, and only one may call Recv, so concurrent senders must be serialized, for example through a channel feeding a single sender goroutine. One sender and one receiver at once is fine.

Messages with a oneof of message types and request ids, so either side can send commands, acknowledgments and events in any order.

By returning from the handler, which sends the final status in trailers. The client's Recv then returns io.EOF for OK or the error status. The client closing its send side doesn't end the call; only the server's return does.