A gRPC Cheat Sheet for Go Servers Clients and Streams

syntax = "proto3";
package orders.v1;                        // the version is part of every method path
option go_package = "example.test/gen/orders/v1;ordersv1";

service OrderService {
  rpc Get(GetRequest) returns (Order);                       // unary
  rpc List(ListRequest) returns (stream Order);              // server streaming
  rpc Upload(stream Chunk) returns (Summary);                // client streaming
  rpc Chat(stream Message) returns (stream Message);         // bidirectional
}

protoc -I proto \
  --go_out=. --go_opt=paths=source_relative \
  --go-grpc_out=. --go-grpc_opt=paths=source_relative \
  proto/orders/v1/orders.proto

type server struct{ pb.UnimplementedOrderServiceServer }   // always embed

func (s *server) Get(ctx context.Context, r *pb.GetRequest) (*pb.Order, error) {
	if r.GetId() == "" {
		return nil, status.Error(codes.InvalidArgument, "id is required")
	}
	return &pb.Order{Id: r.GetId()}, nil
}

lis, _ := net.Listen("tcp", ":50051")
srv := grpc.NewServer(
	grpc.ChainUnaryInterceptor(logging, recovery, auth),
	grpc.ChainStreamInterceptor(streamLogging, streamRecovery, streamAuth), // both, always
	grpc.Creds(credentials.NewTLS(tlsConfig)),
	grpc.KeepaliveParams(keepalive.ServerParameters{MaxConnectionAge: 30 * time.Minute, MaxConnectionAgeGrace: 30 * time.Second}),
	grpc.MaxRecvMsgSize(8<<20),
)
pb.RegisterOrderServiceServer(srv, &server{})
healthpb.RegisterHealthServer(srv, hs)
srv.Serve(lis)

conn, err := grpc.NewClient("dns:///orders.internal:50051",
	grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)),
	grpc.WithDefaultServiceConfig(`{"loadBalancingConfig":[{"round_robin":{}}]}`),
	grpc.WithChainUnaryInterceptor(withDeadline(5*time.Second), propagateRequestID),
)
defer conn.Close()                         // one per target, for the life of the process
c := pb.NewOrderServiceClient(conn)

ctx, cancel := context.WithTimeout(ctx, 2*time.Second)   // every call has a deadline
defer cancel()
o, err := c.Get(ctx, &pb.GetRequest{Id: "o1"})

// server streaming, client side
stream, _ := c.List(ctx, &pb.ListRequest{})
for {
	o, err := stream.Recv()
	if errors.Is(err, io.EOF) { break }          // clean end
	if err != nil { return err }                 // a real failure
	use(o)
}

// server streaming, server side
for _, o := range items {
	if err := stream.Send(o); err != nil { return err }   // client gone or deadline passed
}

// client streaming
up, _ := c.Upload(ctx)
for _, ch := range chunks { up.Send(ch) }
sum, err := up.CloseAndRecv()

// bidirectional: send and receive on separate goroutines, CloseSend() when done sending

st := status.New(codes.InvalidArgument, "the request is invalid")
st, _ = st.WithDetails(&errdetails.BadRequest{FieldViolations: violations})
return nil, st.Err()
// client
code := status.Code(err); st := status.Convert(err); details := st.Details()

ctx = metadata.AppendToOutgoingContext(ctx, "x-request-id", id)          // client to server
md, _ := metadata.FromIncomingContext(ctx)                               // in a handler
grpc.SetHeader(ctx, metadata.Pairs("k", "v")); grpc.SetTrailer(ctx, md)  // server to client
c.Get(ctx, req, grpc.Header(&hdr), grpc.Trailer(&trl))                   // client reads them

ctx, cancel := context.WithTimeout(parent, 2*time.Second)       // pass the handler's ctx down: the budget shrinks

{"methodConfig":[{"name":[{"service":"orders.v1.OrderService"}],
  "retryPolicy":{"maxAttempts":3,"initialBackoff":"0.1s","maxBackoff":"1s","backoffMultiplier":2,
                 "retryableStatusCodes":["UNAVAILABLE"]}}],
 "retryThrottling":{"maxTokens":10,"tokenRatio":0.1}}

hs.Shutdown()                       // NOT_SERVING: balancers stop sending
time.Sleep(drain)                   // let that propagate
go func() { srv.GracefulStop(); close(done) }()
select { case <-done: case <-time.After(budget): srv.Stop() }

lis := bufconn.Listen(1 << 20)                       // in-memory listener
conn, _ := grpc.NewClient("passthrough:///bufnet",
	grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) { return lis.DialContext(ctx) }),
	grpc.WithTransportCredentials(insecure.NewCredentials()))