search

libp2p / specs

Technical specifications for the libp2p networking stack
https://libp2p.io
1.58k stars 275 forks source link

Add yamux specification #519

Closed thomaseizinger closed 1 year ago

thomaseizinger commented 1 year ago

cc @marten-seemann @mxinden @wemeetagain

The specification itself is a verbatim copy from https://github.com/hashicorp/yamux/blob/master/spec.md modulo formatting changes.

The only addition is the "Implementation considerations" section at the bottom where we document the ACK backlog of 256. To my knowledge, only go-libp2p implements this at the moment. rust-yamux still needs to implement this: https://github.com/libp2p/rust-yamux/issues/150. I am not sure about the status of this in js-libp2p-yamux?

TODO

marten-seemann commented 1 year ago

The only addition is the "Implementation considerations" section at the bottom where we document the ACK backlog of 256. To my knowledge, only go-libp2p implements this at the moment. rust-yamux still needs to implement this: https://github.com/libp2p/rust-yamux/issues/150. I am not sure about the status of this in js-libp2p-yamux?

That's fine. Doesn't block the spec, as it's a SHOULD anyway.

thomaseizinger commented 1 year ago

Just remembered that this is missing the protocol identifier that we use. Will add.

thomaseizinger commented 1 year ago

The only addition is the "Implementation considerations" section at the bottom where we document the ACK backlog of 256. To my knowledge, only go-libp2p implements this at the moment. rust-yamux still needs to implement this: https://github.com/libp2p/rust-yamux/issues/150. I am not sure about the status of this in js-libp2p-yamux?

That's fine. Doesn't block the spec, as it's a SHOULD anyway.

Agreed. I only mentioned it for visibility.

thomaseizinger commented 1 year ago

Any other people I should add to the interest group?

Menduist commented 1 year ago

Does it really make sense to copy the yamux spec here? It's not like we copied the quic spec in this repo for instance, we just specified how it's used inside libp2p Maybe just point to a specific hash of the upstream spec, and add libp2p specifics

thomaseizinger commented 1 year ago

Does it really make sense to copy the yamux spec here? It's not like we copied the quic spec in this repo for instance, we just specified how it's used inside libp2p Maybe just point to a specific hash of the upstream spec, and add libp2p specifics

I see your point. The QUIC spec is hosted by the IETF though which I'd consider more trustworthy and I am sure there are other copies of it around too.

The yamux spec is owned by an unrelated GitHub account so I figured copying is better. It is also not too long and copying it allows us to improve wording or structure in the future if we want to.

I don't feel super strongly though. Curious to hear more opinions.

marten-seemann commented 1 year ago

https://github.com/libp2p/specs/issues/479 will require us to make some (backwards-compatible) changes to yamux to encode errors, so having a spec in this repo that we can modify makes sense.

thomaseizinger commented 1 year ago

This is ready to merge from my end.