protocols/kad: Implement log2 for Distance

[mxinden]

In order to make use of the distances returned by KBucketRef::range in
a human readable format, one needs to be able to tranlate the 256 bit in
a Distance to a smaller space, e.g. the currently used 8 bit bucket
scheme. To be able to do so one needs to be able to extract the 256 bit
from a Distance.

This commit makes the U256 within a Distance public allowing callers
of KBucketRef::range to work with the raw bits themselves.

---

Follow up on #1680.

With this pull request the implementation internal struct U256 is exposed on the public interface. That is not great. I have been unable to come up with a better way of exposing this information without tying the public interface to the internal 256-bit-fixed-array-implementation (see #1680 (comment) for past discussion). Instead of exposing U256 itself, one could as well offer a method on Distance returning a [u8] instead.

I don't think simply exposing a 256bit bucket identifier via Distance's Debug implementation in logs or metrics is of much help for any human being.

Thoughts?

[romanb]

In order to make use of the distances returned by KBucketRef::range in
a human readable format, one needs to be able to tranlate the 256 bit in
a Distance to a smaller space, e.g. the currently used 8 bit bucket
scheme.

What format do you have in mind and what do you mean by translating it to an "8 bit bucket scheme"? External code shouldn't presume there to be 256 buckets either. Since you mention a human-readable format for logs and metrics, wouldn't it be appropriate to implement Display for Distance?

[romanb]

What format do you have in mind and what do you mean by translating it to an "8 bit bucket scheme"? External code shouldn't presume there to be 256 buckets either.

Oh, I guess you just want to show or distribute the distances on a (base 2) logarithmic scale, independent of how many buckets there are? I think I would have a slight preference to just offering functions like Distance::log2() over making uint crate types part of the public API and exposing the implementation of Distance.

[mxinden]

We could now use Distance::log2 in BucketIndex::new.

rust-libp2p/protocols/kad/src/kbucket.rs

Lines 108 to 112 in 7b415d5

	fn new(d: &Distance) -> Option<BucketIndex> {
	(NUM_BUCKETS - d.0.leading_zeros() as usize)
	.checked_sub(1)
	.map(BucketIndex)
	}

As a downside that would blur the lines between the public log2 and the internal bucket scheme. I am fine either way. Thoughts?

[romanb]

We could now use Distance::log2 in BucketIndex::new.

I think we should do that.