feat!: update relay protocol to iroh-relay-v2, add new Health frame, test protocol update mechanism by Frando · Pull Request #3955 · n0-computer/iroh

Frando · 2026-02-18T09:46:31Z

Description

This branch add a iroh-relay-v2 protocol. The only changes to the iroh-relay-v1 protocol are:

removed Health frame (id 11) with string payload
added Status frame (id 13) with binary-encoded enum payload that can be extended with further variants or payloads
From now on, unknown frames will be ignored in iroh (instead of erroring out)

The actual change is thus quite minor, but serves as a real-world test for our protocol negotiation.

The PR also fixes a bug in how the relay server parsed the supported protocols; it is harmless because all existing deployments support a single version anyway, but good to fix now.

Everything is fully backwards-compatible on the wire (old clients can talk to new relays, and new clients can talk to old relays).

Breaking Changes

iroh_relay::http::RELAY_PROTOCOL_VERSION has been removed. The relay protocol now supports version negotiation between client and server. Use iroh_relay::http::ProtocolVersion instead. For the previous constant value, use ProtocolVersion::V1.to_str().
iroh_relay::server::client::Config has a new field protocol_version: ProtocolVersion.
iroh_relay::protos::relay::RelayToClientMsg has a new Status(Status) variant and the existing Health variant is deprecated. Clients should handle RelayToClientMsg::Status for connection health information. The Health variant is still sent by V1 relay servers but should not be relied upon going forward.

Notes & open questions

Change checklist

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

…ame id connects

This reverts commit a68a89a.

…-close

matheus23

Let's ship this - at the very least for the important bugfix.

Let's discuss changes to code structure later and open another PR for those if need be.

matheus23 · 2026-04-15T09:46:49Z

From now on, unknown frames will be ignored in iroh (instead of erroring out)

Hmmm. I'm sorry I just reread the PR description again and that's why I'm coming back to this.

We should reconsider this (after merging!). We can always change this IMO, that's not a problem, as long as we change this before we do the next breaking change without adding another relay protocol version (and I think we'll always want to use a new protocol version even if we add optional frames).

This is contrary to what e.g. QUIC does: If you receive a frame you don't know - that's a protocol violation.

We should really think through what this means in various cases again before we do the next protocol change.

Frando · 2026-04-16T07:23:16Z

This is contrary to what e.g. QUIC does: If you receive a frame you don't know - that's a protocol violation.

Good point. I think you are right and we should fix that. I'll look into it.

…ror (#4127) ## Description #3955 added a new relay protocol version. This PR fixes the contract: We should only allow frames that are defined for the negotiated protocol version, and abort if we receive a frame not allowed in the negotiated version. ## Breaking Changes None ## 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.

This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [iroh](https://github.com/n0-computer/iroh) | workspace.dependencies | minor | `0.97.0` → `0.98.0` | --- ### Release Notes <details> <summary>n0-computer/iroh (iroh)</summary> ### [`v0.98.0`](https://github.com/n0-computer/iroh/blob/HEAD/CHANGELOG.md#0980---2026-04-17) [Compare Source](n0-computer/iroh@v0.97.0...v0.98.0) ##### ⛰️ Features - *(iroh)* Avoid allocations in `AddrFilter` ([#4018](n0-computer/iroh#4018)) - ([d26cbd2](n0-computer/iroh@d26cbd2)) - *(iroh)* Pluggable crypto backends ([#3992](n0-computer/iroh#3992)) - ([387c2e4](n0-computer/iroh@387c2e4)) - *(iroh)* Add ability to configure external addrs ([#4098](n0-computer/iroh#4098)) - ([372aab9](n0-computer/iroh@372aab9)) - *(iroh)* Do not advertise deprecated IPv6 addrs ([#4106](n0-computer/iroh#4106)) - ([b2b1d46](n0-computer/iroh@b2b1d46)) - *(iroh-relay)* Expose more metrics on the relay server ([#4085](n0-computer/iroh#4085)) - ([ee844a6](n0-computer/iroh@ee844a6)) - Expose the new fn decrypt on noq. ([#4002](n0-computer/iroh#4002)) - ([197d8db](n0-computer/iroh@197d8db)) - Update noq and net-tools to latest ([#4088](n0-computer/iroh#4088)) - ([159a5cf](n0-computer/iroh@159a5cf)) - Rate limiting in router ([#3951](n0-computer/iroh#3951)) - ([ea7a634](n0-computer/iroh@ea7a634)) - Update relay protocol to iroh-relay-v2, add new Health frame, test protocol update mechanism ([#3955](n0-computer/iroh#3955)) - ([0a22d76](n0-computer/iroh@0a22d76)) - Update to noq\@0.18 ([#4121](n0-computer/iroh#4121)) - ([72e4538](n0-computer/iroh@72e4538)) - Vendor pkarr implementation ([#4026](n0-computer/iroh#4026)) - ([3ab6222](n0-computer/iroh@3ab6222)) ##### 🐛 Bug Fixes - *(ci)* Install cmake and nasm for aws-lc-sys on Windows ([#4032](n0-computer/iroh#4032)) - ([405de1d](n0-computer/iroh@405de1d)) - *(iroh)* \[**breaking**] Faster relay health check after network change ([#4041](n0-computer/iroh#4041)) - ([b11b0eb](n0-computer/iroh@b11b0eb)) - *(iroh)* `Endpoint::online` should only return once connected to a relay ([#4115](n0-computer/iroh#4115)) - ([3424c6d](n0-computer/iroh@3424c6d)) - *(iroh)* \[**breaking**] Don't stop address lookup when one service errors ([#4126](n0-computer/iroh#4126)) - ([321443d](n0-computer/iroh@321443d)) - *(iroh)* Don't falsely report home relay as connected on change ([#4136](n0-computer/iroh#4136)) - ([1b04d34](n0-computer/iroh@1b04d34)) - *(iroh-relay)* Send EndpointGone message to the right peers ([#4079](n0-computer/iroh#4079)) - ([6be4b3c](n0-computer/iroh@6be4b3c)) - *(iroh-relay)* Treat frames not allowed in a protocol version as error ([#4127](n0-computer/iroh#4127)) - ([1c92a39](n0-computer/iroh@1c92a39)) - Improve holepunching after network changes ([#3928](n0-computer/iroh#3928)) - ([cc21f51](n0-computer/iroh@cc21f51)) - Poll for default route with exponential backoff after network change ([#4039](n0-computer/iroh#4039)) - ([dc01a77](n0-computer/iroh@dc01a77)) - Modify test\_ip\_wins\_over\_custom so it is a noop if no ip transport is… ([#4048](n0-computer/iroh#4048)) - ([b141e02](n0-computer/iroh@b141e02)) - Increase path idle timeouts and configure relay paths ([#4038](n0-computer/iroh#4038)) - ([eba6afc](n0-computer/iroh@eba6afc)) - Handle wine properly ([#3902](n0-computer/iroh#3902)) - ([8bf7002](n0-computer/iroh@8bf7002)) - Set default crypto provider for iroh-relay binary ([#4087](n0-computer/iroh#4087)) - ([2433645](n0-computer/iroh@2433645)) ##### 🚜 Refactor - *(iroh)* \[**breaking**] Improve address lookup registry ([#4130](n0-computer/iroh#4130)) - ([481c870](n0-computer/iroh@481c870)) - *(iroh, iroh-relay)* \[**breaking**] Mark public types as non\_exhaustive ([#4107](n0-computer/iroh#4107)) - ([86d3ac6](n0-computer/iroh@86d3ac6)) - *(iroh-base)* \[**breaking**] Don't expose third-party error types in iroh-base ([#4073](n0-computer/iroh#4073)) - ([d803dfe](n0-computer/iroh@d803dfe)) - *(iroh-base)* \[**breaking**] Rename `CustomAddr::as_vec` to `CustomAddr::to_vec` and improve docs ([#4074](n0-computer/iroh#4074)) - ([3077f17](n0-computer/iroh@3077f17)) - *(iroh-base)* \[**breaking**] Change `SecretKey::generate` to not take an `Rng` arg ([#4075](n0-computer/iroh#4075)) - ([36781ad](n0-computer/iroh@36781ad)) - *(iroh-relay)* \[**breaking**] Proper timeouts on relay connections ([#4083](n0-computer/iroh#4083)) - ([79bb0e4](n0-computer/iroh@79bb0e4)) - Use latest noq api ([#4057](n0-computer/iroh#4057)) - ([8af8370](n0-computer/iroh@8af8370)) - Remove needless alloc in relay server ([#4084](n0-computer/iroh#4084)) - ([40b50a1](n0-computer/iroh@40b50a1)) - Move to\_z32/from\_z32 into iroh-base and remove EndpointIdExt trait ([#4133](n0-computer/iroh#4133)) - ([382bf36](n0-computer/iroh@382bf36)) ##### 🧪 Testing - *(iroh)* Add patchbay test matrix for switching uplinks ([#4095](n0-computer/iroh#4095)) - ([d72f1cb](n0-computer/iroh@d72f1cb)) - *(iroh)* Add more patchbay tests and improve existing tests ([#4118](n0-computer/iroh#4118)) - ([f5ec24a](n0-computer/iroh@f5ec24a)) - *(iroh)* Improve patchbay NAT matrix ([#4135](n0-computer/iroh#4135)) - ([2ad657a](n0-computer/iroh@2ad657a)) - Fix ip\_wins\_over\_custom flakiness ([#4047](n0-computer/iroh#4047)) - ([174b58b](n0-computer/iroh@174b58b)) - Add patchbay tests ([#3986](n0-computer/iroh#3986)) - ([2ab1240](n0-computer/iroh@2ab1240)) - Improve patchbay test setup ([#4078](n0-computer/iroh#4078)) - ([9b01751](n0-computer/iroh@9b01751)) - Minor patchbay test improvements ([#4091](n0-computer/iroh#4091)) - ([0cc2441](n0-computer/iroh@0cc2441)) ##### ⚙️ Miscellaneous Tasks - *(ci)* Move more CI jobs to self hosted runners ([#4072](n0-computer/iroh#4072)) - ([54442c3](n0-computer/iroh@54442c3)) - *(iroh)* Update hickory to 0.26.0-beta.4 and use exact-version deps for prereleased crates ([#4117](n0-computer/iroh#4117)) - ([f829593](n0-computer/iroh@f829593)) - *(iroh-bench)* Allow configuring the number of worker threads for each endpoint in iroh-bench ([#4063](n0-computer/iroh#4063)) - ([065b448](n0-computer/iroh@065b448)) - Update to netwatch\@0.16 and portmapper\@0.16 ([#4128](n0-computer/iroh#4128)) - ([24efedf](n0-computer/iroh@24efedf)) - Fix changelog generation - ([08c6454](n0-computer/iroh@08c6454)) ##### Deps - *(iroh)* Update patchbay to 0.5 ([#4097](n0-computer/iroh#4097)) - ([811a062](n0-computer/iroh@811a062)) - Bump noq and net-tools ([#4113](n0-computer/iroh#4113)) - ([184e378](n0-computer/iroh@184e378)) ##### Examples - *(iroh)* Allow to configure the receive window in the transfer example ([#4082](n0-computer/iroh#4082)) - ([c865251](n0-computer/iroh@c865251)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Reviewed-on: https://git.erwanleboucher.dev/eleboucher/towonel/pulls/19

Frando added 23 commits February 9, 2026 14:56

refactor: add Close frame to relay protocol

a68a89a

fix test

b6f08b7

docs

e15cd96

fixup

6d80b55

fixup

8a0e0b2

fixup tests

1668159

chore: cleanup

5daad90

fix: keep relay connections alive even when a new endpoint with the s…

2ce353e

…ame id connects

Revert "refactor: add Close frame to relay protocol"

8cd8d3a

This reverts commit a68a89a.

fixup test

f4322c4

fixup

485acd4

Merge branch 'main' into Frando/refactor-relay-close

32a45e7

cleanup errors

cfb4403

more cleanup

1e74662

chore: clippy

b2112f8

improve naming

be5cd37

Merge branch 'main' into Frando/refactor-relay-close

d3402af

fix: don't rely on timings alone for established relay connection

a2002e5

Merge branch 'main' into Frando/refactor-relay-close

0bbb6cd

refactor: reactive inactive client if active client disconnects

79501bf

add test

265c6e1

Merge remote-tracking branch 'origin/main' into Frando/refactor-relay…

cf8f92e

…-close

cleanup

04cd398

Frando force-pushed the Frando/relay-protocol-v2 branch 2 times, most recently from dbda584 to 89da514 Compare February 18, 2026 09:47

Merge remote-tracking branch 'origin/main' into Frando/refactor-relay…

7cf0ed9

…-close

Frando force-pushed the Frando/refactor-relay-close branch from b420ff2 to 7cf0ed9 Compare February 18, 2026 09:48

Frando added 2 commits February 18, 2026 10:49

refactor: add iroh-relay-v2 protocol

ef15092

cleanup, add test

52a4783

Frando force-pushed the Frando/relay-protocol-v2 branch from 89da514 to 52a4783 Compare February 18, 2026 09:50

fixup wasm

aecabee

matheus23 reviewed Mar 5, 2026

View reviewed changes

Comment thread iroh-relay/src/http.rs Outdated

fix: wrong comment

e3bb955

Frando marked this pull request as ready for review March 6, 2026 18:56

Frando requested a review from matheus23 March 6, 2026 18:56

Frando added 3 commits March 9, 2026 10:21

chore: clippy

a995f21

Merge remote-tracking branch 'origin/main' into Frando/relay-protocol-v2

bc27dc1

chore: clippy

3440fcd

matheus23 approved these changes Mar 9, 2026

View reviewed changes

dignifiedquire modified the milestones: iroh: v0.97, iroh: v0.98 Mar 10, 2026

Frando added 5 commits April 14, 2026 15:44

Merge remote-tracking branch 'origin/main' into Frando/relay-protocol-v2

9034c67

fixup after merge

b8a1c22

chore: fmt

5ba3dad

Merge branch 'main' into Frando/relay-protocol-v2

cc52f30

fix comments

374a3c0

matheus23 reviewed Apr 15, 2026

View reviewed changes

Comment thread iroh-relay/src/http.rs Outdated

Frando added 4 commits April 15, 2026 09:35

Merge remote-tracking branch 'origin/main' into Frando/relay-protocol-v2

a80f52b

cleanups

1f6b32e

fixup doclinks

8cd8d14

chore: bump rustls-webpki for cargo deny

39e9fed

Frando merged commit 0a22d76 into main Apr 15, 2026
37 of 40 checks passed

github-project-automation Bot moved this from 👍 Ready to ✅ Done in iroh Apr 15, 2026

Frando changed the title ~~feat: update relay protocol to iroh-relay-v2, add new Health frame, test protocol update mechanism~~ feat!: update relay protocol to iroh-relay-v2, add new Health frame, test protocol update mechanism Apr 15, 2026

matheus23 deleted the Frando/relay-protocol-v2 branch April 16, 2026 08:32

Frando mentioned this pull request Apr 16, 2026

fix(iroh-relay): treat frames not allowed in a protocol version as error #4127

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat!: update relay protocol to iroh-relay-v2, add new Health frame, test protocol update mechanism#3955

feat!: update relay protocol to iroh-relay-v2, add new Health frame, test protocol update mechanism#3955
Frando merged 50 commits intomainfrom
Frando/relay-protocol-v2

Frando commented Feb 18, 2026 •

edited

Loading

Uh oh!

Uh oh!

matheus23 left a comment

Uh oh!

Uh oh!

matheus23 commented Apr 15, 2026 •

edited

Loading

Uh oh!

Uh oh!

Frando commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Frando commented Feb 18, 2026 • edited 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!

Uh oh!

matheus23 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

matheus23 commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Frando commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Frando commented Feb 18, 2026 •

edited

Loading

matheus23 commented Apr 15, 2026 •

edited

Loading