feat(iroh-relay): Embeddable relay server #3832

lucksus · 2026-01-08T23:21:08Z

Description

This PR renders the iroh-relay server embeddable as a library by making RelayService public and adding a native axum integration around it, enabling the relay service to be integrated directly into axum applications as a standard route handler without requiring connection-level routing, separate ports, or reverse proxies.

Adds docs, examples and tests for all new and/or now public functions/structs.

Key changes:

Refactored relay internals (RelayedStream, Client, Actor, Clients) to be generic over stream types while maintaining backward compatibility
~~Added new axum feature and server::axum_integration module~~
~~Implemented AxumWebSocketAdapter that bridges axum's WebSocket to the relay's Stream/Sink traits~~
~~Created RelayState and relay_handler for easy integration into axum routers~~
~~Full relay protocol support including handshake, authentication, authorization, and client registration~~
Made all types public that are needed to have the Axum integration be done in an external crate

Breaking Changes

None. All changes are internal refactoring or new additions. The generic implementations are backward compatible with existing relay server usage through type aliases and preserved public APIs.

Notes & open questions

~~Rate limiting: Client-side rate limiting configuration is accepted but not fully enforced yet in the axum integration (similar limitation exists in the existing HTTP server integration)~~
TLS key export: AxumWebSocketAdapter implements ExportKeyingMaterial but returns None since axum's WebSocket doesn't support TLS key material export. This matches the behavior of non-TLS connections in the existing relay server.
~~Error handling: Axum WebSocket errors are wrapped in tokio_websockets::Error::Io variant for consistency with the relay's error handling~~
~~Testing: Integration tests verify both non-TLS and TLS scenarios with full end-to-end relay communication~~

Could We Reduce This?

We could potentially create a single public "escape hatch" function:

  pub async fn handle_custom_websocket<S>(
      stream: S,
      access_config: &AccessConfig,
      clients: &Clients,
  ) -> Result<()>
  where S: Stream + Sink + ExportKeyingMaterial

This would hide all the intermediate types and just expose one function. However, this would:

Remove flexibility (consuming crates couldn't customize the handshake or authorization logic)
Still require AccessConfig, Clients, and the trait bounds to be public

Change checklist

Self-review.
AI review
Documentation updates following the https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text, if relevant.
Tests added.
All breaking changes documented.
- N/A - No breaking changes to public API

This commit makes the following changes to enable embedding the iroh relay server directly into other HTTP servers: 1. Made RelayService public and exposed it from the server module 2. Made RelayService::new(), shutdown(), and handle_connection() public 3. Made Handlers public for constructing RelayService 4. Exported KeyCache publicly instead of pub(crate) These changes allow applications to: - Create a RelayService instance without spawning a full HTTP server - Integrate the relay service into existing axum/hyper-based HTTP servers - Use the relay service as a fallback handler for unmatched routes Breaking changes: None - only exposes previously private APIs Based on stable release v0.95.1

- Add axum as optional dependency - Create axum_integration module with relay_handler - Implement AxumWebSocketAdapter for Stream/Sink traits - Note: Full integration requires refactoring internal protocol code to be generic over WebSocket type

- Made RelayedStream generic over stream types - Updated Client and Actor to be generic - Made Clients::register() generic - Completed AxumWebSocketAdapter implementation - Implemented full relay protocol in handle_relay_websocket

- Wrap AccessConfig in Arc since it can't be cloned - Use Clients::default() instead of non-existent new() method - Fix error type conversions from axum::Error to std::io::Error - Fix AxumMessage::Binary to use Bytes directly instead of Vec<u8>

- Properly match on Poll results to convert error types - This fixes type mismatches between axum::Error and std::io::Error

StreamError is tokio_websockets::Error, not std::io::Error. Wrap std::io::Error in WsError::Io variant for proper type conversion.

…ements

matheus23

I was hoping we could get away with exposing some functions in iroh-relay required for making an integration with axum.

I feel strongly about not adding the axum dependency (even if it's optional).

I'm unsure about abstracting away the WebSocketStream inside RelayedStream. I think this can be achieved with axum::extract::ConnectInfo. If that ends up working, you even get to re-use more iroh-relay code.

iroh-relay/src/server/axum_integration.rs

iroh-relay/Cargo.toml

iroh-relay/src/server/axum_integration.rs

Also adds comments to now public types. All types needed to run the exact same axum_integration code in an external crate.

…server

Resolve Cargo.lock conflicts

matheus23

Just one general change, and then I'd say this is good to go.

I talked to the team, and we generally want to make it possible for users of iroh-relay to be embedded into axum or other webservers! :)

matheus23 · 2026-01-30T09:28:27Z

iroh-relay/src/server/clients.rs

+        S: Stream<Item = Result<bytes::Bytes, crate::protos::streams::StreamError>>
+            + Sink<bytes::Bytes, Error = crate::protos::streams::StreamError>
+            + Unpin


We already have BytesStreamSink in iroh-relay/src/proto/streams.rs. We should re-use this here.

matheus23 · 2026-01-30T09:29:07Z

iroh-relay/src/server/client.rs

+    S: Stream<Item = Result<bytes::Bytes, crate::protos::streams::StreamError>>
+        + Sink<bytes::Bytes, Error = crate::protos::streams::StreamError>
+        + Unpin,


We can use BytesStreamSink here, too.

matheus23 · 2026-01-30T09:35:06Z

There's also unfortunately more things that need to be made pub (and thus need comments). That's why the CI checks fail.

To fix the formatting CI check, run cargo make format with cargo-make installed.

matheus23 · 2026-01-30T09:35:34Z

The Wasm CI check should be fixed by updating to the Cargo.lock file used in main.

matheus23 · 2026-01-30T09:36:26Z

The netsim integration tests might currently fail, due to reasons unrelated to this PR IIRC. I'll keep an eye on this once you addressed the other CI issues.

lucksus · 2026-01-30T09:42:34Z

Great 🙂 I'll try to address the failing tests shortly

lucksus · 2026-01-30T16:08:12Z

Ok, everything is passing now except for the netsim integration tests.

matheus23 · 2026-01-31T08:08:45Z

Thank you for addressing CI. There are still two review comments from myself that you've missed @lucksus

lucksus added 16 commits January 8, 2026 16:50

Complete axum integration for iroh-relay

b15f775

- Made RelayedStream generic over stream types - Updated Client and Actor to be generic - Made Clients::register() generic - Completed AxumWebSocketAdapter implementation - Implemented full relay protocol in handle_relay_websocket

Fix axum integration compilation errors

9e307db

- Wrap AccessConfig in Arc since it can't be cloned - Use Clients::default() instead of non-existent new() method - Fix error type conversions from axum::Error to std::io::Error - Fix AxumMessage::Binary to use Bytes directly instead of Vec<u8>

Fix Poll error type conversions in axum adapter

1d64898

- Properly match on Poll results to convert error types - This fixes type mismatches between axum::Error and std::io::Error

Fix error type conversions to use tokio_websockets::Error

9ae65e1

StreamError is tokio_websockets::Error, not std::io::Error. Wrap std::io::Error in WsError::Io variant for proper type conversion.

Remove unused rate limit config from RelayState and clean up use stat…

0bf532b

…ements

Make TlsConfig public and add doc comments

89e4d30

fmt

8d6a63c

Tests for axum integration

5e2a033

Make new doc examples run

ffbbac7

Fix build of adjacent test

01031e1

fmt

79d130e

More efficient loop pattern in websocket poll_next

3fde2d3

fmt

d15e010

Merge branch 'main' into embeddable-relay-server

3f69150

lucksus mentioned this pull request Jan 8, 2026

feat(bootstrap_srv) iroh-relay integrated in axum routes holochain/kitsune2#432

Open

n0bot bot added this to iroh Jan 9, 2026

github-project-automation bot moved this to 🏗 In progress in iroh Jan 9, 2026

matheus23 requested changes Jan 9, 2026

View reviewed changes

iroh-relay/src/server/axum_integration.rs Outdated Show resolved Hide resolved

iroh-relay/Cargo.toml Outdated Show resolved Hide resolved

iroh-relay/src/server/axum_integration.rs Outdated Show resolved Hide resolved

matheus23 changed the title ~~feat(iroh-relay) Embeddable relay server~~ feat(iroh-relay): Embeddable relay server Jan 9, 2026

lucksus added 5 commits January 9, 2026 14:28

Remove axum integration and make needed types public

1b62149

Also adds comments to now public types. All types needed to run the exact same axum_integration code in an external crate.

Merge branch 'embeddable-relay-server-v0.95.1' into embeddable-relay-…

58c2d3d

…server

Cargo.lock: remove unused dependencies

dd23788

Merge remote-tracking branch 'upstream/main'

df4744f

Merge branch 'main' into embeddable-relay-server

818f3c7

Resolve Cargo.lock conflicts

ThetaSinner mentioned this pull request Jan 16, 2026

Authentication service holochain/kitsune2#425

Open

matheus23 requested changes Jan 30, 2026

View reviewed changes

lucksus added 2 commits January 30, 2026 13:40

Merge branch 'main' into embeddable-relay-server

1515e4b

chore: fix docs checks

d00ce07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(iroh-relay): Embeddable relay server #3832

feat(iroh-relay): Embeddable relay server #3832

lucksus commented Jan 8, 2026 •

edited

Loading

Uh oh!

matheus23 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matheus23 left a comment •

edited

Loading

Uh oh!

matheus23 Jan 30, 2026

Uh oh!

matheus23 Jan 30, 2026

Uh oh!

matheus23 commented Jan 30, 2026

Uh oh!

matheus23 commented Jan 30, 2026 •

edited

Loading

Uh oh!

matheus23 commented Jan 30, 2026

Uh oh!

lucksus commented Jan 30, 2026

Uh oh!

lucksus commented Jan 30, 2026

Uh oh!

matheus23 commented Jan 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(iroh-relay): Embeddable relay server #3832

Are you sure you want to change the base?

feat(iroh-relay): Embeddable relay server #3832

Conversation

lucksus commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Key changes:

Breaking Changes

Notes & open questions

Could We Reduce This?

Change checklist

Uh oh!

matheus23 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matheus23 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matheus23 Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

matheus23 Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

matheus23 commented Jan 30, 2026

Uh oh!

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

Uh oh!

Uh oh!

matheus23 commented Jan 30, 2026

Uh oh!

lucksus commented Jan 30, 2026

Uh oh!

lucksus commented Jan 30, 2026

Uh oh!

matheus23 commented Jan 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lucksus commented Jan 8, 2026 •

edited

Loading

matheus23 left a comment •

edited

Loading

matheus23 commented Jan 30, 2026 •

edited

Loading