Document encoding/decoding algorithm

[ghost]

Feedback welcome!

[ghost]

Note that this is not actually the exact algorithm we currently use -- currently we mostly just dumbly split on forward-slashes, which we should stop doing, since there are protocols that whose values stretch across forward-slashes.

[Stebalien]

There are three cases:

1. Some protocols have multiple arguments.
2. Some protocols have no arguments (?)
3. Some protocols have arguments with embedded slashes.

One solution is to define a multiaddr as / PROTO [/ ARG]* where the arguments can be embedded multiaddrs. It would be up to the top-level protocol to interpret them and do recursive resolution.

However, from a usability standpoint, this makes it hard for users to read multiaddrs.

[ghost]

One solution is to define a multiaddr as / PROTO [/ ARG]* where the arguments can be embedded multiaddrs. It would be up to the top-level protocol to interpret them and do recursive resolution.

Yes that's exactly what I'm trying to get at, thanks for providing better wording for it :)

The algorithm I try to describe in this PR is what IPLD resolvers do too (or did?) -- parse what we can do, and return the rest so it can be handled as another encapsulated multiaddr. In Go-land, we'll basically have an interface like func (p *Proto) Encode(string) []byte, string, err and func (p *Proto) Decode([]byte) string, []byte, err, where the second return value is the rest.

I'm also realizing the encode step in this PR is broken -- it should just be pretty much the exact reverse of decode, algorithm-wise.

[ghost]

However, from a usability standpoint, this makes it hard for users to read multiaddrs.

I see no way around it -- there's strong cases for each of the three variants (0, 1, 1+ values), and we're already using all three too.

[ghost]

Will take a new attempt at this soon

[ethindp]

My thoughts:

Why not just use keyword arguments?

/protocol?arg1=1,arg2=2,arg3=3,arg4=4

Or something like this... We really need a way to specify arguments that (don't) use characters that another protocol would use. One idea I just had (off the top of my head) is to just do /protocol and then everything else after that is an argument to the protocol in question. I feel like if we create a specific format, you'll run into problems of "well I'm trying to open /http?secure=1,host=example.org,path=/path/to/file/that/has,commas,in,it" or something like that, and then the parser will just get ridiculously convoluted. Perhaps maybe just /protocol?args would work? Leave it up to the protocol handler in question to interpret data after the '?'?