documentation: clarify SendMsg documentation

[jeanbza]

Relevant issue: #2159

[MakMukhi]

I was actually thinking about it this morning. A documentation like this seems confusing given that a stream ends only with receiving either an EOF or an Error. From a user's point of view when or if a message is delivered should be opaque.

Perhaps the documentation that we need is a stream's life cycle (if it doesn't already exist.);

1. Client creates a stream(headers are sent to the server)
2. Client sends data(potentially more than one message)
3. Server sends headers.
4. Server sends data(potentially more than one message)
5. Client sends end of stream.
6. Server sends trailers(status).
7. Client receives EOF/error.

[jeanbza]

A documentation like this seems confusing given that a stream ends only with receiving either an EOF or an Error.

I don't follow, could you elaborate? That detail is what this documentation attempts to address.

From a user's point of view when or if a message is delivered should be opaque.

That would only be possible if individual messages (not frames) were acked. But, since they aren't, I don't think we can get around informing folks that they must wait for EOF or risk losing messages.

Perhaps the documentation that we need is a stream's life cycle

I think that would be valuable, but is separate from / not mutually exclusive with this documentation.

[MakMukhi]

I don't follow, could you elaborate? That detail is what this documentation attempts to address.

What I mean is perhaps changing the documentation from "it blocks until the message is sent" to "blocks until a message is scheduled" makes more sense, rather than warning users of what unexpected behavior may occur in the current implementation if they don't use the API right.

We bind a stream's context to all operations happening on that stream, if the context is canceled then no further operations can happen on it. Further, for a client stream to only send messages and not read a status is incorrect usage. I see the motivation to inform users that a send call doesn't block until the whole message is written to the wire, but more importantly they shouldn't be cancelling streams' context without reading an EOF or error.

Does that make sense?

[jeanbza]

My two goals:

• Remove the assumption that the message is delivered after calling SendMsg.
• Educate users that until they receive EOF, their message may not have been delivered. SendMsg seems a natural place to put an abbreviated warning about this since users expecting ack behavior are likely to look at SendMsg documentation.

What I mean is perhaps changing the documentation from "it blocks until the message is sent" to "blocks until a message is scheduled" makes more sense, rather than warning users of what unexpected behavior may occur in the current implementation if they don't use the API right.

Done, PTAL.

[jeanbza]

Did a final round of cleanup. (no real content change) Does this look ok?

[MakMukhi]

LGTM

[dfawley]

SendMsg does not return an RPC status -- it returns io.EOF and the client needs to call RecvMsg to determine the status.

"To ensure delivery..." should end with "before cancelling the context" instead of "before closing the stream". (The stream is already closed when RecvMsg returns io.EOF and it's not necessary to cancel the context after then - but it's still a good idea anyway.)

[jeanbza]

Shoot. I just hit squash and merge. I can open a new PR to fix those comments @dfawley.

[jeanbza]

#2184