feat(iroh): publish and resolve user-defined data in discovery #3176
+232
−27
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Frando
force-pushed
the
feat/discovery-user-data
branch
from
5e49912 to
9432910
Compare
|
Documentation for this PR has been generated and is available at: https://n0-computer.github.io/iroh/pr/3176/docs/iroh/ Last updated: 2025-02-14T10:47:12Z |
Frando
force-pushed
the
feat/discovery-user-data
branch
5 times, most recently
from
32a29f4 to
14b1f3b
Compare
4 tasks
Frando
force-pushed
the
feat/discovery-user-data
branch
from
14b1f3b to
0324657
Compare
Frando
force-pushed
the
feat/discovery-user-data
branch
4 times, most recently
from
a2cd248 to
644e762
Compare
Frando
changed the title
ramfox
reviewed
Feb 12, 2025
iroh-relay/src/dns/node_info.rs
Outdated
| } | ||
| } | ||
|
|
||
| // User defined data that can be published and resolved through node discovery. |
There was a problem hiding this comment.
Suggested change
| // User defined data that can be published and resolved through node discovery. | |
| /// User-defined data that can be published and resolved through node discovery. |
Comment on lines
137
to
138
| node_addr: impl Into<NodeAddr>, | ||
| user_data: Option<UserData>, |
There was a problem hiding this comment.
node_data: NodeData? to guard against future breaks?
There was a problem hiding this comment.
👍 Fixed in #3175 and thus here too (this PR is rebased on top of 3175)__
| @@ -144,7 +151,7 @@ impl StaticProvider { | |||
| /// The provided addressing information is combined with the existing info in the static | |||
| /// provider. Any new direct addresses are added to those already present while the | |||
| /// relay URL is overwritten. | |||
| pub fn add_node_addr(&self, info: impl Into<NodeAddr>) { | |||
| pub fn add_node_addr(&self, info: impl Into<NodeAddr>, user_data: Option<UserData>) { | |||
There was a problem hiding this comment.
node_data: impl Into<NodeData> ?
There was a problem hiding this comment.
Also fixed via rebase on top of newest commits in #3175 (but with impl Into<NodeInfo> not NodeData because we also need the node id).
iroh-relay/src/dns/node_info.rs
Outdated
| /// Under the hood this is a UTF-8 String that is less than or equal to | ||
| /// [`USER_DATA_MAX_LENGTH`] bytes. | ||
| /// | ||
| /// Iroh does not keep track of or examine user defined data. |
There was a problem hiding this comment.
Suggested change
| /// Iroh does not keep track of or examine user defined data. | |
| /// Iroh does not keep track of or examine user-defined data. |
iroh-relay/src/dns/node_info.rs
Outdated
| #[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] | ||
| pub struct UserData(String); | ||
|
|
||
| /// The max byte length allowed for user defined data. |
There was a problem hiding this comment.
Suggested change
| /// The max byte length allowed for user defined data. | |
| /// The max byte length allowed for user-defined data. |
There was a problem hiding this comment.
Fixed, and also moved the const onto the UserData struct
Frando
force-pushed
the
feat/discovery-user-data
branch
7 times, most recently
from
9970bb3 to
66f9691
Compare
Frando
force-pushed
the
feat/discovery-data
branch
from
761ffe7 to
181a4be
Compare
Frando
force-pushed
the
feat/discovery-user-data
branch
from
66f9691 to
1514e11
Compare
Frando
force-pushed
the
feat/discovery-user-data
branch
from
1514e11 to
c1627cb
Compare
github-merge-queue bot
pushed a commit
that referenced
this pull request
Feb 18, 2025
## Description Adds a `NodeData` struct that contains the information about a node that can be published in discovery services. This struct is both used in `iroh_relay::dns::NodeInfo` and in `iroh::discovery::Discovery`. Also, `iroh::discovery::DiscoveryItem` has no public fields anymore and uses `NodeInfo` internally to again reduce duplication. With these changes, the fields published about a node in discovery now are only defined in a single place. This PR also serves these prupsoes: * We want to add some "user defined data" to discovery (see #3176). This would add a third argument to `Discovery::publish`; with this PR instead we can just add it as an optional field to `NodeData`. * It makes it possible to potentially add data to discovery after 1.0. The fields of `NodeData` are private, so we can add fields, and setter/getter methods, without this being a semver-breaking change. A few other places are changed for consistency: `StaticProvider` now works with `NodeInfo` instead of `NodeAddr` (`NodeInfo` can be easily converted into `NodeAddr`). `DnsProvider::lookup_node_by_id` etc. now return `NodeInfo` instead of `NodeAddr`. A few method names are adjusted for consistency. `NodeInfo` is constructed in a builder-style fashion instead of passing all fields to `new`. ## Breaking Changes * `iroh::discovery::Discovery::publish` now takes `data: &NodeData` as its single argument. `iroh::discovery::NodeData` is a re-export of `iroh_relay::dns::node_info::NodeData`, and contains relay URL and direct addresses. See docs for `NodeData` for details. * `iroh::discovery::DiscoveryItem` no longer has any public fields. There are now getters for the contained data, and constructors for createing a `DiscoveryItem` from a `NodeInfo`. * `iroh_relay::dns::node_info::NodeInfo` is changed. * `NodeInfo::new` now has a single `NodeId` argument. Use `NodeInfo::with_direct_addresses` and `NodeInfo::with_relay_url` to set addresses and relay URL. Alternatively, use `NodeInfo::from_parts` and pass a `NodeData` struct. * `NodeInfo` now has two public fields `node_id: NodeId` and `data: NodeData`, and setter and getter methods for the relay URL and direct addresses. * ` iroh::discovery::pkarr::PkarrPublisher::update_addr_info` now takes a `NodeData` argument ## Notes & open questions <!-- Any notes, remarks or open questions you have to make about the PR. --> ## Change checklist - [x] Self-review. - [x] Documentation updates following the [style guide](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text), if relevant. - [x] Tests if relevant. - [x] All breaking changes documented.
Frando
force-pushed
the
feat/discovery-user-data
branch
from
c1627cb to
51319ec
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Based on #3175
Adds support for publishing and resolving a string of user-defined data through Iroh's discovery services.
This gives applications a way to add additional information to the records published and resolved through discovery, in addition to the addressing information (relay URL and direct addresses). Iroh itself does not parse or use this user-defined data string in any way.
All existing discovery services are updated to support the user data. All DNS-based discovery services encode the user-defined data in a TXT record, in the same way as the DNS/pkarr services already encode the relay URL and direct addresses. Therefore, the length of the
user-data=<user-data>string is limited to 255 bytes, which is the max length for a single character string in DNS messages. Thus, the length of the actual user-defined data string is limited to 245 bytes (255 minuxuser-data=). This limit is enforced when constructing aUserData(which is just a wrapper around aStringotherwise).The local swarm discovery uses
swarm-discoveryunder the hood, for which I added support for TXT records in rkuhn/swarm-discovery#12. This was released as[email protected].Breaking Changes
Notes & open questions
Note that currently the
DiscoveryItemwhich contains the user-defined data is only accessible when directly calling the methods on theDiscoverytrait. For discoveries initiated by the endpoint, both active fromEndpoint::connectand passive from the magicsock's subscription toDiscovery::subscribe, theDiscoveryItems are currently not exposed in any way, thus there's no way for an app to access the user data of nodes discovered by the endpoint. However, with #3181, there will be a way to watch for allDiscoveryItems found by the endpoint.Change checklist