Clarify/confirm <src><dst><data> multistream flow in relay

[dryajov]

@lgierth @diasdavid @dignifiedquire

The current spec describes the multistream interaction as <src><dst><data>, further defining it as:

After getting a stream to the relay node from its libp2p swarm, the dialing transport writes the header to the stream. The relaying node reads the header, gets a stream to the destination node, then writes the header to the destination stream and shortcircuits the two streams.

In order to make sure that this is unambiguous an example might be required, such as:

• Peer A connects to relay (Relay) and writes the destination address as a header
  • The header is in the form of /ipfs/relay/circuit/1.0.0\n/<valid multiaddr of dest node>
• The Relay reads the header and the address of Peer B from the stream
  • Relay then connects to Peer B and writes a header in the form of /ipfs/relay/circuit/1.0.0\n/<valid multiaddr of source node>
  • Peer B stores the origin/source address to be able to later dial back (is this the case?)
• Once connected to both peers, the Relay short circuits the two streams

This is what I currently have implemented as well, but I still feel that I might be reading the spec incorrectly, so just making sure this is the intended flow. Adding an example like this to the spec might also help future implementors. Please feel free to correct were things are off.

[ghost]

Mh yes, thanks for catching this. The semantics of the header are pretty under-specified...

It should be exactly as you say above. There's an A-to-R header (dest multiaddr), and an R-to-B header (src multiaddr). (Note that the multicodec now starts in /libp2p though.)

/libp2p/relay/circuit/1.0.0\n
/p2p/QmPeerB\n
<data-stream>

R needs the dest multiaddr to know what to do. It MUST be at least a /p2p multiaddr, but later the relay SHOULD also accept other multiaddrs which would bypass R's peer routing. Being able to run R without the overhead of peer routing, as a thin stream-in-stream-out service, will be very useful in the future. (This is called "forced addresses" in the current spec.)

B doesn't need the src multiaddr, but it's pretty helpful in that it allows to establish the reverse connection. The same peer routing semantics as with the A-to-R header apply. The relay can send a full multiaddr for A, or it can send just /p2p/QmOne which would require peer routing before being able to dial back.

[ghost]

I think it's good to go 👍

One more explanation addition:

B doesn't need the src multiaddr, but it's pretty helpful in that it allows to establish the reverse connection.

The same peer routing semantics as with the A-to-R header apply. The relay can send a full multiaddr for A, or it can send just /p2p/QmOne which would require peer routing before being able to dial back.

---

I'll think a bit more about the semantics of the header and nested relay connections too (example "Dial QmThree, through a relayed connection to QmTwo" in the current spec).

[daviddias]

This issue is old. Let's converge on #22