diff --git a/README.md b/README.md index 8f15bc8..9ea383a 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,44 @@ Multiaddr solves these problems by modelling network addresses as arbitrary enca Multiaddr was originally [thought up by @jbenet](https://github.com/jbenet/random-ideas/issues/11). +## Interpreting multiaddrs + +Multiaddrs are parsed from left to right, but they should be interpreted right +to left. Each component of a multiaddr wraps all the left components in its +context. For example, the multiaddr `/dns4/example.com/tcp/1234/tls/ws/tls` +(ignore the double encryption for now) is interpreted by taking the first `tls` +component from the right and interpreting it as the libp2p security protocol to +use for the connection, then passing the rest of the multiaddr to the websocket +transport to create the websocket connection. The websocket transport sees +`/dns4/example.com/tcp/1234/tls/ws/` and interprets the `tls` in this context to +mean that this is going to be a secure websocket connection. The websocket +transport also gets the host to dial along with the tcp port from the rest of +the multiaddr. + +Components to the right can also provide parameters to components to the left, +since they are in charge of the rest of the multiaddr's interpretation. For +example, in `/ip4/1.2.3.4/tcp/1234/tls/p2p/QmFoo` the `p2p` component has the +value of the peer id and it passes it to the next component, in this case the +`tls` security protocol, as the expected peer id for this connection. Another +example is `/ip4/.../p2p/QmR/p2p-circuit/p2p/QmA`, here `p2p/QmA` is passed to +`p2p-circuit` and then the `p2p-circuit` component knows it needs to use the +rest of the multiaddr as the information to connect to the relay node. + +This enables nesting and arbitrary parameters. A component can parse +arbitrary data with some encoding and pass it as a parameter to the next +component of the multiaddr. For example, we could reference a specific HTTP path +by composing `path` and `urlencode` components along with an `http` component. +This would look like +`/dns4/example.com/http/path/percentencode/somepath%2ftosomething`. The +`percentencode` parses the data and passes it as a parameter to `path`, which +passes it as a named parameter (`path=somepath/tosomething`). A user may not +like percentencode for their use case and may prefer to use `lenprefixencode` to +have the multiaddr instead look like +`/dns4/example.com/http/path/lenprefixencode/20_somepath/tosomething`. This +would work the same and require no changes to the `path` or `http` component. +It's important to note that the binary representation of the data in +`percentencode` and `lenprefixencode` would be the same. The only difference is +how it appears in the human-readable representation. ## Use cases