connections: Document stream behaviour

[thomaseizinger]

An initial draft for documenting the behaviour of libp2p streams. Feedback welcome!

Open questions

• The mplex spec differs in regards to how reading from closed streams is handled. Which one is the better behaviour? What mplex specifies or what I wrote here? I took inspiration from our current implementations in rust-libp2p.
• Do we need specify more behaviour?
• The "Definitions" section specifies "They can also be "half closed", meaning that a stream can be closed for writing data but still open to receiving data and vice versa." I am not sure about the "vice-versa" part, i.e. actively closing the read-half but still writing to the stream. Neither mplex nor yamux support this. The Rust implementation doesn't have an interface for this. I am not sure about others. We built it for WebRTC with inspiration from QUIC but personally don't know when I'd use it.

Fixes #466.

[mxinden]

Thanks for documenting this! Very much appreciated.

Minus the comments, I think this is good to go. Bonus would be to document the behavior of QUIC, WebRTC, mplex and yamux here as well.

@marten-seemann want to give this a review as well?

[mxinden]

Intuitively this is to implementation specific. E.g. some may express this through a special event, some might express this through 0 bytes. I don't think we should dictate the way of how an implementation expresses this.

[thomaseizinger]

Suggested change

	Reading from a read-closed stream SHOULD succeed by reading 0 bytes.
	Reading from a read-closed stream SHOULD succeed.

Would that be better?

[mxinden]

I don't think this needs to be in the specification.

[thomaseizinger]

Would you just omit it? I think I'd find it helpful because it explains, why we want read operations on closed streams to be successful. Without this, people may rightfully ask, why reading from a read-closed stream shouldn't fail?

I am happy to reword it, but I think it is useful to have in the spec in one form or another.

[mxinden]

Cross referencing a past discussion for the curious reader here, namely that QUIC only closes the write side.

#412 (comment)

I don't have a strong opinion here. Maybe @marten-seemann does. Ideally we would be consistent across the different multiplexers. At least we should document the difference here.

[marten-seemann]

As I've explained on the WebRTC PR, I don't think we should define our stream state machine to match the behavior of legacy stream muxers like yamux or mplex. I'd like our stream state machine to take advantage of what QUIC has to offer.
By virtue of that, make it possible to map protocols like HTTP onto libp2p. The current proposal would prohibit this.

[thomaseizinger]

As I've explained on the WebRTC PR, I don't think we should define our stream state machine to match the behavior of legacy stream muxers like yamux or mplex. I'd like our stream state machine to take advantage of what QUIC has to offer. By virtue of that, make it possible to map protocols like HTTP onto libp2p. The current proposal would prohibit this.

That does make sense.

Would you still keep it symmetric though? More specifically, can you reset a read-only stream? From this conversation it appears that QUIC cannot do that. I am curious to understand why. Does "closing" a read-only stream always communicate the same intent?

[mxinden]

@thomaseizinger @marten-seemann what are the next steps here? What do you think of documenting the QUIC stream behavior as the reference plus how the other stream muxers deviate from that? While not ideal, it would document the status quo and where we are heading.

[marten-seemann]

What do you think of documenting the QUIC stream behavior as the reference plus how the other stream muxers deviate from that? While not ideal, it would document the status quo and where we are heading.

Sounds good to me.

[thomaseizinger]

@thomaseizinger @marten-seemann what are the next steps here? What do you think of documenting the QUIC stream behavior as the reference plus how the other stream muxers deviate from that? While not ideal, it would document the status quo and where we are heading.

I would still like to understand why resetting a read-stream is something that is unsupported. It seems like an obvious step from the two-stream mental model that you can reset both to signal an abrupt termination.