Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 39 ยท Streaming

gRPC Client Streaming RPCs

Learn client-streaming RPCs: the client sends many messages and receives one reply. Build chunked file uploads with checksums, with real code read-only and runnable Go stand-ins.

A client-streaming call reverses the server-streaming shape: the client sends a sequence of messages and the server replies with one response after the client finishes sending. Typical uses are uploading a large file in chunks, sending a batch of telemetry points, or feeding a calculation that produces a single result.

The real gRPC library cannot run on this site, so real code is read-only. The Go stand-ins are runnable and reproduce the control flow with channels and the standard library.

The contract

The stream keyword goes before the request type:

PROTO
service Files {
  rpc Upload(stream UploadChunk) returns (UploadResult);
}

message UploadChunk {
  // The first chunk carries metadata, the rest carry data.
  oneof payload {
    FileInfo info = 1;
    bytes data = 2;
  }
}

message FileInfo {
  string name = 1;
  string content_type = 2;
}

message UploadResult {
  int64 size_bytes = 1;
  string sha256 = 2;
}

The oneof (see oneof, optional and well-known types) lets the first message carry file metadata and the following ones carry bytes. This pattern is common because a stream has no separate "header" message.

The server (Go, read-only)

Go
func (s *filesServer) Upload(stream pb.Files_UploadServer) error {
	var name string
	h := sha256.New()
	var size int64

	for {
		chunk, err := stream.Recv()
		if err == io.EOF {
			// The client finished sending: answer with one message.
			return stream.SendAndClose(&pb.UploadResult{
				SizeBytes: size,
				Sha256:    hex.EncodeToString(h.Sum(nil)),
			})
		}
		if err != nil {
			return err
		}
		switch p := chunk.Payload.(type) {
		case *pb.UploadChunk_Info:
			name = p.Info.GetName()
		case *pb.UploadChunk_Data:
			if name == "" {
				return status.Error(codes.InvalidArgument, "first message must be file info")
			}
			size += int64(len(p.Data))
			h.Write(p.Data)
		}
	}
}

The server loops on Recv until io.EOF (the client called CloseAndRecv/CloseSend), then answers with SendAndClose. It may also return an error early, for example to reject a file that is too big, which tells the client to stop sending.

The client (Go, read-only)

Go
stream, err := client.Upload(ctx)
if err != nil {
	return err
}
if err := stream.Send(&pb.UploadChunk{Payload: &pb.UploadChunk_Info{Info: &pb.FileInfo{Name: "report.pdf"}}}); err != nil {
	return err
}
buf := make([]byte, 64*1024) // 64 KB chunks
for {
	n, err := f.Read(buf)
	if n > 0 {
		if serr := stream.Send(&pb.UploadChunk{Payload: &pb.UploadChunk_Data{Data: buf[:n]}}); serr != nil {
			return serr
		}
	}
	if err == io.EOF {
		break
	}
	if err != nil {
		return err
	}
}
result, err := stream.CloseAndRecv() // finish sending and wait for the one reply

Choose chunk sizes thoughtfully: 16 to 256 KB works well. Tiny chunks waste CPU on framing; chunks near the 4 MB message limit hurt flow control and memory.

Stand-in 1: chunked upload with a checksum

This runnable program chops a byte slice into chunks and "sends" them over a channel. The server side reassembles, counts bytes and computes a SHA-256, then returns one result, like SendAndClose.

Go Stand-in: chunked upload

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.

The checksum test is the point of the exercise: the reassembled stream equals the original, whatever the chunk size.

Stand-in 2: aggregation and early rejection

A client-streaming server does not have to read everything. This stand-in sums sensor readings, but rejects the stream at the first invalid value. The client discovers this when its next Send fails.

Go Stand-in: aggregate or reject early

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.

In the second run the server rejects 500. The client's next Send returns the rejection, so it stops uploading instead of pushing the rest of the data into the void.

Design considerations

  1. The reply is final. The client gets nothing until it has sent everything. For feedback during the upload, use bidirectional streaming.
  2. Resumable uploads. If a long upload dies at 90%, restarting wastes work. Return a resume offset from a separate unary method (GetUploadStatus) and let the client continue from there.
  3. Validate the first message. Make the protocol explicit: metadata first, data after. Reject streams that break the rule.
  4. Set limits. Reject streams bigger than a policy maximum; return RESOURCE_EXHAUSTED.
  5. Idempotency. Retrying a stream re-sends everything; include an upload id so the server can deduplicate.
  6. Deadlines. A big upload may need a long deadline; per-chunk timeouts are an alternative. See deadlines and cancellation.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a client-streaming RPC, how many responses does the server send?

    The server answers once, typically with SendAndClose after the client closes its sending side.
  2. 2. How does the server know the client has finished sending?

    When the client half-closes the stream, the server's Recv returns io.EOF.
  3. 3. Why does the example UploadChunk use a oneof?

    A stream has no separate header, so a oneof carries either info or data.
  4. 4. What should a server do when it wants to refuse more data mid-upload?

    Returning an error ends the call, and the client learns it on its next Send or when closing.

Summary

  • Client streaming: many requests, one response; declared with rpc X(stream Req) returns (Resp).
  • Servers loop on Recv until io.EOF, then call SendAndClose.
  • Use a oneof to carry metadata first and data afterwards.
  • Pick moderate chunk sizes, enforce limits, and plan for resumption.
  • For progress feedback during the upload, use bidirectional streaming.

Next: Bidirectional Streaming