Play with friends without a server: endpoints and key in the code

Ludovic can't pay for a hosted relay, so nothing depends on one now. The
host's game finds how it can be reached on its own: its interface
addresses (LAN, VPNs such as Tailscale or ZeroTier, IPv6), a port opened
on the router for an hour at a time (PCP, then NAT-PMP, then UPnP IGD;
renewed while sharing, deleted on stop) and its public address from STUN
(Cloudflare's and Google's public servers by default, configurable). The
invite code carries those endpoints and an 80-bit secret in base32 groups
with a checksum; guests dial every endpoint at once and run the same
SPAKE2 + ChaCha20-Poly1305 handshake, no rendezvous involved. When nothing
can reach the host it says why and what to do (UPnP, the port to forward,
a relay, a VPN; CGNAT and double NAT detected).

The relay stays as something anyone can run (binary, Dockerfile, systemd
unit; Railway config removed): with one configured the host also gets a
short code, and the full code names the relay so guests fall back to it.
No relay by default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-15 00:31:36 +02:00
parent 74c1a90980
commit de464a8fc0
15 changed files with 2809 additions and 534 deletions
Generated
+11
View File
@@ -1039,6 +1039,7 @@ dependencies = [
"chacha20poly1305",
"getrandom 0.3.4",
"hkdf",
"if-addrs",
"serde",
"serde_json",
"sha2",
@@ -1231,6 +1232,16 @@ dependencies = [
"icu_properties",
]
[[package]]
name = "if-addrs"
version = "0.13.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "69b2eeee38fef3aa9b4cc5f1beea8a2444fc00e7377cafae396de3f5c2065e24"
dependencies = [
"libc",
"windows-sys 0.59.0",
]
[[package]]
name = "indexmap"
version = "2.14.2"
+2
View File
@@ -15,6 +15,8 @@ sha2 = "0.10"
getrandom = "0.3"
# SO_REUSEADDR/SO_REUSEPORT for the direct socket (TCP simultaneous open).
socket2 = { version = "0.5", features = ["all"] }
# This machine's addresses (LAN, VPNs such as Tailscale or ZeroTier, IPv6) for the code.
if-addrs = "0.13"
serde = { version = "1", features = ["derive"] }
serde_json = "1.0.151"
+55 -37
View File
@@ -5,7 +5,7 @@
use socket2::{Domain, Protocol, SockAddr, Socket, Type};
use std::{
io::{self, Read, Write},
net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, TcpListener, TcpStream, UdpSocket},
net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, TcpListener, TcpStream},
sync::{
Arc,
atomic::{AtomicBool, Ordering},
@@ -18,6 +18,8 @@ use std::{
pub const RACE: Duration = Duration::from_millis(3000);
const RETRY: Duration = Duration::from_millis(250);
const MAGIC: &[u8; 4] = b"HZF1";
/// A guest dialling an endpoint from an invite code (no relay involved).
pub const CODE_MAGIC: &[u8; 4] = b"HZF2";
fn socket_for(addr: &SocketAddr) -> io::Result<Socket> {
let s = Socket::new(
@@ -85,47 +87,16 @@ pub fn connect_from(port: Option<u16>, to: SocketAddr, timeout: Duration) -> io:
TcpStream::connect_timeout(&to, timeout)
}
/// The source address the OS would use toward `to` (a UDP socket only picks
/// a route: no packet is sent).
fn route_to(to: SocketAddr) -> Option<IpAddr> {
let bind = unspecified(to.is_ipv6(), 0);
let s = UdpSocket::bind(bind).ok()?;
s.connect(to).ok()?;
let ip = s.local_addr().ok()?.ip();
(!ip.is_unspecified()).then_some(ip)
}
/// The addresses this machine can be reached on, best first: toward the
/// relay (a LAN or tailnet address when the relay is near), then toward the
/// public IPv4 and IPv6 internet. Loopback only when the relay is local.
pub fn local_addresses(relay: Option<SocketAddr>) -> Vec<IpAddr> {
let mut targets: Vec<SocketAddr> = relay.into_iter().collect();
targets.push(SocketAddr::from(([1, 1, 1, 1], 53)));
targets.push(SocketAddr::from((
[0x2606, 0x4700, 0x4700, 0, 0, 0, 0, 0x1111],
53,
)));
let local_relay = relay.is_some_and(|r| r.ip().is_loopback());
let mut out = Vec::new();
for t in targets {
if let Some(ip) = route_to(t)
&& (local_relay || !ip.is_loopback())
&& !out.contains(&ip)
{
out.push(ip);
}
}
out
}
/// This end's candidates: each local address with the direct port, then the
/// address the relay saw (when it is not one of them).
/// This end's candidates for a relayed session: its interface addresses
/// with the direct port (loopback when the relay is local), then the address
/// the relay saw (when it is not one of them).
pub fn candidates(
port: u16,
relay: Option<SocketAddr>,
observed: Option<SocketAddr>,
) -> Vec<SocketAddr> {
let mut out: Vec<SocketAddr> = local_addresses(relay)
let loopback = relay.is_some_and(|r| r.ip().is_loopback());
let mut out: Vec<SocketAddr> = crate::reach::interface_addresses(loopback)
.into_iter()
.map(|ip| SocketAddr::new(ip, port))
.collect();
@@ -135,6 +106,7 @@ pub fn candidates(
{
out.push(o);
}
out.truncate(crate::invite::MAX_ENDPOINTS);
out
}
@@ -171,6 +143,52 @@ pub fn read_session(stream: &mut TcpStream) -> io::Result<u64> {
}
Ok(u64::from_be_bytes(theirs[4..].try_into().unwrap()))
}
/// What an inbound stream on the host's direct port is.
pub enum Hello {
/// A relayed session's direct race.
Relayed(u64),
/// A guest with the invite code.
Code(u64),
}
pub fn read_hello(stream: &mut TcpStream) -> io::Result<Hello> {
stream.set_read_timeout(Some(Duration::from_secs(5)))?;
let mut theirs = [0u8; 12];
stream.read_exact(&mut theirs)?;
let session = u64::from_be_bytes(theirs[4..].try_into().unwrap());
match &theirs[..4] {
m if m == MAGIC => Ok(Hello::Relayed(session)),
m if m == CODE_MAGIC => Ok(Hello::Code(session)),
_ => Err(io::Error::new(
io::ErrorKind::InvalidData,
"not a Horizon stream",
)),
}
}
/// The guest's side of a code session's opening: send the hello, wait for
/// its echo (proof a Horizon host listens there).
pub fn code_hello(stream: &mut TcpStream, session: u64) -> io::Result<()> {
let mut hello = [0u8; 12];
hello[..4].copy_from_slice(CODE_MAGIC);
hello[4..].copy_from_slice(&session.to_be_bytes());
stream.set_read_timeout(Some(Duration::from_secs(4)))?;
stream.write_all(&hello)?;
let mut theirs = [0u8; 12];
stream.read_exact(&mut theirs)?;
if theirs != hello {
return Err(io::Error::new(
io::ErrorKind::InvalidData,
"not a Horizon host",
));
}
Ok(())
}
/// The host echoes a code session's hello.
pub fn answer_code(stream: &mut TcpStream, session: u64) -> io::Result<()> {
let mut hello = [0u8; 12];
hello[..4].copy_from_slice(CODE_MAGIC);
hello[4..].copy_from_slice(&session.to_be_bytes());
stream.write_all(&hello)
}
/// Answer an inbound stream's introduction for `session`.
pub fn answer(stream: &mut TcpStream, session: u64) -> io::Result<()> {
let mut hello = [0u8; 12];
+101 -25
View File
@@ -1,24 +1,30 @@
//! The guest's end: find the host behind a code, agree on the key, settle
//! on a direct or relayed stream, then offer it on a loopback port the
//! The guest's end: reach the host from the code (directly, or through a
//! relay), agree on the key, then offer the session on a loopback port the
//! game's client connects to like to any server.
use crate::{
Code, PathMode,
crypto::{self, Role},
direct, resolve_relay,
direct,
invite::{Invite, Parsed},
resolve_relay,
session::{self, Secure},
wire::{self, ErrorCode, FromRelay, ToRelay},
};
use std::{
fmt, io,
net::{Ipv4Addr, SocketAddr, TcpListener, TcpStream},
sync::mpsc::channel,
thread::JoinHandle,
time::Duration,
time::{Duration, Instant},
};
pub struct GuestConfig {
pub relay: String,
pub code: Code,
/// The game's protocol number and version name (the relay refuses a
/// The code as pasted: a full invite, or a relay's short code.
pub code: String,
/// The relay to use for short codes (the player's setting); a full
/// invite names its own.
pub relay: Option<String>,
/// The game's protocol number and version name (a relay refuses a
/// guest whose protocol differs from the host's).
pub protocol: i32,
pub game: String,
@@ -28,8 +34,11 @@ pub struct GuestConfig {
/// Why joining failed, in words for the player.
#[derive(Debug)]
pub enum JoinError {
/// No relay is configured in this build.
NotAvailable,
BadCode(crate::invite::CodeError),
/// A short code without a relay to resolve it.
NeedsRelay,
/// None of the code's endpoints answered, and no relay to fall back to.
NotReachable,
Unreachable(String),
UnknownCode,
Ended,
@@ -46,8 +55,16 @@ pub enum JoinError {
impl fmt::Display for JoinError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::NotAvailable => write!(f, "Joining friends is not available yet in this build."),
Self::Unreachable(e) => write!(f, "Couldn't reach the invite service ({e})."),
Self::BadCode(e) => write!(f, "{e}"),
Self::NeedsRelay => write!(
f,
"This short code works through your friend's relay: add the relay's address under Join a friend, or ask for the full code."
),
Self::NotReachable => write!(
f,
"Couldn't reach your friend's game. Ask them to read the note under their code: they may need UPnP on their router, a forwarded port, a relay or a VPN."
),
Self::Unreachable(e) => write!(f, "Couldn't reach the relay ({e})."),
Self::UnknownCode => write!(
f,
"No world uses this code. Check it, or ask your friend for a new one."
@@ -90,10 +107,76 @@ pub struct Tunnel {
pub direct: bool,
}
/// Find the host, agree on the key and settle on a path. Blocks for up to a
/// few seconds (the direct race).
/// Join with what the player pasted: a full invite is dialled directly
/// (every endpoint at once), then through the relay it names, if any; a
/// short code goes through the configured relay. Blocks for a few seconds.
pub fn join(config: &GuestConfig) -> Result<Tunnel, JoinError> {
let relays = resolve_relay(&config.relay).map_err(|e| JoinError::Unreachable(e.to_string()))?;
match crate::invite::parse_detailed(&config.code).map_err(JoinError::BadCode)? {
Parsed::Short(code) => {
let relay = config.relay.as_deref().ok_or(JoinError::NeedsRelay)?;
join_relay(config, relay, &code)
}
Parsed::Long(invite) => {
if config.path != PathMode::RelayOnly
&& !invite.endpoints.is_empty()
&& let Some(t) = join_direct(&invite)?
{
return Ok(t);
}
match &invite.relay {
Some(r) if config.path != PathMode::DirectOnly => {
join_relay(config, &r.address, &r.code)
}
_ => Err(JoinError::NotReachable),
}
}
}
}
/// Dial every endpoint of the code; the first that answers as a Horizon
/// host gets the handshake, the others are dropped before it.
fn join_direct(invite: &Invite) -> Result<Option<Tunnel>, JoinError> {
let (tx, rx) = channel();
let deadline = Instant::now() + Duration::from_secs(5);
let mut session = [0u8; 8];
crate::fill_random(&mut session).map_err(|e| JoinError::Failed(e.to_string()))?;
let session = u64::from_le_bytes(session);
for &endpoint in &invite.endpoints {
let tx = tx.clone();
let _ = std::thread::Builder::new()
.name("horizon-friends-dial".into())
.spawn(move || {
if let Ok(mut s) = TcpStream::connect_timeout(&endpoint, Duration::from_secs(4))
&& direct::code_hello(&mut s, session).is_ok()
{
let _ = tx.send(s);
}
});
}
drop(tx);
let left = deadline.saturating_duration_since(Instant::now());
let Ok(mut stream) = rx.recv_timeout(left) else {
return Ok(None);
};
let key = crypto::exchange(&mut stream, &invite.secret_text(), "direct", session)
.map_err(|e| JoinError::Failed(e.to_string()))?;
let secure = session::secure(stream, &key, Role::Guest).map_err(|e| {
if crypto::is_wrong_code(&e) {
JoinError::WrongCode
} else {
JoinError::Failed(e.to_string())
}
})?;
Ok(Some(Tunnel {
secure,
direct: true,
}))
}
/// Through a relay with its short code (its own direct race, then the
/// relay's byte stream).
fn join_relay(config: &GuestConfig, relay_url: &str, code: &Code) -> Result<Tunnel, JoinError> {
let relays = resolve_relay(relay_url).map_err(|e| JoinError::Unreachable(e.to_string()))?;
let direct_allowed = config.path != PathMode::RelayOnly;
let (listeners, port) = if direct_allowed {
match direct::listen(0) {
@@ -124,7 +207,7 @@ pub fn join(config: &GuestConfig) -> Result<Tunnel, JoinError> {
&mut stream,
&ToRelay::Join {
v: wire::VERSION,
nameplate: config.code.nameplate.clone(),
nameplate: code.nameplate.clone(),
protocol: config.protocol,
game: config.game.clone(),
},
@@ -143,20 +226,13 @@ pub fn join(config: &GuestConfig) -> Result<Tunnel, JoinError> {
ErrorCode::HostUnreachable => JoinError::HostUnreachable,
ErrorCode::Full => JoinError::Full,
ErrorCode::RateLimited => JoinError::RateLimited,
ErrorCode::BadRequest => {
JoinError::Failed("the invite service refused the request".into())
}
ErrorCode::BadRequest => JoinError::Failed("the relay refused the request".into()),
});
}
other => return Err(JoinError::Failed(format!("unexpected answer {other:?}"))),
};
let key = crypto::exchange(
&mut stream,
&config.code.secret,
&config.code.nameplate,
session,
)
.map_err(|_| JoinError::HostUnreachable)?;
let key = crypto::exchange(&mut stream, &code.secret, &code.nameplate, session)
.map_err(|_| JoinError::HostUnreachable)?;
let relayed = session::secure(stream, &key, Role::Guest).map_err(|e| {
if crypto::is_wrong_code(&e) {
JoinError::WrongCode
+286 -127
View File
@@ -1,56 +1,76 @@
//! The host's end: registers with the relay for a code and keeps that
//! control connection open; for each guest the relay announces, attaches a
//! new connection, agrees on the key, settles on a path and connects the
//! session to the integrated server's port. Everything runs on its own
//! threads; the game polls [`Host::poll`] and [`Host::state`].
//! The host's end. It listens on its direct port, works out how it can be
//! reached (interfaces, a router mapping, STUN) and puts that with a fresh
//! secret into the invite code: guests with the code dial it directly, no
//! server involved. When a relay is configured (the player's own, or any
//! they trust), it also registers there for a short code and serves relayed
//! sessions (with their own direct race, then the relay as fallback).
//! Every session ends at the integrated server's port. Everything runs on
//! its own threads; the game polls [`Host::poll`] and [`Host::state`].
use crate::{
Code, PathMode,
crypto::{self, Role},
direct, resolve_relay, session,
direct,
invite::{Invite, RelayRef},
reach::{self, Reach, Verdict},
resolve_relay, session,
wire::{self, FromRelay, ToRelay},
};
use std::{
collections::HashMap,
io::{self, BufReader},
net::{Shutdown, SocketAddr, TcpStream},
net::{Shutdown, SocketAddr, TcpListener, TcpStream},
sync::{
Arc, Mutex,
atomic::{AtomicBool, AtomicU32, Ordering},
atomic::{AtomicBool, AtomicU32, AtomicUsize, Ordering},
mpsc::{Receiver, Sender, channel},
},
thread::JoinHandle,
time::{Duration, Instant},
};
/// Wrong codes tried before the host retires its code for a new one.
/// Wrong short codes tried at the relay before the host retires it.
pub const MAX_WRONG: u32 = 5;
/// Guests that can be connecting at once (IntegratedServer.MAX_PLAYERS).
/// Sessions open at once (IntegratedServer.MAX_PLAYERS).
pub const MAX_SESSIONS: usize = 8;
/// The direct port asked for first, so a port forwarded by hand keeps
/// working from one session to the next (`HORIZON_FRIENDS_PORT`).
pub const DEFAULT_PORT: u16 = 25580;
/// Code handshakes in progress at once (scanners can't pile them up).
const MAX_HANDSHAKES: usize = 8;
#[derive(Clone)]
pub struct HostConfig {
pub relay: String,
/// The integrated server's port (Open to LAN's).
pub lan: SocketAddr,
pub protocol: i32,
pub game: String,
/// A relay to register with as well (short code, relay fallback).
pub relay: Option<String>,
pub path: PathMode,
/// The direct port to ask for (0: any).
pub port: u16,
pub reach: reach::Options,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum HostState {
/// Waiting for the relay's answer.
Registering,
Sharing(Code),
/// The relay is unreachable or refused; retrying.
Retrying(String),
Stopped,
/// What the host's game shows.
#[derive(Clone, Debug, Default)]
pub struct HostState {
/// The invite code; None while the host is still finding its addresses.
pub invite: Option<String>,
/// The relay's short code, when registered with one.
pub short: Option<Code>,
/// Who can join, and what to do when friends on the internet can't.
pub summary: String,
pub verdict: Option<Verdict>,
/// Why the relay isn't serving, when one is configured.
pub relay_problem: Option<String>,
pub port: u16,
}
#[derive(Debug)]
pub enum HostEvent {
/// A new code (the first, or after the relay restarted or wrong codes).
Code(Code),
/// A new invite code (the first, or after the relay's short code changed).
Code(String),
/// A guest's session is carried directly or through the relay.
Connected {
session: u64,
@@ -59,7 +79,7 @@ pub enum HostEvent {
Disconnected {
session: u64,
},
/// Someone used the nameplate with the wrong secret.
/// Someone tried a wrong code.
WrongCode {
count: u32,
},
@@ -70,72 +90,97 @@ struct Shared {
stop: AtomicBool,
state: Mutex<HostState>,
events: Mutex<Sender<HostEvent>>,
/// The current control connection (shut down to stop).
/// The invite (endpoints and secret), rebuilt when the relay part changes.
invite: Mutex<Option<Invite>>,
/// The current relay control connection (shut down to stop).
control: Mutex<Option<TcpStream>>,
/// Inbound direct streams waiting for their session.
/// Inbound direct streams waiting for their relayed session.
routes: Mutex<HashMap<u64, (Sender<TcpStream>, Instant)>>,
sessions: Mutex<usize>,
sessions: AtomicUsize,
handshakes: AtomicUsize,
wrong: AtomicU32,
relay_wrong: AtomicU32,
reach: Mutex<Option<Reach>>,
}
impl Shared {
fn emit(&self, e: HostEvent) {
let _ = self.events.lock().unwrap().send(e);
}
fn set(&self, s: HostState) {
*self.state.lock().unwrap() = s;
}
fn stopped(&self) -> bool {
self.stop.load(Ordering::Relaxed)
}
/// Rebuild the code from the invite and the relay's short code.
fn publish(&self, short: Option<Code>) {
let text = {
let mut invite = self.invite.lock().unwrap();
let Some(inv) = invite.as_mut() else { return };
inv.relay = match (&short, &self.config.relay) {
(Some(code), Some(address)) => Some(RelayRef {
address: address.clone(),
code: code.clone(),
}),
_ => None,
};
inv.encode()
};
{
let mut s = self.state.lock().unwrap();
if s.invite.as_deref() == Some(&text) && s.short == short {
return;
}
s.invite = Some(text.clone());
s.short = short;
}
self.emit(HostEvent::Code(text));
}
}
pub struct Host {
shared: Arc<Shared>,
events: Receiver<HostEvent>,
thread: Option<JoinHandle<()>>,
accept: Option<JoinHandle<()>>,
threads: Vec<JoinHandle<()>>,
}
impl Host {
/// Start sharing in the background: the code arrives as an event.
/// Start sharing in the background: the code arrives as an event once
/// the host knows its addresses (a few seconds).
pub fn start(config: HostConfig) -> io::Result<Self> {
let (tx, events) = channel();
let listeners = if config.path == PathMode::RelayOnly {
None
} else {
direct::listen(0).ok()
};
let (listeners, port) = direct::listen(config.port).or_else(|_| direct::listen(0))?;
let shared = Arc::new(Shared {
config,
stop: AtomicBool::new(false),
state: Mutex::new(HostState::Registering),
state: Mutex::new(HostState {
port,
..HostState::default()
}),
events: Mutex::new(tx),
invite: Mutex::new(None),
control: Mutex::new(None),
routes: Mutex::new(HashMap::new()),
sessions: Mutex::new(0),
sessions: AtomicUsize::new(0),
handshakes: AtomicUsize::new(0),
wrong: AtomicU32::new(0),
relay_wrong: AtomicU32::new(0),
reach: Mutex::new(None),
});
let port = listeners.as_ref().map(|(_, p)| *p);
let accept = match listeners {
Some((l, _)) => {
let s = shared.clone();
Some(
std::thread::Builder::new()
.name("horizon-friends-listen".into())
.spawn(move || route_inbound(l, s))?,
)
}
None => None,
};
let mut threads = Vec::new();
let s = shared.clone();
let thread = std::thread::Builder::new()
.name("horizon-friends-host".into())
.spawn(move || run(s, port))?;
threads.push(
std::thread::Builder::new()
.name("horizon-friends-listen".into())
.spawn(move || route_inbound(listeners, s))?,
);
let s = shared.clone();
threads.push(
std::thread::Builder::new()
.name("horizon-friends-reach".into())
.spawn(move || share(s, port))?,
);
Ok(Self {
shared,
events,
thread: Some(thread),
accept,
threads,
})
}
pub fn state(&self) -> HostState {
@@ -146,22 +191,22 @@ impl Host {
}
/// Guests whose sessions are open (connecting or playing).
pub fn sessions(&self) -> usize {
*self.shared.sessions.lock().unwrap()
self.shared.sessions.load(Ordering::Relaxed)
}
/// End the code. Sessions already playing go on until the integrated
/// server closes them (stopping the LAN server ends them).
/// End the code: close the direct port, delete the router mapping, leave
/// the relay. Sessions already playing go on until the integrated server
/// closes them.
pub fn stop(&mut self) {
self.shared.stop.store(true, Ordering::Relaxed);
if let Some(c) = self.shared.control.lock().unwrap().take() {
let _ = c.shutdown(Shutdown::Both);
}
if let Some(t) = self.thread.take() {
for t in self.threads.drain(..) {
let _ = t.join();
}
if let Some(t) = self.accept.take() {
let _ = t.join();
if let Some(r) = self.shared.reach.lock().unwrap().as_mut() {
r.release();
}
self.shared.set(HostState::Stopped);
}
}
impl Drop for Host {
@@ -170,30 +215,105 @@ impl Drop for Host {
}
}
/// Hand inbound direct streams to the session they introduce themselves for.
fn route_inbound(listeners: Vec<std::net::TcpListener>, shared: Arc<Shared>) {
/// Find the addresses, publish the code, keep the router mapping alive,
/// serve the relay when there is one.
fn share(shared: Arc<Shared>, port: u16) {
let config = &shared.config;
let reach = if config.path == PathMode::RelayOnly {
Reach {
port,
..Reach::default()
}
} else {
Reach::discover(port, &config.reach)
};
let endpoints = if config.path == PathMode::RelayOnly {
Vec::new()
} else {
reach.endpoints()
};
let invite = match Invite::new(port, endpoints, None) {
Ok(i) => i,
Err(_) => return,
};
{
let mut s = shared.state.lock().unwrap();
s.summary = if config.path == PathMode::RelayOnly {
"Friends join through the relay only.".into()
} else {
reach.summary()
};
s.verdict = Some(reach.verdict());
}
*shared.invite.lock().unwrap() = Some(invite);
*shared.reach.lock().unwrap() = Some(reach);
if shared.stopped() {
return;
}
shared.publish(None);
let relay = match &config.relay {
Some(r) => {
let s = shared.clone();
let r = r.clone();
std::thread::Builder::new()
.name("horizon-friends-relay".into())
.spawn(move || run_relay(s, r))
.ok()
}
None => None,
};
// Renew the router mapping at half-lease until stopped.
while !shared.stopped() {
std::thread::sleep(Duration::from_millis(100));
let mut reach = shared.reach.lock().unwrap();
if let Some(m) = reach.as_mut().and_then(|r| r.mapping.as_mut())
&& m.due()
&& m.renew().is_err()
{
// Try again in a minute rather than hammering the router.
m.renewed = Instant::now() - m.lifetime / 2 + Duration::from_secs(60);
}
}
if let Some(t) = relay {
let _ = t.join();
}
}
/// Inbound streams on the direct port: a relayed session's direct race, or
/// a guest with the code.
fn route_inbound(listeners: Vec<TcpListener>, shared: Arc<Shared>) {
while !shared.stopped() {
let mut idle = true;
for l in &listeners {
let Ok((mut s, _)) = l.accept() else { continue };
idle = false;
if shared.handshakes.load(Ordering::Relaxed) >= MAX_HANDSHAKES {
continue;
}
shared.handshakes.fetch_add(1, Ordering::Relaxed);
let shared = shared.clone();
let _ = std::thread::Builder::new()
.name("horizon-friends-inbound".into())
.spawn(move || {
let _ = s.set_nonblocking(false);
let Ok(session) = direct::read_session(&mut s) else {
return;
};
let route = {
let mut routes = shared.routes.lock().unwrap();
routes.retain(|_, (_, until)| *until > Instant::now());
routes.get(&session).map(|(tx, _)| tx.clone())
};
if let Some(tx) = route
&& direct::answer(&mut s, session).is_ok()
{
let _ = tx.send(s);
match direct::read_hello(&mut s) {
Ok(direct::Hello::Relayed(session)) => {
shared.handshakes.fetch_sub(1, Ordering::Relaxed);
let route = {
let mut routes = shared.routes.lock().unwrap();
routes.retain(|_, (_, until)| *until > Instant::now());
routes.get(&session).map(|(tx, _)| tx.clone())
};
if let Some(tx) = route
&& direct::answer(&mut s, session).is_ok()
{
let _ = tx.send(s);
}
}
Ok(direct::Hello::Code(session)) => serve_code(&shared, s, session),
Err(_) => {
shared.handshakes.fetch_sub(1, Ordering::Relaxed);
}
}
});
}
@@ -203,13 +323,61 @@ fn route_inbound(listeners: Vec<std::net::TcpListener>, shared: Arc<Shared>) {
}
}
fn connect_relay(config: &HostConfig, port: Option<u16>) -> io::Result<(TcpStream, SocketAddr)> {
/// A guest who dialled an endpoint from the code: agree on the key from
/// the code's secret, then carry the session.
fn serve_code(shared: &Arc<Shared>, mut s: TcpStream, session: u64) {
let secret = shared
.invite
.lock()
.unwrap()
.as_ref()
.map(Invite::secret_text);
let secured = (|| -> io::Result<session::Secure> {
let secret = secret.ok_or_else(|| io::Error::other("not ready"))?;
direct::answer_code(&mut s, session)?;
let key = crypto::exchange(&mut s, &secret, "direct", session)?;
session::secure(s, &key, Role::Host)
})();
shared.handshakes.fetch_sub(1, Ordering::Relaxed);
match secured {
Ok(secure) => carry(shared, session, secure, true),
Err(e) if crypto::is_wrong_code(&e) => {
let count = shared.wrong.fetch_add(1, Ordering::Relaxed) + 1;
shared.emit(HostEvent::WrongCode { count });
}
Err(_) => {}
}
}
/// Connect a settled session to the integrated server and carry it.
fn carry(shared: &Arc<Shared>, session: u64, (r, w): session::Secure, direct: bool) {
if shared.sessions.fetch_add(1, Ordering::Relaxed) >= MAX_SESSIONS {
shared.sessions.fetch_sub(1, Ordering::Relaxed);
let _ = r.get_ref().shutdown(Shutdown::Both);
return;
}
let Ok(server) = TcpStream::connect_timeout(&shared.config.lan, Duration::from_secs(5)) else {
let _ = r.get_ref().shutdown(Shutdown::Both);
shared.sessions.fetch_sub(1, Ordering::Relaxed);
return;
};
shared.emit(HostEvent::Connected { session, direct });
if let Ok(t) = crate::pump(server, r, w) {
let _ = t.join();
}
shared.sessions.fetch_sub(1, Ordering::Relaxed);
shared.emit(HostEvent::Disconnected { session });
}
// ----- The relay (optional) ---------------------------------------------------------------------
fn connect_relay(relay: &str, port: Option<u16>) -> io::Result<(TcpStream, SocketAddr)> {
let mut last = io::Error::other("no address");
for relay in resolve_relay(&config.relay)? {
match direct::connect_from(port, relay, Duration::from_secs(5)) {
for address in resolve_relay(relay)? {
match direct::connect_from(port, address, Duration::from_secs(5)) {
Ok(s) => {
let _ = s.set_nodelay(true);
return Ok((s, relay));
return Ok((s, address));
}
Err(e) => last = e,
}
@@ -218,17 +386,22 @@ fn connect_relay(config: &HostConfig, port: Option<u16>) -> io::Result<(TcpStrea
}
/// Register, serve the control connection, register again when it drops
/// (a new code) until stopped.
fn run(shared: Arc<Shared>, port: Option<u16>) {
/// (a new short code) until stopped.
fn run_relay(shared: Arc<Shared>, relay: String) {
let mut backoff = Duration::from_secs(1);
while !shared.stopped() {
match register(&shared, port) {
Ok(()) => backoff = Duration::from_secs(1),
match register(&shared, &relay) {
Ok(()) => {
backoff = Duration::from_secs(1);
shared.state.lock().unwrap().relay_problem = None;
}
Err(e) => {
if shared.stopped() {
break;
}
shared.set(HostState::Retrying(e.to_string()));
shared.state.lock().unwrap().relay_problem =
Some(format!("Couldn't reach the relay {relay}: {e}"));
shared.publish(None);
let until = Instant::now() + backoff;
while Instant::now() < until && !shared.stopped() {
std::thread::sleep(Duration::from_millis(50));
@@ -239,11 +412,12 @@ fn run(shared: Arc<Shared>, port: Option<u16>) {
}
}
fn register(shared: &Arc<Shared>, port: Option<u16>) -> io::Result<()> {
fn register(shared: &Arc<Shared>, relay_url: &str) -> io::Result<()> {
let config = &shared.config;
let port = Some(shared.state.lock().unwrap().port);
// The control connection uses any port: the direct port stays free for
// the attach connections, whose observed address is the one that counts.
let (mut control, relay) = connect_relay(config, None)?;
let (mut control, relay) = connect_relay(relay_url, None)?;
control.set_read_timeout(Some(Duration::from_secs(70)))?;
wire::send(
&mut control,
@@ -259,10 +433,7 @@ fn register(shared: &Arc<Shared>, port: Option<u16>) -> io::Result<()> {
nameplate, token, ..
} => (nameplate, token),
FromRelay::Error { code, .. } => {
return Err(io::Error::other(format!(
"the invite service refused: {}",
code.as_str()
)));
return Err(io::Error::other(format!("it refused ({})", code.as_str())));
}
other => return Err(io::Error::other(format!("unexpected answer {other:?}"))),
};
@@ -272,15 +443,16 @@ fn register(shared: &Arc<Shared>, port: Option<u16>) -> io::Result<()> {
let _ = control.shutdown(Shutdown::Both);
return Ok(());
}
shared.wrong.store(0, Ordering::Relaxed);
shared.set(HostState::Sharing(code.clone()));
shared.emit(HostEvent::Code(code.clone()));
shared.relay_wrong.store(0, Ordering::Relaxed);
shared.publish(Some(code.clone()));
loop {
let message = match wire::recv_buffered::<_, FromRelay>(&mut reader) {
Ok(m) => m,
Err(e) => {
shared.control.lock().unwrap().take();
return if shared.stopped() || shared.wrong.load(Ordering::Relaxed) >= MAX_WRONG {
return if shared.stopped()
|| shared.relay_wrong.load(Ordering::Relaxed) >= MAX_WRONG
{
Ok(())
} else {
Err(e)
@@ -290,23 +462,22 @@ fn register(shared: &Arc<Shared>, port: Option<u16>) -> io::Result<()> {
match message {
FromRelay::Ping => wire::send(&mut control, &ToRelay::Pong)?,
FromRelay::Join { session } => {
let mut open = shared.sessions.lock().unwrap();
if *open >= MAX_SESSIONS {
if shared.sessions.load(Ordering::Relaxed) >= MAX_SESSIONS {
continue;
}
*open += 1;
drop(open);
let (shared, code, token, control) = (
let (shared, code, token, control, relay_url) = (
shared.clone(),
code.clone(),
token.clone(),
control.try_clone()?,
relay_url.to_owned(),
);
let _ = std::thread::Builder::new()
.name("horizon-friends-session".into())
.spawn(move || {
serve(&shared, &code, &token, session, port, relay, &control);
*shared.sessions.lock().unwrap() -= 1;
serve_relayed(
&shared, &relay_url, &code, &token, session, port, relay, &control,
)
});
}
_ => {}
@@ -314,10 +485,12 @@ fn register(shared: &Arc<Shared>, port: Option<u16>) -> io::Result<()> {
}
}
/// One guest: attach, agree on the key, settle, connect to the integrated
/// server, carry the session until it ends.
fn serve(
/// One guest through the relay: attach, agree on the key from the short
/// code, settle on a direct or relayed stream, carry it.
#[allow(clippy::too_many_arguments)]
fn serve_relayed(
shared: &Arc<Shared>,
relay_url: &str,
code: &Code,
token: &str,
session: u64,
@@ -326,7 +499,7 @@ fn serve(
control: &TcpStream,
) {
let config = &shared.config;
let Ok((mut stream, _)) = connect_relay(config, port) else {
let Ok((mut stream, _)) = connect_relay(relay_url, port) else {
return;
};
let _ = stream.set_read_timeout(Some(Duration::from_secs(15)));
@@ -351,11 +524,11 @@ fn serve(
Ok(s) => s,
Err(e) => {
if crypto::is_wrong_code(&e) {
let count = shared.wrong.fetch_add(1, Ordering::Relaxed) + 1;
let count = shared.relay_wrong.fetch_add(1, Ordering::Relaxed) + 1;
shared.emit(HostEvent::WrongCode { count });
if count >= MAX_WRONG {
// Retire the code: dropping the control connection ends
// it at the relay, and `run` registers a new one.
// Retire the short code: dropping the control connection
// ends it at the relay, and `run_relay` registers anew.
let _ = control.shutdown(Shutdown::Both);
}
}
@@ -363,7 +536,7 @@ fn serve(
}
};
let candidates = port.map_or_else(Vec::new, |p| direct::candidates(p, Some(relay), observed));
let shared_routes = shared.clone();
let routes = shared.clone();
let settled = session::settle(
relayed,
&key,
@@ -373,7 +546,7 @@ fn serve(
port,
candidates,
Box::new(move |tx, deadline, _stop| {
shared_routes
routes
.routes
.lock()
.unwrap()
@@ -381,21 +554,7 @@ fn serve(
}),
);
shared.routes.lock().unwrap().remove(&session);
let Ok(settled) = settled else {
return;
};
let Ok(server) = TcpStream::connect_timeout(&config.lan, Duration::from_secs(5)) else {
let (r, _) = settled.secure;
let _ = r.get_ref().shutdown(Shutdown::Both);
return;
};
let (r, w) = settled.secure;
shared.emit(HostEvent::Connected {
session,
direct: settled.direct,
});
if let Ok(t) = crate::pump(server, r, w) {
let _ = t.join();
if let Ok(settled) = settled {
carry(shared, session, settled.secure, settled.direct);
}
shared.emit(HostEvent::Disconnected { session });
}
+403
View File
@@ -0,0 +1,403 @@
//! The invite code that needs no server: the host's reachable endpoints and
//! the session secret, in Crockford base32 groups with a checksum, e.g.
//! `2A7KQ-M3XPD-...`. A guest dials the endpoints directly; when the host
//! also uses a relay, the code carries the relay's address and the short
//! code too, so the guest can fall back to it without any setting.
//!
//! Layout (bytes, then base32): version (2), secret (10), the direct port
//! (u16), entries, then the first two bytes of SHA-256 over all of it.
//! Entries: `0x04` IPv4 on the direct port, `0x05` IPv4 and its own port
//! (a router mapping), `0x06`/`0x07` the same for IPv6, `0x10` a relay:
//! address length, address, then the short code's 40 bits.
use crate::code::{ALPHABET, Code, HALF};
use sha2::{Digest, Sha256};
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
const VERSION: u8 = 2;
pub const SECRET: usize = 10;
/// Endpoints a code carries at most.
pub const MAX_ENDPOINTS: usize = 8;
const GROUP: usize = 5;
/// The relay a host also registered with: where, and its short code.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RelayRef {
pub address: String,
pub code: Code,
}
#[derive(Clone, PartialEq, Eq)]
pub struct Invite {
pub secret: [u8; SECRET],
/// The host's direct socket: LAN, VPN and IPv6 addresses use this port.
pub port: u16,
pub endpoints: Vec<SocketAddr>,
pub relay: Option<RelayRef>,
}
/// The secret stays out of logs.
impl std::fmt::Debug for Invite {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Invite")
.field("port", &self.port)
.field("endpoints", &self.endpoints)
.field("relay", &self.relay.as_ref().map(|r| &r.address))
.finish_non_exhaustive()
}
}
/// What a player pasted.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Parsed {
/// Eight symbols: a relay's short code (needs that relay).
Short(Code),
Long(Invite),
}
/// Why a code didn't parse, for the player.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum CodeError {
Characters,
Typo,
Version,
}
impl std::fmt::Display for CodeError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(match self {
Self::Characters => {
"That isn't an invite code: codes are letters and digits in groups."
}
Self::Typo => "The code has a typo: copy it again from your friend's message.",
Self::Version => {
"This invite comes from another version of Horizon. Update both games."
}
})
}
}
fn symbol(c: char) -> Option<u8> {
let c = match c.to_ascii_uppercase() {
'O' => '0',
'I' | 'L' => '1',
c => c,
};
ALPHABET
.iter()
.position(|&a| char::from(a) == c)
.map(|i| i as u8)
}
fn encode32(bytes: &[u8]) -> String {
let mut out = String::with_capacity(bytes.len() * 8 / 5 + 1);
let (mut acc, mut bits) = (0u32, 0u32);
for &b in bytes {
acc = (acc << 8) | u32::from(b);
bits += 8;
while bits >= 5 {
bits -= 5;
out.push(char::from(ALPHABET[((acc >> bits) & 31) as usize]));
}
}
if bits > 0 {
out.push(char::from(ALPHABET[((acc << (5 - bits)) & 31) as usize]));
}
out
}
fn decode32(symbols: &[u8]) -> Option<Vec<u8>> {
let mut out = Vec::with_capacity(symbols.len() * 5 / 8);
let (mut acc, mut bits) = (0u32, 0u32);
for &v in symbols {
acc = ((acc << 5) | u32::from(v)) & 0xFFFF;
bits += 5;
if bits >= 8 {
bits -= 8;
out.push((acc >> bits) as u8);
}
}
// Padding bits must be zero (a canonical encoding).
(acc & ((1 << bits) - 1) == 0).then_some(out)
}
fn checksum(bytes: &[u8]) -> [u8; 2] {
let h = Sha256::digest(bytes);
[h[0], h[1]]
}
/// The 40 bits of a short code (20 per half).
fn short_bits(code: &Code) -> Option<u64> {
let mut v = 0u64;
for c in code.nameplate.chars().chain(code.secret.chars()) {
v = (v << 5) | u64::from(symbol(c)?);
}
Some(v)
}
fn short_from_bits(v: u64) -> Code {
let s: String = (0..2 * HALF)
.rev()
.map(|i| char::from(ALPHABET[((v >> (5 * i)) & 31) as usize]))
.collect();
let (n, sec) = s.split_at(HALF);
Code {
nameplate: n.to_owned(),
secret: sec.to_owned(),
}
}
impl Invite {
/// A fresh secret from the OS random generator.
pub fn new(
port: u16,
endpoints: Vec<SocketAddr>,
relay: Option<RelayRef>,
) -> std::io::Result<Self> {
let mut secret = [0u8; SECRET];
crate::fill_random(&mut secret)?;
Ok(Self {
secret,
port,
endpoints,
relay,
})
}
/// The SPAKE2 password of direct sessions.
pub fn secret_text(&self) -> String {
encode32(&self.secret)
}
fn bytes(&self) -> Vec<u8> {
let mut b = vec![VERSION];
b.extend_from_slice(&self.secret);
b.extend_from_slice(&self.port.to_be_bytes());
for e in self.endpoints.iter().take(MAX_ENDPOINTS) {
let own = e.port() != self.port;
match e.ip() {
IpAddr::V4(ip) => {
b.push(if own { 0x05 } else { 0x04 });
b.extend_from_slice(&ip.octets());
}
IpAddr::V6(ip) => {
b.push(if own { 0x07 } else { 0x06 });
b.extend_from_slice(&ip.octets());
}
}
if own {
b.extend_from_slice(&e.port().to_be_bytes());
}
}
if let Some(r) = &self.relay
&& let Some(bits) = short_bits(&r.code)
&& r.address.len() <= 255
{
b.push(0x10);
b.push(r.address.len() as u8);
b.extend_from_slice(r.address.as_bytes());
b.extend_from_slice(&bits.to_be_bytes()[3..]);
}
let sum = checksum(&b);
b.extend_from_slice(&sum);
b
}
/// The code to share, in groups of five.
pub fn encode(&self) -> String {
let text = encode32(&self.bytes());
text.as_bytes()
.chunks(GROUP)
.map(|c| std::str::from_utf8(c).unwrap())
.collect::<Vec<_>>()
.join("-")
}
fn decode(bytes: &[u8]) -> Result<Self, CodeError> {
if bytes.len() < 1 + SECRET + 2 + 2 {
return Err(CodeError::Characters);
}
let (body, sum) = bytes.split_at(bytes.len() - 2);
if checksum(body) != sum {
return Err(CodeError::Typo);
}
if body[0] != VERSION {
return Err(CodeError::Version);
}
let mut secret = [0u8; SECRET];
secret.copy_from_slice(&body[1..1 + SECRET]);
let port = u16::from_be_bytes([body[1 + SECRET], body[2 + SECRET]]);
let mut rest = &body[3 + SECRET..];
let mut take = |n: usize| -> Result<&[u8], CodeError> {
if rest.len() < n {
return Err(CodeError::Version);
}
let (a, b) = rest.split_at(n);
rest = b;
Ok(a)
};
let mut endpoints = Vec::new();
let mut relay = None;
while let Ok(tag) = take(1) {
let tag = tag[0];
match tag {
0x04..=0x07 => {
let ip = if tag < 0x06 {
let o: [u8; 4] = take(4)?.try_into().unwrap();
IpAddr::V4(Ipv4Addr::from(o))
} else {
let o: [u8; 16] = take(16)?.try_into().unwrap();
IpAddr::V6(Ipv6Addr::from(o))
};
let p = if tag & 1 == 1 {
let p = take(2)?;
u16::from_be_bytes([p[0], p[1]])
} else {
port
};
endpoints.push(SocketAddr::new(ip, p));
}
0x10 => {
let len = usize::from(take(1)?[0]);
let address =
String::from_utf8(take(len)?.to_vec()).map_err(|_| CodeError::Version)?;
let b = take(5)?;
let bits = b.iter().fold(0u64, |v, &x| (v << 8) | u64::from(x));
relay = Some(RelayRef {
address,
code: short_from_bits(bits),
});
}
_ => return Err(CodeError::Version),
}
}
Ok(Self {
secret,
port,
endpoints,
relay,
})
}
}
/// Read what a player pasted: a short relay code or a full invite.
pub fn parse_detailed(text: &str) -> Result<Parsed, CodeError> {
let mut symbols = Vec::with_capacity(text.len());
for c in text.chars() {
if c.is_whitespace() || c == '-' {
continue;
}
symbols.push(symbol(c).ok_or(CodeError::Characters)?);
}
if symbols.len() == 2 * HALF {
let s: String = symbols
.iter()
.map(|&v| char::from(ALPHABET[v as usize]))
.collect();
return Code::parse(&s)
.map(Parsed::Short)
.ok_or(CodeError::Characters);
}
let bytes = decode32(&symbols).ok_or(CodeError::Typo)?;
Invite::decode(&bytes).map(Parsed::Long)
}
pub fn parse(text: &str) -> Option<Parsed> {
parse_detailed(text).ok()
}
#[cfg(test)]
mod tests {
use super::*;
fn sample() -> Invite {
Invite {
secret: *b"0123456789",
port: 25580,
endpoints: vec![
"203.0.113.5:41234".parse().unwrap(),
"192.168.1.20:25580".parse().unwrap(),
"100.72.51.8:25580".parse().unwrap(),
"[2001:db8::20]:25580".parse().unwrap(),
],
relay: None,
}
}
#[test]
fn base32_round_trips() {
for n in 0..40 {
let bytes: Vec<u8> = (0..n).map(|i| (i * 37 + 11) as u8).collect();
let text = encode32(&bytes);
let symbols: Vec<u8> = text.chars().map(|c| symbol(c).unwrap()).collect();
assert_eq!(decode32(&symbols).unwrap(), bytes);
}
}
#[test]
fn codes_round_trip_and_stay_pasteable() {
let invite = sample();
let code = invite.encode();
assert!(
code.split('-')
.all(|g| g.len() <= GROUP && g.chars().all(|c| ALPHABET.contains(&(c as u8))))
);
// A home with a router mapping, a LAN, a tailnet and IPv6: 79 symbols
// in 16 groups; without IPv6, 52.
assert_eq!(code.replace('-', "").len(), 79, "{code}");
let mut v4 = invite.clone();
v4.endpoints.pop();
assert_eq!(v4.encode().replace('-', "").len(), 52);
assert_eq!(parse(&code), Some(Parsed::Long(invite.clone())));
// Case, spaces and look-alike letters don't matter.
let sloppy = code.to_lowercase().replace('-', " ").replace('0', "o");
assert_eq!(parse(&sloppy), Some(Parsed::Long(invite)));
}
#[test]
fn a_relay_rides_along() {
let mut invite = sample();
invite.relay = Some(RelayRef {
address: "relay.example.org:7000".into(),
code: Code::parse("K7QM-3XPD").unwrap(),
});
let Some(Parsed::Long(back)) = parse(&invite.encode()) else {
panic!()
};
assert_eq!(back.relay, invite.relay);
assert_eq!(back.endpoints, invite.endpoints);
}
#[test]
fn typos_are_caught() {
let code = sample().encode();
let mut caught = 0;
let symbols: Vec<char> = code.chars().collect();
for i in (0..symbols.len()).filter(|&i| symbols[i] != '-') {
let mut changed = symbols.clone();
changed[i] = if changed[i] == 'Z' { 'Y' } else { 'Z' };
let text: String = changed.into_iter().collect();
if parse_detailed(&text).is_err() {
caught += 1;
}
}
// Every single-symbol change is refused (the checksum misses one in 65536).
assert_eq!(caught, symbols.iter().filter(|&&c| c != '-').count());
// A dropped group too.
let shorter: String = code.split('-').skip(1).collect::<Vec<_>>().join("-");
assert!(parse(&shorter).is_none());
}
#[test]
fn short_codes_and_garbage() {
assert_eq!(
parse("k7qm-3xpd"),
Some(Parsed::Short(Code::parse("K7QM-3XPD").unwrap()))
);
assert_eq!(parse_detailed("hello world!"), Err(CodeError::Characters));
assert!(parse("").is_none());
// Another version is told apart from a typo.
let mut b = sample().bytes();
b[0] = 3;
let n = b.len() - 2;
let sum = checksum(&b[..n]);
b[n..].copy_from_slice(&sum);
assert_eq!(parse_detailed(&encode32(&b)), Err(CodeError::Version));
}
#[test]
fn debug_hides_the_secret() {
assert!(!format!("{:?}", sample()).contains("0123456789"));
}
}
+15 -10
View File
@@ -1,6 +1,9 @@
//! Play with friends: a host shares the world it opened to LAN behind an
//! invite code; guests join with the code, directly when the network allows
//! and through the relay otherwise. Both ends carry the game's TCP stream
//! invite code that holds its addresses and a secret; guests dial it
//! directly (the host opens its router port with PCP / NAT-PMP / UPnP and
//! learns its public address with STUN). A relay anyone can run
//! (`horizon-relay`) adds short codes and a fallback for networks that
//! can't be reached. Both ends carry the game's TCP stream
//! unchanged between loopback ports (the integrated server on the host, a
//! local port the guest's client connects to), end-to-end encrypted with a
//! key only the holders of the code can derive. The design, the protocol and
@@ -10,7 +13,11 @@ pub mod crypto;
pub mod direct;
pub mod guest;
pub mod host;
pub mod invite;
pub mod portmap;
pub mod reach;
mod session;
pub mod stun;
pub mod wire;
pub use code::Code;
@@ -48,16 +55,14 @@ impl PathMode {
}
}
/// The relay's address: `HORIZON_RELAY_URL` at run time, else the one
/// compiled in from the same variable. None until a relay is deployed.
/// A relay from `HORIZON_RELAY_URL` (tests, or players who set it in the
/// environment); the game adds its own setting. None by default: friends
/// join from the code alone.
pub fn relay_url() -> Option<String> {
let runtime = std::env::var("HORIZON_RELAY_URL").ok();
let compiled = option_env!("HORIZON_RELAY_URL").map(str::to_owned);
runtime
.into_iter()
.chain(compiled)
std::env::var("HORIZON_RELAY_URL")
.ok()
.map(|s| s.trim().to_owned())
.find(|s| !s.is_empty())
.filter(|s| !s.is_empty())
}
/// `host:port`, optionally written `tcp://host:port`.
+980
View File
@@ -0,0 +1,980 @@
//! Opening the host's direct port on the home router, for a limited time:
//! PCP (RFC 6887), then NAT-PMP (RFC 6886) on the gateway's port 5351, then
//! UPnP IGD (SSDP discovery, then SOAP `AddPortMapping`). The mapping is
//! renewed while sharing and deleted when it stops; a crashed game's mapping
//! expires with its lease.
use std::{
io::{self, Read, Write},
net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, TcpStream, ToSocketAddrs, UdpSocket},
time::{Duration, Instant},
};
/// How long a mapping is asked for; it is renewed at half-time.
pub const LEASE: Duration = Duration::from_secs(3600);
const PMP_PORT: u16 = 5351;
const DESCRIPTION: &str = "Horizon (play with friends)";
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Method {
Pcp,
NatPmp,
Upnp,
}
impl Method {
pub fn name(self) -> &'static str {
match self {
Self::Pcp => "PCP",
Self::NatPmp => "NAT-PMP",
Self::Upnp => "UPnP",
}
}
}
#[derive(Clone, Debug)]
enum Handle {
Pmp {
gateway: SocketAddr,
client: Ipv4Addr,
nonce: [u8; 12],
},
NatPmp {
gateway: SocketAddr,
},
Upnp {
igd: Igd,
client: Ipv4Addr,
permanent: bool,
},
}
/// A port opened on the router.
#[derive(Clone, Debug)]
pub struct Mapping {
pub method: Method,
pub internal: u16,
/// The router's public side: its WAN address (unspecified when the
/// router didn't say) and the external port.
pub external: SocketAddr,
pub lifetime: Duration,
pub renewed: Instant,
handle: Handle,
}
/// Where to ask: gateways speaking PCP/NAT-PMP, UPnP description URLs.
#[derive(Clone, Debug, Default)]
pub struct Targets {
pub pmp: Vec<SocketAddr>,
pub upnp: Vec<String>,
}
impl Targets {
/// The default gateway's port 5351, and the IGDs answering SSDP.
pub fn discover(timeout: Duration) -> Self {
let mut pmp: Vec<SocketAddr> = default_gateway()
.into_iter()
.map(|g| SocketAddr::new(IpAddr::V4(g), PMP_PORT))
.collect();
let upnp = ssdp_discover(timeout);
// An IGD's own address is a gateway too.
for l in &upnp {
if let Some((host, _, _)) = split_url(l)
&& let Ok(ip) = host.parse::<Ipv4Addr>()
{
let a = SocketAddr::new(IpAddr::V4(ip), PMP_PORT);
if !pmp.contains(&a) {
pmp.push(a);
}
}
}
Self { pmp, upnp }
}
}
/// Open `internal` on the router for `client` (this machine's LAN address),
/// trying each method in turn. The error lists why each failed.
pub fn map(
targets: &Targets,
client: Ipv4Addr,
internal: u16,
lease: Duration,
) -> Result<Mapping, String> {
let mut why = Vec::new();
for &gw in &targets.pmp {
let mut nonce = [0u8; 12];
let _ = crate::fill_random(&mut nonce);
match pcp_map(gw, client, internal, internal, lease, &nonce) {
Ok((external, life)) => {
return Ok(Mapping {
method: Method::Pcp,
internal,
external,
lifetime: life,
renewed: Instant::now(),
handle: Handle::Pmp {
gateway: gw,
client,
nonce,
},
});
}
Err(e) => why.push(format!("PCP: {e}")),
}
match natpmp_map(gw, internal, internal, lease) {
Ok((port, life)) => {
let ip = natpmp_external(gw).map_or(IpAddr::V4(Ipv4Addr::UNSPECIFIED), IpAddr::V4);
return Ok(Mapping {
method: Method::NatPmp,
internal,
external: SocketAddr::new(ip, port),
lifetime: life,
renewed: Instant::now(),
handle: Handle::NatPmp { gateway: gw },
});
}
Err(e) => why.push(format!("NAT-PMP: {e}")),
}
}
for location in &targets.upnp {
match Igd::from_location(location).and_then(|igd| upnp_map(igd, client, internal, lease)) {
Ok(m) => return Ok(m),
Err(e) => why.push(format!("UPnP: {e}")),
}
}
if why.is_empty() {
why.push("no router answered".into());
}
Err(why.join("; "))
}
fn upnp_map(igd: Igd, client: Ipv4Addr, internal: u16, lease: Duration) -> io::Result<Mapping> {
let mut permanent = false;
let mut last = io::Error::other("no port");
// The same port outside first (easy to forward by hand later), then others.
let mut ports = vec![internal];
let mut r = [0u8; 2];
for _ in 0..3 {
let _ = crate::fill_random(&mut r);
ports.push(20000 + u16::from_le_bytes(r) % 40000);
}
for port in ports {
let secs = if permanent { 0 } else { lease.as_secs() as u32 };
match igd.add(port, internal, client, secs) {
Ok(()) => {
let ip = igd
.external_ip()
.unwrap_or(IpAddr::V4(Ipv4Addr::UNSPECIFIED));
return Ok(Mapping {
method: Method::Upnp,
internal,
external: SocketAddr::new(ip, port),
lifetime: if permanent { LEASE } else { lease },
renewed: Instant::now(),
handle: Handle::Upnp {
igd,
client,
permanent,
},
});
}
// OnlyPermanentLeasesSupported: ask without a lease (deleted on stop).
Err(UpnpError::Code(725)) if !permanent => {
permanent = true;
match igd.add(port, internal, client, 0) {
Ok(()) => {
let ip = igd
.external_ip()
.unwrap_or(IpAddr::V4(Ipv4Addr::UNSPECIFIED));
return Ok(Mapping {
method: Method::Upnp,
internal,
external: SocketAddr::new(ip, port),
lifetime: LEASE,
renewed: Instant::now(),
handle: Handle::Upnp {
igd,
client,
permanent,
},
});
}
Err(e) => last = e.into(),
}
}
// ConflictInMappingEntry and friends: another port.
Err(UpnpError::Code(c)) => last = io::Error::other(format!("error {c}")),
Err(UpnpError::Io(e)) => return Err(e),
}
}
Err(last)
}
impl Mapping {
/// A mapping as a router would have granted it (tests elsewhere).
#[cfg(test)]
pub(crate) fn granted(method: Method, external: SocketAddr) -> Self {
Self {
method,
internal: 25580,
external,
lifetime: LEASE,
renewed: Instant::now(),
handle: Handle::NatPmp {
gateway: SocketAddr::from(([127, 0, 0, 1], 9)),
},
}
}
/// Whether the lease is past half-time.
pub fn due(&self) -> bool {
self.renewed.elapsed() >= self.lifetime / 2
}
pub fn renew(&mut self) -> io::Result<()> {
let internal = self.internal;
let lease = LEASE;
match &self.handle {
Handle::Pmp {
gateway,
client,
nonce,
} => {
let (external, life) = pcp_map(
*gateway,
*client,
internal,
self.external.port(),
lease,
nonce,
)?;
self.external = external;
self.lifetime = life;
}
Handle::NatPmp { gateway } => {
let (port, life) = natpmp_map(*gateway, internal, self.external.port(), lease)?;
self.external.set_port(port);
self.lifetime = life;
}
Handle::Upnp {
igd,
client,
permanent,
} => {
let secs = if *permanent {
0
} else {
lease.as_secs() as u32
};
igd.add(self.external.port(), internal, *client, secs)?;
}
}
self.renewed = Instant::now();
Ok(())
}
/// Delete the mapping (best effort).
pub fn remove(&self) {
match &self.handle {
Handle::Pmp {
gateway,
client,
nonce,
} => {
let _ = pcp_map(*gateway, *client, self.internal, 0, Duration::ZERO, nonce);
}
Handle::NatPmp { gateway } => {
let _ = natpmp_map(*gateway, self.internal, 0, Duration::ZERO);
}
Handle::Upnp { igd, .. } => {
let _ = igd.delete(self.external.port());
}
}
}
}
// ----- PCP and NAT-PMP --------------------------------------------------------------------------
/// Send `req` and wait for a datagram from the gateway, with RFC 6886's
/// retransmissions (250 ms, doubling), three tries.
fn exchange(gateway: SocketAddr, req: &[u8]) -> io::Result<Vec<u8>> {
let socket = UdpSocket::bind("0.0.0.0:0")?;
socket.connect(gateway)?;
let mut wait = Duration::from_millis(250);
let mut buf = [0u8; 1100];
for _ in 0..3 {
socket.send(req)?;
socket.set_read_timeout(Some(wait))?;
match socket.recv(&mut buf) {
Ok(n) => return Ok(buf[..n].to_vec()),
Err(e) if e.kind() == io::ErrorKind::ConnectionRefused => return Err(e),
Err(_) => wait *= 2,
}
}
Err(io::Error::new(io::ErrorKind::TimedOut, "no answer"))
}
fn mapped_v6(ip: Ipv4Addr) -> [u8; 16] {
ip.to_ipv6_mapped().octets()
}
/// PCP MAP for TCP: the external address and the granted lifetime. A
/// zero lifetime deletes.
pub fn pcp_map(
gateway: SocketAddr,
client: Ipv4Addr,
internal: u16,
external: u16,
lease: Duration,
nonce: &[u8; 12],
) -> io::Result<(SocketAddr, Duration)> {
let mut req = vec![0u8; 60];
req[0] = 2;
req[1] = 1;
req[4..8].copy_from_slice(&(lease.as_secs() as u32).to_be_bytes());
req[8..24].copy_from_slice(&mapped_v6(client));
req[24..36].copy_from_slice(nonce);
req[36] = 6;
req[40..42].copy_from_slice(&internal.to_be_bytes());
req[42..44].copy_from_slice(&external.to_be_bytes());
req[44..60].copy_from_slice(&mapped_v6(Ipv4Addr::UNSPECIFIED));
let r = exchange(gateway, &req)?;
if r.len() < 2 || r[0] != 2 {
return Err(io::Error::other("not a PCP router"));
}
if r.len() < 60 || r[1] != 0x81 || &r[24..36] != nonce {
return Err(io::Error::other("bad answer"));
}
if r[3] != 0 {
return Err(io::Error::other(format!("result {}", r[3])));
}
let life = Duration::from_secs(u64::from(u32::from_be_bytes(r[4..8].try_into().unwrap())));
let port = u16::from_be_bytes([r[42], r[43]]);
let o: [u8; 16] = r[44..60].try_into().unwrap();
let v6 = Ipv6Addr::from(o);
let ip = v6.to_ipv4_mapped().map_or(IpAddr::V6(v6), IpAddr::V4);
Ok((SocketAddr::new(ip, port), life))
}
/// NAT-PMP's external address request.
pub fn natpmp_external(gateway: SocketAddr) -> io::Result<Ipv4Addr> {
let r = exchange(gateway, &[0, 0])?;
if r.len() < 12 || r[0] != 0 || r[1] != 128 {
return Err(io::Error::other("bad answer"));
}
if r[2..4] != [0, 0] {
return Err(io::Error::other(format!(
"result {}",
u16::from_be_bytes([r[2], r[3]])
)));
}
Ok(Ipv4Addr::new(r[8], r[9], r[10], r[11]))
}
/// NAT-PMP TCP mapping: the external port and lifetime. Zero deletes.
pub fn natpmp_map(
gateway: SocketAddr,
internal: u16,
external: u16,
lease: Duration,
) -> io::Result<(u16, Duration)> {
let mut req = [0u8; 12];
req[1] = 2;
req[4..6].copy_from_slice(&internal.to_be_bytes());
req[6..8].copy_from_slice(&external.to_be_bytes());
req[8..12].copy_from_slice(&(lease.as_secs() as u32).to_be_bytes());
let r = exchange(gateway, &req)?;
if r.len() < 16 || r[0] != 0 || r[1] != 130 {
return Err(io::Error::other("not a NAT-PMP router"));
}
if r[2..4] != [0, 0] {
return Err(io::Error::other(format!(
"result {}",
u16::from_be_bytes([r[2], r[3]])
)));
}
Ok((
u16::from_be_bytes([r[10], r[11]]),
Duration::from_secs(u64::from(u32::from_be_bytes(r[12..16].try_into().unwrap()))),
))
}
// ----- UPnP IGD ---------------------------------------------------------------------------------
/// `http://host:port/path` → host, port, path.
fn split_url(url: &str) -> Option<(String, u16, String)> {
let rest = url.strip_prefix("http://")?;
let (hostport, path) = match rest.find('/') {
Some(i) => (&rest[..i], &rest[i..]),
None => (rest, "/"),
};
let (host, port) = match hostport.rsplit_once(':') {
Some((h, p)) if !h.contains(']') || h.ends_with(']') => (h, p.parse().ok()?),
_ => (hostport, 80),
};
Some((
host.trim_matches(|c| c == '[' || c == ']').to_owned(),
port,
path.to_owned(),
))
}
/// A tiny HTTP/1.1 client (Connection: close; Content-Length, chunked or
/// to the end).
fn http(
method: &str,
url: &str,
headers: &[(&str, &str)],
body: &str,
) -> io::Result<(u16, String)> {
let (host, port, path) = split_url(url).ok_or_else(|| io::Error::other("bad URL"))?;
let addr = (host.as_str(), port)
.to_socket_addrs()?
.next()
.ok_or_else(|| io::Error::other("no address"))?;
let mut s = TcpStream::connect_timeout(&addr, Duration::from_secs(3))?;
s.set_read_timeout(Some(Duration::from_secs(5)))?;
let mut req = format!(
"{method} {path} HTTP/1.1\r\nHost: {host}:{port}\r\nConnection: close\r\nContent-Length: {}\r\n",
body.len()
);
for (k, v) in headers {
req.push_str(&format!("{k}: {v}\r\n"));
}
req.push_str("\r\n");
req.push_str(body);
s.write_all(req.as_bytes())?;
let mut raw = Vec::new();
s.take(1 << 20).read_to_end(&mut raw)?;
let text = String::from_utf8_lossy(&raw).into_owned();
let (head, rest) = text
.split_once("\r\n\r\n")
.ok_or_else(|| io::Error::other("bad response"))?;
let status = head
.split_whitespace()
.nth(1)
.and_then(|c| c.parse().ok())
.ok_or_else(|| io::Error::other("bad status"))?;
let chunked = head.lines().any(|l| {
let l = l.to_ascii_lowercase();
l.starts_with("transfer-encoding:") && l.contains("chunked")
});
let body = if chunked {
dechunk(rest)
} else {
rest.to_owned()
};
Ok((status, body))
}
fn dechunk(mut s: &str) -> String {
let mut out = String::new();
while let Some((size, rest)) = s.split_once("\r\n") {
let Ok(n) = usize::from_str_radix(size.split(';').next().unwrap_or("").trim(), 16) else {
break;
};
if n == 0 || rest.len() < n {
break;
}
out.push_str(&rest[..n]);
s = rest[n..].trim_start_matches("\r\n");
}
out
}
/// The text of the first `<tag>` (any namespace prefix) in `xml`.
fn tag<'a>(xml: &'a str, name: &str) -> Option<&'a str> {
let mut from = 0;
while let Some(i) = xml[from..].find('<') {
let start = from + i + 1;
let end = start + xml[start..].find('>')?;
let open = &xml[start..end];
let local = open.split_whitespace().next().unwrap_or("");
let local = local.rsplit(':').next().unwrap_or(local);
if local == name && !open.starts_with('/') {
let body = &xml[end + 1..];
let close = body.find("</")?;
return Some(body[..close].trim());
}
from = end + 1;
}
None
}
/// The Location headers of SSDP answers (devices answering an M-SEARCH for
/// internet gateways).
pub fn ssdp_discover(timeout: Duration) -> Vec<String> {
let Ok(s) = UdpSocket::bind("0.0.0.0:0") else {
return Vec::new();
};
let _ = s.set_read_timeout(Some(Duration::from_millis(200)));
for st in [
"urn:schemas-upnp-org:device:InternetGatewayDevice:1",
"urn:schemas-upnp-org:device:InternetGatewayDevice:2",
"urn:schemas-upnp-org:service:WANIPConnection:1",
] {
let m = format!(
"M-SEARCH * HTTP/1.1\r\nHOST: 239.255.255.250:1900\r\nST: {st}\r\nMAN: \"ssdp:discover\"\r\nMX: 2\r\n\r\n"
);
let _ = s.send_to(m.as_bytes(), "239.255.255.250:1900");
}
let deadline = Instant::now() + timeout;
let mut found = Vec::new();
let mut buf = [0u8; 2048];
while Instant::now() < deadline {
if let Ok((n, _)) = s.recv_from(&mut buf)
&& let Some(l) = ssdp_location(&String::from_utf8_lossy(&buf[..n]))
&& !found.contains(&l)
{
found.push(l);
}
}
found
}
pub fn ssdp_location(response: &str) -> Option<String> {
response.lines().find_map(|l| {
let (k, v) = l.split_once(':')?;
k.trim()
.eq_ignore_ascii_case("location")
.then(|| v.trim().to_owned())
})
}
enum UpnpError {
Code(u32),
Io(io::Error),
}
impl From<io::Error> for UpnpError {
fn from(e: io::Error) -> Self {
Self::Io(e)
}
}
impl From<UpnpError> for io::Error {
fn from(e: UpnpError) -> Self {
match e {
UpnpError::Code(c) => io::Error::other(format!("error {c}")),
UpnpError::Io(e) => e,
}
}
}
/// An internet gateway's connection service.
#[derive(Clone, Debug)]
pub struct Igd {
control: String,
service: String,
}
impl Igd {
/// Read the device description for a WANIPConnection (or WANPPPConnection) service.
pub fn from_location(location: &str) -> io::Result<Self> {
let (status, xml) = http("GET", location, &[], "")?;
if status != 200 {
return Err(io::Error::other(format!("description: HTTP {status}")));
}
let (host, port, _) = split_url(location).ok_or_else(|| io::Error::other("bad URL"))?;
let base = tag(&xml, "URLBase")
.map(|b| b.trim_end_matches('/').to_owned())
.unwrap_or_else(|| format!("http://{host}:{port}"));
for block in xml.split("<service>").skip(1) {
let Some(service) = tag(block, "serviceType") else {
continue;
};
if !(service.contains(":WANIPConnection:") || service.contains(":WANPPPConnection:")) {
continue;
}
let Some(control) = tag(block, "controlURL") else {
continue;
};
let control = if control.starts_with("http://") {
control.to_owned()
} else {
format!("{base}/{}", control.trim_start_matches('/'))
};
return Ok(Self {
control,
service: service.to_owned(),
});
}
Err(io::Error::other("no WAN connection service"))
}
fn soap(&self, action: &str, args: &[(&str, String)]) -> Result<String, UpnpError> {
let mut body = format!(
"<?xml version=\"1.0\"?>\n<s:Envelope xmlns:s=\"http://schemas.xmlsoap.org/soap/envelope/\" s:encodingStyle=\"http://schemas.xmlsoap.org/soap/encoding/\"><s:Body><u:{action} xmlns:u=\"{}\">",
self.service
);
for (k, v) in args {
body.push_str(&format!("<{k}>{v}</{k}>"));
}
body.push_str(&format!("</u:{action}></s:Body></s:Envelope>"));
let soap_action = format!("\"{}#{action}\"", self.service);
let (status, reply) = http(
"POST",
&self.control,
&[
("Content-Type", "text/xml; charset=\"utf-8\""),
("SOAPAction", &soap_action),
],
&body,
)?;
if status == 200 {
return Ok(reply);
}
match tag(&reply, "errorCode").and_then(|c| c.parse().ok()) {
Some(code) => Err(UpnpError::Code(code)),
None => Err(UpnpError::Io(io::Error::other(format!("HTTP {status}")))),
}
}
fn add(
&self,
external: u16,
internal: u16,
client: Ipv4Addr,
lease: u32,
) -> Result<(), UpnpError> {
self.soap(
"AddPortMapping",
&[
("NewRemoteHost", String::new()),
("NewExternalPort", external.to_string()),
("NewProtocol", "TCP".into()),
("NewInternalPort", internal.to_string()),
("NewInternalClient", client.to_string()),
("NewEnabled", "1".into()),
("NewPortMappingDescription", DESCRIPTION.into()),
("NewLeaseDuration", lease.to_string()),
],
)
.map(|_| ())
}
fn delete(&self, external: u16) -> Result<(), UpnpError> {
self.soap(
"DeletePortMapping",
&[
("NewRemoteHost", String::new()),
("NewExternalPort", external.to_string()),
("NewProtocol", "TCP".into()),
],
)
.map(|_| ())
}
fn external_ip(&self) -> io::Result<IpAddr> {
let r = self.soap("GetExternalIPAddress", &[])?;
tag(&r, "NewExternalIPAddress")
.and_then(|t| t.parse().ok())
.ok_or_else(|| io::Error::other("no external address"))
}
}
// ----- The default gateway ----------------------------------------------------------------------
/// The IPv4 default gateway from the OS routing table.
pub fn default_gateway() -> Option<Ipv4Addr> {
#[cfg(target_os = "linux")]
{
linux_gateway(&std::fs::read_to_string("/proc/net/route").ok()?)
}
#[cfg(any(target_os = "macos", target_os = "freebsd", target_os = "openbsd"))]
{
let out = std::process::Command::new("route")
.args(["-n", "get", "default"])
.output()
.ok()?;
bsd_gateway(&String::from_utf8_lossy(&out.stdout))
}
#[cfg(windows)]
{
let out = std::process::Command::new("route")
.args(["print", "-4", "0.0.0.0"])
.output()
.ok()?;
windows_gateway(&String::from_utf8_lossy(&out.stdout))
}
#[cfg(not(any(
target_os = "linux",
target_os = "macos",
target_os = "freebsd",
target_os = "openbsd",
windows
)))]
{
None
}
}
pub fn linux_gateway(table: &str) -> Option<Ipv4Addr> {
table.lines().skip(1).find_map(|l| {
let f: Vec<&str> = l.split_whitespace().collect();
if f.len() > 2 && f[1] == "00000000" {
let g = u32::from_str_radix(f[2], 16).ok()?;
(g != 0).then(|| Ipv4Addr::from(g.swap_bytes()))
} else {
None
}
})
}
pub fn bsd_gateway(text: &str) -> Option<Ipv4Addr> {
text.lines().find_map(|l| {
l.trim()
.strip_prefix("gateway:")
.and_then(|g| g.trim().parse().ok())
})
}
pub fn windows_gateway(text: &str) -> Option<Ipv4Addr> {
text.lines().find_map(|l| {
let f: Vec<&str> = l.split_whitespace().collect();
(f.len() >= 3 && f[0] == "0.0.0.0" && f[1] == "0.0.0.0")
.then(|| f[2].parse().ok())
.flatten()
})
}
#[cfg(test)]
mod tests {
use super::*;
use std::{
collections::HashMap,
net::TcpListener,
sync::{Arc, Mutex},
};
type Table = Arc<Mutex<HashMap<u16, (u16, u32)>>>;
/// A router on loopback speaking PCP (unless `pmp_only`) and NAT-PMP;
/// external port = internal + 1000, WAN address 198.51.100.7.
fn mock_pmp(pmp_only: bool) -> (SocketAddr, Table) {
let s = UdpSocket::bind("127.0.0.1:0").unwrap();
let addr = s.local_addr().unwrap();
let table: Table = Arc::default();
let t = table.clone();
std::thread::spawn(move || {
let mut buf = [0u8; 1100];
while let Ok((n, from)) = s.recv_from(&mut buf) {
let r = &buf[..n];
let reply = match (r[0], r.get(1)) {
(2, _) if pmp_only => vec![0, 0x81, 0, 1],
(2, Some(1)) => {
let internal = u16::from_be_bytes([r[40], r[41]]);
let life = u32::from_be_bytes(r[4..8].try_into().unwrap());
let mut out = r.to_vec();
out[1] = 0x81;
out[2] = 0;
out[3] = 0;
let ext = if life == 0 {
t.lock().unwrap().remove(&internal);
0
} else {
t.lock().unwrap().insert(internal, (internal + 1000, life));
internal + 1000
};
out[42..44].copy_from_slice(&ext.to_be_bytes());
out[44..60].copy_from_slice(
&Ipv4Addr::new(198, 51, 100, 7).to_ipv6_mapped().octets(),
);
out
}
(0, Some(0)) => vec![0, 128, 0, 0, 0, 0, 0, 1, 198, 51, 100, 7],
(0, Some(2)) => {
let internal = u16::from_be_bytes([r[4], r[5]]);
let life = u32::from_be_bytes(r[8..12].try_into().unwrap());
let ext = if life == 0 {
t.lock().unwrap().remove(&internal);
0
} else {
t.lock().unwrap().insert(internal, (internal + 1000, life));
internal + 1000
};
let mut out = vec![0, 130, 0, 0, 0, 0, 0, 1];
out.extend_from_slice(&internal.to_be_bytes());
out.extend_from_slice(&ext.to_be_bytes());
out.extend_from_slice(&life.to_be_bytes());
out
}
_ => continue,
};
let _ = s.send_to(&reply, from);
}
});
(addr, table)
}
#[test]
fn pcp_maps_renews_and_deletes() {
let (gw, table) = mock_pmp(false);
let targets = Targets {
pmp: vec![gw],
upnp: vec![],
};
let mut m = map(&targets, Ipv4Addr::new(192, 168, 1, 20), 25580, LEASE).unwrap();
assert_eq!(m.method, Method::Pcp);
assert_eq!(m.external, "198.51.100.7:26580".parse().unwrap());
assert_eq!(table.lock().unwrap()[&25580], (26580, 3600));
assert!(!m.due());
m.renew().unwrap();
m.remove();
assert!(table.lock().unwrap().is_empty());
}
#[test]
fn nat_pmp_when_pcp_is_unsupported() {
let (gw, table) = mock_pmp(true);
let targets = Targets {
pmp: vec![gw],
upnp: vec![],
};
let m = map(&targets, Ipv4Addr::new(192, 168, 1, 20), 25580, LEASE).unwrap();
assert_eq!(m.method, Method::NatPmp);
assert_eq!(m.external, "198.51.100.7:26580".parse().unwrap());
m.remove();
assert!(table.lock().unwrap().is_empty());
}
/// An IGD on loopback: description, then SOAP. `permanent_only` answers
/// 725 to leases; `taken` ports answer 718.
fn mock_igd(
permanent_only: bool,
taken: u16,
) -> (String, Arc<Mutex<HashMap<u16, (u16, String, u32)>>>) {
let l = TcpListener::bind("127.0.0.1:0").unwrap();
let port = l.local_addr().unwrap().port();
let table: Arc<Mutex<HashMap<u16, (u16, String, u32)>>> = Arc::default();
let t = table.clone();
std::thread::spawn(move || {
for s in l.incoming() {
let Ok(mut s) = s else { continue };
let mut req = Vec::new();
let mut buf = [0u8; 4096];
// Read the headers, then Content-Length bytes.
loop {
let n = s.read(&mut buf).unwrap_or(0);
if n == 0 {
break;
}
req.extend_from_slice(&buf[..n]);
let text = String::from_utf8_lossy(&req);
if let Some((head, body)) = text.split_once("\r\n\r\n") {
let len: usize = head
.lines()
.find_map(|l| l.strip_prefix("Content-Length: "))
.and_then(|v| v.trim().parse().ok())
.unwrap_or(0);
if body.len() >= len {
break;
}
}
}
let text = String::from_utf8_lossy(&req).into_owned();
let (status, body) = if text.starts_with("GET /desc.xml") {
(200, "<root><device><serviceList><service><serviceType>urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1</serviceType><controlURL>/wrong</controlURL></service><service><serviceType>urn:schemas-upnp-org:service:WANIPConnection:1</serviceType><controlURL>/ctl</controlURL></service></serviceList></device></root>".to_owned())
} else if text.contains("#GetExternalIPAddress") {
(200, "<s:Envelope><s:Body><u:GetExternalIPAddressResponse><NewExternalIPAddress>198.51.100.8</NewExternalIPAddress></u:GetExternalIPAddressResponse></s:Body></s:Envelope>".to_owned())
} else if text.contains("#AddPortMapping") {
let ext: u16 = tag(&text, "NewExternalPort").unwrap().parse().unwrap();
let int: u16 = tag(&text, "NewInternalPort").unwrap().parse().unwrap();
let client = tag(&text, "NewInternalClient").unwrap().to_owned();
let lease: u32 = tag(&text, "NewLeaseDuration").unwrap().parse().unwrap();
if permanent_only && lease != 0 {
(500, "<s:Fault><detail><UPnPError><errorCode>725</errorCode></UPnPError></detail></s:Fault>".to_owned())
} else if ext == taken {
(500, "<s:Fault><detail><UPnPError><errorCode>718</errorCode></UPnPError></detail></s:Fault>".to_owned())
} else {
t.lock().unwrap().insert(ext, (int, client, lease));
(200, "<ok/>".to_owned())
}
} else if text.contains("#DeletePortMapping") {
let ext: u16 = tag(&text, "NewExternalPort").unwrap().parse().unwrap();
t.lock().unwrap().remove(&ext);
(200, "<ok/>".to_owned())
} else {
(404, String::new())
};
let _ = write!(
s,
"HTTP/1.1 {status} X\r\nContent-Type: text/xml\r\nTransfer-Encoding: chunked\r\n\r\n{:x}\r\n{body}\r\n0\r\n\r\n",
body.len()
);
}
});
(format!("http://127.0.0.1:{port}/desc.xml"), table)
}
#[test]
fn upnp_maps_and_deletes() {
let (location, table) = mock_igd(false, 0);
let targets = Targets {
pmp: vec![],
upnp: vec![location],
};
let client = Ipv4Addr::new(192, 168, 1, 20);
let mut m = map(&targets, client, 25580, LEASE).unwrap();
assert_eq!(m.method, Method::Upnp);
assert_eq!(m.external, "198.51.100.8:25580".parse().unwrap());
assert_eq!(
table.lock().unwrap()[&25580],
(25580, "192.168.1.20".into(), 3600)
);
m.renew().unwrap();
m.remove();
assert!(table.lock().unwrap().is_empty());
}
#[test]
fn upnp_permanent_leases_and_taken_ports() {
let (location, table) = mock_igd(true, 25580);
let targets = Targets {
pmp: vec![],
upnp: vec![location],
};
let m = map(&targets, Ipv4Addr::new(10, 0, 0, 2), 25580, LEASE).unwrap();
// 725 → no lease; 718 on 25580 → another port.
assert_ne!(m.external.port(), 25580);
let entry = table.lock().unwrap()[&m.external.port()].clone();
assert_eq!(entry, (25580, "10.0.0.2".into(), 0));
m.remove();
assert!(table.lock().unwrap().is_empty());
}
#[test]
fn nothing_answering_says_why() {
let quiet = UdpSocket::bind("127.0.0.1:0").unwrap();
let targets = Targets {
pmp: vec![quiet.local_addr().unwrap()],
upnp: vec![],
};
let e = map(&targets, Ipv4Addr::new(10, 0, 0, 2), 1, LEASE).unwrap_err();
assert!(e.contains("PCP") && e.contains("NAT-PMP"), "{e}");
assert_eq!(
map(&Targets::default(), Ipv4Addr::LOCALHOST, 1, LEASE).unwrap_err(),
"no router answered"
);
}
#[test]
fn parsers() {
assert_eq!(
ssdp_location(
"HTTP/1.1 200 OK\r\nCACHE-CONTROL: max-age=120\r\nLOCATION: http://192.168.1.1:5000/rootDesc.xml\r\nST: x\r\n\r\n"
),
Some("http://192.168.1.1:5000/rootDesc.xml".into())
);
assert_eq!(
split_url("http://192.168.1.1:5000/a/b"),
Some(("192.168.1.1".into(), 5000, "/a/b".into()))
);
assert_eq!(
split_url("http://router/"),
Some(("router".into(), 80, "/".into()))
);
assert_eq!(
linux_gateway(
"Iface\tDestination\tGateway \tFlags\neth0\t0001A8C0\t00000000\t0001\neth0\t00000000\t0101A8C0\t0003\n"
),
Some(Ipv4Addr::new(192, 168, 1, 1))
);
assert_eq!(
bsd_gateway(" route to: default\ndestination: default\n gateway: 192.168.1.254\n"),
Some(Ipv4Addr::new(192, 168, 1, 254))
);
assert_eq!(
windows_gateway(
"Network Destination Netmask Gateway Interface Metric\n 0.0.0.0 0.0.0.0 10.0.0.138 10.0.0.12 25\n"
),
Some(Ipv4Addr::new(10, 0, 0, 138))
);
assert_eq!(
tag("<a:Body><x:Name attr=\"1\"> v </x:Name></a:Body>", "Name"),
Some("v")
);
}
}
+360
View File
@@ -0,0 +1,360 @@
//! How a host can be reached, worked out on its own: its interface
//! addresses (LAN, VPNs such as Tailscale or ZeroTier, IPv6), a port opened
//! on the router (PCP / NAT-PMP / UPnP), and its public address from STUN.
//! The endpoints go into the invite code; the verdict tells the host what
//! friends outside its network can expect, and what to do when it's nothing.
use crate::portmap::{self, Mapping};
use std::{
net::{IpAddr, Ipv4Addr, SocketAddr},
time::Duration,
};
/// Where the troubleshooting lives (shown to hosts nobody can reach).
pub const HELP_URL: &str =
"https://github.com/ludovic111/horizon/blob/main/docs/play-with-friends.md#troubleshooting";
#[derive(Clone, Debug)]
pub struct Options {
/// Ask the router to open the port.
pub map_port: bool,
pub stun: Vec<String>,
/// Offer 127.0.0.1 too (tests with both ends on one machine).
pub loopback: bool,
}
#[derive(Clone, Debug, Default)]
pub struct Reach {
pub port: u16,
pub local: Vec<IpAddr>,
pub mapping: Option<Mapping>,
pub mapping_error: Option<String>,
pub public_ip: Option<IpAddr>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Verdict {
/// The router opened the port (method name).
Mapped(&'static str),
/// This machine has the public address itself.
Public,
/// Only the LAN and VPNs reach it; `cgnat` when the router is itself
/// behind another NAT (the provider's, or a second router), so port
/// forwarding on it can't help.
LocalOnly { cgnat: bool },
}
/// 100.64.0.0/10 (carrier-grade NAT, also Tailscale's range) or private.
fn shared(ip: IpAddr) -> bool {
match ip {
IpAddr::V4(v4) => {
let o = v4.octets();
v4.is_private() || (o[0] == 100 && (64..128).contains(&o[1]))
}
IpAddr::V6(_) => false,
}
}
/// Interface names of containers and VMs, whose addresses nobody else reaches.
fn virtual_interface(name: &str) -> bool {
[
"docker", "br-", "veth", "virbr", "vboxnet", "vmnet", "lxc", "cni", "podman",
]
.iter()
.any(|p| name.starts_with(p))
}
/// This machine's addresses worth offering, best first: private IPv4 (the
/// LAN), shared IPv4 (Tailscale's 100.64/10, CGNAT), other IPv4, global
/// IPv6, unique-local IPv6 (some VPNs). No link-local; loopback on request.
pub fn interface_addresses(loopback: bool) -> Vec<IpAddr> {
let mut found: Vec<(u8, IpAddr)> = Vec::new();
for i in if_addrs::get_if_addrs().unwrap_or_default() {
if virtual_interface(&i.name) {
continue;
}
let ip = i.ip();
let rank = match ip {
IpAddr::V4(v4) if v4.is_loopback() => {
if loopback {
6
} else {
continue;
}
}
IpAddr::V4(v4) if v4.is_link_local() || v4.is_unspecified() => continue,
IpAddr::V4(v4) if v4.is_private() => 0,
v4 @ IpAddr::V4(_) if shared(v4) => 1,
IpAddr::V4(_) => 2,
IpAddr::V6(v6) if v6.is_loopback() || v6.is_unspecified() => continue,
// fe80::/10.
IpAddr::V6(v6) if v6.segments()[0] & 0xffc0 == 0xfe80 => continue,
// fc00::/7.
IpAddr::V6(v6) if v6.segments()[0] & 0xfe00 == 0xfc00 => 4,
IpAddr::V6(_) => 3,
};
if !found.iter().any(|(_, a)| *a == ip) {
found.push((rank, ip));
}
}
found.sort_by_key(|(r, _)| *r);
// One IPv6 address per kind is enough (temporary addresses multiply them).
let mut out = Vec::new();
let mut v6_kinds = Vec::new();
for (rank, ip) in found {
if ip.is_ipv6() {
if v6_kinds.contains(&rank) {
continue;
}
v6_kinds.push(rank);
}
out.push(ip);
}
out
}
impl Reach {
/// Find out (takes a few seconds: router discovery and STUN).
pub fn discover(port: u16, options: &Options) -> Self {
let local = interface_addresses(options.loopback);
let stun = {
let servers = options.stun.clone();
std::thread::spawn(move || crate::stun::public_ip(&servers, Duration::from_secs(2)))
};
let (mapping, mapping_error) = if options.map_port {
match local.iter().find_map(|ip| match ip {
IpAddr::V4(v4) if v4.is_private() => Some(*v4),
_ => None,
}) {
Some(client) => {
let targets = portmap::Targets::discover(Duration::from_millis(1500));
match portmap::map(&targets, client, port, portmap::LEASE) {
Ok(m) => (Some(m), None),
Err(e) => (None, Some(e)),
}
}
None => (
None,
Some("no private IPv4 address (no router to ask)".into()),
),
}
} else {
(None, Some("port mapping is off".into()))
};
let public_ip = stun.join().ok().flatten();
Self {
port,
local,
mapping,
mapping_error,
public_ip,
}
}
/// The router's public side, with the WAN address from STUN when the
/// router didn't give one.
fn mapped_endpoint(&self) -> Option<SocketAddr> {
let m = self.mapping.as_ref()?;
let ip = if m.external.ip().is_unspecified() {
self.public_ip?
} else {
m.external.ip()
};
Some(SocketAddr::new(ip, m.external.port()))
}
pub fn verdict(&self) -> Verdict {
if let Some(m) = &self.mapping {
let wan = m.external.ip();
// The router's own WAN side is shared or private, or STUN sees
// another address: a second NAT upstream.
let behind = (!wan.is_unspecified() && shared(wan))
|| self
.public_ip
.is_some_and(|p| !wan.is_unspecified() && p != wan);
if !behind {
return Verdict::Mapped(m.method.name());
}
return Verdict::LocalOnly { cgnat: true };
}
if let Some(p) = self.public_ip
&& self.local.contains(&p)
{
return Verdict::Public;
}
Verdict::LocalOnly { cgnat: false }
}
/// The code's endpoints, best first: the router mapping (or this
/// machine's own public address), then the public address on the
/// direct port (works once the port is forwarded by hand), then the
/// interface addresses.
pub fn endpoints(&self) -> Vec<SocketAddr> {
let mut out = Vec::new();
let mut push = |a: SocketAddr| {
if !out.contains(&a) {
out.push(a);
}
};
if let Some(m) = self.mapped_endpoint() {
push(m);
}
if let Some(p) = self.public_ip {
push(SocketAddr::new(p, self.port));
}
for ip in &self.local {
push(SocketAddr::new(*ip, self.port));
}
out.truncate(crate::invite::MAX_ENDPOINTS);
out
}
/// The LAN address a port forward should point at.
pub fn lan_ip(&self) -> Option<Ipv4Addr> {
self.local.iter().find_map(|ip| match ip {
IpAddr::V4(v4) if v4.is_private() => Some(*v4),
_ => None,
})
}
/// What the host reads under the code.
pub fn summary(&self) -> String {
match self.verdict() {
Verdict::Mapped(method) => {
let at = self.mapped_endpoint().map(|a| format!(" ({a})")).unwrap_or_default();
format!("Friends anywhere can join: your router opened the port with {method}{at}.")
}
Verdict::Public => format!(
"Friends anywhere can join: this computer has a public address (TCP port {} must not be blocked by a firewall).",
self.port
),
Verdict::LocalOnly { cgnat: true } => "Friends on your network or VPN can join. From the internet they can't: \
your router is itself behind another NAT (your provider's carrier-grade NAT, CGNAT, or a second router), \
so opening its port isn't enough. Use a relay or a VPN such as Tailscale or ZeroTier."
.to_owned(),
Verdict::LocalOnly { cgnat: false } => {
let forward = match self.lan_ip() {
Some(ip) => format!("forward TCP port {} to {ip}", self.port),
None => format!("forward TCP port {}", self.port),
};
format!(
"Friends on your network or VPN can join. For friends on the internet: turn on UPnP on your router, \
or {forward}, or use a relay, or a VPN such as Tailscale or ZeroTier (the code already holds \
your VPN address)."
)
}
}
}
/// Delete the router mapping.
pub fn release(&mut self) {
if let Some(m) = self.mapping.take() {
m.remove();
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn reach(public: Option<&str>, local: &[&str]) -> Reach {
Reach {
port: 25580,
local: local.iter().map(|s| s.parse().unwrap()).collect(),
mapping: None,
mapping_error: Some("no router answered".into()),
public_ip: public.map(|s| s.parse().unwrap()),
}
}
#[test]
fn endpoints_put_the_public_side_first() {
let r = reach(
Some("203.0.113.5"),
&["192.168.1.20", "100.72.51.8", "2001:db8::20"],
);
assert_eq!(
r.endpoints(),
[
"203.0.113.5:25580",
"192.168.1.20:25580",
"100.72.51.8:25580",
"[2001:db8::20]:25580"
]
.map(|s| s.parse::<SocketAddr>().unwrap())
);
assert_eq!(r.verdict(), Verdict::LocalOnly { cgnat: false });
let s = r.summary();
assert!(
s.contains("forward TCP port 25580 to 192.168.1.20") && s.contains("Tailscale"),
"{s}"
);
}
#[test]
fn a_public_address_on_this_machine() {
let r = reach(Some("203.0.113.5"), &["203.0.113.5"]);
assert_eq!(r.verdict(), Verdict::Public);
assert_eq!(
r.endpoints(),
vec!["203.0.113.5:25580".parse::<SocketAddr>().unwrap()]
);
}
#[test]
fn a_router_mapping_and_what_is_behind_it() {
use crate::portmap::{Mapping, Method};
let mut r = reach(Some("203.0.113.5"), &["192.168.1.20"]);
r.mapping = Some(Mapping::granted(
Method::Upnp,
"203.0.113.5:40123".parse().unwrap(),
));
assert_eq!(r.verdict(), Verdict::Mapped("UPnP"));
assert_eq!(
r.endpoints()[0],
"203.0.113.5:40123".parse::<SocketAddr>().unwrap()
);
assert!(r.summary().contains("UPnP (203.0.113.5:40123)"));
// The router didn't say its address: STUN's is used.
r.mapping = Some(Mapping::granted(
Method::NatPmp,
"0.0.0.0:40123".parse().unwrap(),
));
assert_eq!(
r.endpoints()[0],
"203.0.113.5:40123".parse::<SocketAddr>().unwrap()
);
// The router's WAN side is in the carrier's shared range: CGNAT.
r.mapping = Some(Mapping::granted(
Method::Pcp,
"100.80.1.2:40123".parse().unwrap(),
));
assert_eq!(r.verdict(), Verdict::LocalOnly { cgnat: true });
assert!(r.summary().contains("CGNAT"));
// STUN sees another address than the router's: a second NAT.
r.mapping = Some(Mapping::granted(
Method::Pcp,
"198.51.100.1:40123".parse().unwrap(),
));
assert_eq!(r.verdict(), Verdict::LocalOnly { cgnat: true });
}
#[test]
fn shared_ranges() {
assert!(shared("100.72.51.8".parse().unwrap()));
assert!(shared("10.1.2.3".parse().unwrap()));
assert!(!shared("100.128.0.1".parse().unwrap()));
assert!(!shared("8.8.8.8".parse().unwrap()));
assert!(
virtual_interface("docker0")
&& !virtual_interface("tailscale0")
&& !virtual_interface("en0")
);
}
#[test]
fn interface_addresses_skip_loopback_unless_asked() {
assert!(interface_addresses(false).iter().all(|a| !a.is_loopback()));
assert!(interface_addresses(true).contains(&IpAddr::V4(Ipv4Addr::LOCALHOST)));
}
}
+207
View File
@@ -0,0 +1,207 @@
//! The host's public IPv4 address, from a STUN Binding request (RFC 8489)
//! to public STUN servers. Only the address is used: the port a STUN server
//! sees is a UDP mapping, while the game listens on TCP.
use std::{
io,
net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, ToSocketAddrs, UdpSocket},
time::Duration,
};
/// Two independent operators, so one outage doesn't break discovery; both
/// run free public STUN for WebRTC at a global scale. Configurable with
/// `HORIZON_STUN_SERVERS` (a comma list; `none` turns STUN off).
pub const DEFAULT_SERVERS: &[&str] = &["stun.cloudflare.com:3478", "stun.l.google.com:19302"];
const MAGIC: u32 = 0x2112_A442;
/// The servers to ask: `HORIZON_STUN_SERVERS`, else the defaults.
pub fn servers_from_env() -> Vec<String> {
match std::env::var("HORIZON_STUN_SERVERS") {
Ok(v) => parse_servers(&v),
Err(_) => DEFAULT_SERVERS.iter().map(|s| (*s).to_owned()).collect(),
}
}
/// A comma list; empty or `none` means no STUN.
pub fn parse_servers(list: &str) -> Vec<String> {
if list.trim().eq_ignore_ascii_case("none") {
return Vec::new();
}
list.split(',')
.map(str::trim)
.filter(|s| !s.is_empty())
.map(str::to_owned)
.collect()
}
fn request(id: &[u8; 12]) -> [u8; 20] {
let mut m = [0u8; 20];
m[0..2].copy_from_slice(&0x0001u16.to_be_bytes());
m[4..8].copy_from_slice(&MAGIC.to_be_bytes());
m[8..20].copy_from_slice(id);
m
}
/// The mapped address in a Binding success response for transaction `id`.
pub fn parse_response(m: &[u8], id: &[u8; 12]) -> Option<SocketAddr> {
if m.len() < 20 || m[0..2] != [0x01, 0x01] || m[4..8] != MAGIC.to_be_bytes() || &m[8..20] != id
{
return None;
}
let len = usize::from(u16::from_be_bytes([m[2], m[3]]));
let attrs = m.get(20..20 + len)?;
let mut i = 0;
let mut plain = None;
while i + 4 <= attrs.len() {
let kind = u16::from_be_bytes([attrs[i], attrs[i + 1]]);
let alen = usize::from(u16::from_be_bytes([attrs[i + 2], attrs[i + 3]]));
let value = attrs.get(i + 4..i + 4 + alen)?;
let xor = kind == 0x0020;
if (xor || kind == 0x0001) && value.len() >= 8 {
let mut port = u16::from_be_bytes([value[2], value[3]]);
if xor {
port ^= (MAGIC >> 16) as u16;
}
let ip = match value[1] {
1 => {
let mut o: [u8; 4] = value[4..8].try_into().ok()?;
if xor {
for (b, k) in o.iter_mut().zip(MAGIC.to_be_bytes()) {
*b ^= k;
}
}
IpAddr::V4(Ipv4Addr::from(o))
}
2 if value.len() >= 20 => {
let mut o: [u8; 16] = value[4..20].try_into().ok()?;
if xor {
let mut key = MAGIC.to_be_bytes().to_vec();
key.extend_from_slice(id);
for (b, k) in o.iter_mut().zip(key) {
*b ^= k;
}
}
IpAddr::V6(Ipv6Addr::from(o))
}
_ => return None,
};
let found = SocketAddr::new(ip, port);
if xor {
return Some(found);
}
plain = Some(found);
}
i += 4 + alen.div_ceil(4) * 4;
}
plain
}
/// Ask one server (resolved to IPv4), retrying twice.
pub fn query(server: &str, timeout: Duration) -> io::Result<SocketAddr> {
let target = server
.to_socket_addrs()?
.find(SocketAddr::is_ipv4)
.ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "no IPv4 address"))?;
let socket = UdpSocket::bind("0.0.0.0:0")?;
socket.set_read_timeout(Some(timeout / 3))?;
let mut id = [0u8; 12];
crate::fill_random(&mut id)?;
let mut buf = [0u8; 576];
for _ in 0..3 {
socket.send_to(&request(&id), target)?;
loop {
match socket.recv_from(&mut buf) {
Ok((n, from)) if from == target => {
if let Some(a) = parse_response(&buf[..n], &id) {
return Ok(a);
}
}
Ok(_) => {}
Err(_) => break,
}
}
}
Err(io::Error::new(io::ErrorKind::TimedOut, "no STUN answer"))
}
/// The public IPv4 address from the first server that answers.
pub fn public_ip(servers: &[String], timeout: Duration) -> Option<IpAddr> {
servers
.iter()
.find_map(|s| query(s, timeout).ok())
.map(|a| a.ip())
}
#[cfg(test)]
pub(crate) mod tests {
use super::*;
/// A STUN server answering with XOR-MAPPED-ADDRESS = `answer`.
pub(crate) fn mock(answer: SocketAddr) -> SocketAddr {
let s = UdpSocket::bind("127.0.0.1:0").unwrap();
let addr = s.local_addr().unwrap();
std::thread::spawn(move || {
let mut buf = [0u8; 576];
while let Ok((n, from)) = s.recv_from(&mut buf) {
if n < 20 {
continue;
}
let id: [u8; 12] = buf[8..20].try_into().unwrap();
let _ = s.send_to(&response(&id, answer), from);
}
});
addr
}
pub(crate) fn response(id: &[u8; 12], a: SocketAddr) -> Vec<u8> {
let IpAddr::V4(ip) = a.ip() else { panic!() };
let mut attr = vec![0x00, 0x20, 0x00, 0x08, 0x00, 0x01];
attr.extend_from_slice(&(a.port() ^ (MAGIC >> 16) as u16).to_be_bytes());
let o = ip.octets();
let k = MAGIC.to_be_bytes();
attr.extend((0..4).map(|i| o[i] ^ k[i]));
let mut m = vec![0x01, 0x01];
m.extend_from_slice(&(attr.len() as u16).to_be_bytes());
m.extend_from_slice(&MAGIC.to_be_bytes());
m.extend_from_slice(id);
m.extend(attr);
m
}
#[test]
fn asks_and_reads_the_mapped_address() {
let answer: SocketAddr = "203.0.113.9:40000".parse().unwrap();
let server = mock(answer);
assert_eq!(
query(&server.to_string(), Duration::from_secs(2)).unwrap(),
answer
);
// The first server that answers wins; dead ones are skipped.
let dead = UdpSocket::bind("127.0.0.1:0")
.unwrap()
.local_addr()
.unwrap()
.to_string();
assert_eq!(
public_ip(&[dead, server.to_string()], Duration::from_millis(300)),
Some(answer.ip())
);
}
#[test]
fn responses_are_checked() {
let id = [7u8; 12];
let a: SocketAddr = "198.51.100.4:1234".parse().unwrap();
let good = response(&id, a);
assert_eq!(parse_response(&good, &id), Some(a));
assert_eq!(parse_response(&good, &[8u8; 12]), None);
let mut error = good.clone();
error[1] = 0x11;
assert_eq!(parse_response(&error, &id), None);
assert_eq!(parse_response(&good[..10], &id), None);
}
#[test]
fn server_lists() {
assert_eq!(parse_servers("none"), Vec::<String>::new());
assert_eq!(parse_servers(" a:1 , b:2,"), vec!["a:1", "b:2"]);
}
}
+1 -1
View File
@@ -1,4 +1,4 @@
# The Play with friends relay (docs/play-with-friends.md, "Deploying the relay").
# The Play with friends relay, for anyone to run (docs/play-with-friends.md, "Running your own relay").
# Build context: the repository root (the workspace's manifests and lockfile):
# docker build -f crates/horizon-relay/Dockerfile -t horizon-relay .
FROM rust:1-slim-bookworm AS build
@@ -0,0 +1,24 @@
# A systemd unit for a self-hosted Play with friends relay (docs/play-with-friends.md,
# "Running your own relay"). Install the binary as /usr/local/bin/horizon-relay, copy this
# file to /etc/systemd/system/, then: systemctl enable --now horizon-relay
[Unit]
Description=Horizon play-with-friends relay
After=network-online.target
Wants=network-online.target
[Service]
ExecStart=/usr/local/bin/horizon-relay
# The port friends reach (forward it on your router, TCP). Limits: RELAY_* in the docs.
Environment=PORT=7000
# Environment=RELAY_SESSION_KBPS=1024
# Environment=RELAY_TOTAL_MBPS=20
DynamicUser=yes
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
-13
View File
@@ -1,13 +0,0 @@
# Railway service for the Play with friends relay. Set the service's config
# file path to crates/horizon-relay/railway.toml (docs/play-with-friends.md).
[build]
builder = "DOCKERFILE"
dockerfilePath = "crates/horizon-relay/Dockerfile"
watchPatterns = ["crates/horizon-relay/**", "crates/horizon-friends/**", "Cargo.lock"]
[deploy]
healthcheckPath = "/health"
healthcheckTimeout = 30
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10
numReplicas = 1
+185 -100
View File
@@ -1,11 +1,16 @@
//! A relay, a host tunnel in front of an echo server standing in for the
//! integrated server, and guest tunnels, all on loopback in one process.
//! Hosts in front of an echo server standing in for the integrated server,
//! guests, and (for the relay cases) a self-hosted relay, all on loopback
//! in one process. Port mapping and STUN are off here: they have their own
//! tests against mock routers and servers in horizon-friends.
use horizon_friends::{
Code, Host, HostConfig, HostEvent, JoinError, PathMode,
guest::{self, GuestConfig},
invite::{self, Invite, Parsed},
reach,
};
use horizon_relay::{Config, Relay, limits::Rates};
use std::{
cell::RefCell,
io::{Read, Write},
net::{SocketAddr, TcpListener, TcpStream},
time::{Duration, Instant},
@@ -45,25 +50,26 @@ fn generous() -> Config {
}
}
fn host(relay: &str, lan: SocketAddr, path: PathMode) -> (Host, Code) {
let host = Host::start(HostConfig {
relay: relay.to_owned(),
lan,
fn start(relay: Option<&str>, path: PathMode) -> Host {
Host::start(HostConfig {
lan: echo_server(),
protocol: PROTOCOL,
game: "26.3".into(),
relay: relay.map(str::to_owned),
path,
port: 0,
reach: reach::Options {
map_port: false,
stun: Vec::new(),
loopback: true,
},
})
.unwrap();
let code = wait_event(&host, |e| match e {
HostEvent::Code(c) => Some(c.clone()),
_ => None,
});
(host, code)
.unwrap()
}
thread_local! {
/// Events polled but not yet waited for.
static BACKLOG: std::cell::RefCell<Vec<HostEvent>> = const { std::cell::RefCell::new(Vec::new()) };
static BACKLOG: RefCell<Vec<HostEvent>> = const { RefCell::new(Vec::new()) };
}
/// The first event (in order) that `f` picks; the others stay queued.
@@ -83,10 +89,25 @@ fn wait_event<T>(host: &Host, mut f: impl FnMut(&HostEvent) -> Option<T>) -> T {
panic!("no such host event");
}
fn join(relay: &str, code: &Code, path: PathMode) -> Result<guest::Tunnel, JoinError> {
/// The invite once ready (and, with a relay, once it holds the short code).
fn invite_of(host: &Host, with_relay: bool) -> (String, Option<Code>) {
let deadline = Instant::now() + Duration::from_secs(10);
loop {
let s = host.state();
if let Some(code) = s.invite
&& (!with_relay || s.short.is_some())
{
return (code, s.short);
}
assert!(Instant::now() < deadline, "no code");
std::thread::sleep(Duration::from_millis(10));
}
}
fn join(code: &str, relay: Option<&str>, path: PathMode) -> Result<guest::Tunnel, JoinError> {
guest::join(&GuestConfig {
relay: relay.to_owned(),
code: code.clone(),
code: code.to_owned(),
relay: relay.map(str::to_owned),
protocol: PROTOCOL,
game: "26.3".into(),
path,
@@ -114,110 +135,174 @@ fn payload(n: usize) -> Vec<u8> {
(0..n).map(|i| (i * 7 + i / 251) as u8).collect()
}
fn long(code: &str) -> Invite {
match invite::parse(code) {
Some(Parsed::Long(i)) => i,
other => panic!("{other:?}"),
}
}
#[test]
fn the_direct_path_carries_the_stream() {
let (relay, address) = relay(generous());
let (host, code) = host(&address, echo_server(), PathMode::Auto);
assert_eq!(code.nameplate.len(), 4);
let tunnel = join(&address, &code, PathMode::Auto).unwrap();
fn the_code_alone_connects_without_any_server() {
let host = start(None, PathMode::Auto);
let (code, short) = invite_of(&host, false);
assert!(short.is_none());
let invite = long(&code);
assert!(invite.relay.is_none());
assert!(
tunnel.direct,
"loopback ends should reach each other directly"
invite.endpoints.iter().any(|e| e.ip().is_loopback()),
"{invite:?}"
);
let data = payload(1 << 20);
round_trip(tunnel, &data);
let tunnel = join(&code, None, PathMode::Auto).unwrap();
assert!(tunnel.direct);
round_trip(tunnel, &payload(1 << 20));
assert!(wait_event(&host, |e| match e {
HostEvent::Connected { direct, .. } => Some(*direct),
_ => None,
}));
// Only the handshake went through the relay.
let counts = relay.counts();
assert!(counts.relayed_bytes < 16 * 1024, "{counts:?}");
assert_eq!(counts.hosts, 1);
wait_event(&host, |e| {
matches!(e, HostEvent::Disconnected { .. }).then_some(())
});
assert_eq!(host.sessions(), 0);
}
#[test]
fn the_relay_path_carries_the_stream() {
let (relay, address) = relay(generous());
let (host, code) = host(&address, echo_server(), PathMode::Auto);
let tunnel = join(&address, &code, PathMode::RelayOnly).unwrap();
assert!(!tunnel.direct);
let data = payload(1 << 20);
round_trip(tunnel, &data);
assert!(!wait_event(&host, |e| match e {
HostEvent::Connected { direct, .. } => Some(*direct),
_ => None,
}));
// Both directions, encrypted and framed: a little more than twice.
let relayed = relay.counts().relayed_bytes;
assert!(relayed > 2 * data.len() as u64, "{relayed}");
// Two guests at once, one per path.
let a = join(&address, &code, PathMode::RelayOnly).unwrap();
let b = join(&address, &code, PathMode::Auto).unwrap();
// Two guests at once.
let a = join(&code, None, PathMode::Auto).unwrap();
let b = join(&code, None, PathMode::Auto).unwrap();
let ta = std::thread::spawn(move || round_trip(a, &payload(50_000)));
round_trip(b, &payload(70_000));
ta.join().unwrap();
}
#[test]
fn the_host_can_refuse_direct_connections() {
let (_relay, address) = relay(generous());
let (_host, code) = host(&address, echo_server(), PathMode::RelayOnly);
let tunnel = join(&address, &code, PathMode::Auto).unwrap();
assert!(!tunnel.direct);
round_trip(tunnel, b"relay only");
// A guest that insists on a direct path gets none.
// Without a relay, a relay-only guest has nowhere to go.
assert!(matches!(
join(&address, &code, PathMode::DirectOnly),
Err(JoinError::Failed(_))
join(&code, None, PathMode::RelayOnly),
Err(JoinError::NotReachable)
));
}
#[test]
fn wrong_secrets_fail_and_retire_the_code() {
fn a_short_code_through_a_self_hosted_relay() {
let (relay, address) = relay(generous());
let host = start(Some(&address), PathMode::Auto);
let (code, short) = invite_of(&host, true);
let short = short.unwrap().to_string();
// The full code names the relay too.
assert_eq!(long(&code).relay.unwrap().address, address);
// A short code needs the relay's address.
assert!(matches!(
join(&short, None, PathMode::Auto),
Err(JoinError::NeedsRelay)
));
let tunnel = join(&short, Some(&address), PathMode::RelayOnly).unwrap();
assert!(!tunnel.direct);
let data = payload(1 << 20);
round_trip(tunnel, &data);
let relayed = relay.counts().relayed_bytes;
assert!(relayed > 2 * data.len() as u64, "{relayed}");
// The relay's own direct race (both ends on loopback): direct.
let tunnel = join(&short, Some(&address), PathMode::Auto).unwrap();
assert!(tunnel.direct);
round_trip(tunnel, b"raced");
}
#[test]
fn unreachable_endpoints_fall_back_to_the_relay_in_the_code() {
let (relay, address) = relay(generous());
let host = start(Some(&address), PathMode::Auto);
let (code, _) = invite_of(&host, true);
// The same invite with an endpoint nobody answers on.
let mut invite = long(&code);
let dead = TcpListener::bind("127.0.0.1:0")
.unwrap()
.local_addr()
.unwrap();
invite.endpoints = vec![dead];
let started = Instant::now();
assert!(matches!(
join(&invite.encode(), None, PathMode::DirectOnly),
Err(JoinError::NotReachable)
));
assert!(started.elapsed() < Duration::from_secs(6));
let tunnel = join(&invite.encode(), None, PathMode::Auto).unwrap();
round_trip(tunnel, b"fallback");
assert!(relay.counts().relayed_bytes > 0);
// Without a relay in the code: the host's advice is the way out.
invite.relay = None;
assert!(matches!(
join(&invite.encode(), None, PathMode::Auto),
Err(JoinError::NotReachable)
));
}
#[test]
fn wrong_secrets_fail() {
let (_relay, address) = relay(generous());
let (host, code) = host(&address, echo_server(), PathMode::Auto);
let host = start(Some(&address), PathMode::Auto);
let (code, short) = invite_of(&host, true);
// A full code with another secret (re-encoded, so the checksum passes).
let mut forged = long(&code);
forged.secret[0] ^= 1;
assert!(matches!(
join(&forged.encode(), None, PathMode::DirectOnly),
Err(JoinError::WrongCode)
));
assert_eq!(
wait_event(&host, |e| match e {
HostEvent::WrongCode { count } => Some(*count),
_ => None,
}),
1
);
// Short codes: five wrong secrets retire it for a new one.
let short = short.unwrap();
let wrong = Code {
nameplate: code.nameplate.clone(),
secret: if code.secret == "0000" {
nameplate: short.nameplate.clone(),
secret: if short.secret == "0000" {
"0001".into()
} else {
"0000".into()
},
};
for i in 1..=horizon_friends::host::MAX_WRONG {
let e = join(&address, &wrong, PathMode::Auto).err().unwrap();
for _ in 0..horizon_friends::host::MAX_WRONG {
let e = join(&wrong.to_string(), Some(&address), PathMode::Auto)
.err()
.unwrap();
assert!(matches!(e, JoinError::WrongCode), "{e}");
let count = wait_event(&host, |e| match e {
HostEvent::WrongCode { count } => Some(*count),
_ => None,
});
assert_eq!(count, i);
}
// A new code replaces the old one, which has ended.
let fresh = wait_event(&host, |e| match e {
HostEvent::Code(c) => Some(c.clone()),
_ => None,
});
assert_ne!(fresh.nameplate, code.nameplate);
let deadline = Instant::now() + Duration::from_secs(10);
let fresh = loop {
if let Some(s) = host.state().short
&& s.nameplate != short.nameplate
{
break s;
}
assert!(Instant::now() < deadline, "no new short code");
std::thread::sleep(Duration::from_millis(20));
};
assert!(matches!(
join(&address, &code, PathMode::Auto),
join(&short.to_string(), Some(&address), PathMode::Auto),
Err(JoinError::Ended)
));
round_trip(join(&address, &fresh, PathMode::Auto).unwrap(), b"fresh");
round_trip(
join(&fresh.to_string(), Some(&address), PathMode::Auto).unwrap(),
b"fresh",
);
// The full code follows the new short code; its secret stays.
let (code2, _) = invite_of(&host, true);
assert_eq!(long(&code2).relay.unwrap().code, fresh);
assert_eq!(long(&code2).secret, long(&code).secret);
}
#[test]
fn unknown_codes_versions_and_ended_invites() {
fn bad_codes_unknown_codes_versions_and_ended_invites() {
assert!(matches!(
join("hello", None, PathMode::Auto),
Err(JoinError::BadCode(_))
));
let (relay, address) = relay(generous());
let (mut host, code) = host(&address, echo_server(), PathMode::Auto);
let mut host = start(Some(&address), PathMode::RelayOnly);
let (_, short) = invite_of(&host, true);
let short = short.unwrap();
let other = guest::join(&GuestConfig {
relay: address.clone(),
code: code.clone(),
code: short.to_string(),
relay: Some(address.clone()),
protocol: PROTOCOL - 1,
game: "26.2".into(),
path: PathMode::Auto,
@@ -233,26 +318,23 @@ fn unknown_codes_versions_and_ended_invites() {
}
host.stop();
assert!(matches!(
join(&address, &code, PathMode::Auto),
join(&short.to_string(), Some(&address), PathMode::Auto),
Err(JoinError::Ended)
));
// A nameplate nobody holds; five of them block this address for a while.
let free = (0..)
.map(|i| horizon_friends::code::nameplate(i * 7919))
.find(|n| *n != code.nameplate)
.find(|n| *n != short.nameplate)
.unwrap();
let unknown = Code {
nameplate: free,
secret: "0000".into(),
};
let unknown = format!("{free}0000");
for _ in 0..5 {
assert!(matches!(
join(&address, &unknown, PathMode::Auto),
join(&unknown, Some(&address), PathMode::Auto),
Err(JoinError::UnknownCode)
));
}
assert!(matches!(
join(&address, &code, PathMode::Auto),
join(&short.to_string(), Some(&address), PathMode::Auto),
Err(JoinError::RateLimited)
));
let counts = relay.counts();
@@ -284,15 +366,12 @@ fn a_host_that_never_attaches_is_unreachable() {
else {
panic!()
};
let code = Code {
nameplate,
secret: "0000".into(),
};
let code = format!("{nameplate}0000");
assert!(matches!(
join(&address, &code, PathMode::Auto),
join(&code, Some(&address), PathMode::Auto),
Err(JoinError::HostUnreachable)
));
// The relay announced the session; attaching late or with another token fails.
// The relay announced the session; attaching late fails.
let FromRelay::Join { session } = wire::recv(&mut control).unwrap() else {
panic!()
};
@@ -319,8 +398,14 @@ fn relayed_bandwidth_is_capped() {
session_rate: rate,
..generous()
});
let (_host, code) = host(&address, echo_server(), PathMode::RelayOnly);
let tunnel = join(&address, &code, PathMode::RelayOnly).unwrap();
let host = start(Some(&address), PathMode::RelayOnly);
let (_, short) = invite_of(&host, true);
let tunnel = join(
&short.unwrap().to_string(),
Some(&address),
PathMode::RelayOnly,
)
.unwrap();
let started = Instant::now();
round_trip(tunnel, &payload(600_000));
// The first 100 kB pass at once, the rest at 200 kB/s.
+179 -221
View File
@@ -1,259 +1,217 @@
# Play with friends (invite codes)
# Play with friends
A player hosts their single-player world with one click and gets a short code such as
`K7QM-3XPD`. Friends paste the code (on the multiplayer screen in game, or on the launcher's
Play page) and join. No port forwarding, no accounts.
A player opens their single-player world to friends with one click and gets an **invite code**.
Friends paste the code (on the multiplayer screen in game, or on the launcher's Play page) and join.
There is no Horizon server in the middle and no account: the code itself says where the host is and
holds the key that encrypts the game between them.
It is built on what Open to LAN already does: the integrated server (`crates/horizon-client/src/lan`)
listens on a local TCP port and speaks the vanilla protocol. Play with friends adds a tunnel in front
of that port and a small relay service (`crates/horizon-relay`) that introduces the two ends. Neither
the integrated server nor the guest's client changes: the tunnel carries exactly the bytes vanilla's
protocol would send, between a loopback port on each side.
It is built on Open to LAN: the integrated server (`crates/horizon-client/src/lan`) listens on a local
TCP port and speaks the vanilla protocol. Play with friends puts an encrypted tunnel in front of that
port. Neither the integrated server nor the guest's client changes: the tunnel carries exactly the
bytes vanilla's protocol would send, between a loopback port on each side.
```
guest's game host's game
┌──────────────┐ 127.0.0.1:A ┌────────────┐ direct TCP ┌────────────┐ 127.0.0.1:LAN ┌──────────────┐
│ client │──────────────▶│ guest │◀═══ (preferred) ════▶│ host │────────────────▶│ integrated │
│ (unchanged) │ │ tunnel │ │ tunnel │ │ server (LAN) │
└──────────────┘ └─────┬──────┘ └─────┬──────┘ └──────────────┘
│ ┌──────────────────┐ │
└─────▶│ horizon-relay │◀────────┘
join, PAKE, │ codes, rendezvous│ register, control,
or the whole│ byte relay │ attach per guest
stream └──────────────────┘
guest's game host's game
┌──────────────┐ 127.0.0.1:A ┌────────────┐ TCP, end-to-end encrypted ┌────────────┐ 127.0.0.1:LAN ┌──────────────┐
│ client │────────────▶│ guest │══════════════════════════════▶│ host │──────────────▶│ integrated │
│ (unchanged) │ │ tunnel │ to an address from the code │ tunnel │ │ server (LAN) │
└──────────────┘ └────────────┘ └────────────┘ └──────────────┘
╲ optional: a relay anyone can run ╱
╲──────────▶ horizon-relay (short codes, fallback) ◀╱
```
## What vanilla has
## How it works
Vanilla 26.3 (read with `tools/rea_vanilla.py`) has two related things, and neither is this:
**Hosting.** "Invite friends" (in Horizon's pause menu) opens the world to LAN if it isn't (Open to
LAN's defaults), then the host's game, on its own:
- **Open to LAN** (`IntegratedServer.publishServer`, `ShareToLanScreen`, `LanServerPinger`,
`PublishCommand`): the integrated server listens on a port and announces itself by multicast on the
local network. This is the baseline Horizon follows exactly: Play with friends uses the very same
server, the same `IntegratedServer.MAX_PLAYERS` (8), the same offline-mode login, game mode and
command settings as Open to LAN. Hosting through a code *is* opening to LAN, plus the tunnel.
- **Realms invite codes** (`com.mojang.realmsclient.dto.InviteCode`, `RealmsInviteCodesScreen`):
codes that add a player to a Realm, a server Mojang hosts. They need accounts and Mojang's
service; nothing in the client tunnels a local world.
1. listens on its **direct port**, TCP 25580 by default (the same port every time, so a port forwarded
by hand keeps working; another one if it is taken; `HORIZON_FRIENDS_PORT` picks it);
2. collects this computer's addresses: the LAN address, VPN addresses (Tailscale's `100.x`, ZeroTier
and others), IPv6. Container and VM bridges are left out;
3. asks the home router to open the direct port for an hour, renewed every half hour and deleted when
sharing stops: **PCP** (RFC 6887), then **NAT-PMP** (RFC 6886) on the default gateway, then **UPnP
IGD** (SSDP discovery, SOAP `AddPortMapping`). A router that only takes permanent UPnP mappings gets
one, deleted on stop the same way;
4. asks public **STUN** servers for its public IPv4 address (only the address: STUN sees UDP, the game
is TCP). Defaults: `stun.cloudflare.com:3478` and `stun.l.google.com:19302`, two independent
operators of free STUN at a global scale, so one outage doesn't break discovery. `HORIZON_STUN_SERVERS`
(a comma list, or `none`) changes them;
5. builds the **invite code**: the endpoints (the router mapping, the public address on the direct
port, the interface addresses) and a fresh 80-bit secret, in base32 with a checksum.
So the code, the relay and the screens are Horizon's own, in the launcher's design language (the
existing `ui_theme` widgets, so the redesign in flight restyles them with everything else).
**Joining.** The guest's game dials every endpoint in the code at once. The first that answers as a
Horizon host gets the handshake, the others are dropped. On the same LAN, over a VPN, with IPv6, with a
router that opened the port, or with a forwarded port, that's it: no server took part.
**Codes.** Crockford base32 (`0-9 A-Z` without `I L O U`; input ignores case, spaces and dashes and reads
`O` as `0`, `I`/`L` as `1`) in groups of five, with a 16-bit checksum so a typo is caught before
anything is dialled:
- a home with a router mapping, a LAN address and a tailnet address: 52 symbols
(`2A7KQ-M3XPD-…`, 11 groups); with IPv6 too, 79;
- byte layout: version, secret (10 bytes), direct port, endpoints (tag, address, own port when it
differs), an optional relay entry, the first two bytes of SHA-256 of all that.
A code lives as long as the host shares: stopping, closing the world or quitting ends it (the direct
port closes, the router mapping is deleted). Sharing again makes a new secret.
## When friends can't reach the host
The host's panel says what to expect, from what the game found:
| What the game found | What the host reads |
| --- | --- |
| The router opened the port | "Friends anywhere can join: your router opened the port with UPnP (203.0.113.5:25580)." |
| This computer has a public address | "Friends anywhere can join … (TCP port 25580 must not be blocked by a firewall)." |
| No router answered | "Friends on your network or VPN can join. For friends on the internet: turn on UPnP on your router, or forward TCP port 25580 to 192.168.1.20, or use a relay, or a VPN such as Tailscale or ZeroTier (the code already holds your VPN address)." |
| The router is behind another NAT (the router's public side is a private or `100.64/10` address, or STUN sees another address) | "… your router is itself behind another NAT (your provider's carrier-grade NAT, CGNAT, or a second router), so opening its port isn't enough. Use a relay or a VPN such as Tailscale or ZeroTier." |
The code always holds the public address on the direct port when STUN found it, so **forwarding the
port by hand** works without a new code. A guest that can't reach any endpoint is told: "Couldn't reach
your friend's game. Ask them to read the note under their code: they may need UPnP on their router, a
forwarded port, a relay or a VPN."
## Encryption
The code's secret never leaves the code. Every session runs a password-authenticated key exchange
(SPAKE2 over Ed25519, RustCrypto's `spake2`) keyed by it and bound to a session number, then derives
per-direction ChaCha20-Poly1305 keys with HKDF-SHA256 from the exchange and two fresh randoms, with a
key confirmation first. A wrong code, a changed byte, a replayed or reordered frame ends the stream.
The same exchange runs over relayed sessions, where it matters most: the relay gets nothing to test
guesses against offline.
## Privacy: who sees what
- **Friends with the code** see the host's addresses in it (LAN, VPN, public), as with any server
address. A guest's address is seen by the host, as on any server.
- **STUN servers** see the host's public IP address and a 20-byte request, like any website it visits.
Turn them off with `HORIZON_STUN_SERVERS=none` (the code then lacks the public address unless the
router reported it).
- **The router** gets a port mapping named "Horizon (play with friends)".
- **A relay** (only if one is configured) sees the IP addresses of the host and the guests, the short
code's first half, when sessions start and end and the size of encrypted frames. It can't see the
secret, the key or the game (names, chat, the world). It logs counts every five minutes, nothing else.
- **Horizon** sees nothing: there is no Horizon service.
## Identity
Like LAN today: offline mode. A guest joins with the name their game uses; the server gives them the
offline UUID for it; the host's own profile is reserved so nobody can take the host's name. Online-mode
identity (the host checks guests against Mojang's session servers when both are signed in to a
Microsoft account) can come later on top of the same tunnel, since the tunnel carries the login
packets unchanged. Because every tunnelled guest reaches the integrated server from `127.0.0.1`,
`/ban-ip` has nothing useful to act on for them (the LAN host has no such command anyway).
Like LAN: offline mode. A guest joins with the name their game uses; the host's own profile is reserved.
Online-mode checks against Mojang's session servers can come later on top of the same tunnel. Every
tunnelled guest reaches the integrated server from `127.0.0.1`.
## Codes
## Relays (optional)
A code is 8 symbols of Crockford base32 (`0-9 A-Z` without `I L O U`), shown as two groups of four:
`K7QM-3XPD`. Input ignores case, spaces and dashes, and reads `O` as `0` and `I`/`L` as `1`.
For networks nothing can reach (CGNAT on both sides, no VPN), a **relay** carries the session: one small
binary, `horizon-relay`, that anyone can run on their own PC, a VPS, a Raspberry Pi or a free tier.
There is no default relay. With one configured:
- The first four symbols are the **nameplate** (20 bits). The relay allocates it at random among the
free ones when the host registers, and uses it to find the host. It is the only part the relay sees.
- The last four are the **secret** (20 bits). The host's game draws it from the OS random generator
and never sends it anywhere. It is the password of the key exchange below.
- the host also registers there and gets a **short code** (`K7QM-3XPD`: a 4-symbol nameplate the relay
allocates, a 4-symbol secret it never sees), and the full code names the relay and carries the short
code, so guests with the full code fall back to the relay without any setting;
- guests with only the short code need the relay's address (on the Join a friend page);
- a relayed session first races direct connections both ways (candidates exchanged encrypted, TCP
simultaneous open from the direct port), and stays on the relay only if none connects.
A code lives as long as the host keeps sharing: when the host stops sharing, closes the world or loses
its connection to the relay, the nameplate is freed (the relay keeps a bare "ended" mark for 15 minutes
so a guest gets "this invite has ended" rather than "unknown code").
Configuring it: the **Relay** field on the Join a friend page (saved to `horizon.txt` as
`friendsRelay:host:port`, used for hosting too), or `HORIZON_RELAY_URL`.
Guessing: to join a world uninvited, someone needs an active nameplate (the relay limits resolution
attempts per address and in total, see below) and then the secret, for which each attempt is one online run of the
key exchange (20 bits: one chance in a million). After 5 failed exchanges the host's game retires the
code and shows a new one, so a nameplate found by luck is worth at most 5 tries.
### Running your own relay
## Encryption: SPAKE2, then ChaCha20-Poly1305
The relay needs one TCP port reachable by your friends and almost nothing else (a few MB of memory, no
disk). Relayed players cost what the game sends: a join is a few MB, play is about 10–50 KB/s, flying
over new terrain up to a few hundred KB/s (capped per session).
The relay must not be able to read or change game traffic, but all the two ends share is a short
code, and the relay sees part of it. A key derived directly from the code would fall to an offline
search in seconds, so the ends run a **password-authenticated key exchange** (SPAKE2 over Ed25519,
the RustCrypto `spake2` crate, the construction magic-wormhole uses for the same problem):
**From a release or source** (any OS with Rust):
1. Over the relayed connection, each end sends one SPAKE2 message built from the secret and bound to
the nameplate and the session number. Each derives a 32-byte key `K`. With different secrets the
keys differ, and nothing in the messages helps an offline guess: a dishonest relay gets exactly one
guess per session, and a wrong guess shows up as a failed join.
2. Every stream that carries the session (the relayed one, and each direct connection tried) then
exchanges two fresh 16-byte randoms in the clear and derives its own keys with HKDF-SHA256 from `K`,
the randoms and the direction. Frames are ChaCha20-Poly1305 with a per-direction counter nonce, at
most 16 KiB of payload each. The first frame each way is a key confirmation: a wrong code or a
tampered byte ends the stream.
```
cargo build --release -p horizon-relay
PORT=7000 ./target/release/horizon-relay
```
What the relay **can** see: the nameplate, the IP addresses and ports of the host and of each guest
(it is their TCP peer), when sessions start and end, and the size and timing of the encrypted frames
of relayed sessions. What it **can't**: the secret half of the code, the key, the game bytes (names,
chat, positions, the world), or the candidate addresses the ends exchange (they travel encrypted).
**With Docker** (build context: the repository root):
The relay connection itself is plain TCP (a TLS front would hide the nameplate from the network
path, but adds certificates to a service that holds nothing worth hiding).
```
docker build -f crates/horizon-relay/Dockerfile -t horizon-relay .
docker run -d --restart unless-stopped -p 7000:7000 horizon-relay
```
## Connecting: direct first, then the relay
**As a service** (Linux, including a Raspberry Pi): copy the binary to `/usr/local/bin/horizon-relay`,
`crates/horizon-relay/horizon-relay.service` to `/etc/systemd/system/`, then
`systemctl enable --now horizon-relay`.
Every session starts through the relay, so the key exchange always has a path. Then:
Then forward TCP port 7000 on your router to that machine (or run it on a VPS with a public address),
check `curl http://<address>:7000/health` from outside, and give friends `<address>:7000`. `GET /whoami`
shows the address the relay sees for you: behind a proxy that hides client addresses (some hosting
platforms' TCP proxies), set `RELAY_PER_ADDRESS_LIMITS=0`. Run **one** instance per address: codes live
in its memory.
1. Over the encrypted relayed stream, the ends swap their **candidates**: the local addresses they can
be reached on (found by asking the OS which source address it would use toward the relay, toward
the public IPv4 internet and toward the public IPv6 internet; this finds the LAN address, a global
IPv6 address and a tailnet address when there is one) plus the address the relay saw them come
from (their public, reflexive address), all with the port of their **direct socket**. The guest's
join connection and the host's attach connection leave from that port, so the address the relay
saw is the NAT's mapping of it. (The host's long-lived control connection uses another port, so
it never holds the direct port's connection to the relay.)
2. Both ends then dial every candidate of the other at once, for up to 3 seconds, retrying every 250
ms, from their direct socket's port (`SO_REUSEADDR`/`SO_REUSEPORT`, so the same port also listens and
carried the relay connection). Dialling from both sides at once is **TCP simultaneous open**: each
side's outgoing SYN opens its own NAT for the other's, which gets through NATs that map a local port
to the same public port for every destination (most home routers) and stateful firewalls (IPv6).
On the same LAN, on a tailnet, with IPv6 or with a forwarded port the plain dial wins first.
3. Each direct stream that connects is authenticated with the session key as above. The guest keeps
the first one that passes, says so over the relayed stream, and both ends close the rest. If none
passes in time, the session stays on the relayed stream: the relay copies the encrypted bytes.
Settings, all optional:
Why TCP and not UDP hole punching with QUIC: punching UDP succeeds more often across NATs (published
measurements put it around 80% against 60–65% for TCP), but it needs a reliable transport over UDP,
which means QUIC (an async runtime and a QUIC/TLS stack in the game) for a stream that then still needs
the same end-to-end layer. The relay fallback makes every session connect either way; the direct path
only saves latency and relay bandwidth. The tunnel takes any byte stream (`Read + Write`), so a QUIC
transport can be added later beside the TCP one without touching the rest.
| Variable | Default | |
| --- | --- | --- |
| `PORT` | 7000 | the TCP port (also answers `GET /health` and `GET /whoami`) |
| `RELAY_BIND` | all addresses | listen on one address only (e.g. a tailnet address) |
| `RELAY_MAX_HOSTS` | 1000 | short codes at once |
| `RELAY_MAX_BRIDGES` | 200 | relayed streams at once |
| `RELAY_MAX_PENDING_PER_HOST` | 8 | guests joining one host at the same time |
| `RELAY_SESSION_KBPS` | 1024 | KiB/s each way per relayed stream |
| `RELAY_TOTAL_MBPS` | 100 | Mbit/s for everything relayed |
| `RELAY_GLOBAL_UNKNOWN_PER_MIN` | 120 | unknown short codes a minute, all clients together |
| `RELAY_PER_ADDRESS_LIMITS` | 1 | per-address rate limits (see below) |
| `RELAY_PROXY_PROTOCOL` | 0 | read the client address from a PROXY protocol v1 line |
The reflexive candidate is only as good as the relay's view of addresses: if the hosting platform's
TCP proxy hides client addresses (Railway's documentation doesn't say), the relay sees the proxy's
and that candidate simply never connects; the LAN, IPv6, tailnet and forwarded-port paths still work.
`GET /whoami` on the relay shows what it sees, to check after deploying.
Fixed limits: per client address (IPv6 by /64), 6 host registrations a minute (burst 3), 12 joins a
minute (burst 6), 5 unknown short codes in 10 minutes block joins for 10 minutes; a relayed stream idle
for 120 s is closed (the game's keep-alive sends every 15 s); a first line must arrive within 10 s;
hosts answer pings within 60 s; five wrong secrets on a short code and the host retires it for a new one.
`HORIZON_FRIENDS_PATH=relay` skips the direct attempts (players who don't want to share their address
with the other end, and the tests); `=direct` refuses the relay fallback (tests).
### The relay protocol
## The relay protocol
One TCP port. The first line of each connection is a JSON object (at most 4 KiB, within 10 seconds);
a connection whose first bytes are `GET ` gets an HTTP answer instead (`GET /health`, for the hosting
platform's health check), so one port serves both.
One TCP port. The first line of each connection is a JSON object (at most 4 KiB, within 10 seconds); a
connection starting with `GET ` gets an HTTP answer instead.
| From | Line | Meaning |
| --- | --- | --- |
| host | `{"op":"host","v":1,"protocol":P,"game":"26.3"}` | register; the relay answers `{"op":"registered","nameplate":"K7QM","token":T,"observed":"ip:port"}` |
| guest | `{"op":"join","v":1,"nameplate":"K7QM","protocol":P,"game":"26.3"}` | resolve; the relay announces the session to the host, waits for its attach, then answers `{"op":"bridged","session":S,"observed":…}` or `{"op":"error","code":…}` |
| relay → host | `{"op":"join","session":S}` | a guest wants in: open a new connection and attach |
| host | `{"op":"attach","v":1,"session":S,"token":T}` (new connection) | the relay pairs it with the guest's connection, answers `{"op":"bridged","session":S,"observed":…}` to both, then copies bytes |
| relay ↔ host | `{"op":"ping"}` / `{"op":"pong"}` | every 20 s; a host silent for 60 s is dropped and its code ends |
| host | `{"op":"host","v":1,"protocol":P,"game":"26.3"}` | register; answer `{"op":"registered","nameplate":"K7QM","token":T,"observed":"ip:port"}` |
| guest | `{"op":"join","v":1,"nameplate":"K7QM","protocol":P,"game":"26.3"}` | resolve; the relay announces the session to the host and waits for its attach, then answers `{"op":"bridged","session":S,"observed":…}` or `{"op":"error","code":…}` |
| relay → host | `{"op":"join","session":S}` | open a new connection and attach |
| host | `{"op":"attach","v":1,"session":S,"token":T}` | paired with the guest; both get `bridged`, then raw bytes |
| relay ↔ host | `{"op":"ping"}` / `{"op":"pong"}` | every 20 s |
Error codes the guest can get: `unknown_code`, `ended` (the host stopped sharing), `version_mismatch`
(with the host's game version: the relay compares protocol numbers, so a guest on another Minecraft
version is told before anything else happens), `host_unreachable` (the host didn't attach within 10
seconds), `full` (the host has 8 guests connecting or the relay is at capacity), `rate_limited`,
`bad_request`.
Errors: `unknown_code`, `ended` (kept 15 minutes after a host leaves), `version_mismatch` (with the
host's version), `host_unreachable`, `full`, `rate_limited`, `bad_request`.
After `bridged`, the stream is the session: the SPAKE2 messages, then the encrypted frames.
## Troubleshooting
## Limits
All set by environment variables on the relay (defaults in brackets):
- `RELAY_MAX_HOSTS` [1000] codes at once; `RELAY_MAX_BRIDGES` [200] relayed streams at once;
`RELAY_MAX_PENDING_PER_HOST` [8] guests joining one host at the same time.
- Per client address (IPv6 grouped by /64): 6 host registrations a minute (burst 3); 12 joins a minute
(burst 6); 5 unknown codes in 10 minutes block joins from that address for 10 minutes.
`RELAY_PER_ADDRESS_LIMITS=0` turns these off for a proxy that shows every client as one address;
`RELAY_PROXY_PROTOCOL=1` reads the client's address from a PROXY protocol v1 line instead.
- For everyone together: `RELAY_GLOBAL_UNKNOWN_PER_MIN` [120] unknown codes a minute (burst 30); past
it, joins are refused as rate limited before the code is looked up, so a refusal says nothing about
whether a code exists. Even if one attacker had the whole budget: with 1000 worlds shared, an active
nameplate turns up about every 9 minutes, and each is worth 5 one-in-a-million tries before its
code is retired, so a break-in takes on the order of thousands of years.
- `RELAY_SESSION_KBPS` [1024] KiB/s each way per relayed stream; `RELAY_TOTAL_MBPS` [100] Mbit/s for
the whole relay; a relayed stream with no byte either way for 120 s is closed (the game's keep-alive
sends one every 15 s, so only dead streams idle).
- A first line must arrive within 10 s; hosts answer pings within 60 s.
## Privacy
No accounts. The relay keeps only what a live session needs, in memory: active nameplates and the
host connection behind each, pending sessions, rate-limit counters per address (forgotten after 10
minutes). It logs **counts** every 5 minutes (hosts, relayed streams, joins, unknown codes,
rate-limited requests, relayed bytes) and nothing else: no addresses, no codes, no names.
`/health` answers counts too.
A direct connection shows each player's IP address to the other, as a LAN game or a server address
would. `HORIZON_FRIENDS_PATH=relay` avoids it at the cost of relay bandwidth.
## What players see
Host (pause menu, Horizon style): **Invite friends** beside Open to LAN. It opens the world to the
network if it isn't (same settings as Open to LAN), registers with the relay and shows the code with a
**Copy** button, the friends connected, and **Stop sharing**. Stopping sharing ends the code; it leaves
Open to LAN as it was before sharing started.
Guest: **Join a friend** on the multiplayer screen (a code field) and a **Join a friend** row on the
launcher's Play page, which starts the game straight into the join. Errors are plain: "No world uses
this code", "This invite has ended", "The code doesn't match (check the last four characters)",
"Your friend's game didn't answer", "Your friend plays Minecraft X; you have Y".
Configuration: `HORIZON_RELAY_URL=host:port` at run time, else the address compiled in from the same
variable at build time. **Empty by default**: until a relay is deployed, the buttons say "Not available
yet" and do nothing else.
## Failure modes
| Failure | What happens |
| --- | --- |
| Relay down or not configured | Host: "Couldn't reach the invite service" (the world stays open to LAN if it was). Guest: same message. |
| Host closes the world / quits / loses the network | The relay drops the code ("ended"); connected guests see the usual disconnect. |
| Relay restarts | Codes end; hosts reconnect and get a **new** code (shown in the panel). Direct sessions keep running; relayed ones drop. |
| Direct attempt half works (one SYN through) | Only authenticated streams count; the rest are closed after 3 s. |
| A guest's NAT blocks everything but the relay | Relayed, at most `RELAY_SESSION_KBPS`. |
| Wrong secret | That guest gets "The code doesn't match"; after 5, the host gets a new code. |
| Guest on another version | Refused by the relay before any key exchange, with both versions in the message. |
## Deploying the relay
**Needs Ludovic**: nothing is deployed yet, and the game's default relay address is empty.
The relay is one static binary, `horizon-relay`, with no disk state; it fits Railway's smallest
instance. Files: `crates/horizon-relay/Dockerfile` (build context: the repository root) and
`crates/horizon-relay/railway.toml`.
1. New Railway service from the `ludovic111/horizon` repository; in its settings set the config file
path to `crates/horizon-relay/railway.toml` (it selects the Dockerfile and the health check).
2. Variables: `PORT=7000` (the relay listens on `$PORT`); optionally the limits above. **One
replica only** (`numReplicas = 1` in `railway.toml`): codes live in the relay's memory, and the
TCP proxy spreads connections over replicas at random.
3. Networking: add a **TCP proxy** to port 7000. Railway gives an address like
`example.proxy.rlwy.net:12345`. (An HTTP domain is not needed; the health check reaches the service
directly on `$PORT`.)
4. Health check: `GET /health` on `$PORT` (in `railway.toml`), answers `200` with counts.
5. Check addresses: `curl http://<tcp proxy address>/whoami` from a home connection. If it shows your
public address, keep the defaults. If it shows a Railway address, set `RELAY_PER_ADDRESS_LIMITS=0`
(the global limits remain) and expect fewer direct connections across NATs.
6. Point the game at it: set the repository variable `HORIZON_RELAY_URL` to the TCP proxy address so
release builds compile it in, or test first with `HORIZON_RELAY_URL=… horizon-client`.
Cost and bandwidth: the relay idles at a few MB of memory and no CPU. Sessions that connect directly
cost a few kilobytes of relay traffic each. A relayed player costs what the game sends: joining (the
chunks around the spawn) is a few MB, playing is roughly 10–50 KB/s, flying over new terrain up to a
few hundred KB/s (capped at `RELAY_SESSION_KBPS`). A relayed player-hour is therefore around 50–200 MB
of egress; 100 relayed player-hours a month is 5–20 GB. Check Railway's current egress, memory and
CPU prices against that; `RELAY_TOTAL_MBPS` bounds the worst case.
- **"Friends on your network or VPN can join"**: turn on UPnP (sometimes "UPnP IGD" or "NAT-PMP") in
the router's settings and share again; or forward TCP port 25580 (the panel shows the port and your
LAN address) to this computer; or install Tailscale or ZeroTier on both computers (the code already
holds the VPN address); or run a relay.
- **CGNAT / a second router**: port forwarding on your own router can't help. Use a VPN or a relay (on a
machine with a public address, e.g. a VPS).
- **"Couldn't reach your friend's game"** (guest): the host's note under the code says why. A firewall
on the host computer can also block the direct port: allow `horizon-client` on private and public
networks.
- **"The code has a typo"**: copy it again; codes are only letters and digits in groups of five.
- **"This short code works through your friend's relay"**: enter the relay's address under Join a
friend, or ask for the full code.
- **"Your friend plays Minecraft X; you have Y"**: both need the same game version.
## Testing
- Rust unit tests: codes (alphabet, normalisation, parsing), frames and the key exchange (wrong secret,
tampering, nonce order), rate limiters and bandwidth buckets.
- `crates/horizon-relay/tests/tunnel.rs`: a relay, a host tunnel in front of an echo server standing in
for the integrated server, and guest tunnels, in one process: direct path, forced relay path, wrong
secret (and the 5-strike new code), unknown and ended codes, version mismatch, rate limits.
- `tools/test_friends.py`: a relay, a host Horizon with an integrated world and a guest Horizon, through
the direct path and the forced relay path; chat, movement and a placed block seen by both.
- Two machines over the tailnet (relay on one, host and guest on two others).
## Pull requests
1. `horizon-friends` (codes, wire, key exchange, tunnel ends) and `horizon-relay` (the service, its
Dockerfile and Railway config) with their tests. Nothing player-facing.
2. Host: Invite friends in the pause menu, `horizon-ctl friends …`.
3. Guest: Join a friend in game and in the launcher, `tools/test_friends.py`.
- Unit tests (`horizon-friends`): code format (round trips, every single-symbol typo caught, versions),
STUN against a mock server, PCP / NAT-PMP against a mock router (map, renew, delete; NAT-PMP when PCP
is unsupported), UPnP against a mock IGD (description, chunked replies, `AddPortMapping`, permanent-only
leases (725), taken ports (718), `DeletePortMapping`), the verdicts and endpoint order, gateway
parsing for Linux, macOS and Windows, the key exchange and frames (wrong secret, tampering), the direct
race.
- `crates/horizon-relay/tests/tunnel.rs`: the code alone with no server (1 MiB, two guests at once); a
self-hosted relay with the short code (relayed, then its direct race); dead endpoints falling back to
the relay named in the code; wrong secrets (full and short codes, the short code retired after five);
unknown and ended codes, version mismatch, rate limits, bandwidth caps, `/health`.
- `tools/test_friends.py`: real games: a host Horizon sharing a world and a guest Horizon joining over
plain LAN (`--baseline`), with the **code alone** (no relay running), and through a **locally run
relay** with the short code; chat, movement and blocks both ways, then the ended invite.
- Two machines over a tailnet with the code alone (`--role host` on one, `--role guest --code …` on the
other).