feat: Make Endpoint::node_addr watchable and add trait Watcher & combinators

[matheus23]

Description

Goal of this PR was: make Endpoint::node_addr return something that can be watched, so you can use ep.node_addr().initialized().await? or ep.node_addr().get()? or ep.node_addr().updated().await?, etc.

Unfortunately, there's no Watchable<Option<NodeAddr>> anywhere, instead, a NodeAddr technically consists of a Watchable<Option<BTreeSet<DirectAddr>>> and a Watchable<Option<RelayUrl>>.

So this PR abstracts all the initialized, updated, etc. functionality of Watcher into a trait Watcher, and renames watchable::Watcher into watcher::Direct. (the whole watchable module was renamed to watcher)
On top of this we can build the usual combinators like watcher::Map that transforms a Watcher<Value = A> into a Watcher<Value = B> using a function A -> B, or the tuple (impl Watcher<Value = A>, impl Watcher<Value = B>) that takes the two watchers and implements Watcher<Value = (A, B)>.

Breaking Changes

• Renamed watchable module to watcher
• Moved watchable::Watcher::{get, updated, initialized, stream, stream_updates_only} to trait watcher::Watcher
• Renamed watchable::Watcher to watcher::Direct
• Renamed watchable::WatchNextFut to watcher::NextFut
• Renamed watchable::WatchInitializedFut to watcher::InitializedFut
• Renamed watchable::WatcherStream to watcher::Stream
• Moved watchable::Watchable to watcher::Watchable
• Moved watchable::Disconnected to watcher::Disconnected

Notes & open questions

This PR would subsume #2732

You're probably wondering:

Why is Watcher a trait?

Two reasons:

1. You need a way to abstract away the watcher functionality, if you want to be able to combine them in arbitrary ways, like e.g. watcher::Map or the watcher tuple are doing. The alternative is to have a concrete type for special cases per-api, like e.g. a custom NodeAddrWatcher that implements essentially watcher::Map and watcher tuple functionality inside. This works, but I'd argue is less comprehensible ("What is the difference between NodeAddrWatcher and watcher::Direct? They seem to have the same API?") and also less composable "What if I want to combine the Watchers further?".
2. By depending on carefully-built composable structs like watcher::Direct, watcher::Map, etc. we can re-use the same default implementations of the Watcher trait, instead of having to repeat these implementations for all watchers, potentially allowing them to get out of sync or behave differently from one another.

What is the difference between Stream and Watcher?

The main difference is that Watcher combines a poll function for the next item with a function get(&self) -> Result<Self::Value, Disconnected> that allows you to always try to get the current value.

This allows the poll_updated function (which is very similar to Stream::poll_next) to gain some superpowers, e.g. the OrWatcher combinator can get the value of the other Watcher when one of its watchers has an update.

Change checklist

• Self-review.
• Documentation updates following the style guide, if relevant.
• Tests if relevant.
• All breaking changes documented.

[flub]

I'm not a huge fan of the DirectWatcher name. I wonder if this name can be something else instead? Maybe ValueWatcher? Or even WatcherTrait? I don't know, just some random names that came out of my keyboard.

[matheus23]

Yeah, not super happy either.

I would like to keep the clean trait Watcher name, since I'd rather have people use impl Watcher in their APIs than surface DirectWatcher... But of course that means no named types 😭

And I do think Value doesn't actually help, since every watcher is a "value" watcher.

SourceWatcher?

Not sure.

[github-actions]

Documentation for this PR has been generated and is available at: https://n0-computer.github.io/iroh/pr/3045/docs/iroh/

Last updated: 2024-12-19T16:06:33Z

[github-actions]

Netsim report & logs for this PR have been generated and is available at: LOGS
This report will remain available for 3 days.

Last updated for commit: c318846