gRPC Bidirectional Streaming Explained
On this page
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:
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
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:
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
<-doneThe lab run:
bidi received: agent: Thanks, looking into it.
bidi received: agent: Your order shipped this morning.Concurrency rules for gRPC streams
In grpc-go (and similar in other languages):
- One goroutine may call
Sendat a time, and one may callRecvat a time. Sending and receiving concurrently is fine; two goroutines sending at once is not. Funnel sends through one goroutine or a mutex. CloseSendhalf-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.