Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

server: clarify documentation around setting and sending headers and ServerStream errors #5302

Merged
merged 4 commits into from Apr 8, 2022
Merged

server: clarify documentation around setting and sending headers and ServerStream errors #5302

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5b30033
server: clarify documentation around setting and sending headers and …
dfawley Apr 7, 2022
ab5679c
updates
dfawley Apr 8, 2022
c5af1cd
finish updates
dfawley Apr 8, 2022
c67012d
finish the finished updates
dfawley Apr 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
38 changes: 30 additions & 8 deletions server.go
View file
Open in desktop
Expand Up @@ -1801,12 +1801,26 @@ func (s *Server) getCodec(contentSubtype string) baseCodec {
return codec
}

// SetHeader sets the header metadata.
// When called multiple times, all the provided metadata will be merged.
// All the metadata will be sent out when one of the following happens:
// - grpc.SendHeader() is called;
// - The first response is sent out;
// - An RPC status is sent out (error or success).
// SetHeader sets the header metadata to be sent from the server to the client.
// The context provided must be the context passed to the server's handler.
//
// Streaming RPCs should prefer the SetHeader method of the ServerStream.
//
// When called multiple times, all the provided metadata will be merged. All
// the metadata will be sent out when one of the following happens:
//
// - grpc.SendHeader is called, or for streaming handlers, stream.SendHeader.
// - The first response message is sent. For unary handlers, this occurs when
// the handler returns; for streaming handlers, this can happen when stream's
// SendMsg method is called.
// - An RPC status is sent out (error or success). This occurs when the handler
// returns.
//
// SetHeader will fail if called after any of these events.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make it more clear what these events are?
"the events above"?

Or move it above, right after the "send out" section

All the metadata will be sent out when one of the following happens, and SetHeader will fail if called after any of the events:

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done (the former)

//
// The error returned is compatible with the status package. However, the
// status will often not match the status seen by the client application, and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the status code will often not

And did you want to say that the meanings of the codes are different from the client side? Or just that this code might be different from what the client functions return?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clarified. I intended the latter. The "meaning" of our codes is pretty variable already.

// therefore, should not be relied upon for this purpose.
func SetHeader(ctx context.Context, md metadata.MD) error {
if md.Len() == 0 {
return nil
Expand All @@ -1818,8 +1832,12 @@ func SetHeader(ctx context.Context, md metadata.MD) error {
return stream.SetHeader(md)
}

// SendHeader sends header metadata. It may be called at most once.
// The provided md and headers set by SetHeader() will be sent.
// SendHeader sends header metadata. It may be called at most once. The
// provided md and headers set by SetHeader() will be sent.
//
// The error returned is compatible with the status package. However, the
// status will often not match the status seen by the client application, and
// therefore, should not be relied upon for this purpose.
func SendHeader(ctx context.Context, md metadata.MD) error {
stream := ServerTransportStreamFromContext(ctx)
if stream == nil {
Expand All @@ -1833,6 +1851,10 @@ func SendHeader(ctx context.Context, md metadata.MD) error {

// SetTrailer sets the trailer metadata that will be sent when an RPC returns.
// When called more than once, all the provided metadata will be merged.
//
// The error returned is compatible with the status package. However, the
// status will often not match the status seen by the client application, and
// therefore, should not be relied upon for this purpose.
func SetTrailer(ctx context.Context, md metadata.MD) error {
if md.Len() == 0 {
return nil
Expand Down
6 changes: 4 additions & 2 deletions stream.go
View file
Open in desktop
Expand Up @@ -1370,8 +1370,10 @@ func (as *addrConnStream) finish(err error) {

// ServerStream defines the server-side behavior of a streaming RPC.
//
// All errors returned from ServerStream methods are compatible with the
// status package.
// Errors returned from ServerStream methods are compatible with the status
// package. However, the status will often not match the status seen by the
// client application, and therefore, should not be relied upon for this
// purpose.
type ServerStream interface {
// SetHeader sets the header metadata. It may be called multiple times.
// When call multiple times, all the provided metadata will be merged.
Expand Down