connections: Document stream behaviour

libp2p / specs

Technical specifications for the libp2p networking stack

https://libp2p.io

1.56k stars 273 forks source link

connections: Document stream behaviour #469

Open thomaseizinger opened 1 year ago

thomaseizinger commented 1 year ago

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.

thomaseizinger commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

@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.