feat(p2p): Phase 4 cross-relay direct calling over federation
Teaches the relay pair to route direct-call signaling across an
existing federation link. Alice on Relay A can now place a direct
call to Bob on Relay B if A and B are federation peers — the
wire protocol, call registry, and signal dispatch all learn to
track and route the cross-relay flow.
Phase 3.5's dual-path QUIC race then carries the media directly
peer-to-peer using the advertised reflex addrs, with zero
changes needed on the client side.
## Wire protocol (wzp-proto)
New `SignalMessage::FederatedSignalForward { inner, origin_relay_fp }`
envelope variant, appended at end of enum — JSON serde is
name-tagged so pre-Phase-4 relays just log "unknown variant" and
drop it. 2 new roundtrip tests (any-inner nesting + single
DirectCallOffer case).
## Call registry (wzp-relay)
`DirectCall.peer_relay_fp: Option<String>` — federation TLS fp
of the peer relay that forwarded the offer/answer for this call.
`None` on local calls, `Some` on cross-relay. Used by the answer
path to route the reply back through the same federation link
instead of trying (and failing) to deliver via local signal_hub.
New `set_peer_relay_fp` setter + 1 new unit test.
## FederationManager (wzp-relay)
Three new methods:
- `local_tls_fp()` — exposes the relay's own federation TLS fp
so main.rs can build `origin_relay_fp` fields.
- `broadcast_signal(msg) -> usize` — fan out any signal message
(in practice `FederatedSignalForward`) to every active peer
link, returning the reach count. Used when Relay A doesn't
know which peer has the target fingerprint.
- `send_signal_to_peer(fp, msg)` — targeted send for the reply
path where the registry already knows which peer relay to
hit.
Plus a new `cross_relay_signal_tx: Mutex<Option<Sender<...>>>`
field that `set_cross_relay_tx()` wires at startup so the
federation `handle_signal` can push unwrapped inner messages
into the main signal dispatcher.
## Federation handle_signal (wzp-relay)
New match arm for `FederatedSignalForward`:
- Loop prevention: drops forwards whose `origin_relay_fp` equals
this relay's own fp (prevents A→B→A echo loops without needing
TTL yet).
- Otherwise pulls the inner message out and pushes it through
`cross_relay_signal_tx` so the main loop's dispatcher task
handles it as if it had arrived locally.
## Main signal loop (wzp-relay)
### DirectCallOffer when target not local
Before falling through to Hangup, try the federation path:
- Wrap the offer in `FederatedSignalForward` with
`origin_relay_fp = this relay's tls_fp`
- `fm.broadcast_signal(forward)` — returns peer count
- If any peers reached, stash the call in local registry with
`caller_reflexive_addr` set, `peer_relay_fp` still None
(broadcast — the answer-side will identify itself when it
replies)
- Send `CallRinging` to caller immediately for UX feedback
- Only if no federation or no peers → legacy Hangup path
### DirectCallAnswer when peer is remote
- Registry lookup now reads both `peer_fingerprint` and
`peer_relay_fp` in one acquisition
- If `peer_relay_fp.is_some()`:
* Reject → forward a `Hangup` over federation via
`send_signal_to_peer` instead of local signal_hub
* Accept → wrap the raw answer in `FederatedSignalForward`,
route to the specific origin peer, then emit the LOCAL
CallSetup to our callee with `peer_direct_addr =
caller_reflexive_addr` (caller is remote; this side only
has the callee)
- If `peer_relay_fp.is_none()` → existing Phase 3 same-relay
path with both CallSetups (caller + callee)
### Cross-relay signal dispatcher task
New long-running task reading `(inner, origin_relay_fp)` from
`cross_relay_rx`. In Phase 4 MVP handles:
- `DirectCallOffer` — if target is local, create the call in
the registry with `peer_relay_fp = origin_relay_fp`, stash
caller addr, deliver offer to local callee. If target isn't
local, drop (no multi-hop in Phase 4 MVP).
- `DirectCallAnswer` — look up local caller by call_id, stash
callee addr, forward raw answer to local caller via
signal_hub, emit local CallSetup with `peer_direct_addr =
callee_reflexive_addr` (peer is local now; this side only
has the caller).
- `CallRinging` — best-effort forward to local caller for UX.
- `Hangup` — logged for now; Phase 4.1 will target by call_id.
## Integration tests
`crates/wzp-relay/tests/cross_relay_direct_call.rs` — 3 tests
that reproduce the main.rs cross-relay dispatcher logic inline
and assert the invariants without spinning up real binaries:
1. `cross_relay_offer_forwards_and_stashes_peer_relay_fp` —
Relay A gets Alice's offer, broadcasts. Relay B's dispatcher
creates the call with `peer_relay_fp = relay_a_tls_fp`.
2. `cross_relay_answer_crosswires_peer_direct_addrs` — full
round trip; both CallSetups (one on each relay) carry the
OTHER party's reflex addr.
3. `cross_relay_loop_prevention_drops_self_sourced_forward` —
explicit loop-prevention check.
Full workspace test goes from 413 → 419 passing. Clippy clean
on touched files.
## Non-goals (deferred to Phase 4.1+)
- Relay-mediated media fallback across federation — if P2P
direct fails (symmetric NAT on either side), the call errors
out with "no media path". Making the existing federation
media pipeline carry ephemeral call-<id> rooms is the Phase
4.1 lift.
- Multi-hop federation (A → B → C). Phase 4 MVP supports a
direct federation link between A and B only.
- Fingerprint → peer-relay routing gossip.
PRD: .taskmaster/docs/prd_phase4_cross_relay_p2p.txt
Tasks: 70-78 all completed
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -820,6 +820,38 @@ pub enum SignalMessage {
|
||||
ReflectResponse {
|
||||
observed_addr: String,
|
||||
},
|
||||
|
||||
// ── Phase 4: cross-relay direct-call signaling ────────────────────
|
||||
|
||||
/// Phase 4: relay-to-relay envelope for forwarding direct-call
|
||||
/// signaling across a federation link. When Alice on Relay A
|
||||
/// sends a `DirectCallOffer` for Bob whose fingerprint isn't
|
||||
/// in A's local SignalHub, Relay A wraps the offer in this
|
||||
/// envelope and broadcasts it over every active federation
|
||||
/// peer link. Whichever peer has Bob registered unwraps the
|
||||
/// inner message and delivers it locally.
|
||||
///
|
||||
/// Never originated by clients — only relays create and
|
||||
/// consume this variant.
|
||||
///
|
||||
/// Loop prevention: the receiving relay drops any forward
|
||||
/// where `origin_relay_fp` matches its own federation TLS
|
||||
/// fingerprint. With broadcast-to-all-peers this prevents
|
||||
/// A→B→A echo loops; proper TTL + dedup will land when
|
||||
/// multi-hop federation is added (Phase 4.2).
|
||||
FederatedSignalForward {
|
||||
/// The signal message being forwarded
|
||||
/// (`DirectCallOffer`, `DirectCallAnswer`, `CallRinging`,
|
||||
/// `Hangup`, ...). Boxed because `SignalMessage` is
|
||||
/// relatively large and JSON serde handles recursion
|
||||
/// cleanly.
|
||||
inner: Box<SignalMessage>,
|
||||
/// Federation TLS fingerprint of the sending relay.
|
||||
/// Used (a) for loop prevention by the receiver and (b)
|
||||
/// to route the peer's reply back through the same
|
||||
/// federation link via `send_signal_to_peer`.
|
||||
origin_relay_fp: String,
|
||||
},
|
||||
}
|
||||
|
||||
/// How the callee responds to a direct call.
|
||||
@@ -988,6 +1020,82 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn federated_signal_forward_roundtrip() {
|
||||
// Wrap a DirectCallOffer inside FederatedSignalForward and
|
||||
// prove both directions of serde preserve every field.
|
||||
let inner = SignalMessage::DirectCallOffer {
|
||||
caller_fingerprint: "alice".into(),
|
||||
caller_alias: Some("Alice".into()),
|
||||
target_fingerprint: "bob".into(),
|
||||
call_id: "c1".into(),
|
||||
identity_pub: [1u8; 32],
|
||||
ephemeral_pub: [2u8; 32],
|
||||
signature: vec![3u8; 64],
|
||||
supported_profiles: vec![],
|
||||
caller_reflexive_addr: Some("192.0.2.1:4433".into()),
|
||||
};
|
||||
let forward = SignalMessage::FederatedSignalForward {
|
||||
inner: Box::new(inner),
|
||||
origin_relay_fp: "relay-a-tls-fp".into(),
|
||||
};
|
||||
let json = serde_json::to_string(&forward).unwrap();
|
||||
let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
|
||||
match decoded {
|
||||
SignalMessage::FederatedSignalForward { inner, origin_relay_fp } => {
|
||||
assert_eq!(origin_relay_fp, "relay-a-tls-fp");
|
||||
match *inner {
|
||||
SignalMessage::DirectCallOffer {
|
||||
caller_fingerprint,
|
||||
target_fingerprint,
|
||||
caller_reflexive_addr,
|
||||
..
|
||||
} => {
|
||||
assert_eq!(caller_fingerprint, "alice");
|
||||
assert_eq!(target_fingerprint, "bob");
|
||||
assert_eq!(caller_reflexive_addr.as_deref(), Some("192.0.2.1:4433"));
|
||||
}
|
||||
_ => panic!("inner was not DirectCallOffer after roundtrip"),
|
||||
}
|
||||
}
|
||||
_ => panic!("outer was not FederatedSignalForward"),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn federated_signal_forward_can_nest_any_inner() {
|
||||
// Sanity check that every direct-call signaling variant
|
||||
// we intend to forward survives being boxed + re-serialized.
|
||||
let cases: Vec<SignalMessage> = vec![
|
||||
SignalMessage::DirectCallAnswer {
|
||||
call_id: "c1".into(),
|
||||
accept_mode: CallAcceptMode::AcceptTrusted,
|
||||
identity_pub: None,
|
||||
ephemeral_pub: None,
|
||||
signature: None,
|
||||
chosen_profile: None,
|
||||
callee_reflexive_addr: Some("198.51.100.9:4433".into()),
|
||||
},
|
||||
SignalMessage::CallRinging { call_id: "c1".into() },
|
||||
SignalMessage::Hangup { reason: HangupReason::Normal },
|
||||
];
|
||||
for inner in cases {
|
||||
let inner_disc = std::mem::discriminant(&inner);
|
||||
let forward = SignalMessage::FederatedSignalForward {
|
||||
inner: Box::new(inner),
|
||||
origin_relay_fp: "r".into(),
|
||||
};
|
||||
let json = serde_json::to_string(&forward).unwrap();
|
||||
let decoded: SignalMessage = serde_json::from_str(&json).unwrap();
|
||||
match decoded {
|
||||
SignalMessage::FederatedSignalForward { inner, .. } => {
|
||||
assert_eq!(std::mem::discriminant(&*inner), inner_disc);
|
||||
}
|
||||
_ => panic!("outer variant lost"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn hole_punching_optional_fields_roundtrip() {
|
||||
// DirectCallOffer with Some(caller_reflexive_addr)
|
||||
|
||||
Reference in New Issue
Block a user