search

multiformats / multistream-select

Friendly protocol negotiation. It enables a multicodec to be negotiated between two entities.
MIT License
62 stars 11 forks source link

multistream-select specification isn't very clear #24

Open dhuseby opened 11 months ago

dhuseby commented 11 months ago

Reading the spec I noticed that the code blocks in the beginning show a pseudo-wire protocol representation by just showing the contents of each message without explicitly showing the varint message length and the newline suffix. For instance this example is like that:

https://github.com/multiformats/multistream-select/blob/77f0b4449e9daea8bfefc3ffcb07084175f4c6d7/README.md?plain=1#L45-L48

Only later, in an easy-to-miss note do we point out the critical details that every message has a varint length and newline suffix:

https://github.com/multiformats/multistream-select/blob/77f0b4449e9daea8bfefc3ffcb07084175f4c6d7/README.md?plain=1#L82

Farther down in the spec, the examples begin to show the varint length explicitly:

https://github.com/multiformats/multistream-select/blob/77f0b4449e9daea8bfefc3ffcb07084175f4c6d7/README.md?plain=1#L182-L188

Suggestions for improvement:

  1. Highlight the basic message wire format first and have an example showing the varint, message body, newline suffix.
  2. Make all of the examples consistent in explicitly showing the varint lengths and newline suffixes. The way it is now is ambiguous. Does each protocol line constitute a message and thus has a varint length and newline suffix or is it only the overall message that does?
  3. Add a little terminology/vocab note at the top explaining "initiator" and "responder" and explicitly stating that any message that starts with ">" is a message from the initiator to the responder and any message that starts with "<" is a message from the responder to the initiator.
  4. Remove the newline suffixes. If you have varint length prefixes the newline suffixes are redundant framing.
dhuseby commented 11 months ago

I would make a PR right now to fix the problems but the spec, as it is, can be interpreted different ways and I don't want to dump raw messages to figure out the behavior in the wild. Once I confirm the actual wire protocol, I can submit a PR to clean this up.

marten-seemann commented 11 months ago

When using the TCP transport, the first multistream exchange happens in the clear, so it should be easy to inspect using Wireshark.