feat!: endpoint groups and attributes - #86
Conversation
|
Documentation for this PR has been generated and is available at: https://n0-computer.github.io/iroh-services/pr/86/docs/iroh_services/ Last updated: 2026-08-10T13:07:32Z |
Add cloud-side metadata for client endpoints beyond the existing name: a single `group` and an arbitrary key-value `attributes` map. Both are settable at build time via `ClientBuilder::group` / `attributes` and updatable post-construction via `Client::set_group` / `set_attributes`, mirroring the name API. Attributes use full-replace semantics on each call. Adds matching `SetGroup` / `SetAttributes` RPC messages to the protocol, plus an `endpoint_meta` example that exercises both paths. Group names follow the same 2–128 byte UTF-8 rules as endpoint names. Attribute keys share those rules; values may be empty and are capped at 128 bytes; the map is capped at 128 entries.
aa6d719 to
097602e
Compare
c6021b0 to
f074627
Compare
dignifiedquire
changed the title
Add set_attribute(key, value) which merges a single entry into the endpoint's attributes (rather than replacing the whole map) and sends the full SetAttributes. Attributes remain a BTreeMap.
f074627 to
8581e5a
Compare
divagant-martian
left a comment
divagant-martian
left a comment
There was a problem hiding this comment.
One relevant bug and many minor comments.
How does versioning work here? because this updated the underlying protocol without a new ALPN. Are we relying on how unlikely it is that a client with updated protocol dials an oudated "server" with one of the new calls and the connection is killed because of that? I can try to understand this but it would be good to have an explicit policy here because as it is, this is making alpn negotiation rather meaningless
- set_attribute validates the *merged* set in the actor: a valid single entry can still push a full set over the max-entry limit, so the single-entry check was insufficient. Surfaces InvalidAttributes(TooManyEntries) locally. - Read initial name/group/attributes from the actor's own state instead of passing them to run() again; add ReadGroup + Client::group() to mirror name. - Docs: single-sentence style, state the 2-128 byte rules directly, drop the misleading insertion-order / group-uniqueness / same-as-names claims, and clarify that builder validation errors return immediately while startup-send failures are logged (use set_* for explicit handling). - Log the group (not just its length) in the set-group debug line.
…ot characters Reword the versioning doc and cleanups without em dashes, en dashes, ellipses, or arrows. Fix the ValidateNameError messages to say bytes, matching the actual byte-length (name.len()) check and the doc wording.
Added a policy statement matching what we have done in the past. TLDR we only extend the protocol, so we need to make sure old clients can talk to new servers, but as we first deploy the server side updates, we are safe on that side |
divagant-martian
left a comment
divagant-martian
left a comment
There was a problem hiding this comment.
LGTM, it's a bit sad that set_attribute can't have the same "explicit error handling" guarantee the others have but I don't really see a workaround. Otherwise the bug is fixed and docs and code style were improved
|
@dignifiedquire will this need to be v2 of iroh-services? Also does it need to be published before the server? |
Yes, this is semver-breaking, unfortunately. Reason is that the
No, the other way around: We first need to deploy svc with support for the new methods, by using a git dependency onto this branch of iroh-services in svc. And only once svc is deployed to prod with this, we can release iroh-services 2.0.0 with this PR merged. Otherwise, people doing |
6 participants
Description
Add cloud-side metadata for client endpoints beyond the existing name: a single
groupand an arbitrary key-valueattributesmap. Both are settable at build time viaClientBuilder::group/attributesand updatable post-construction viaClient::set_group/set_attributes, mirroring the name API. Attributes use full-replace semantics on each call. Adds matchingSetGroup/SetAttributesRPC messages to the protocol, plus anendpoint_metaexample that exercises both paths.Group names follow the same 2–128 byte UTF-8 rules as endpoint names. Attribute keys share those rules; values may be empty and are capped at 128 bytes; the map is capped at 128 entries.
Breaking Changes
non_exhaustiveNotes & open questions
This unfortunately requires a v2 as we forgot to mark the protocol enums as
non_exhaustive, need to ensure though the protocol stays compatible