Skip to content

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

Merged
Frando merged 50 commits intomainfrom
Frando/relay-protocol-v2
Apr 15, 2026
Merged

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

Conversation

@Frando
Copy link
Copy Markdown
Member

@Frando Frando commented Feb 18, 2026

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.

@Frando Frando force-pushed the Frando/relay-protocol-v2 branch 2 times, most recently from dbda584 to 89da514 Compare February 18, 2026 09:47
@Frando Frando force-pushed the Frando/refactor-relay-close branch from b420ff2 to 7cf0ed9 Compare February 18, 2026 09:48
@Frando Frando force-pushed the Frando/relay-protocol-v2 branch from 89da514 to 52a4783 Compare February 18, 2026 09:50
Comment thread iroh-relay/src/http.rs Outdated
@Frando Frando marked this pull request as ready for review March 6, 2026 18:56
@Frando Frando requested a review from matheus23 March 6, 2026 18:56
Copy link
Copy Markdown
Member

@matheus23 matheus23 left a comment

Choose a reason for hiding this comment

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

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.

Comment thread iroh-relay/src/http.rs Outdated
@matheus23
Copy link
Copy Markdown
Member

matheus23 commented Apr 15, 2026

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 Frando merged commit 0a22d76 into main Apr 15, 2026
37 of 40 checks passed
@github-project-automation github-project-automation bot moved this from 👍 Ready to ✅ Done in iroh Apr 15, 2026
@Frando 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
@Frando
Copy link
Copy Markdown
Member Author

Frando commented Apr 16, 2026

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.

@matheus23 matheus23 deleted the Frando/relay-protocol-v2 branch April 16, 2026 08:32
dignifiedquire pushed a commit that referenced this pull request Apr 16, 2026
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: ✅ Done

Development

Successfully merging this pull request may close these issues.

4 participants