kademlia: be louder about the kind of mode we are operating in

[thomaseizinger]

Description

The whole client/server mode functionality is quite involved and hard to understand for newcomers. We should find a way to be loud about it without spamming people's logs.

Are you planning to do it yourself in a pull request?

No but maybe @dhuseby wants to land his first contribution to rust-libp2p :)

Tasks

Beta Give feedback

1. Add a ModeChanged variant to the kademlia events that gets fired every time the mode changes automatically
2. Rewrite unit tests to also assert the mode changed event
3. Expand documentation to say that Client is the default mode
4. Expand documentation to explain how the mode changes work in detail

[dhuseby]

I think the best way to make this newb-friendly would be to add network behavior events that reflect the current state of the kademlia behavior. AFAICT, the kademlia behavior has roughly these states:

1. initialized but not participating because it doesn't have an external address
2. external address has been confirmed
3. kademlia protocol has been added to list of local protocols for Identify to send out
4. received KAD messages from external peers

I think there are valid transitions from 1 to 2 to 3 to 4 and then from 3 to 1 and 4 to 1 whenever the external address goes away and also 3 to 2 and 4 to 2 whenever the external address changes. All transitions should have kademlia events associated with them so that an app can monitor the status of the peer's kademlia participation and reflect that in the logs/UI.

The only way to be 100% certain that a peer is participating in a KAD DHT is to receive KAD messags from external peers. There is no notion of a "session" with confirmation from other peers. So state 4 is important to have as well as an event for the state transition from 3 to 4.

[dhuseby]

@thomaseizinger do you have any more specifics about what it would look like to "be louder" about the state of the kademlia behavior? Are my four states the ones that would suffice?

[thomaseizinger]

Perhaps a single event ModeChanged would also suffice?

I don't think we should fire that when the mode is set manually. I am also not sure we should fire it initially because the mode technically hasn't changed, we always start in client-mode.

So maybe it needs several individual improvements.

I am of the opinion that we can expect users to read some documentation. Like what the default mode is and perhaps even how the algorithm works for determining it automatically.

Overall, what I find tricky to balance here is:

• Making the API as minimal as possible. Each symbol adds complexity which also makes things harder to understand.
• Staying/being modular. If we want to be a modular networking library, we need to work with multiple usecases. Every API element we add should make sense in all cases.
• Documentation vs code. Some code can be self-explaining and guide the user. But some things are just better expressed as docs.

[dhuseby]

I think it is useful to know when the kademlia behavior switches, both from client to server and back. I guess a single ModeChanged with the new mode as an enum would suffice. There's no other way to know what mode it is in.

[mxinden]

Perhaps a single event ModeChanged would also suffice?

In favor of this. Especially since we can then expose the Mode as a Prometheus metric in libp2p-metrics.

[thomaseizinger]

I'll update the PR description!

[dhuseby]

this would be useful.