Skip to content

aeronet_iroh: add PathReport session telemetry and prompt path-migration updates - #102

Open
baadc0de wants to merge 1 commit into
aecsocket:mainfrom
baadc0de:iroh-path-report
Open

aeronet_iroh: add PathReport session telemetry and prompt path-migration updates#102
baadc0de wants to merge 1 commit into
aecsocket:mainfrom
baadc0de:iroh-path-report

Conversation

@baadc0de

Copy link
Copy Markdown

What

Adds per-session path telemetry to aeronet_iroh sessions, and makes
relay→direct path migration visible to the ECS world within a frame instead
of up to 100 ms late.

PathReport component

New session::PathReport component, inserted when a session connects and
updated by the IO layer alongside the existing SelectedPath/PacketRtt:

pub struct PathReport {
    pub kind: PathKind,              // Direct | Relayed { relay: RelayUrl }
    pub rtt: Duration,               // RTT of the currently selected path
    pub connected_at: Instant,       // when the session connected
    pub direct_since: Option<Instant>,
}

impl PathReport {
    pub fn time_to_direct(&self) -> Option<Duration>; // direct_since - connected_at
}

SelectedPath already exposes the raw TransportAddr; PathReport adds the
two things games actually want to graph and gate on:

  1. relay-vs-direct as a first-class enum (no per-frame matching on
    TransportAddr variants), and
  2. time-to-direct-path — how long hole punching took. This is the key
    NAT-traversal health metric for peered sessions (iroh's own baseline is
    ~90% direct); without it you can only observe the current path, never
    the migration latency.

Prompt migration updates

The backend meta loop previously polled path state on a fixed 100 ms
interval, so a relay→direct migration could surface up to a full interval
late. It now also wakes on Connection::path_events()
(PathEvent::Selected/Closed), so PathReport, SelectedPath, and
PacketRtt update on the next frame after a migration.

This needs no new dependencies and works on WASM too: PathEventStream is
not a fused stream, but StreamExt::fuse() wraps any stream into a
FusedStream, so plain futures::select! can poll it.

test-utils feature

New optional feature exposing test_utils::run_test_relay(): an in-process
loopback Iroh relay (HTTPS + QUIC, self-signed certs via
iroh-relay/test-utils) returning (RelayMap, RelayUrl, Server). Lets
downstream crates write offline integration tests that exercise the real
relay path — including hole punching — with no external network.

Used by the new tests/relay_path_report.rs: two endpoints over the
loopback relay connect, exchange datagrams both ways, and assert
PathReport populates with a sane path kind, non-zero RTT, and (when a
direct path is selected) a time_to_direct.

Why

We're building a P2P multiplayer stack on aeronet + iroh
(Orrery) where relay-vs-direct path
and time-to-direct are first-class session telemetry: the coordinator uses
them to size islands and to detect degraded peers. Every P2P game on this
transport will want the same signals; they belong in the IO layer.

Compatibility

  • Purely additive: new component, new feature (default-off), no changes to
    existing public API or behavior (besides the faster telemetry updates
    noted above).
  • No new required dependencies — the prompt-update path uses only futures,
    which the crate already depends on, and works on WASM.
  • test-utils pulls in iroh-relay with server + test-utils features,
    only when enabled.

Validation

  • cargo clippy -p aeronet_iroh --all-targets --all-features -- -D warnings — clean
  • cargo test -p aeronet_iroh --all-features — all pass (existing
    session.rs tests, new relay_path_report.rs, doctests)
  • cargo doc -p aeronet_iroh --no-deps --all-features — clean
  • cargo build -p aeronet_iroh --examples — clean

…ion updates

Add a PathReport component to iroh sessions exposing relay-vs-direct path
kind, RTT, and time-to-direct-path, and wake the backend meta loop on
Connection::path_events() so relay-to-direct migration is reported within a
frame instead of up to 100ms late (native targets; WASM keeps the plain
interval since PathEventStream is not fused).

Also add a test-utils feature with run_test_relay(), an in-process loopback
Iroh relay helper, and an end-to-end test exercising datagram exchange and
PathReport over that relay.
@aecsocket

Copy link
Copy Markdown
Owner

re test_utils, would rather have that as a separate file in tests that you include! or treat as a mod, rather than a cargo feature

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants