Repository: grpc/grpc-go
File: stream_interfaces.go (Go)

Code before:
 */

package grpc

// ServerStreamingClient represents the client side of a server-streaming (one
// request, many responses) RPC. It is generic over the type of the response
// message. It is used in generated code.
type ServerStreamingClient[Res any] interface {
	// Recv receives the next message from the server in the stream. The type of
	// message is determined by the Res type parameter of the ServerStreamingClient.
	// The client can repeatedly call the Recv method on the returned ServerStreamingClient
	// stream in order to read the server-to-client response stream. This Recv method returns
	// (nil, io.EOF) once the server-to-client stream has been completely read through.
	Recv() (*Res, error)
	ClientStream
}

// ServerStreamingServer represents the server side of a server-streaming (one
// request, many responses) RPC. It is generic over the type of the response
// message. It is used in generated code.
type ServerStreamingServer[Res any] interface {
	// Send sends a response message to the client. This method is called to
	// send each individual message as part of the server's response stream.
	// It takes a pointer to the response message of type Res and returns an error if
	// there was an issue sending the message. The server-side handler can send a
	// stream of protobuf messages to the client through this parameter’s Send method.
	// End-of-stream for the server-to-client stream is caused by the return of the handler method.
	Send(*Res) error
	ServerStream
}

// ClientStreamingClient represents the client side of a client-streaming (many
// requests, one response) RPC. It is generic over both the type of the request
// message stream and the type of the unary response message. It is used in
// generated code.
type ClientStreamingClient[Req any, Res any] interface {
	// Send sends a request message to the server. This method is called repeatedly to
	// send all messages as part of the client’s request stream. The type of message is
	// determined by the Req type parameter of the ClientStreamingClient. The client can
	// repeatedly call the Send method on the returned ClientStreamingClient stream in
	// order to send the client-to-server message stream. It returns an error if the
	// message could not be sent.
	Send(*Req) error

	// CloseAndRecv closes the sending side of the request stream and waits for the server
	// to send a unary response message. This method is typically called after sending all
	// request messages to signal the end of the stream and to receive the final response
	// from the server. The response message type is determined by the Res type parameter
	// of the ClientStreamingClient. The CloseAndRecv method on this stream must be called
	// once and only once, in order to both close the client-to-server stream and receive
	// the single response message from the server.

Review comment (suggestion):
Please remove any mention of protobuf throughout.  Also.. This sentence seems like it could be entirely deleted since it's redundant with the first sentence.  And some of the above is probably too wordy or just obvious, e.g. "it takes a pointer to the response message o ftype Res" (yes, it's a `*Res` in the parameter list).  How about:

```go
// Send sends a response message to the client.  It may be called multiple times to send
// multiple messages.
```

And the bit about ending the stream should be moved into the interface itself, since that invalidates the entire interface, not just the Send method.  E.g.

```go
// The stream is terminated upon returning from the method handler that was provided this stream.
// No methods on this interface should be called after that time.
```

Code after:
 */

package grpc

// ServerStreamingClient represents the client side of a server-streaming (one
// request, many responses) RPC. It is generic over the type of the response
// message. It is used in generated code.
type ServerStreamingClient[Res any] interface {
	// Recv receives the next response message from the server. The client may
	// repeatedly call Recv to read messages from the response stream.  If
	// io.EOF is returned, the stream has terminated with an OK status.  Any
	// other error is compatible with the status package and indicates the
	// RPC's status code and message.
	Recv() (*Res, error)

	// ClientStream is embedded to provide Context, Header, and Trailer
	// functionality.  No other methods in the ClientStream should be called
	// directly.
	ClientStream
}

// ServerStreamingServer represents the server side of a server-streaming (one
// request, many responses) RPC. It is generic over the type of the response
// message. It is used in generated code.
//
// To terminate the response stream, return from the handler method and return
// an error from the status package, or use nil to indicate an OK status code.
type ServerStreamingServer[Res any] interface {
	// Send sends a response message to the client.  The server handler may
	// call Send multiple times to send multiple messages to the client.  An
	// error is returned if the stream was terminated unexpectedly, and the
	// handler method should return, as the stream is no longer usable.
	Send(*Res) error

	// ServerStream is embedded to provide Context, SetHeader, SendHeader, and
	// SetTrailer functionality.  No other methods in the ServerStream should
	// be called directly.
	ServerStream
}

// ClientStreamingClient represents the client side of a client-streaming (many
// requests, one response) RPC. It is generic over both the type of the request
// message stream and the type of the unary response message. It is used in
// generated code.
type ClientStreamingClient[Req any, Res any] interface {
	// Send sends a request message to the server.  The client may call Send
	// multiple times to send multiple messages to the server.  On error, Send
	// aborts the stream.  If the error was generated by the client, the status
	// is returned directly.  Otherwise, io.EOF is returned, and the status of
	// the stream may be discovered using CloseAndRecv().
	Send(*Req) error