feat(client): add optional name for endpoints by okdistribute · Pull Request #71 · n0-computer/iroh-services

okdistribute · 2026-03-11T21:16:10Z

Description

This adds the capability to give endpoints a label so they are more easily identifiable in metrics & observability services such as https://services.iroh.computer/

Breaking Changes

No breaking changes.

This is acceptable because we don't want to break people's existing deployments, we already know ottomatic & nous have integrated this into their client apps.

This can be an opt-in feature but since the examples will all use .name, it's likely most new developers will add a name. So we get the best of both, without restricting devs who want endpoints to remain anonymous.

Notes & open questions

This does not need to be rolled out with any server changes because I've added a test to ensure it'll still work with older server versions. Hopefully this can be the case.

If we do need to roll out a server version first before publishing, we can do that but was trying to avoid the coupling of the two releases.

I asked copilot to review just to see what their changes suggested would be, and it was a disaster. Never using that again. Claude's review was much more accurate.

Change checklist

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

github-actions · 2026-03-11T21:17:41Z

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

Last updated: 2026-04-11T10:39:05Z

Copilot

Pull request overview

Adds an optional, human-readable endpoint label that can be sent during authentication so endpoints are easier to identify in metrics/observability.

Changes:

Extend Auth protocol message with an optional label: Option<String>.
Add a ClientBuilder::label(...) API and plumb the value into the client actor’s Auth RPC.
Update examples and add tests around label behavior / compatibility.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
`src/protocol.rs`	Adds `Auth.label` field and introduces serialization/compatibility tests.
`src/client.rs`	Adds builder support for setting a label and sends it in the `Auth` RPC; adds a unit test.
`examples/quickstart.rs`	Demonstrates setting a client label.
`examples/net_diagnostics.rs`	Demonstrates setting a client label for net diagnostics usage.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

dignifiedquire · 2026-03-16T19:30:22Z

this is a breaking change, as the API is breaking, it is also breaking on the wire, as sending the new protocol to an old client will break, if the name is set

okdistribute · 2026-03-17T21:03:15Z

@dignifiedquire yes, I had bumped semver to be a breaking change, looks like you moved it back down? 165238c#diff-2e9d962a08321605940b5a657135052fbcef87b5e360662bb527c96d9a615542R3

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

b5 · 2026-03-23T22:52:55Z

fml that was a pain, but I've implemented this as a non-breaking set of changes.

Copilot

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 10 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-23T22:57:28Z

+  "permissions": {
+    "allow": [
+      "mcp__acp__Edit",
+      "mcp__acp__Bash"
+    ]
+  }


This looks like a machine-/developer-local Claude configuration file (and it grants tool permissions). It’s usually not appropriate to commit settings.local.json to the repository; consider removing it from the PR and adding .claude/settings.local.json to .gitignore instead.

Suggested change

"permissions": {

"allow": [

"mcp__acp__Edit",

"mcp__acp__Bash"

]

}

Copilot · 2026-03-23T22:57:29Z

+    #[error("Label is too long (must be no more than {LABEL_MAX_LENGTH} characters).")]
+    TooLong,
+    #[error("Label is too short (must be at least {LABEL_MIN_LENGTH} characters).")]


ValidateLabelError messages talk about "characters", but validation uses label.len() which is UTF-8 byte length (and the docs above mention bytes). Please either change the validation to count characters (or grapheme clusters), or update the error text to say "bytes" to match the actual constraint.

Suggested change

#[error("Label is too long (must be no more than {LABEL_MAX_LENGTH} characters).")]

TooLong,

#[error("Label is too short (must be at least {LABEL_MIN_LENGTH} characters).")]

#[error("Label is too long (must be no more than {LABEL_MAX_LENGTH} bytes).")]

TooLong,

#[error("Label is too short (must be at least {LABEL_MIN_LENGTH} bytes).")]

Copilot · 2026-03-23T22:57:29Z

+
+        let too_long_name = "👋".repeat(129);
+        let Err(err) = Client::builder(&endpoint).label(&too_long_name) else {
+            panic!("label should fail for strings over 1024 bytes");


This panic message says "over 1024 bytes", but the max is LABEL_MAX_LENGTH = 128 (bytes). Please update the message so failures are self-explanatory and consistent with the actual constraint.

Suggested change

panic!("label should fail for strings over 1024 bytes");

panic!("label should fail for strings over 128 bytes");

Copilot · 2026-03-23T22:57:29Z

 [package]
 name = "iroh-services"
-version = "0.12.0"
+version = "0.11.0"


The crate version is being decreased from 0.12.0 to 0.11.0. Cargo package versions should be monotonically increasing; this will confuse downstream users and can break publishing. Please revert to 0.12.0 (or bump forward appropriately) and regenerate the lockfile accordingly.

Suggested change

version = "0.11.0"

version = "0.12.0"

Copilot · 2026-03-23T22:57:29Z

+    /// from this endpoint easier to identify. This is often used for associating
+    /// with other services in your app, like a database user id.
+    ///
+    /// When this builder method is called, the provided label label is sent


Doc typo: "the provided label label" has a duplicated word. Please fix to avoid confusion in the public API docs.

Suggested change

/// When this builder method is called, the provided label label is sent

/// When this builder method is called, the provided label is sent

Copilot · 2026-03-23T22:57:30Z

+        self.message_channel
+            .send(ClientActorMessage::ReadLabel { done: tx })
+            .await
+            .map_err(|_| Error::Other(anyhow!("sending ping request")))?;


The error context here says "sending ping request", but this code is sending a ReadLabel request. This makes debugging harder; please update the message to reflect the actual operation (e.g. "sending label read request").

Suggested change

.map_err(|_| Error::Other(anyhow!("sending ping request")))?;

.map_err(|_| Error::Other(anyhow!("sending label read request")))?;

Copilot · 2026-03-23T22:57:30Z

+    ///
+    /// labels can be any UTF-8 string, with a min length of 2 bytes, and
+    /// maximum length of 128 bytes. **label uniqueness is not enforced.**
+    pub async fn set_label(&self, label: String) -> Result<(), Error> {


Client::set_label (and set_label_inner) does not validate the label length, even though the docs claim min/max constraints and the builder enforces them. This makes the API inconsistent and allows invalid labels to be sent at runtime; consider reusing the same validation logic in set_label and returning a structured validation error.

Suggested change

pub async fn set_label(&self, label: String) -> Result<(), Error> {

pub async fn set_label(&self, label: String) -> Result<(), Error> {

let len = label.as_bytes().len();

if len < 2 || len > 128 {

return Err(Error::Other(anyhow!(

"label length must be between 2 and 128 bytes (got {} bytes)",

len

)));

}

Copilot · 2026-03-23T22:57:30Z

+                            }
+                        }
+                        ClientActorMessage::LabelEndpoint{ label, done } => {
+                            let res = self.send_label_endpoint(label).await;


ClientActor keeps a local label, but it is never updated when a LabelEndpoint request succeeds. As a result, Client::label() will keep returning the initial builder value (or None) even after calling Client::set_label. Consider updating self.label = Some(label) after a successful RPC, so the local read reflects the latest label.

Suggested change

let res = self.send_label_endpoint(label).await;

let res = self.send_label_endpoint(label.clone()).await;

if res.is_ok() {

self.label = Some(label);

}

Copilot · 2026-03-23T22:57:30Z

+    message_channel: tokio::sync::mpsc::Sender<ClientActorMessage>,
+    label: String,
+) -> Result<(), Error> {
+    debug!(label=%label, "calling set label");


This debug log emits the full label value. Since labels are described as potentially containing user identifiers, this can leak PII into logs. Consider removing the label value from logs or logging only a redacted/hashed form (or just length).

Suggested change

debug!(label=%label, "calling set label");

debug!(label_len = label.len(), "calling set label");

Copilot · 2026-03-23T22:57:31Z

+    /// Set an optional human-readable name for this endpoint, making metrics
+    /// from this endpoint easier to identify. This is often used for associating
+    /// with other services in your app, like a database user id.
+    ///
+    /// When this builder method is called, the provided label label is sent
+    /// after the client initially authenticates the endpoint server-side.
+    /// Errors will not interrupt client construction, instead producing a
+    /// warn-level log. For explicit error handling, use [`Client::set_label`].
+    ///
+    /// labels can be any UTF-8 string, with a min length of 2 bytes, and
+    /// maximum length of 128 bytes. **label uniqueness is not enforced.**
+    pub fn label(mut self, label: impl Into<String>) -> Result<Self> {


PR description mentions examples using .name, but the public API added here is .label(...) and the example is updated accordingly. Please align the PR description (or rename the API) so the documentation and review context match the actual code.

dignifiedquire · 2026-03-25T18:23:54Z

@@ -0,0 +1,8 @@
+{


lets not check these in please

dignifiedquire · 2026-03-25T18:24:23Z

    // 3. Build a Client that dials iroh-services (as in all other examples).
    let client = Client::builder(&endpoint)
        .api_secret(secret.clone())?
+        .label(label)?


I thought we had settled on name? using label is very confusing imho because I can only set a single one

apologies, I missed that discussion. I can revert to use name. Label made more sense to me, but I don't care either way

Yeah I started with label then we changed it to name; to be honest I don't care either way but I prefer name as well.

dignifiedquire · 2026-03-25T18:25:42Z

I was pretty much ready to approve this pr after the work from @okdistribute but the new commits seem to shuffle a lot of stuff making it more complicated and confusing for me. Is that necessary?

b5 · 2026-04-07T22:58:39Z

I had to re-write this to make the changes non-breaking. Specifically so we can accept both versions of the iroh-services crate

dignifiedquire · 2026-04-08T10:11:04Z

I had to re-write this to make the changes non-breaking. Specifically so we can accept both versions of the iroh-services crate

did you? it was working fine before in my tests

dignifiedquire · 2026-04-10T08:21:40Z

+            let tx = tx.clone();
+            tokio::spawn(async move {
+                if let Err(err) = set_name_inner(tx, name).await {
+                    warn!(err = %err, "setting endpoint label on startup");


maybe something like "failed setting.."

dignifiedquire · 2026-04-10T08:22:06Z

+        if let Some(name) = &self.name {
+            let name = name.clone();
+            let tx = tx.clone();
+            tokio::spawn(async move {


I wish we didn't have this task untracked,

dignifiedquire · 2026-04-10T08:24:39Z

+
+    #[tokio::test]
+    async fn test_name() {
+        let mut rng = rand::rng();


rand_chacha please

do you mean, use the rand_chacha crate instead of rand? we already have dep on rand, I could switch both over, but feels outside of scope for this PR

dignifiedquire · 2026-04-10T08:26:04Z

            .map_err(|_| RemoteError::InternalServerError)
    }

+    async fn send_name_endpoint(&mut self, label: String) -> Result<(), RemoteError> {


this is not updating the name on the actor, when after it is set

okdistribute requested review from b5, Copilot and dignifiedquire and removed request for b5 and dignifiedquire March 11, 2026 21:16

Copilot started reviewing on behalf of okdistribute March 11, 2026 21:16 View session

okdistribute changed the title ~~Endpoint labels~~ feat: add optional label for endpoints Mar 11, 2026

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Comment thread src/client.rs Outdated

Comment thread src/protocol.rs

Comment thread src/protocol.rs Outdated

Comment thread src/protocol.rs Outdated

okdistribute changed the title ~~feat: add optional label for endpoints~~ feat: add optional name for endpoints Mar 11, 2026

dignifiedquire force-pushed the rae/endpoint-labels branch from 505136d to 165238c Compare March 16, 2026 19:29

dignifiedquire changed the title ~~feat: add optional name for endpoints~~ feat!: add optional name for endpoints Mar 23, 2026

b5 force-pushed the rae/endpoint-labels branch from 610ba5f to c6ede8c Compare March 23, 2026 19:49

b5 changed the title ~~feat!: add optional name for endpoints~~ feat!(client): add optional label for endpoints Mar 23, 2026

okdistribute and others added 12 commits March 23, 2026 16:00

feat: Add an explicit optional label field to the endpoint

770fff0

add to examples

ab50010

fix lint

ea89c49

Update src/client.rs

ce6d3e5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update src/protocol.rs

b014f25

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update src/protocol.rs

8526f29

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update src/protocol.rs

50a1649

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fmt

5447792

remove chatgpt rec

f141e4b

add client labels back

2e99afa

fmt

518c5da

fix bad copilot rec

727e765

b5 changed the title ~~feat!(client): add optional label for endpoints~~ feat(client): add optional label for endpoints Mar 23, 2026

fix: auth before setting label

3634621

b5 force-pushed the rae/endpoint-labels branch from 5a9c89e to 52e6f88 Compare March 23, 2026 22:38

b5 requested a review from Copilot March 23, 2026 22:53

Copilot started reviewing on behalf of b5 March 23, 2026 22:53 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

dignifiedquire reviewed Mar 25, 2026

View reviewed changes

Comment thread .claude/settings.local.json Outdated

@@ -0,0 +1,8 @@

{

Copy link
Copy Markdown

Contributor

dignifiedquire Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lets not check these in please

dignifiedquire reviewed Mar 25, 2026

View reviewed changes

b5 added 2 commits April 9, 2026 11:56

refactor: use name instead of label

8745af8

refactor!: rpc protocol: LabelEndpoint -> NameEndpoint

2be4508

b5 force-pushed the rae/endpoint-labels branch from 5395400 to 2be4508 Compare April 9, 2026 20:47

more label -> name renaming

31ca9ba

dignifiedquire reviewed Apr 10, 2026

View reviewed changes

Comment thread src/client.rs

dignifiedquire reviewed Apr 10, 2026

View reviewed changes

Comment thread src/client.rs

dignifiedquire reviewed Apr 10, 2026

View reviewed changes

b5 and others added 4 commits April 10, 2026 09:26

cleanups

eaa08f8

refactor!: LabelEndpoint -> NameEndpoint

f8f0a54

apply more CR

e87ddf8

clippy

41f05be

dignifiedquire changed the title ~~feat(client): add optional label for endpoints~~ feat(client): add optional name for endpoints Apr 11, 2026

fixup validation

94e448d

dignifiedquire merged commit c716b3b into main Apr 11, 2026
24 of 25 checks passed

zachsmith1 mentioned this pull request Apr 15, 2026

feat: bump iroh-services to 0.13, add instance label datum-cloud/iroh-gateway#6

Merged

	panic!("label should fail for strings over 1024 bytes");
	panic!("label should fail for strings over 128 bytes");

	/// When this builder method is called, the provided label label is sent
	/// When this builder method is called, the provided label is sent

	.map_err(\|_\| Error::Other(anyhow!("sending ping request")))?;
	.map_err(\|_\| Error::Other(anyhow!("sending label read request")))?;

-    pub async fn set_label(&self, label: String) -> Result<(), Error> {
+    pub async fn set_label(&self, label: String) -> Result<(), Error> {
+        let len = label.as_bytes().len();
+        if len < 2 || len > 128 {
+            return Err(Error::Other(anyhow!(
+                "label length must be between 2 and 128 bytes (got {} bytes)",
+                len
+            )));
+        }

-                            let res = self.send_label_endpoint(label).await;
+                            let res = self.send_label_endpoint(label.clone()).await;
+                            if res.is_ok() {
+                                self.label = Some(label);
+                            }

	debug!(label=%label, "calling set label");
	debug!(label_len = label.len(), "calling set label");

Conversation

okdistribute commented Mar 11, 2026 • edited by b5 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Breaking Changes

Notes & open questions

Change checklist

Uh oh!

github-actions Bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dignifiedquire commented Mar 16, 2026

Uh oh!

okdistribute commented Mar 17, 2026

Uh oh!

b5 commented Mar 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dignifiedquire commented Mar 25, 2026

Uh oh!

b5 commented Apr 7, 2026

Uh oh!

dignifiedquire commented Apr 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

okdistribute commented Mar 11, 2026 •

edited by b5

Loading

github-actions Bot commented Mar 11, 2026 •

edited

Loading