From 2fbbe1c5e2bb344ee5499afc248c8b83107bc976 Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Wed, 14 Oct 2026 20:35:18 +0100 Subject: [PATCH 01/97] Fix status effect icons and render inventory effect panels --- crates/horizon-client/src/game.rs | 4 + crates/horizon-client/src/game/potions.rs | 40 ++- crates/horizon-client/src/hud.rs | 68 +++++ crates/horizon-client/src/hud_layout.rs | 10 +- crates/horizon-client/src/hud_overlays.rs | 17 +- .../horizon-client/src/inventory_effects.rs | 255 ++++++++++++++++++ crates/horizon-client/src/lib.rs | 1 + 7 files changed, 379 insertions(+), 16 deletions(-) create mode 100644 crates/horizon-client/src/inventory_effects.rs diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index a5cc64b1d..eea0dfdd7 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -3811,6 +3811,9 @@ impl Game<'_> { self.draw_item(batch, &stack, self.cursor.0 - 8.0, self.cursor.1 - 8.0); } self.draw_slot_tooltip(batch); + if self.container.is_none() && self.craft_size == 2 && !self.mount_active() { + self.draw_inventory_effects(batch, (ox, oy), 176); + } } pub(super) fn close_container(&mut self) { self.close_station(); @@ -7364,6 +7367,7 @@ impl Game<'_> { let name = self.res.names.item(&item); self.tooltip(batch, &name, self.cursor.0, self.cursor.1); } + self.draw_inventory_effects(batch, (ox, oy), Creative::WIDTH as i32); } fn creative_trash_hovered(batch: &HudBatch, cursor: (f32, f32)) -> bool { let (ox, oy) = Self::creative_origin(batch); diff --git a/crates/horizon-client/src/game/potions.rs b/crates/horizon-client/src/game/potions.rs index 8dcd2baa9..18b797a17 100644 --- a/crates/horizon-client/src/game/potions.rs +++ b/crates/horizon-client/src/game/potions.rs @@ -7,7 +7,7 @@ use horizon_client::{ brewing, effects::{EffectAction, EffectInstance, PlayerEffects}, hud::HudBatch, - hud_layout, hud_overlays, + hud_layout, hud_overlays, inventory_effects, items::ItemStack, }; use horizon_core::{geometry::Vec3, random::RandomSource}; @@ -574,22 +574,36 @@ impl Game<'_> { .effects .list .iter() - .map(|e| { - let def = brewing::effect(e.id); - hud_overlays::EffectIcon { - id: e.id.to_owned(), - beneficial: def.is_some_and(|d| d.category == brewing::Category::Beneficial), - color: def.map_or(0, |d| d.color as i32), - ambient: e.ambient, - duration: e.duration, - // Horizon keeps no showIcon flag: every effect shows its icon. - show_icon: true, - } - }) + .map(hud_overlays::EffectIcon::from) .collect(); let draws = hud_overlays::effects(batch.width as i32, false, &icons); hud_layout::paint(batch, &self.res.atlas, &draws); } + /// `EffectsInInventory`: panels to the right of survival/creative inventory. + pub(super) fn draw_inventory_effects( + &self, + batch: &mut HudBatch, + origin: (f32, f32), + image_width: i32, + ) { + let panels = inventory_effects::panels( + batch.width as i32, + [origin.0 as i32, origin.1 as i32], + image_width, + &self.potions.effects.list, + self.clock.rate(), + &|key| self.res.names.get(key).map(str::to_owned), + &|text| self.res.atlas.font.width(text).ceil() as i32, + ); + if let Some(lines) = inventory_effects::paint( + batch, + &self.res.atlas, + &panels, + [self.cursor.0 as i32, self.cursor.1 as i32], + ) { + self.draw_tooltip_lines(batch, &lines, self.cursor.0, self.cursor.1); + } + } /// Effects saved in level.dat (`Player.active_effects`). pub(super) fn restore_effects(&mut self) { self.potions = PotionState::default(); diff --git a/crates/horizon-client/src/hud.rs b/crates/horizon-client/src/hud.rs index 6161160dd..d308046c8 100644 --- a/crates/horizon-client/src/hud.rs +++ b/crates/horizon-client/src/hud.rs @@ -802,6 +802,74 @@ impl HudRenderer { mod tests { use super::*; + #[test] + fn effect_icons_are_painted_from_the_mob_effect_directory() { + use crate::{effects::EffectInstance, hud_layout, hud_overlays, inventory_effects}; + // A synthetic resource tree exercises loading and painting together. + // No Minecraft installation or GPU is needed for this regression test. + let root = + std::env::temp_dir().join(format!("horizon-effect-icons-{}", std::process::id())); + for (name, size) in [ + ("mob_effect/levitation", 18), + ("gui/sprites/hud/effect_background", 24), + ("gui/sprites/container/inventory/effect_background", 32), + ] { + let path = root.join(format!("assets/minecraft/textures/{name}.png")); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + let mut encoder = png::Encoder::new(fs::File::create(path).unwrap(), size, size); + encoder.set_color(png::ColorType::Rgba); + encoder.set_depth(png::BitDepth::Eight); + encoder + .write_header() + .unwrap() + .write_image_data(&vec![255; (size * size * 4) as usize]) + .unwrap(); + } + let atlas = HudAtlas::build(&root).unwrap(); + let effect = EffectInstance::new("levitation", -1, 0); + let icon = hud_overlays::EffectIcon::from(&effect); + let draws = hud_overlays::effects(320, false, &[icon]); + let mut batch = HudBatch::new([320, 240]); + hud_layout::paint(&mut batch, &atlas, &draws); + // Both the background and the 18x18 effect icon must reach the batch. + assert_eq!(batch.vertices.len(), 12); + let rect = atlas.sprites["mob_effect/levitation"]; + assert_eq!(batch.vertices[6].pos, [298.0, 30.0]); + assert_eq!(batch.vertices[6].uv, [rect.u0, rect.v0]); + assert_eq!(batch.vertices[8].uv, [rect.u1, rect.v1]); + + let panels = inventory_effects::panels( + 320, + [72, 37], + 176, + std::slice::from_ref(&effect), + 20.0, + &|_| None, + &|_| 60, + ); + batch.vertices.clear(); + let tooltip = inventory_effects::paint(&mut batch, &atlas, &panels, [257, 44]); + assert_eq!(tooltip.unwrap()[0].0, "levitation"); + assert_eq!(batch.vertices.len(), 24); + assert_eq!(batch.vertices[18].pos, [257.0, 44.0]); + assert_eq!(batch.vertices[18].uv, [rect.u0, rect.v0]); + assert_eq!(batch.vertices[20].uv, [rect.u1, rect.v1]); + + // Wide panels retain the four-pixel border instead of stretching it. + let panels = + inventory_effects::panels(480, [72, 37], 176, &[effect], 20.0, &|_| None, &|_| 60); + batch.vertices.clear(); + assert!(inventory_effects::paint(&mut batch, &atlas, &panels, [0, 0]).is_none()); + assert_eq!(batch.vertices[0].pos, [250.0, 37.0]); + assert_eq!(batch.vertices[1].pos, [254.0, 37.0]); + let background = atlas.sprites["gui/sprites/container/inventory/effect_background"]; + assert!( + (batch.vertices[1].uv[0] - background.u0 - (background.u1 - background.u0) / 8.0).abs() + < 1e-6 + ); + fs::remove_dir_all(root).unwrap(); + } + #[test] fn container_origins_use_java_integer_division() { // Odd scaled dimensions, odd image sizes and an oversized panel. diff --git a/crates/horizon-client/src/hud_layout.rs b/crates/horizon-client/src/hud_layout.rs index ab28ece3e..0392edb3f 100644 --- a/crates/horizon-client/src/hud_layout.rs +++ b/crates/horizon-client/src/hud_layout.rs @@ -761,8 +761,14 @@ pub fn paint(batch: &mut crate::hud::HudBatch, atlas: &crate::hud::HudAtlas, dra region, color, } => { - let Some(mut r) = atlas.sprites.get(&format!("gui/sprites/{sprite}")).copied() - else { + // Effect sprites belong to the mob_effect atlas directory; + // the other blitSprite ids refer to GUI sprites. + let name = if sprite.starts_with("mob_effect/") { + sprite.to_string() + } else { + format!("gui/sprites/{sprite}") + }; + let Some(mut r) = atlas.sprites.get(&name).copied() else { continue; }; if let Some([sw, sh, u, v]) = *region { diff --git a/crates/horizon-client/src/hud_overlays.rs b/crates/horizon-client/src/hud_overlays.rs index 8468735c3..94eb7a369 100644 --- a/crates/horizon-client/src/hud_overlays.rs +++ b/crates/horizon-client/src/hud_overlays.rs @@ -105,8 +105,23 @@ pub struct EffectIcon { pub show_icon: bool, } +impl From<&crate::effects::EffectInstance> for EffectIcon { + fn from(effect: &crate::effects::EffectInstance) -> Self { + let def = crate::brewing::effect(effect.id); + Self { + id: effect.id.to_owned(), + beneficial: def.is_some_and(|d| d.category == crate::brewing::Category::Beneficial), + color: def.map_or(0, |d| d.color as i32), + ambient: effect.ambient, + duration: effect.duration, + // Horizon keeps no showIcon flag: every effect shows its icon. + show_icon: true, + } + } +} + /// `MobEffectInstance.compareTo`. -fn compare_effects(a: &EffectIcon, o: &EffectIcon) -> Ordering { +pub(crate) fn compare_effects(a: &EffectIcon, o: &EffectIcon) -> Ordering { if (a.duration <= 32147 || o.duration <= 32147) && !(a.ambient && o.ambient) { a.ambient .cmp(&o.ambient) diff --git a/crates/horizon-client/src/inventory_effects.rs b/crates/horizon-client/src/inventory_effects.rs new file mode 100644 index 000000000..3a870a1e6 --- /dev/null +++ b/crates/horizon-client/src/inventory_effects.rs @@ -0,0 +1,255 @@ +//! `EffectsInInventory`: active effect panels beside survival and creative +//! inventories, with compact icons when there is little room on the right. +use crate::{ + effects::EffectInstance, + hud::{HudAtlas, HudBatch}, + hud_overlays::{EffectIcon, compare_effects, java_sort}, +}; + +#[derive(Debug, PartialEq)] +pub struct EffectPanel { + pub icon: EffectIcon, + pub name: String, + pub duration: String, + pub x: i32, + pub y: i32, + pub width: i32, + pub spacing: i32, +} + +/// Lay out panels using the container's actual origin (including recipe book +/// shifts). Vanilla hides them when fewer than 32 GUI pixels remain. +pub fn panels( + screen_width: i32, + origin: [i32; 2], + image_width: i32, + effects: &[EffectInstance], + tick_rate: f32, + translate: &dyn Fn(&str) -> Option, + text_width: &dyn Fn(&str) -> i32, +) -> Vec { + let x = origin[0] + image_width + 2; + let available = screen_width - x; + if effects.is_empty() || available < 32 { + return Vec::new(); + } + let max_width = if available >= 120 { available - 7 } else { 32 }; + let spacing = if effects.len() > 5 { + 132 / (effects.len() as i32 - 1) + } else { + 33 + }; + let mut sorted: Vec<_> = effects.iter().map(|e| (e, EffectIcon::from(e))).collect(); + java_sort(&mut sorted, |a, b| compare_effects(&a.1, &b.1)); + sorted + .into_iter() + .enumerate() + .map(|(i, (effect, icon))| { + let mut name = translate(&format!("effect.minecraft.{}", effect.id)) + .unwrap_or_else(|| effect.id.to_owned()); + if (1..=9).contains(&effect.amplifier) { + let level = effect.amplifier + 1; + let suffix = translate(&format!("enchantment.level.{level}")) + .unwrap_or_else(|| crate::enchant::level_name(level as u32)); + name = format!("{name} {suffix}"); + } + let duration = if effect.duration == -1 { + translate("effect.duration.infinite").unwrap_or_else(|| "∞".to_owned()) + } else { + // StringUtil.formatTickDuration uses the level's current rate. + let seconds = (effect.duration as f32 / tick_rate) as i32; + let (hours, minutes, seconds) = (seconds / 3600, seconds / 60 % 60, seconds % 60); + if hours > 0 { + format!("{hours}:{minutes:02}:{seconds:02}") + } else { + format!("{minutes}:{seconds:02}") + } + }; + let width = max_width.min(39 + text_width(&name).max(text_width(&duration))); + EffectPanel { + icon, + name, + duration, + x, + y: origin[1] + i as i32 * spacing, + width, + spacing, + } + }) + .collect() +} + +/// The inventory effect background has a four-pixel nine-slice border. Since +/// its height stays 32, only horizontal slicing/tiling is needed. +fn background(batch: &mut HudBatch, atlas: &HudAtlas, panel: &EffectPanel) { + let name = if panel.icon.ambient { + "gui/sprites/container/inventory/effect_background_ambient" + } else { + "gui/sprites/container/inventory/effect_background" + }; + let Some(rect) = atlas.sprites.get(name).copied() else { + return; + }; + let mut strip = |dx: i32, sx: i32, width: i32| { + let mut r = rect; + let du = rect.u1 - rect.u0; + r.u0 = rect.u0 + du * sx as f32 / 32.0; + r.u1 = r.u0 + du * width as f32 / 32.0; + batch.rect_uv( + (panel.x + dx) as f32, + panel.y as f32, + width as f32, + 32.0, + r, + u32::MAX, + ); + }; + strip(0, 0, 4); + let mut dx = 4; + while dx < panel.width - 4 { + let width = 24.min(panel.width - 4 - dx); + strip(dx, 4, width); + dx += width; + } + strip(panel.width - 4, 28, 4); +} + +/// Paint panels and return the full name/duration tooltip for a hovered compact +/// or clipped panel. Its hover height follows the spacing of overlapping rows. +pub fn paint( + batch: &mut HudBatch, + atlas: &HudAtlas, + panels: &[EffectPanel], + cursor: [i32; 2], +) -> Option<[(String, u32); 2]> { + let mut tooltip = None; + for panel in panels { + background(batch, atlas, panel); + let text_width = panel.width - 39; + let clipped = atlas.font.width(&panel.name).ceil() as i32 > text_width; + if text_width > 0 { + let shown = if clipped { + let available = text_width as f32 - atlas.font.width("..."); + let count = atlas.font.fit(&panel.name, available); + format!("{}...", panel.name.chars().take(count).collect::()) + } else { + panel.name.clone() + }; + batch.text( + atlas, + &shown, + (panel.x + 32) as f32, + (panel.y + 7) as f32, + u32::MAX, + true, + ); + batch.text( + atlas, + &panel.duration, + (panel.x + 32) as f32, + (panel.y + 16) as f32, + 0xff7f7f7f, + true, + ); + } + batch.sprite_scaled( + atlas, + &format!("mob_effect/{}", panel.icon.id), + (panel.x + 7) as f32, + (panel.y + 7) as f32, + 18.0, + 18.0, + u32::MAX, + ); + if (text_width <= 0 || clipped) + && cursor[0] >= panel.x + && cursor[0] <= panel.x + panel.width + && cursor[1] >= panel.y + && cursor[1] <= panel.y + panel.spacing + { + tooltip = Some([ + (panel.name.clone(), u32::MAX), + (panel.duration.clone(), u32::MAX), + ]); + } + } + tooltip +} + +#[cfg(test)] +mod tests { + use super::*; + + fn layout(width: i32, effects: &[EffectInstance]) -> Vec { + panels( + width, + [72, 37], + 176, + effects, + 20.0, + &|key| match key { + "effect.minecraft.levitation" => Some("Levitation".into()), + "effect.minecraft.speed" => Some("Speed".into()), + _ => None, + }, + &|text| text.chars().count() as i32 * 6, + ) + } + + #[test] + fn inventory_labels_levels_and_durations() { + let effects = [ + EffectInstance::new("levitation", -1, 0), + EffectInstance::new("speed", 450, 1), + ]; + let p = layout(480, &effects); + assert_eq!(p.len(), 2); + // Natural order puts shorter durations before infinite effects. + assert_eq!( + (&p[0].name, &p[0].duration), + (&"Speed II".into(), &"0:22".into()) + ); + assert_eq!( + (&p[1].name, &p[1].duration), + (&"Levitation".into(), &"∞".into()) + ); + assert_eq!((p[0].x, p[0].y, p[0].width), (250, 37, 87)); + assert_eq!((p[1].x, p[1].y, p[1].width), (250, 70, 99)); + } + + #[test] + fn narrow_windows_hide_or_compact_the_panels() { + let effects = [EffectInstance::new("levitation", -1, 0)]; + assert!(layout(281, &effects).is_empty()); + assert_eq!(layout(282, &effects)[0].width, 32); + assert_eq!(layout(369, &effects)[0].width, 32); + assert_eq!(layout(370, &effects)[0].width, 99); + assert!(layout(480, &[]).is_empty()); + } + + #[test] + fn crowded_effects_overlap_and_preserve_ambient_order() { + let mut effects: Vec<_> = (0..7) + .map(|i| EffectInstance::new("speed", (i + 1) * 100, 0)) + .collect(); + effects[0].ambient = true; + let p = layout(480, &effects); + assert_eq!(p[0].icon.duration, 200); + assert!(p.last().unwrap().icon.ambient); + assert_eq!( + p.iter().map(|p| p.y).collect::>(), + [37, 59, 81, 103, 125, 147, 169] + ); + } + + #[test] + fn creative_origin_recipe_book_shift_and_tick_rate() { + let effects = [EffectInstance::new("speed", 72000, 10)]; + let p = panels(640, [222, 43], 195, &effects, 10.0, &|_| None, &|_| 60); + assert_eq!((p[0].x, p[0].y), (419, 43)); + assert_eq!(p[0].name, "speed"); + assert_eq!(p[0].duration, "2:00:00"); + let p = panels(480, [149, 37], 176, &effects, 20.0, &|_| None, &|_| 150); + assert_eq!((p[0].x, p[0].width), (327, 146)); + } +} diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs index eae7dc596..b41f03e28 100644 --- a/crates/horizon-client/src/lib.rs +++ b/crates/horizon-client/src/lib.rs @@ -68,6 +68,7 @@ pub mod hud_layout; pub mod hud_overlays; pub mod hunger; pub mod input; +pub mod inventory_effects; pub mod item_data; pub mod item_render; pub mod item_tooltip; From d456dadafa3eb5e55a4f26fa94d382009370ef6c Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Wed, 14 Oct 2026 20:45:33 +0100 Subject: [PATCH 02/97] Match vanilla inventory effect duration text color --- crates/horizon-client/src/hud.rs | 1 + crates/horizon-client/src/inventory_effects.rs | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/horizon-client/src/hud.rs b/crates/horizon-client/src/hud.rs index d308046c8..e20da73a4 100644 --- a/crates/horizon-client/src/hud.rs +++ b/crates/horizon-client/src/hud.rs @@ -860,6 +860,7 @@ mod tests { inventory_effects::panels(480, [72, 37], 176, &[effect], 20.0, &|_| None, &|_| 60); batch.vertices.clear(); assert!(inventory_effects::paint(&mut batch, &atlas, &panels, [0, 0]).is_none()); + assert!(batch.vertices.iter().any(|v| v.color == 0xff808080)); assert_eq!(batch.vertices[0].pos, [250.0, 37.0]); assert_eq!(batch.vertices[1].pos, [254.0, 37.0]); let background = atlas.sprites["gui/sprites/container/inventory/effect_background"]; diff --git a/crates/horizon-client/src/inventory_effects.rs b/crates/horizon-client/src/inventory_effects.rs index 3a870a1e6..02a533867 100644 --- a/crates/horizon-client/src/inventory_effects.rs +++ b/crates/horizon-client/src/inventory_effects.rs @@ -148,7 +148,7 @@ pub fn paint( &panel.duration, (panel.x + 32) as f32, (panel.y + 16) as f32, - 0xff7f7f7f, + 0xff808080, true, ); } From 576e88bd8ce7ceeb3cf9d032fcfb841ed2771f55 Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:29:29 +0100 Subject: [PATCH 03/97] Zero-pad inventory effect duration fields --- crates/horizon-client/src/inventory_effects.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/crates/horizon-client/src/inventory_effects.rs b/crates/horizon-client/src/inventory_effects.rs index 02a533867..86dca9963 100644 --- a/crates/horizon-client/src/inventory_effects.rs +++ b/crates/horizon-client/src/inventory_effects.rs @@ -60,9 +60,9 @@ pub fn panels( let seconds = (effect.duration as f32 / tick_rate) as i32; let (hours, minutes, seconds) = (seconds / 3600, seconds / 60 % 60, seconds % 60); if hours > 0 { - format!("{hours}:{minutes:02}:{seconds:02}") + format!("{hours:02}:{minutes:02}:{seconds:02}") } else { - format!("{minutes}:{seconds:02}") + format!("{minutes:02}:{seconds:02}") } }; let width = max_width.min(39 + text_width(&name).max(text_width(&duration))); @@ -207,7 +207,7 @@ mod tests { // Natural order puts shorter durations before infinite effects. assert_eq!( (&p[0].name, &p[0].duration), - (&"Speed II".into(), &"0:22".into()) + (&"Speed II".into(), &"00:22".into()) ); assert_eq!( (&p[1].name, &p[1].duration), @@ -248,7 +248,7 @@ mod tests { let p = panels(640, [222, 43], 195, &effects, 10.0, &|_| None, &|_| 60); assert_eq!((p[0].x, p[0].y), (419, 43)); assert_eq!(p[0].name, "speed"); - assert_eq!(p[0].duration, "2:00:00"); + assert_eq!(p[0].duration, "02:00:00"); let p = panels(480, [149, 37], 176, &effects, 20.0, &|_| None, &|_| 150); assert_eq!((p[0].x, p[0].width), (327, 146)); } From 2491d49bf5d3e238b45e78095f1ce68d1bf7e0aa Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:25:51 +0100 Subject: [PATCH 04/97] perf: reuse entity material batching scratch buffers --- crates/horizon-client/src/gfx.rs | 53 ++-- crates/horizon-client/src/gfx/entity_batch.rs | 229 ++++++++++++++++++ 2 files changed, 245 insertions(+), 37 deletions(-) create mode 100644 crates/horizon-client/src/gfx/entity_batch.rs diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs index 2b47e2a89..abe2da7dd 100644 --- a/crates/horizon-client/src/gfx.rs +++ b/crates/horizon-client/src/gfx.rs @@ -31,32 +31,8 @@ fn entity_shader() -> String { crate::overlay::wgsl_constants() + include_str!("entity.wgsl") } -// Separate special materials without changing entity order or their overlays. -fn batch_entities( - entities: &[Vertex], - additive: &[Vertex], - hand: &[Vertex], -) -> (Vec, [u32; 4]) { - let mut combined = Vec::with_capacity(entities.len() + additive.len() + hand.len()); - let mut counts = [0u32; 4]; - for (i, layer) in [0, 11, 12, 4].into_iter().enumerate() { - for quad in entities.as_chunks::<4>().0 { - let material = match quad[0].layer { - 11 => 11, - 12 => 12, - 4 => 4, - _ => 0, - }; - if material == layer { - combined.extend_from_slice(quad); - counts[i] += 1; - } - } - } - combined.extend_from_slice(additive); - combined.extend_from_slice(hand); - (combined, counts) -} +mod entity_batch; +use entity_batch::EntityBatch; /// Window.getAppropriateLineWidth, in framebuffer pixels. pub fn outline_width(width: u32) -> f32 { @@ -263,6 +239,7 @@ pub struct Renderer { hand_globals: wgpu::Buffer, entity_buffer: wgpu::Buffer, entity_capacity: u64, + entity_batch: EntityBatch, group: wgpu::BindGroup, globals: wgpu::Buffer, lightmap: wgpu::Texture, @@ -1413,6 +1390,7 @@ impl Renderer { hand_globals, entity_buffer, entity_capacity, + entity_batch: EntityBatch::default(), group, globals, lightmap, @@ -2117,18 +2095,17 @@ impl Renderer { self.queue .write_buffer(&self.outline, 0, bytemuck::cast_slice(&lines)); } - let ( - combined, - [ - entity_quads, - crumbling_quads, - translucent_crumbling_quads, - cloud_quads, - ], - ) = batch_entities(frame.entities, frame.additive, frame.hand); + let [ + entity_quads, + crumbling_quads, + translucent_crumbling_quads, + cloud_quads, + ] = self + .entity_batch + .update(frame.entities, frame.additive, frame.hand); let world_quads = entity_quads + crumbling_quads + translucent_crumbling_quads + cloud_quads; - let all_entities = &combined; + let all_entities = &self.entity_batch.combined; let hand_quads = (frame.hand.len() / 4) as u32; let additive_quads = (frame.additive.len() / 4) as u32; let entity_vertices = all_entities.len() as u64; @@ -2612,7 +2589,9 @@ mod tests { .into_iter() .flat_map(|(layer, id)| quad(layer, id)) .collect(); - let (vertices, counts) = super::batch_entities(&entities, &quad(3, 5), &quad(0, 6)); + let mut batch = super::EntityBatch::default(); + let counts = batch.update(&entities, &quad(3, 5), &quad(0, 6)); + let vertices = &batch.combined; assert_eq!(counts, [2, 1, 1, 2]); assert_eq!( vertices diff --git a/crates/horizon-client/src/gfx/entity_batch.rs b/crates/horizon-client/src/gfx/entity_batch.rs new file mode 100644 index 000000000..484b0b7bc --- /dev/null +++ b/crates/horizon-client/src/gfx/entity_batch.rs @@ -0,0 +1,229 @@ +//! Stable entity material grouping with renderer-owned, reusable CPU scratch. +use super::Vertex; + +#[derive(Default)] +pub(super) struct EntityBatch { + // Quad indices avoid copying vertices twice while grouping materials. + // Keep initialized high-water storage; local counts delimit active entries. + // Each bucket can hold all quads, removing per-quad Vec growth checks. + buckets: [Vec; 4], + pub(super) combined: Vec, +} + +impl EntityBatch { + pub(super) fn update( + &mut self, + entities: &[Vertex], + additive: &[Vertex], + hand: &[Vertex], + ) -> [u32; 4] { + let quads = entities.as_chunks::<4>().0; + for bucket in &mut self.buckets { + if bucket.len() < quads.len() { + bucket.resize(quads.len(), 0); + } + } + let mut counts = [0usize; 4]; + for (index, quad) in quads.iter().enumerate() { + let material = match quad[0].layer { + 11 => 1, + 12 => 2, + 4 => 3, + _ => 0, + }; + self.buckets[material][counts[material]] = index; + counts[material] += 1; + } + let entity_vertices = quads.len() * 4; + self.combined.reserve( + (entity_vertices + additive.len() + hand.len()).saturating_sub(self.combined.len()), + ); + self.combined + .resize(entity_vertices, bytemuck::Zeroable::zeroed()); + if counts.contains(&quads.len()) { + // Uniform materials are already ordered; copy the whole batch. + self.combined.copy_from_slice(&entities[..entity_vertices]); + } else { + let mut offset = 0; + for (bucket, &count) in self.buckets.iter().zip(&counts) { + let bucket = &bucket[..count]; + let end = offset + count * 4; + for (output, &index) in self.combined[offset..end] + .as_chunks_mut::<4>() + .0 + .iter_mut() + .zip(bucket) + { + *output = quads[index]; + } + offset = end; + } + } + self.combined.extend_from_slice(additive); + self.combined.extend_from_slice(hand); + counts.map(|count| count as u32) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use std::{hint::black_box, time::Instant}; + + // Retain the original implementation as the equivalence/benchmark oracle. + fn baseline( + entities: &[Vertex], + additive: &[Vertex], + hand: &[Vertex], + ) -> (Vec, [u32; 4]) { + let mut combined = Vec::with_capacity(entities.len() + additive.len() + hand.len()); + let mut counts = [0; 4]; + for (i, layer) in [0, 11, 12, 4].into_iter().enumerate() { + for quad in entities.as_chunks::<4>().0 { + let material = match quad[0].layer { + 11 => 11, + 12 => 12, + 4 => 4, + _ => 0, + }; + if material == layer { + combined.extend_from_slice(quad); + counts[i] += 1; + } + } + } + combined.extend_from_slice(additive); + combined.extend_from_slice(hand); + (combined, counts) + } + + fn geometry(quads: usize, mixed: bool) -> Vec { + (0..quads * 4) + .map(|index| Vertex { + pos: [index as f32, 2.0, 3.0], + uv: [index as f32, 5.0], + layer: if mixed { + [7, 11, 12, 4, 0][index / 4 % 5] + } else { + 0 + }, + color: index as u32, + light: (index * 3) as u32, + normal: [1, 2, 3, 4], + }) + .collect() + } + + fn equivalent( + batch: &mut EntityBatch, + entities: &[Vertex], + additive: &[Vertex], + hand: &[Vertex], + ) { + let (expected, counts) = baseline(entities, additive, hand); + assert_eq!(batch.update(entities, additive, hand), counts); + assert_eq!( + bytemuck::cast_slice::<_, u8>(&batch.combined), + bytemuck::cast_slice::<_, u8>(&expected) + ); + } + + #[test] + fn stable_material_order_tails_and_reuse() { + let mut batch = EntityBatch::default(); + let mut entities = geometry(4096, true); + // Only the first vertex determines a quad's material. + entities[1].layer = 12; + let additive = geometry(3, true); + let hand = geometry(2, false); + // Warm every bucket and the combined buffer to their maximum sizes. + equivalent(&mut batch, &entities, &additive, &hand); + let capacities = batch.buckets.each_ref().map(|b| b.capacity()); + let capacity = batch.combined.capacity(); + let pointer = batch.combined.as_ptr(); + for length in [0, 1, 3, 4, 511, entities.len(), 17, 0, entities.len()] { + equivalent(&mut batch, &entities[..length], &additive[..5], &hand[..3]); + assert_eq!(batch.buckets.each_ref().map(|b| b.capacity()), capacities); + assert_eq!(batch.combined.capacity(), capacity); + assert_eq!(batch.combined.as_ptr(), pointer); + } + equivalent(&mut batch, &[], &[], &[]); + assert!(batch.combined.is_empty()); + // Grow again, then confirm empty/small frames retain the new storage. + let larger = geometry(8192, true); + equivalent(&mut batch, &larger, &additive, &hand); + let capacities = batch.buckets.each_ref().map(|b| b.capacity()); + let capacity = batch.combined.capacity(); + for entities in [&larger[..7], &larger[..], &[]] { + equivalent(&mut batch, entities, &[], &[]); + assert_eq!(batch.buckets.each_ref().map(|b| b.capacity()), capacities); + assert_eq!(batch.combined.capacity(), capacity); + } + } + + #[test] + #[ignore = "manual production-helper microbenchmark"] + fn benchmark_entity_batch() { + let additive = geometry(16, false); + let hand = geometry(8, false); + for (name, mixed, quads) in [ + ("mixed", true, 65_536), + ("single", false, 65_536), + ("runs", true, 65_536), + ("mixed", true, 262_144), + ("single", false, 262_144), + ] { + let mut entities = geometry(quads, mixed); + if name == "runs" { + // Model/material runs: normal 16, glint 4, overlay 4, shadow 2. + for (index, quad) in entities.as_chunks_mut::<4>().0.iter_mut().enumerate() { + let layer = match index % 26 { + 0..16 => 0, + 16..20 => 11, + 20..24 => 12, + _ => 4, + }; + for vertex in quad { + vertex.layer = layer; + } + } + } + let mut batch = EntityBatch::default(); + equivalent(&mut batch, &entities, &additive, &hand); + for _ in 0..50 { + black_box(baseline(black_box(&entities), &additive, &hand)); + black_box(batch.update(black_box(&entities), &additive, &hand)); + black_box(&batch.combined); + } + let mut before = Vec::new(); + let mut after = Vec::new(); + for _ in 0..15 { + let start = Instant::now(); + for _ in 0..100 { + black_box(baseline(black_box(&entities), &additive, &hand)); + } + before.push(start.elapsed().as_nanos() / 100); + let start = Instant::now(); + for _ in 0..100 { + black_box(batch.update(black_box(&entities), &additive, &hand)); + black_box(&batch.combined); + } + after.push(start.elapsed().as_nanos() / 100); + } + before.sort_unstable(); + after.sort_unstable(); + println!( + "{name}: {quads} quads, baseline={} ns/frame optimized={} ns/frame speedup={:.2}x scratch={} bytes", + before[7], + after[7], + before[7] as f64 / after[7] as f64, + batch.combined.capacity() * std::mem::size_of::() + + batch + .buckets + .iter() + .map(|b| b.capacity() * std::mem::size_of::()) + .sum::() + ); + } + } +} From 5c076ca38f70f2564a5ef1d79fde704ace47a8e4 Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:05:20 +0100 Subject: [PATCH 05/97] perf(client): parse entity model document once for startup batches --- .../README.md | 78 +++++ .../generate_fixture.py | 31 ++ .../results.json | 43 +++ crates/horizon-client/src/game.rs | 18 +- .../horizon-client/src/game/armor_stands.rs | 7 +- crates/horizon-client/src/game/boats.rs | 13 +- .../src/game/entity_model_loading_tests.rs | 272 ++++++++++++++++++ crates/horizon-client/src/game/minecarts.rs | 6 +- crates/horizon-client/src/mobs.rs | 28 +- 9 files changed, 476 insertions(+), 20 deletions(-) create mode 100644 benchmarks/entity-model-document-2026-10-14/README.md create mode 100644 benchmarks/entity-model-document-2026-10-14/generate_fixture.py create mode 100644 benchmarks/entity-model-document-2026-10-14/results.json create mode 100644 crates/horizon-client/src/game/entity_model_loading_tests.rs diff --git a/benchmarks/entity-model-document-2026-10-14/README.md b/benchmarks/entity-model-document-2026-10-14/README.md new file mode 100644 index 000000000..eeb8f6673 --- /dev/null +++ b/benchmarks/entity-model-document-2026-10-14/README.md @@ -0,0 +1,78 @@ +# Entity model document loading + +The three startup batches (boats/chest boats, minecarts, armor stands/player armor) +now share one parsed document. For this fixture, that replaces 43 full document +reads/parses (boat discovery plus 42 selected layers) with one. Selected models +still produce independent `Part` trees; the document is dropped after the batches +are built. Other entity loaders retain their existing behavior. + +## Reproduce + +From the repository root: + +```sh +python3 benchmarks/entity-model-document-2026-10-14/generate_fixture.py /tmp/horizon-entity-model-document-fixture.json +ENTITY_MODEL_BENCH_DOCUMENT=/tmp/horizon-entity-model-document-fixture.json \ + CARGO_TARGET_DIR=/home/bob/Documents/horizon/target \ + cargo test -p horizon-client --profile fast --bin horizon-client \ + entity_model_document_benchmark -- --ignored --nocapture +``` + +`CARGO_TARGET_DIR` is optional and can be changed for another machine. Supply a +prepared `entity-models.json` through `ENTITY_MODEL_BENCH_DOCUMENT` to benchmark +that document instead; the harness copies only that file to a temporary root. +`ENTITY_MODEL_BENCH_REPETITIONS` controls repetitions (default 15). + +The opt-in Rust test calls the actual three optimized production loaders and +compares every selected part name, pose, polygon normal/vertex and child against +the previous algorithm using the compatible per-model `load_model` API. Timings +include reading, parsing, constructing, normalizing into a common result map, and +dropping the result. Each variant gets three warmups and 15 measured calls, with +order alternating. `black_box` consumes inputs/results. No other builds or +optimization benchmarks ran during the measured calls. + +## Input and limitations + +Prepared resources were unavailable in the repository and local Horizon asset +directories. This is a **synthetic** 2,473,695-byte document with 458 model layers, +each containing 12 posed parts with six exported quads and normals. It selects 22 +boat/chest-boat layers, six minecart layers and 14 armor/player layers (42 total). +One wood name is synthetic (`test_wood`); boat discovery accepts arbitrary wood +names. The extra layers model the cost of parsing a full production-size document +for each selected model. + +File data is warm in the OS page cache. Equipment files are absent, so equipment +texture loading is excluded. This measures the entity-model batch only and does +not establish overall startup, frame time or FPS improvement. Shapes/layer counts +in real prepared documents can produce different absolute timings. + +Machine: AMD Ryzen 5 5600X (6 cores / 12 threads), Linux x86_64, +Rust 1.99.0 (b940084d7, LLVM 23.1.1), Cargo `fast` profile (opt-level 3, +16 codegen units, no LTO). Baseline algorithm corresponds to main +`73a019967e9665c6b96332988c13cb66679d8477`. + +## Results + +| Variant | Median batch time | Full document reads/parses | +| --- | ---: | ---: | +| Previous per-model algorithm | 1,434.974 ms | 43 | +| Shared document | 33.420 ms | 1 | + +The measured batch is **42.94× faster** on this synthetic input. All 15 samples +for both variants, warmup count, document size and selected model count are in +[`results.json`](results.json). + +## Validation + +```sh +cargo fmt --all -- --check +CARGO_TARGET_DIR=/home/bob/Documents/horizon/target \ + cargo test -p horizon-client --profile fast --bin horizon-client \ + entity_model_loading_tests -- --nocapture +CARGO_TARGET_DIR=/home/bob/Documents/horizon/target \ + cargo clippy -p horizon-client --profile fast --lib --bin horizon-client --tests -- -D warnings +``` + +The regular tests cover full/sparse documents, unrelated layers, a missing file, +invalid JSON, non-object JSON, missing model keys, independent model trees, and +equipment loading when the document is unavailable. diff --git a/benchmarks/entity-model-document-2026-10-14/generate_fixture.py b/benchmarks/entity-model-document-2026-10-14/generate_fixture.py new file mode 100644 index 000000000..624a7abe1 --- /dev/null +++ b/benchmarks/entity-model-document-2026-10-14/generate_fixture.py @@ -0,0 +1,31 @@ +"""Generate a production-size synthetic document; no prepared assets required.""" +import json +import pathlib +import sys + +woods = "oak spruce birch jungle acacia dark_oak mangrove cherry bamboo pale_oak test_wood".split() +carts = "minecart chest_minecart hopper_minecart furnace_minecart tnt_minecart command_block_minecart".split() +keys = [f"minecraft:{prefix}/{wood}#main" for prefix in ("boat", "chest_boat") for wood in woods] +keys += [f"minecraft:{cart}#main" for cart in carts] +keys += [f"minecraft:{model}#{slot}" for model in ("player", "armor_stand", "armor_stand_small") + for slot in ("helmet", "chestplate", "leggings", "boots")] +keys += [f"minecraft:{model}#main" for model in ("armor_stand", "armor_stand_small")] + +face = [[0, 0, 0, 0, 0], [16, 0, 0, 1, 0], [16, 16, 0, 1, 1], [0, 16, 0, 0, 1]] +part = {"pose": [1, 2, 3, 0.25, -0.5, 0.75, 1, 1, 1], "polygons": [face] * 6, + "normals": [[0, 0, 1]] * 6} +model = {"pose": [0, 0, 0, 0, 0, 0, 1, 1, 1], + "children": {f"part_{i}": part for i in range(12)}} +encoded = json.dumps(model, separators=(",", ":")) +entries = [json.dumps(key) + ":" + encoded for key in keys] +size = 2 + sum(map(len, entries)) + len(entries) - 1 +index = 0 +while size < 2_470_000: + entry = json.dumps(f"minecraft:fixture_{index}#main") + ":" + encoded + entries.append(entry) + size += 1 + len(entry) + index += 1 +output = pathlib.Path(sys.argv[1]) +output.write_text("{" + ",".join(entries) + "}") +print(json.dumps({"path": str(output), "bytes": output.stat().st_size, + "layers": len(entries), "selected_layers": len(keys)})) diff --git a/benchmarks/entity-model-document-2026-10-14/results.json b/benchmarks/entity-model-document-2026-10-14/results.json new file mode 100644 index 000000000..1ef0c6576 --- /dev/null +++ b/benchmarks/entity-model-document-2026-10-14/results.json @@ -0,0 +1,43 @@ +{ + "baseline_median_ms": 1434.973835, + "baseline_ms": [ + 1400.008286, + 1406.761694, + 1408.9131360000001, + 1418.6680549999999, + 1419.149658, + 1427.082872, + 1433.088092, + 1434.973835, + 1449.7688150000001, + 1452.143883, + 1453.987998, + 1455.518231, + 1457.0334540000001, + 1458.588552, + 1485.34133 + ], + "document_bytes": 2473695, + "optimized_median_ms": 33.419768000000005, + "optimized_ms": [ + 32.64795, + 32.812732, + 33.054488, + 33.056914, + 33.102999000000004, + 33.23532, + 33.28287, + 33.419768000000005, + 33.610569, + 33.874749, + 33.915657, + 33.93877, + 34.009893999999996, + 34.550526, + 36.096408000000004 + ], + "repetitions": 15, + "selected_models": 42, + "speedup": 42.937875421516985, + "warmup_pairs": 3 +} diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index 96be2f137..c0420c748 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -9200,6 +9200,15 @@ pub fn run() -> Result<()> { player_arm: horizon_client::mobs::load_model(&root, "minecraft:player#main") .and_then(|m| m.children.into_iter().find(|c| c.name == "right_arm")), }; + // These batches share the exported document instead of reparsing it per layer. + let (armor_stand_assets, boat_models, cart_models) = { + let document = horizon_client::mobs::EntityModelDocument::load(&root).ok(); + ( + armor_stands::ArmorStandAssets::load(&root, document.as_ref()), + boats::BoatModels::load(document.as_ref()), + minecarts::CartModels::load(document.as_ref()), + ) + }; let inventory = vec![None; 36]; let now = Instant::now(); let game_root = options.resources.clone(); @@ -9371,9 +9380,9 @@ pub fn run() -> Result<()> { glow_map_frame_model: frames::bake_frame(&root, "glow_item_frame_map"), armor_stands: Vec::new(), others: Vec::new(), - armor_stand_assets: armor_stands::ArmorStandAssets::load(&root), + armor_stand_assets, boats: Vec::new(), - boat_models: boats::BoatModels::load(&root), + boat_models, crystal_model: horizon_client::mobs::load_model(&root, "minecraft:end_crystal#main"), carts: Vec::new(), jukebox_sounds: HashMap::new(), @@ -9392,7 +9401,7 @@ pub fn run() -> Result<()> { .join("assets/skins"), ), skin_slots: Vec::new(), - cart_models: minecarts::CartModels::load(&root), + cart_models, riding: None, ender_items: vec![None; 27], ender_open: None, @@ -9556,6 +9565,9 @@ mod runtime_reset_tests { } } +#[cfg(test)] +mod entity_model_loading_tests; + #[cfg(test)] mod tests { use super::*; diff --git a/crates/horizon-client/src/game/armor_stands.rs b/crates/horizon-client/src/game/armor_stands.rs index dfc6adfd8..94e9422ed 100644 --- a/crates/horizon-client/src/game/armor_stands.rs +++ b/crates/horizon-client/src/game/armor_stands.rs @@ -27,8 +27,11 @@ pub(super) struct ArmorStandAssets { pub equipment: HashMap)>>, } impl ArmorStandAssets { - pub fn load(root: &std::path::Path) -> Self { - let load = |key: &str| horizon_client::mobs::load_model(root, key); + pub fn load( + root: &std::path::Path, + document: Option<&horizon_client::mobs::EntityModelDocument>, + ) -> Self { + let load = |key: &str| document.and_then(|document| document.model(key)); let mut layers = HashMap::new(); let mut player = HashMap::new(); for slot in ["helmet", "chestplate", "leggings", "boots"] { diff --git a/crates/horizon-client/src/game/boats.rs b/crates/horizon-client/src/game/boats.rs index b31127e1e..5f2897c67 100644 --- a/crates/horizon-client/src/game/boats.rs +++ b/crates/horizon-client/src/game/boats.rs @@ -151,25 +151,22 @@ impl BoatModels { self.models.contains_key(wood) } } - pub fn load(root: &std::path::Path) -> Self { + pub fn load(document: Option<&horizon_client::mobs::EntityModelDocument>) -> Self { let mut models = HashMap::new(); let mut chest_models = HashMap::new(); - if let Ok(bytes) = std::fs::read(root.join("entity-models.json")) - && let Ok(serde_json::Value::Object(all)) = - serde_json::from_slice::(&bytes) - { - for key in all.keys() { + if let Some(document) = document { + for key in document.keys() { if let Some(wood) = key .strip_prefix("minecraft:boat/") .and_then(|k| k.strip_suffix("#main")) - && let Some(part) = horizon_client::mobs::load_model(root, key) + && let Some(part) = document.model(key) { models.insert(wood.to_owned(), part); } if let Some(wood) = key .strip_prefix("minecraft:chest_boat/") .and_then(|k| k.strip_suffix("#main")) - && let Some(part) = horizon_client::mobs::load_model(root, key) + && let Some(part) = document.model(key) { chest_models.insert(wood.to_owned(), part); } diff --git a/crates/horizon-client/src/game/entity_model_loading_tests.rs b/crates/horizon-client/src/game/entity_model_loading_tests.rs new file mode 100644 index 000000000..61ed81491 --- /dev/null +++ b/crates/horizon-client/src/game/entity_model_loading_tests.rs @@ -0,0 +1,272 @@ +//! Model-batch equivalence tests and an opt-in benchmark of the actual loaders. +use super::{armor_stands::ArmorStandAssets, boats::BoatModels, minecarts::CartModels}; +use horizon_client::mobs::{EntityModelDocument, Part, load_model}; +use serde_json::{Value, json}; +use std::{collections::BTreeMap, fs, hint::black_box, path::Path, time::Instant}; + +const WOODS: [&str; 11] = [ + "oak", + "spruce", + "birch", + "jungle", + "acacia", + "dark_oak", + "mangrove", + "cherry", + "bamboo", + "pale_oak", + "test_wood", +]; +const CARTS: [&str; 6] = [ + "minecart", + "chest_minecart", + "hopper_minecart", + "furnace_minecart", + "tnt_minecart", + "command_block_minecart", +]; + +fn fixture() -> Value { + let mut all = serde_json::Map::new(); + let part = json!({ + "pose": [1,2,3,0.25,-0.5,0.75,1,2,0.5], + "polygons": [[[0,0,0,0,0],[1,0,0,1,0],[1,1,0,1,1],[0,1,0,0,1]]], + "normals": [[0,0,1]], + "children": {"root": {"children": {"bone": {"pose": [4,5,6]}}}, "other": {}} + }); + for wood in WOODS { + for prefix in ["boat", "chest_boat"] { + all.insert(format!("minecraft:{prefix}/{wood}#main"), part.clone()); + } + } + for cart in CARTS { + all.insert(format!("minecraft:{cart}#main"), part.clone()); + } + for model in ["player", "armor_stand", "armor_stand_small"] { + for layer in ["helmet", "chestplate", "leggings", "boots"] { + all.insert(format!("minecraft:{model}#{layer}"), part.clone()); + } + } + for model in ["armor_stand", "armor_stand_small"] { + all.insert(format!("minecraft:{model}#main"), part.clone()); + } + // Discovery must exclude other models and non-main boat layers. + all.insert("minecraft:boat/oak#water_patch".into(), part.clone()); + all.insert("minecraft:unrelated#main".into(), part); + Value::Object(all) +} + +struct FixtureRoot(std::path::PathBuf); +impl FixtureRoot { + fn new() -> Self { + static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + let next = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed); + let root = std::env::temp_dir().join(format!( + "horizon-entity-models-{}-{next}", + std::process::id() + )); + fs::create_dir(&root).unwrap(); + Self(root) + } +} +impl Drop for FixtureRoot { + fn drop(&mut self) { + fs::remove_dir_all(&self.0).unwrap(); + } +} + +// Preserve the previous production algorithm: one discovery parse, then a full +// file read/parse through load_model for each of the 42 selected layers. +fn baseline(root: &Path) -> BTreeMap { + let mut models = BTreeMap::new(); + if let Ok(bytes) = fs::read(root.join("entity-models.json")) + && let Ok(Value::Object(all)) = serde_json::from_slice::(&bytes) + { + for key in all.keys() { + for (prefix, label) in [ + ("minecraft:boat/", "boat"), + ("minecraft:chest_boat/", "chest_boat"), + ] { + if let Some(wood) = key + .strip_prefix(prefix) + .and_then(|k| k.strip_suffix("#main")) + && let Some(part) = load_model(root, key) + { + models.insert(format!("{label}/{wood}"), part); + } + } + } + } + for cart in CARTS { + if let Some(part) = load_model(root, &format!("minecraft:{cart}#main")) { + models.insert(format!("cart/{cart}"), part); + } + } + for slot in ["helmet", "chestplate", "leggings", "boots"] { + for model in ["player", "armor_stand", "armor_stand_small"] { + if let Some(part) = load_model(root, &format!("minecraft:{model}#{slot}")) { + models.insert(format!("{model}/{slot}"), part); + } + } + } + // The fixture contains only entity-models.json; armor equipment is absent. + let _ = fs::read_dir(root.join("assets/minecraft/equipment")); + for model in ["armor_stand", "armor_stand_small"] { + if let Some(part) = load_model(root, &format!("minecraft:{model}#main")) { + models.insert(format!("{model}/main"), part); + } + } + models +} + +fn optimized(root: &Path) -> BTreeMap { + let document = EntityModelDocument::load(root).ok(); + let boats = BoatModels::load(document.as_ref()); + let carts = CartModels::load(document.as_ref()); + let armor = ArmorStandAssets::load(root, document.as_ref()); + let mut models = BTreeMap::new(); + for (label, group) in [("boat", boats.models), ("chest_boat", boats.chest_models)] { + for (wood, part) in group { + models.insert(format!("{label}/{wood}"), part); + } + } + for (kind, part) in carts.models { + models.insert( + format!("cart/{}", kind.id().trim_start_matches("minecraft:")), + part, + ); + } + for ((slot, small), part) in armor.layers { + let model = if small { + "armor_stand_small" + } else { + "armor_stand" + }; + models.insert(format!("{model}/{slot}"), part); + } + for (slot, part) in armor.player { + models.insert(format!("player/{slot}"), part); + } + for (model, part) in [ + ("armor_stand", armor.main), + ("armor_stand_small", armor.small), + ] { + if let Some(part) = part { + models.insert(format!("{model}/main"), part); + } + } + models +} + +fn assert_equivalent(root: &Path) { + // Debug includes every part name, pose, polygon normal/vertex and child. + assert_eq!( + format!("{:?}", baseline(root)), + format!("{:?}", optimized(root)) + ); +} + +#[test] +fn entity_model_batches_preserve_parts_missing_layers_and_load_failures() { + let root = FixtureRoot::new(); + assert_equivalent(&root.0); // missing file + let file = root.0.join("entity-models.json"); + for bytes in [b"{".as_slice(), b"null", b"[]", b"{}"] { + fs::write(&file, bytes).unwrap(); + assert_equivalent(&root.0); + } + let mut all = fixture(); + fs::write(&file, serde_json::to_vec(&all).unwrap()).unwrap(); + assert_equivalent(&root.0); + assert_eq!(optimized(&root.0).len(), 42); + all.as_object_mut() + .unwrap() + .remove("minecraft:armor_stand_small#main"); + all.as_object_mut() + .unwrap() + .remove("minecraft:boat/oak#main"); + fs::write(&file, serde_json::to_vec(&all).unwrap()).unwrap(); + assert_equivalent(&root.0); + assert_eq!(optimized(&root.0).len(), 40); + let document = EntityModelDocument::load(&root.0).unwrap(); + let mut first = document.model("minecraft:armor_stand#main").unwrap(); + first.children.clear(); + assert!( + !document + .model("minecraft:armor_stand#main") + .unwrap() + .children + .is_empty() + ); +} + +#[test] +fn armor_equipment_loads_without_an_entity_model_document() { + let root = FixtureRoot::new(); + let equipment = root.0.join("assets/minecraft/equipment"); + fs::create_dir_all(&equipment).unwrap(); + fs::write( + equipment.join("leather.json"), + serde_json::to_vec(&json!({"layers": {"humanoid": [{ + "texture": "minecraft:leather", "dyeable": {"color_when_undyed": 0x123456} + }]}})) + .unwrap(), + ) + .unwrap(); + fs::write(equipment.join("invalid.json"), b"{").unwrap(); + let assets = ArmorStandAssets::load(&root.0, None); + assert!(assets.main.is_none()); + assert!(assets.layers.is_empty()); + assert_eq!( + assets.equipment["minecraft:leather"]["humanoid"], + ("entity/equipment/humanoid/leather".into(), Some(0x123456)) + ); + assert!(!assets.equipment.contains_key("minecraft:invalid")); +} + +#[test] +#[ignore = "opt-in benchmark; requires ENTITY_MODEL_BENCH_DOCUMENT"] +fn entity_model_document_benchmark() { + let input = std::env::var("ENTITY_MODEL_BENCH_DOCUMENT").unwrap(); + let root = FixtureRoot::new(); + let bytes = fs::read(&input).unwrap(); + fs::write(root.0.join("entity-models.json"), &bytes).unwrap(); + assert_equivalent(&root.0); + let model_count = optimized(&root.0).len(); + let repetitions: usize = std::env::var("ENTITY_MODEL_BENCH_REPETITIONS") + .unwrap_or_else(|_| "15".into()) + .parse() + .unwrap(); + assert!(repetitions > 0); + for _ in 0..3 { + black_box(baseline(black_box(&root.0))); + black_box(optimized(black_box(&root.0))); + } + let mut before = Vec::new(); + let mut after = Vec::new(); + for i in 0..repetitions { + for optimized_first in [i % 2 == 0, i % 2 != 0] { + let started = Instant::now(); + if optimized_first { + black_box(optimized(black_box(&root.0))); + after.push(started.elapsed().as_secs_f64() * 1000.0); + } else { + black_box(baseline(black_box(&root.0))); + before.push(started.elapsed().as_secs_f64() * 1000.0); + } + } + } + before.sort_by(f64::total_cmp); + after.sort_by(f64::total_cmp); + let old = before[repetitions / 2]; + let new = after[repetitions / 2]; + println!( + "{}", + json!({ + "document_bytes": bytes.len(), "selected_models": model_count, + "warmup_pairs": 3, "repetitions": repetitions, + "baseline_ms": before, "optimized_ms": after, + "baseline_median_ms": old, "optimized_median_ms": new, "speedup": old / new + }) + ); +} diff --git a/crates/horizon-client/src/game/minecarts.rs b/crates/horizon-client/src/game/minecarts.rs index b81d09325..47b1ab053 100644 --- a/crates/horizon-client/src/game/minecarts.rs +++ b/crates/horizon-client/src/game/minecarts.rs @@ -191,7 +191,7 @@ pub(super) struct CartModels { pub models: HashMap, } impl CartModels { - pub fn load(root: &std::path::Path) -> Self { + pub fn load(document: Option<&horizon_client::mobs::EntityModelDocument>) -> Self { let kinds = [ CartKind::Rideable, CartKind::Chest, @@ -202,9 +202,7 @@ impl CartModels { ]; let models = kinds .into_iter() - .filter_map(|k| { - horizon_client::mobs::load_model(root, &format!("{}#main", k.id())).map(|m| (k, m)) - }) + .filter_map(|k| document?.model(&format!("{}#main", k.id())).map(|m| (k, m))) .collect(); Self { models } } diff --git a/crates/horizon-client/src/mobs.rs b/crates/horizon-client/src/mobs.rs index b2b63626e..1c1ac82a8 100644 --- a/crates/horizon-client/src/mobs.rs +++ b/crates/horizon-client/src/mobs.rs @@ -1767,11 +1767,33 @@ pub fn render( ) { render::render_single(mob, alpha, camera, uv, light, out); } +/// A parsed `entity-models.json` document, shared while loading model batches. +/// Each lookup still constructs an independent part tree for the caller. +pub struct EntityModelDocument(Value); + +impl EntityModelDocument { + pub fn load(root: &Path) -> crate::Result { + Ok(Self(serde_json::from_slice(&fs::read( + root.join("entity-models.json"), + )?)?)) + } + + pub fn model(&self, key: &str) -> Option { + self.0.get(key).map(|m| Part::parse("root", m)) + } + + pub fn keys(&self) -> impl Iterator { + self.0 + .as_object() + .into_iter() + .flat_map(|all| all.keys().map(String::as_str)) + } +} + /// Load one baked model layer from `entity-models.json` (e.g. `minecraft:chest#main`). +/// Batch loaders should share an `EntityModelDocument` instead. pub fn load_model(root: &Path, key: &str) -> Option { - let models: Value = - serde_json::from_slice(&fs::read(root.join("entity-models.json")).ok()?).ok()?; - models.get(key).map(|m| Part::parse("root", m)) + EntityModelDocument::load(root).ok()?.model(key) } /// ModelPart.render: translate, rotate ZYX, scale, then children. pub fn render_model( From 4cac0a13cd8cebdad0640c0107b2d2f6d4a14f76 Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:01:00 +0100 Subject: [PATCH 06/97] perf(client): track structural chunk membership revisions --- crates/horizon-client/src/chunk_map.rs | 122 +++++++++++++++++++++++++ crates/horizon-client/src/lib.rs | 1 + crates/horizon-client/src/world.rs | 2 +- 3 files changed, 124 insertions(+), 1 deletion(-) create mode 100644 crates/horizon-client/src/chunk_map.rs diff --git a/crates/horizon-client/src/chunk_map.rs b/crates/horizon-client/src/chunk_map.rs new file mode 100644 index 000000000..81e06f020 --- /dev/null +++ b/crates/horizon-client/src/chunk_map.rs @@ -0,0 +1,122 @@ +//! Resident chunk membership, with a token for consumers that cache its keys. +use crate::{chunk::Chunk, fast_hash::FxHashMap}; +use std::{ + collections::hash_map::{Iter, ValuesMut}, + ops::Deref, + sync::{ + Arc, + atomic::{AtomicU64, Ordering}, + }, +}; + +type Key = (i32, i32); +type Columns = FxHashMap>; +static NEXT_REVISION: AtomicU64 = AtomicU64::new(1); +fn next_revision() -> u64 { + NEXT_REVISION.fetch_add(1, Ordering::Relaxed) +} + +/// Read access behaves like a map. Structural writes are explicit so edits to +/// blocks or light don't invalidate consumers of the loaded chunk key set. +/// Tokens are process-wide: replacing the entire map also invalidates caches. +pub struct ChunkMap { + columns: Columns, + revision: u64, +} +impl Default for ChunkMap { + fn default() -> Self { + Self { + columns: Columns::default(), + revision: next_revision(), + } + } +} +impl ChunkMap { + pub fn membership_revision(&self) -> u64 { + self.revision + } + pub fn insert(&mut self, key: Key, chunk: Arc) -> Option> { + let previous = self.columns.insert(key, chunk); + if previous.is_none() { + self.revision = next_revision(); + } + previous + } + pub fn remove(&mut self, key: &Key) -> Option> { + let previous = self.columns.remove(key); + if previous.is_some() { + self.revision = next_revision(); + } + previous + } + pub fn clear(&mut self) { + if !self.columns.is_empty() { + self.columns.clear(); + self.revision = next_revision(); + } + } + pub fn get_mut(&mut self, key: &Key) -> Option<&mut Arc> { + self.columns.get_mut(key) + } + pub fn values_mut(&mut self) -> ValuesMut<'_, Key, Arc> { + self.columns.values_mut() + } +} +impl Deref for ChunkMap { + type Target = Columns; + fn deref(&self) -> &Columns { + &self.columns + } +} +impl<'a> IntoIterator for &'a ChunkMap { + type Item = (&'a Key, &'a Arc); + type IntoIter = Iter<'a, Key, Arc>; + fn into_iter(self) -> Self::IntoIter { + self.columns.iter() + } +} +impl crate::light::LightWorld for ChunkMap { + fn state(&self, x: i32, y: i32, z: i32) -> Option { + self.columns.state(x, y, z) + } + fn light(&self, x: i32, y: i32, z: i32) -> Option { + self.columns.light(x, y, z) + } + fn set_light(&mut self, x: i32, y: i32, z: i32, packed: u8) { + self.columns.set_light(x, y, z, packed); + } +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn membership_tokens_track_keys_and_map_replacement_only() { + let mut map = ChunkMap::default(); + let empty = map.membership_revision(); + map.clear(); + map.remove(&(0, 0)); + assert_eq!(empty, map.membership_revision()); + let chunk = Arc::new(Chunk::empty(0, 0)); + map.insert((0, 0), chunk.clone()); + let inserted = map.membership_revision(); + assert_ne!(empty, inserted); + map.insert((0, 0), chunk.clone()); + Arc::make_mut(map.get_mut(&(0, 0)).unwrap()).lit = true; + for column in map.values_mut() { + Arc::make_mut(column).light_loaded = true; + } + crate::light::LightWorld::set_light(&mut map, 0, 0, 0, 0); + assert_eq!(inserted, map.membership_revision()); + map.remove(&(0, 0)); + map.insert((1, 0), chunk); + assert_eq!(map.len(), 1); + assert_ne!(inserted, map.membership_revision()); + let replaced = map.membership_revision(); + map.clear(); + assert_ne!(replaced, map.membership_revision()); + let cleared = map.membership_revision(); + map = ChunkMap::default(); + assert_ne!(cleared, map.membership_revision()); + } +} diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs index 07ba1af2a..315d8ede9 100644 --- a/crates/horizon-client/src/lib.rs +++ b/crates/horizon-client/src/lib.rs @@ -27,6 +27,7 @@ pub mod camera; pub mod cauldron; pub mod chat; pub mod chunk; +pub mod chunk_map; pub mod clipboard; pub mod clock; pub mod clouds; diff --git a/crates/horizon-client/src/world.rs b/crates/horizon-client/src/world.rs index 1b589041d..2d8213905 100644 --- a/crates/horizon-client/src/world.rs +++ b/crates/horizon-client/src/world.rs @@ -10,7 +10,7 @@ use std::{ pub struct World { pub fast_lava: bool, - pub chunks: crate::fast_hash::FxHashMap<(i32, i32), Arc>, + pub chunks: crate::chunk_map::ChunkMap, pub random: LegacyRandom, pub revision: u64, pub health_rules: crate::health::HealthRules, From 27468021523a8cb69eaf27819670f117b6c5e63f Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:31:01 +0100 Subject: [PATCH 07/97] perf(client): synchronize tick chunk membership only on changes --- .../examples/tick_chunk_membership_bench.rs | 143 +++++++++++ crates/horizon-client/src/game.rs | 20 +- crates/horizon-client/src/lib.rs | 1 + .../src/tick_chunk_membership.rs | 226 ++++++++++++++++++ 4 files changed, 382 insertions(+), 8 deletions(-) create mode 100644 crates/horizon-client/examples/tick_chunk_membership_bench.rs create mode 100644 crates/horizon-client/src/tick_chunk_membership.rs diff --git a/crates/horizon-client/examples/tick_chunk_membership_bench.rs b/crates/horizon-client/examples/tick_chunk_membership_bench.rs new file mode 100644 index 000000000..6b9cb8a0a --- /dev/null +++ b/crates/horizon-client/examples/tick_chunk_membership_bench.rs @@ -0,0 +1,143 @@ +//! Resident-key synchronization used by Game (registration callback work excluded). +//! Run: CARGO_INCREMENTAL=0 cargo run -p horizon-client --profile fast --example tick_chunk_membership_bench +use horizon_client::{ + chunk::Chunk, chunk_map::ChunkMap, tick_chunk_membership::TickChunkMembership, +}; +use std::{collections::HashSet, hint::black_box, sync::Arc, time::Instant}; + +type Key = (i32, i32); +#[derive(Default)] +struct Old { + keys: HashSet, +} +impl Old { + fn sync(&mut self, map: &ChunkMap) -> (usize, usize) { + let loaded: HashSet<_> = map.keys().copied().collect(); + let mut counts = (0, 0); + for key in loaded.difference(&self.keys.clone()) { + black_box(key); + counts.0 += 1; + } + for key in self.keys.difference(&loaded) { + black_box(key); + counts.1 += 1; + } + self.keys = loaded; + counts + } +} +fn new_sync(cache: &mut TickChunkMembership, map: &ChunkMap) -> (usize, usize) { + if !cache.synchronize(map) { + return (0, 0); + } + let added = cache.take_added(); + for key in &added { + black_box(key); + } + for key in cache.removed() { + black_box(key); + } + let counts = (added.len(), cache.removed().len()); + cache.recycle_added(added); + counts +} +fn map(offset: i32) -> ChunkMap { + let mut map = ChunkMap::default(); + // Share a payload: the synchronization path reads only keys, not block data. + let chunk = Arc::new(Chunk::empty(0, 0)); + for x in -16..=16 { + for z in -16..=16 { + map.insert((x + offset, z), chunk.clone()); + } + } + map +} +fn run(new: bool, scenario: usize, iterations: usize) -> (f64, (usize, usize)) { + let mut a = map(0); + let b = map(33); + let chunk = Arc::new(Chunk::empty(0, 0)); + let mut old = Old::default(); + let mut cache = TickChunkMembership::default(); + for _ in 0..64 { + if new { + black_box(new_sync(&mut cache, &a)); + } else { + black_box(old.sync(&a)); + } + } + let mut total = (0, 0); + let start = Instant::now(); + for i in 0..iterations { + let resident = match scenario { + 0 => &a, + 1 => { + let (previous, next) = if i % 2 == 0 { + ((-16, -16), (-17, -16)) + } else { + ((-17, -16), (-16, -16)) + }; + a.remove(&previous); + a.insert(next, chunk.clone()); + &a + } + 2 => { + if i % 2 == 0 { + &b + } else { + &a + } + } + _ => unreachable!(), + }; + let counts = if new { + new_sync(black_box(&mut cache), black_box(resident)) + } else { + old.sync(black_box(resident)) + }; + total.0 += counts.0; + total.1 += counts.1; + } + ( + start.elapsed().as_secs_f64() * 1e9 / iterations as f64, + black_box(total), + ) +} +fn main() { + println!("1089 keys, 64 warmup calls, 9 samples; ns/sync, median"); + for (scenario, name, iterations) in [ + (0, "stable", 10_000), + (1, "one-key same-count replacement", 2_000), + (2, "whole-map replacement", 1_000), + ] { + let mut before = Vec::new(); + let mut after = Vec::new(); + for sample in 0..9 { + let (old, new) = if sample % 2 == 0 { + ( + run(false, scenario, iterations), + run(true, scenario, iterations), + ) + } else { + let new = run(true, scenario, iterations); + (run(false, scenario, iterations), new) + }; + assert_eq!(old.1, new.1); + let expected = match scenario { + 0 => (0, 0), + 1 => (iterations, iterations), + _ => (1089 * iterations, 1089 * iterations), + }; + assert_eq!(new.1, expected); + before.push(old.0); + after.push(new.0); + } + before.sort_by(f64::total_cmp); + after.sort_by(f64::total_cmp); + println!( + "{name}: {:.1} -> {:.1} ns, {:.2}x; {iterations} iterations/sample", + before[4], + after[4], + before[4] / after[4] + ); + } +} diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index 96be2f137..3e7469d3d 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -837,7 +837,7 @@ struct Game<'a> { end_portal_travel: bool, end: end::EndState, block_ticks: Ticks, - tick_chunks: HashSet<(i32, i32)>, + tick_chunks: horizon_client::tick_chunk_membership::TickChunkMembership, level_events: Vec, falling: Vec, paintings: Vec, @@ -1549,15 +1549,19 @@ impl Game<'_> { } /// Track which chunks are ticking (Ticks needs chunk load/unload). fn sync_tick_chunks(&mut self) { - let loaded: HashSet<(i32, i32)> = self.world.chunks.keys().copied().collect(); - for k in loaded.difference(&self.tick_chunks.clone()) { - self.register_chunk_ticks(*k); + if !self.tick_chunks.synchronize(&self.world.chunks) { + return; } - for k in self.tick_chunks.difference(&loaded) { + // Move only the added keys out so registration can borrow all of Game. + let added = self.tick_chunks.take_added(); + for &key in &added { + self.register_chunk_ticks(key); + } + for &key in self.tick_chunks.removed() { self.block_ticks - .remove_chunk(horizon_core::position::ChunkPos::new(k.0, k.1)); + .remove_chunk(horizon_core::position::ChunkPos::new(key.0, key.1)); } - self.tick_chunks = loaded; + self.tick_chunks.recycle_added(added); } /// ServerLevel.tick block phases: scheduled ticks, random ticks within the /// simulation distance, block events and moving pistons. @@ -9359,7 +9363,7 @@ pub fn run() -> Result<()> { end_portal_travel: false, end: Default::default(), block_ticks: Ticks::new(0), - tick_chunks: HashSet::new(), + tick_chunks: Default::default(), level_events: Vec::new(), falling: Vec::new(), paintings: Vec::new(), diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs index 315d8ede9..d8b45bdbd 100644 --- a/crates/horizon-client/src/lib.rs +++ b/crates/horizon-client/src/lib.rs @@ -146,6 +146,7 @@ pub mod structure_blocks; pub mod tab_list; pub mod testgen; pub mod text; +pub mod tick_chunk_membership; pub mod title; pub mod title_edition; pub mod ui; diff --git a/crates/horizon-client/src/tick_chunk_membership.rs b/crates/horizon-client/src/tick_chunk_membership.rs new file mode 100644 index 000000000..42785f289 --- /dev/null +++ b/crates/horizon-client/src/tick_chunk_membership.rs @@ -0,0 +1,226 @@ +//! Tick scheduler membership, invalidated by resident key changes or resets. +use crate::chunk_map::ChunkMap; +use std::collections::HashSet; + +type Key = (i32, i32); + +#[derive(Default)] +pub struct TickChunkMembership { + keys: HashSet, + revision: Option, + added: Vec, + removed: Vec, +} + +impl TickChunkMembership { + /// A scheduler reset must re-register resident chunks even if the world did + /// not change. Keep this invalidation with the keys so callers cannot forget. + pub fn clear(&mut self) { + self.keys.clear(); + self.revision = None; + self.added.clear(); + self.removed.clear(); + } + + /// Returns false in O(1) when resident membership is unchanged. On change, + /// update the existing set and record only registration/removal deltas. + pub fn synchronize(&mut self, chunks: &ChunkMap) -> bool { + let revision = chunks.membership_revision(); + if self.revision == Some(revision) { + return false; + } + self.added.clear(); + self.removed.clear(); + self.keys.retain(|key| { + if chunks.contains_key(key) { + true + } else { + self.removed.push(*key); + false + } + }); + for &key in chunks.keys() { + if self.keys.insert(key) { + self.added.push(key); + } + } + self.revision = Some(revision); + true + } + + /// Allows registration to borrow the owning Game without cloning its set. + pub fn take_added(&mut self) -> Vec { + std::mem::take(&mut self.added) + } + + /// Retain scratch capacity after registration. + pub fn recycle_added(&mut self, mut added: Vec) { + added.clear(); + self.added = added; + } + + pub fn removed(&self) -> &[Key] { + &self.removed + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::chunk::Chunk; + use std::sync::Arc; + + fn compare(cache: &mut TickChunkMembership, old: &mut HashSet, map: &ChunkMap) { + let loaded: HashSet<_> = map.keys().copied().collect(); + let expected_added: HashSet<_> = loaded.difference(old).copied().collect(); + let expected_removed: HashSet<_> = old.difference(&loaded).copied().collect(); + if cache.synchronize(map) { + let added = cache.take_added(); + assert_eq!( + added.iter().copied().collect::>(), + expected_added + ); + assert_eq!( + cache.removed().iter().copied().collect::>(), + expected_removed + ); + cache.recycle_added(added); + } else { + assert!(expected_added.is_empty() && expected_removed.is_empty()); + } + assert_eq!(cache.keys, loaded); + *old = loaded; + } + + #[test] + fn matches_old_deltas_through_load_unload_replacement_and_reset() { + let mut map = ChunkMap::default(); + let chunk = Arc::new(Chunk::empty(0, 0)); + let mut cache = TickChunkMembership::default(); + let mut old = HashSet::new(); + compare(&mut cache, &mut old, &map); + assert!(!cache.synchronize(&map)); + for key in [(-16, -8), (0, 0), (12, -1)] { + map.insert(key, chunk.clone()); + compare(&mut cache, &mut old, &map); + } + map.remove(&(-16, -8)); + map.insert((-15, -8), chunk.clone()); // Same count, different key. + compare(&mut cache, &mut old, &map); + map.insert((0, 0), Arc::new(Chunk::empty(0, 0))); + assert!(!cache.synchronize(&map)); // Payload replacement needs no registration. + cache.clear(); + old.clear(); // Scheduler replaced with unchanged resident map. + compare(&mut cache, &mut old, &map); + map.clear(); + compare(&mut cache, &mut old, &map); + map = ChunkMap::default(); + assert!(cache.synchronize(&map)); // Distinct empty world has distinct token. + map.insert((-2, 4), chunk); + compare(&mut cache, &mut old, &map); + cache.clear(); + old.clear(); + map = ChunkMap::default(); + compare(&mut cache, &mut old, &map); + } + + #[test] + fn scheduler_keeps_saved_ticks_on_stable_membership_and_removes_unloaded_chunks() { + use horizon_core::{ + position::{BlockPos, ChunkPos}, + ticks::{ChunkTicks, SavedTick, TickPriority, TickTypeId}, + }; + use horizon_world::level::Ticks; + + fn register(ticks: &mut Ticks, key: Key) { + let pos = ChunkPos::new(key.0, key.1); + let saved = SavedTick { + kind: TickTypeId(1), + pos: BlockPos::new(key.0 * 16, 0, key.1 * 16), + delay: 5, + priority: TickPriority::Normal, + }; + ticks + .add_chunk( + pos, + ChunkTicks::from_saved(vec![saved]), + ChunkTicks::from_saved(vec![saved]), + ) + .unwrap(); + ticks.blocks.unpack_chunk(pos, 100); + ticks.fluids.unpack_chunk(pos, 100); + } + let mut map = ChunkMap::default(); + let chunk = Arc::new(Chunk::empty(0, 0)); + let mut cache = TickChunkMembership::default(); + let mut old_keys = HashSet::new(); + let mut old_ticks = Ticks::default(); + let mut new_ticks = Ticks::default(); + let keys = [(-3, -1), (2, 4), (-2, -1)]; + for step in 0..7 { + match step { + 0 => { + map.insert(keys[0], chunk.clone()); + map.insert(keys[1], chunk.clone()); + } + 2 => { + map.remove(&keys[0]); + map.insert(keys[2], chunk.clone()); + } + 3 => { + map.insert(keys[1], chunk.clone()); + } + 4 => { + // Reset only the scheduler: resident token is unchanged. + new_ticks = Ticks::default(); + old_ticks = Ticks::default(); + cache.clear(); + old_keys.clear(); + } + 5 => { + map.clear(); + } + 6 => { + map = ChunkMap::default(); + map.insert(keys[0], chunk.clone()); + new_ticks = Ticks::default(); + old_ticks = Ticks::default(); + cache.clear(); + old_keys.clear(); + } + _ => {} + } + let loaded: HashSet<_> = map.keys().copied().collect(); + for &key in loaded.difference(&old_keys) { + register(&mut old_ticks, key); + } + for &key in old_keys.difference(&loaded) { + old_ticks.remove_chunk(ChunkPos::new(key.0, key.1)); + } + old_keys = loaded; + if cache.synchronize(&map) { + let added = cache.take_added(); + for &key in &added { + register(&mut new_ticks, key); + } + for &key in cache.removed() { + new_ticks.remove_chunk(ChunkPos::new(key.0, key.1)); + } + cache.recycle_added(added); + } + for key in keys { + let pos = ChunkPos::new(key.0, key.1); + for (old, new) in [ + (&old_ticks.blocks, &new_ticks.blocks), + (&old_ticks.fluids, &new_ticks.fluids), + ] { + assert_eq!( + old.chunk(pos).map(|c| c.queued()), + new.chunk(pos).map(|c| c.queued()) + ); + assert_eq!(new.chunk(pos).is_some(), map.contains_key(&key)); + } + } + } + } +} From ded40d60c662e0a372c138d3cf3890f7e4cb244c Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:27:59 +0100 Subject: [PATCH 08/97] perf(client): reuse parsed model states during preparation --- benchmarks/model-state-parse-2026-10-14.md | 62 ++++ .../examples/model_states_bench.rs | 291 ++++++++++++++++++ crates/horizon-client/src/models.rs | 4 +- crates/horizon-client/src/models/catalog.rs | 10 + 4 files changed, 365 insertions(+), 2 deletions(-) create mode 100644 benchmarks/model-state-parse-2026-10-14.md create mode 100644 crates/horizon-client/examples/model_states_bench.rs diff --git a/benchmarks/model-state-parse-2026-10-14.md b/benchmarks/model-state-parse-2026-10-14.md new file mode 100644 index 000000000..ad04acc6f --- /dev/null +++ b/benchmarks/model-state-parse-2026-10-14.md @@ -0,0 +1,62 @@ +# Reuse parsed model states + +`models::prepare` parsed `model-states.json` to select blocks, then +`StateModels::load` reopened and parsed the same document for binding and baking. +`StateModels::from_facts` now borrows the first parsed map. The public `load` +entry point still reads, parses and validates its own document. Neither path +changes the unbuffered `serde_json::from_reader(File)` strategy. + +The shared map uses `BTreeMap`, preserving the original catalog loader's JSON +validation, including rejection of top-level `null`. The old selection map was +`serde_json::Map`, also backed by a BTreeMap with the project's current features. +Catalog binding, model selection and baking are unchanged. Preparation no longer +holds a second complete JSON tree while constructing the catalog; no persistent +cache or extra clones were added. + +## Measurement + +The committed `model_states_bench` example runs the original two-parse sequence +(first a serde JSON map, then `StateModels::load`) and the new one-parse sequence +(first a BTreeMap, then `StateModels::from_facts`). Both select blocks from the +same generated document and call the actual catalog binding/baking code. Timing +includes file reads, parsing, filtering, binding, baking and result destruction. +Fixture generation and equality checks run outside the timed region. + +Prepared Minecraft resources were unavailable locally, so this is a synthetic +2,836,696-byte document containing 843 block schemas and 53,952 states. Schemas +combine integer and named properties. Blockstate resources use weighted and +conditional multipart choices with rotations and UV locking, sharing one model +with a baked face. Its absent texture uses the normal missing-sprite fallback. +Both paths read identical files with a warm OS cache. The workload does not +represent the full diversity of production model and texture assets. + +On AMD Ryzen 5 5600X, Linux 7.2.8-zen1-2-zen x86_64, rustc 1.99.0 +(b940084d7 2026-09-28), Cargo `fast` profile, serial execution: + +| Path | Median (15 samples) | +| --- | ---: | +| Before: parse twice | 2732.004 ms | +| After: reuse first parse | 1386.060 ms | + +**1.971x speedup; 49.27% less elapsed time** for this loading segment. Each path +has two warmups, sample order alternates, and inputs/results use `black_box`. +This excludes gallery placements, GPU work and overall application startup. + +Equality validation compares every state's selected variants and baked geometry +at three positions, plus sprite layers and opacity/translucency flags. The +focused test also checks matching schema/registry errors, malformed/missing +source files, rejection of `null`, and successful shared-facts loading after the +source file has been deleted. + +## Reproduce + +```sh +export CARGO_TARGET_DIR=/home/bob/Documents/horizon/target +cargo run -p horizon-client --profile fast --example model_states_bench -- 15 +cargo test -p horizon-client --profile fast --example model_states_bench +cargo clippy -p horizon-client --all-targets --profile fast -- -D warnings +cargo fmt --all -- --check +``` + +The target directory can be changed for another machine. The example creates and +removes its fixtures in the system temporary directory. diff --git a/crates/horizon-client/examples/model_states_bench.rs b/crates/horizon-client/examples/model_states_bench.rs new file mode 100644 index 000000000..884f59923 --- /dev/null +++ b/crates/horizon-client/examples/model_states_bench.rs @@ -0,0 +1,291 @@ +//! Compare the old two-parse loading path with catalog construction from shared facts. +//! Run: cargo run -p horizon-client --profile fast --example model_states_bench -- 15 +use horizon_client::{Result, models::StateModels, sprites::Sprites}; +use horizon_core::position::BlockPos; +use horizon_world::{ + DATA_VERSION, + chunk::BlockState, + nbt::Tag, + registry::{BlockRegistry, BlockStateId}, +}; +use serde_json::{Value, json}; +use std::{collections::BTreeMap, fs, hint::black_box, path::PathBuf, time::Instant}; + +struct Fixture { + root: PathBuf, + registry: BlockRegistry, + bytes: usize, + blocks: usize, +} +impl Fixture { + fn new(target_bytes: usize) -> Result { + let root = + std::env::temp_dir().join(format!("horizon-model-states-{}", std::process::id())); + fs::create_dir_all(root.join("assets/minecraft/blockstates"))?; + fs::create_dir_all(root.join("assets/minecraft/models/block"))?; + let mut possible = Vec::new(); + for age in 0..8 { + for facing in ["north", "south", "east", "west"] { + for waterlogged in ["false", "true"] { + possible.push( + json!({"age":age.to_string(), "facing":facing, "waterlogged":waterlogged}), + ); + } + } + } + let fact = json!({"schema":{ + "age":{"integer":[0,7]}, + "facing":{"named":["north","south","east","west"]}, + "waterlogged":{"named":["false","true"]} + },"states":possible}); + let blocks = (target_bytes / (serde_json::to_vec(&fact)?.len() + 26)).max(1); + let mut facts = BTreeMap::new(); + let mut states = Vec::new(); + let mut defaults = BTreeMap::new(); + for i in 0..blocks { + let block = format!("fixture_{i:04}"); + let name = format!("minecraft:{block}"); + defaults.insert(name.as_str().into(), Tag::Int(states.len() as i32)); + for properties in &possible { + let state = BlockState { + name: name.clone(), + properties: serde_json::from_value(properties.clone())?, + }; + states.push(state.to_nbt()); + } + facts.insert(name, fact.clone()); + fs::write( + root.join(format!("assets/minecraft/blockstates/{block}.json")), + r#"{"multipart":[{"apply":[{"model":"minecraft:block/fixture","weight":2},{"model":"minecraft:block/fixture","y":90,"weight":1}]},{"when":{"waterlogged":"true"},"apply":{"model":"minecraft:block/fixture","y":180,"uvlock":true}}]}"#, + )?; + } + fs::write( + root.join("assets/minecraft/models/block/fixture.json"), + r##"{"textures":{"all":"minecraft:block/fixture"},"elements":[{"from":[0,0,0],"to":[16,16,16],"faces":{"north":{"texture":"#all","cullface":"north"}}}]}"##, + )?; + let document = serde_json::to_vec(&facts)?; + let bytes = document.len(); + fs::write(root.join("model-states.json"), document)?; + let registry = BlockRegistry::from_nbt(&Tag::compound([ + ("DataVersion", Tag::Int(DATA_VERSION)), + ("states", Tag::List(states)), + ("defaults", Tag::Compound(defaults)), + ]))?; + Ok(Self { + root, + registry, + bytes, + blocks, + }) + } + fn facts(&self) -> Result> { + Ok(serde_json::from_reader(fs::File::open( + self.root.join("model-states.json"), + )?)?) + } + fn block_names<'a>(&self, names: impl Iterator) -> Vec<&'a str> { + names + .filter(|name| self.registry.default_state(name).is_some()) + .filter_map(|name| name.strip_prefix("minecraft:")) + .collect() + } + fn load(&self, reuse: bool) -> Result<(StateModels, Sprites)> { + // The first parse and block filtering match models::prepare in both paths. + let mut sprites = Sprites::default(); + let catalog = if reuse { + let facts = self.facts()?; + let blocks = self.block_names(facts.keys()); + StateModels::from_facts(&self.root, &self.registry, &blocks, &mut sprites, &facts)? + } else { + let facts: serde_json::Map = + serde_json::from_reader(fs::File::open(self.root.join("model-states.json"))?)?; + let blocks = self.block_names(facts.keys()); + StateModels::load(&self.root, &self.registry, &blocks, &mut sprites)? + }; + Ok((catalog, sprites)) + } + fn verify(&self) -> Result<()> { + let (before, before_sprites) = self.load(false)?; + let (after, after_sprites) = self.load(true)?; + assert_eq!(before_sprites.layers, after_sprites.layers); + assert_eq!(before_sprites.opaque, after_sprites.opaque); + assert_eq!(before_sprites.translucent, after_sprites.translucent); + for id in 0..self.registry.len() { + for position in [ + BlockPos::new(0, 0, 0), + BlockPos::new(12, -4, 7), + BlockPos::new(42, 9, -19), + ] { + let a = before.collect(BlockStateId(id as u32), position)?; + let b = after.collect(BlockStateId(id as u32), position)?; + assert_eq!(a.len(), b.len()); + for ((av, am), (bv, bm)) in a.into_iter().zip(b) { + assert_eq!(av, bv); + assert_eq!(am.ambient_occlusion, bm.ambient_occlusion); + assert_eq!(am.cube, bm.cube); + assert_eq!(am.faces.len(), bm.faces.len()); + for (af, bf) in am.faces.iter().zip(&bm.faces) { + assert_eq!(af.quad, bf.quad); + assert_eq!( + (af.layer, af.opaque, af.translucent), + (bf.layer, bf.opaque, bf.translucent) + ); + } + } + } + } + Ok(()) + } +} +impl Drop for Fixture { + fn drop(&mut self) { + let _ = fs::remove_dir_all(&self.root); + } +} +fn median(values: &mut [f64]) -> f64 { + values.sort_by(f64::total_cmp); + values[values.len() / 2] +} +fn main() -> Result<()> { + let repetitions: usize = std::env::args() + .nth(1) + .map(|s| s.parse()) + .transpose()? + .unwrap_or(15); + if repetitions == 0 { + return Err("repetitions must be positive".into()); + } + let fixture = Fixture::new(2_840_000)?; + fixture.verify()?; + for _ in 0..2 { + for reuse in [false, true] { + drop(black_box(fixture.load(reuse)?)); + } + } + let mut before = Vec::new(); + let mut after = Vec::new(); + for iteration in 0..repetitions { + // Alternate order to limit cache/order bias. File reads remain unbuffered. + for reuse in if iteration % 2 == 0 { + [false, true] + } else { + [true, false] + } { + let started = Instant::now(); + drop(black_box(fixture.load(black_box(reuse))?)); + let ms = started.elapsed().as_secs_f64() * 1000.0; + if reuse { + after.push(ms); + } else { + before.push(ms); + } + } + } + let before = median(&mut before); + let after = median(&mut after); + println!( + "fixture: {} bytes, {} blocks, {} states; equality: all states at 3 positions", + fixture.bytes, + fixture.blocks, + fixture.registry.len() + ); + println!( + "2 warmups/path, {repetitions} samples/path; median before {before:.3} ms, after {after:.3} ms; {:.3}x speedup ({:.2}% less time)", + before / after, + (1.0 - after / before) * 100.0 + ); + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn shared_facts_match_load_and_preserve_errors() -> Result<()> { + let fixture = Fixture::new(1)?; + fixture.verify()?; + let mut facts = fixture.facts()?; + let blocks = ["fixture_0000"]; + let load_error = |facts: &BTreeMap| -> Result { + fs::write( + fixture.root.join("model-states.json"), + serde_json::to_vec(facts)?, + )?; + let a = StateModels::load( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default(), + ) + .err() + .ok_or("expected load error")? + .to_string(); + let b = StateModels::from_facts( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default(), + facts, + ) + .err() + .ok_or("expected shared facts error")? + .to_string(); + assert_eq!(a, b); + Ok(a) + }; + let good = facts.clone(); + facts.clear(); + assert_eq!(load_error(&facts)?, "missing block model state schema"); + facts = good.clone(); + facts.get_mut("minecraft:fixture_0000").unwrap()["schema"] = Value::Null; + assert_eq!(load_error(&facts)?, "invalid model schema"); + facts = good.clone(); + facts.get_mut("minecraft:fixture_0000").unwrap()["states"] + .as_array_mut() + .unwrap() + .reverse(); + assert_eq!( + load_error(&facts)?, + "model state definitions disagree with the imported block registry" + ); + fs::remove_file(fixture.root.join("model-states.json"))?; + // A parsed document remains usable without reopening its source file. + StateModels::from_facts( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default(), + &good, + )?; + assert!( + StateModels::load( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default() + ) + .is_err() + ); + fs::write(fixture.root.join("model-states.json"), b"null")?; + assert!( + StateModels::load( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default() + ) + .is_err() + ); + fs::write(fixture.root.join("model-states.json"), b"{")?; + assert!( + StateModels::load( + &fixture.root, + &fixture.registry, + &blocks, + &mut Sprites::default() + ) + .is_err() + ); + Ok(()) + } +} diff --git a/crates/horizon-client/src/models.rs b/crates/horizon-client/src/models.rs index b593c1f66..7d1419087 100644 --- a/crates/horizon-client/src/models.rs +++ b/crates/horizon-client/src/models.rs @@ -55,14 +55,14 @@ pub fn prepare( registry: &BlockRegistry, sprites: &mut Sprites, ) -> Result { - let facts: serde_json::Map = + let facts: std::collections::BTreeMap = serde_json::from_slice(&std::fs::read(root.join("model-states.json"))?)?; let blocks: Vec<&str> = facts .keys() .filter(|name| registry.default_state(name).is_some()) .filter_map(|name| name.strip_prefix("minecraft:")) .collect(); - let catalog = StateModels::load(root, registry, &blocks, sprites)?; + let catalog = StateModels::from_facts(root, registry, &blocks, sprites, &facts)?; let mut placements = Vec::new(); let mut states = Vec::new(); for (index, (name, properties)) in GALLERY.iter().enumerate() { diff --git a/crates/horizon-client/src/models/catalog.rs b/crates/horizon-client/src/models/catalog.rs index d39d19a49..53a035b4d 100644 --- a/crates/horizon-client/src/models/catalog.rs +++ b/crates/horizon-client/src/models/catalog.rs @@ -57,6 +57,16 @@ impl StateModels { ) -> Result { let facts: BTreeMap = serde_json::from_slice(&fs::read(root.join("model-states.json"))?)?; + Self::from_facts(root, registry, blocks, sprites, &facts) + } + /// Bind and bake models using an already parsed model-state document. + pub fn from_facts( + root: &Path, + registry: &BlockRegistry, + blocks: &[&str], + sprites: &mut Sprites, + facts: &BTreeMap, + ) -> Result { let mut choices = Vec::new(); let mut states = BTreeMap::new(); let mut variants = BTreeSet::new(); From cb28f691ffedefcf4a125de7dd53c21a1691ec5a Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:09:18 +0100 Subject: [PATCH 09/97] perf: return only lighting from chunk light workers --- crates/horizon-client/examples/chunk_bench.rs | 4 +- .../horizon-client/examples/light_parity.rs | 10 +- .../horizon-client/examples/mob_ai_probe.rs | 4 +- crates/horizon-client/examples/save_parity.rs | 4 +- crates/horizon-client/src/chunk.rs | 14 +- crates/horizon-client/src/light.rs | 240 ++++++++++++++++-- crates/horizon-client/src/streaming.rs | 10 +- docs/performance/lighting-worker-results.md | 56 ++++ 8 files changed, 299 insertions(+), 43 deletions(-) create mode 100644 docs/performance/lighting-worker-results.md diff --git a/crates/horizon-client/examples/chunk_bench.rs b/crates/horizon-client/examples/chunk_bench.rs index be60496f0..0d4a71ce6 100644 --- a/crates/horizon-client/examples/chunk_bench.rs +++ b/crates/horizon-client/examples/chunk_bench.rs @@ -9,7 +9,7 @@ use horizon_client::{ biome::Biomes, blocks::BlockFacts, chunk::{Chunk, MIN_Y, SECTIONS}, - light::{LightTables, light_chunk}, + light::{LightTables, apply_lighting, light_chunk}, mesher::{MeshTables, Mesher}, models, streaming::{ChunkGenerator, Proto}, @@ -105,7 +105,7 @@ fn main() -> Result<()> { ); let mut chunks: Vec = chunks.iter().map(|c| (**c).clone()).collect(); for ((x, z), sections) in lit { - chunks[((z - 1) * inner + x - 1) as usize].sections = sections; + apply_lighting(&mut chunks[((z - 1) * inner + x - 1) as usize], sections); } let chunks: Vec> = chunks.into_iter().map(Arc::new).collect(); let at = |x: i32, z: i32| chunks[((z - 1) * inner + x - 1) as usize].clone(); diff --git a/crates/horizon-client/examples/light_parity.rs b/crates/horizon-client/examples/light_parity.rs index 2307c6da1..afc3e3156 100644 --- a/crates/horizon-client/examples/light_parity.rs +++ b/crates/horizon-client/examples/light_parity.rs @@ -9,7 +9,7 @@ use horizon_client::{ biome::Biomes, blocks::BlockFacts, chunk::{Chunk, MIN_Y, SECTIONS, index}, - light::{LightTables, light_chunk}, + light::{LightTables, apply_lighting, light_chunk}, save, }; use horizon_core::position::ChunkPos; @@ -101,7 +101,7 @@ fn main() -> horizon_client::Result<()> { .unwrap_or((None, None)); let nib = |a: &Option>| a.as_ref().map(|a| (a[i >> 1] >> ((i & 1) * 4)) & 15); let id = chunks[&(x, z)].get(wx & 15, wy, wz & 15); - let packed = lit[si].light(i); + let packed = lit[si].get(i); println!( "{wy}: {} horizon sky {} block {} vanilla sky {:?} block {:?}", facts.states[id as usize].name, @@ -157,7 +157,7 @@ fn main() -> horizon_client::Result<()> { .map_or(15, |a| (a[(i & 255) >> 1] >> ((i & 1) * 4)) & 15), }; let vb = nibble(&block, 0); - let packed = section.light(i); + let packed = section.get(i); let (hs, hb) = (packed >> 4, packed & 15); total += 1; if hs != vs { @@ -228,7 +228,7 @@ fn incremental( std::array::from_fn(|dx| chunks.get(&(x + dx as i32 - 1, z + dz as i32 - 1))) }); let mut c = chunks[&(x, z)].clone(); - c.sections = light_chunk(®ion, tables, sky_light); + apply_lighting(&mut c, light_chunk(®ion, tables, sky_light)); c.lit = true; world.insert((x, z), Arc::new(c)); } @@ -299,7 +299,7 @@ fn incremental( let full = light_chunk(®ion, tables, sky_light); for (si, s) in full.iter().enumerate() { for i in 0..4096 { - let (a, b) = (s.light(i), world[&(kx, kz)].sections[si].light(i)); + let (a, b) = (s.get(i), world[&(kx, kz)].sections[si].light(i)); if a != b { bad += 1; if bad < 20 { diff --git a/crates/horizon-client/examples/mob_ai_probe.rs b/crates/horizon-client/examples/mob_ai_probe.rs index 1645bc01c..b33ebde49 100644 --- a/crates/horizon-client/examples/mob_ai_probe.rs +++ b/crates/horizon-client/examples/mob_ai_probe.rs @@ -11,7 +11,7 @@ use horizon_client::{ collisions, containers::{BlockEntity, CreakingHeart}, items::{ItemStack, Items}, - light::{LightTables, light_chunk}, + light::{LightTables, apply_lighting, light_chunk}, mobs::{ Damage, MobType, creaking, creaking_heart::{self, HeartEvent, HeartHost}, @@ -779,7 +779,7 @@ fn main() -> horizon_client::Result<()> { }) }); let mut c = (*world.chunks[&(x, z)]).clone(); - c.sections = light_chunk(®ion, &tables, true); + apply_lighting(&mut c, light_chunk(®ion, &tables, true)); c.lit = true; ((x, z), c) }) diff --git a/crates/horizon-client/examples/save_parity.rs b/crates/horizon-client/examples/save_parity.rs index 017f60294..ba2c4b0fa 100644 --- a/crates/horizon-client/examples/save_parity.rs +++ b/crates/horizon-client/examples/save_parity.rs @@ -10,7 +10,7 @@ use horizon_client::{ biome::Biomes, blocks::BlockFacts, chunk::{Chunk, MIN_Y, SECTIONS}, - light::{LightTables, light_chunk}, + light::{LightTables, apply_lighting, light_chunk}, save::{self, SaveTables}, }; use horizon_core::position::ChunkPos; @@ -157,7 +157,7 @@ fn main() -> horizon_client::Result<()> { std::array::from_fn(|dx| chunks.get(&(x + dx as i32 - 1, z + dz as i32 - 1))) }); let mut chunk = chunks[&(x, z)].clone(); - chunk.sections = light_chunk(®ion, &lights, sky_light); + apply_lighting(&mut chunk, light_chunk(®ion, &lights, sky_light)); chunk.lit = true; let ours = save::encode_with(&chunk, assets.registry, &biomes, Some(&tables), sky_light); let theirs = &originals[&(x, z)]; diff --git a/crates/horizon-client/src/chunk.rs b/crates/horizon-client/src/chunk.rs index 01147dea5..4e0936a05 100644 --- a/crates/horizon-client/src/chunk.rs +++ b/crates/horizon-client/src/chunk.rs @@ -20,6 +20,15 @@ pub enum Light { Uniform(u8), Full(Box<[u8; 4096]>), } +impl Light { + #[inline] + pub fn get(&self, i: usize) -> u8 { + match self { + Self::Uniform(v) => *v, + Self::Full(a) => a[i], + } + } +} #[inline] pub fn index(x: i32, y: i32, z: i32) -> usize { ((y & 15) << 8 | (z & 15) << 4 | (x & 15)) as usize @@ -59,10 +68,7 @@ impl Section { } #[inline] pub fn light(&self, i: usize) -> u8 { - match &self.light { - Light::Uniform(v) => *v, - Light::Full(a) => a[i], - } + self.light.get(i) } pub fn is_uniform(&self, v: u16) -> bool { self.blocks.is_uniform(u32::from(v)) diff --git a/crates/horizon-client/src/light.rs b/crates/horizon-client/src/light.rs index ae53676c7..6e1a1fece 100644 --- a/crates/horizon-client/src/light.rs +++ b/crates/horizon-client/src/light.rs @@ -16,7 +16,7 @@ //! directly to resident chunks after a block change. use crate::{ blocks::BlockFacts, - chunk::{Chunk, HEIGHT, Light, MIN_Y, SECTIONS, Section, index}, + chunk::{Chunk, HEIGHT, Light, MIN_Y, SECTIONS, index}, }; use horizon_core::geometry::{Direction, ShapeOp, VoxelShape}; use horizon_world::registry::{BlockRegistry, BlockStateId}; @@ -195,8 +195,8 @@ pub fn light_chunk( region: &[[Option<&Chunk>; 3]; 3], tables: &LightTables, sky_light: bool, -) -> Vec> { - let center = region[1][1].expect("centre chunk"); +) -> Vec { + region[1][1].expect("centre chunk"); // Highest occupied section in the region bounds the work. let mut top_section = 0; for chunk in region.iter().flatten().flatten() { @@ -321,20 +321,22 @@ pub fn light_chunk( }; spread(&mut sky, &mut sky_queue); spread(&mut block, &mut queue); - let mut sections = Vec::with_capacity(SECTIONS); - for (si, section) in center.sections.iter().enumerate() { - let mut out = (**section).clone(); - let open = if sky_light { 0xF0 } else { 0x00 }; - if si * 16 >= h { - out.light = Light::Uniform(open); - } else { - let mut data = Box::new([0u8; 4096]); + pack_lighting(h, &sky, &block, sky_light) +} + +/// Extract just the centre column's light; never copy worker snapshot sections. +fn pack_lighting(h: usize, sky: &[u8], block: &[u8], sky_light: bool) -> Vec { + let at = |x: usize, y: usize, z: usize| (y * W + z) * W + x; + let open = if sky_light { 0xF0 } else { 0x00 }; + (0..SECTIONS) + .map(|si| { + if si * 16 >= h { + return Light::Uniform(open); + } + let mut data = Box::new([open; 4096]); for ly in 0..16 { let y = si * 16 + ly; if y >= h { - for i in 0..256 { - data[ly << 8 | i] = open; - } continue; } for lz in 0..16 { @@ -344,12 +346,21 @@ pub fn light_chunk( } } } - out.light = Light::Full(data); - } - out.compact(); - sections.push(Arc::new(out)); + if data.iter().all(|&v| v == data[0]) { + Light::Uniform(data[0]) + } else { + Light::Full(data) + } + }) + .collect() +} + +/// Move a worker's light into current sections, preserving later block/biome +/// edits and immutable snapshots retained by other workers. +pub fn apply_lighting(chunk: &mut Chunk, lights: Vec) { + for (section, light) in chunk.sections.iter_mut().zip(lights) { + Arc::make_mut(section).light = light; } - sections } /// Resident chunks the incremental relighter reads and writes. @@ -622,7 +633,7 @@ mod tests { std::array::from_fn(|dx| chunks.get(&(x + dx as i32 - 1, z + dz as i32 - 1))) }); let mut c = chunks[&(x, z)].clone(); - c.sections = light_chunk(®ion, &tables(), true); + apply_lighting(&mut c, light_chunk(®ion, &tables(), true)); c.lit = true; ((x, z), Arc::new(c)) }) @@ -691,11 +702,198 @@ mod tests { for (si, s) in full.iter().enumerate() { for i in 0..4096 { assert_eq!( - s.light(i), + s.get(i), w[&(0, 0)].sections[si].light(i), "section {si} index {i}" ); } } } + #[test] + fn lighting_result_preserves_current_edits_and_snapshots() { + let mut current = Chunk::empty(0, 0); + current.set(8, MIN_Y, 8, TORCH); + let region = [[None; 3], [None, Some(¤t), None], [None; 3]]; + let lights = light_chunk(®ion, &tables(), true); + let Light::Full(data) = &lights[0] else { + panic!("torch light varies"); + }; + let result_storage = data.as_ptr(); + let snapshot = current.clone(); + current.set(8, MIN_Y, 8, STONE); + Arc::make_mut(&mut current.sections[0]).biomes.set(0, 3); + let edited_snapshot = current.clone(); + apply_lighting(&mut current, lights); + let Light::Full(data) = ¤t.sections[0].light else { + panic!("torch light varies"); + }; + assert_eq!( + result_storage, + data.as_ptr(), + "returned light storage moves without cloning" + ); + current.lit = true; + assert_eq!(current.get(8, MIN_Y, 8), STONE); + assert_eq!(current.sections[0].biomes.get(0), 3); + assert_eq!(snapshot.get(8, MIN_Y, 8), TORCH); + assert_eq!(edited_snapshot.sections[0].light(index(8, MIN_Y, 8)), 0xF0); + let mut world = HashMap::from([((0, 0), Arc::new(current))]); + // Streaming replays edits made after the job snapshot with force=true. + relight(&mut world, &tables(), true, &[(8, MIN_Y, 8)], true); + let region = [[None; 3], [None, Some(&*world[&(0, 0)]), None], [None; 3]]; + let fresh = light_chunk(®ion, &tables(), true); + for (section, light) in world[&(0, 0)].sections.iter().zip(fresh) { + for i in 0..4096 { + assert_eq!(section.light(i), light.get(i)); + } + } + } + + #[test] + fn empty_chunk_missing_neighbours_and_no_sky() { + let mut chunk = Chunk::empty(0, 0); + for sky in [false, true] { + let region = [[None; 3], [None, Some(&chunk), None], [None; 3]]; + let lights = light_chunk(®ion, &tables(), sky); + assert_eq!(lights.len(), SECTIONS); + assert!( + lights + .iter() + .all(|v| matches!(v, Light::Uniform(n) if *n == if sky { 0xF0 } else { 0 })) + ); + let section = Arc::as_ptr(&chunk.sections[0]); + apply_lighting(&mut chunk, lights); + assert_eq!(section, Arc::as_ptr(&chunk.sections[0])); + } + } + + // Original main's worker packaging and streaming application. Kept here + // so the benchmark compares the real former copy/compaction work. + fn baseline_pack( + center: &Chunk, + h: usize, + sky: &[u8], + block: &[u8], + ) -> Vec> { + let at = |x: usize, y: usize, z: usize| (y * W + z) * W + x; + let mut sections = Vec::with_capacity(SECTIONS); + for (si, section) in center.sections.iter().enumerate() { + let mut out = (**section).clone(); + if si * 16 >= h { + out.light = Light::Uniform(0xF0); + } else { + let mut data = Box::new([0u8; 4096]); + for ly in 0..16 { + let y = si * 16 + ly; + if y >= h { + for i in 0..256 { + data[ly << 8 | i] = 0xF0; + } + continue; + } + for lz in 0..16 { + for lx in 0..16 { + let p = at(16 + lx, y, 16 + lz); + data[index(lx as i32, ly as i32, lz as i32)] = sky[p] << 4 | block[p]; + } + } + } + out.light = Light::Full(data); + } + out.compact(); + sections.push(Arc::new(out)); + } + sections + } + fn baseline_apply(chunk: &mut Chunk, sections: Vec>) { + for (target, lit) in chunk.sections.iter_mut().zip(sections) { + let mut section = (**target).clone(); + section.light = lit.light.clone(); + *target = Arc::new(section); + } + } + + #[test] + #[ignore = "microbenchmark; run with --ignored --nocapture"] + fn benchmark_worker_light_results() { + use std::{hint::black_box, time::Instant}; + let mut fixture = Chunk::empty(0, 0); + for (si, s) in fixture.sections.iter_mut().enumerate() { + let section = Arc::make_mut(s); + for i in 0..4096 { + section.set(i, ((i + si) % 16) as u16); + } + for i in 0..64 { + section.biomes.set(i, (i % 4) as u32); + } + section.light = Light::Full(Box::new([0x87; 4096])); + } + let h = HEIGHT as usize; + let sky: Vec<_> = (0..W * W * h).map(|i| (i % 16) as u8).collect(); + let block: Vec<_> = (0..W * W * h).map(|i| ((i / 16) % 16) as u8).collect(); + let mut old = fixture.clone(); + let mut new = fixture.clone(); + baseline_apply(&mut old, baseline_pack(&fixture, h, &sky, &block)); + apply_lighting(&mut new, pack_lighting(h, &sky, &block, true)); + for (a, b) in old.sections.iter().zip(&new.sections) { + for i in 0..4096 { + assert_eq!(a.light(i), b.light(i)); + assert_eq!(a.get(i), b.get(i)); + } + for i in 0..64 { + assert_eq!(a.biomes.get(i), b.biomes.get(i)); + } + } + for shared in [false, true] { + let mut times = [Vec::new(), Vec::new()]; + for round in 0..11 { + for optimized in [round % 2 == 0, round % 2 != 0] { + let mut current = fixture.clone(); + let held = shared.then(|| current.clone()); + // Warm up and detach for the uniquely-owned scenario. + apply_lighting(&mut current, pack_lighting(h, &sky, &block, true)); + let started = Instant::now(); + for _ in 0..500 { + let retained = shared.then(|| current.clone()); + if optimized { + apply_lighting( + black_box(&mut current), + pack_lighting(h, black_box(&sky), black_box(&block), true), + ); + } else { + baseline_apply( + black_box(&mut current), + baseline_pack( + black_box(&fixture), + h, + black_box(&sky), + black_box(&block), + ), + ); + } + black_box(retained); + black_box(¤t); + } + if round > 0 { + times[usize::from(optimized)] + .push(started.elapsed().as_secs_f64() * 1e6 / 500.0); + } + black_box(held); + } + } + for values in &mut times { + values.sort_by(f64::total_cmp); + } + println!( + "pack+apply shared={shared}: baseline {:.3} us optimized {:.3} us speedup {:.2}x", + times[0][5], + times[1][5], + times[0][5] / times[1][5] + ); + } + let payload: usize = fixture.sections.iter().map(|s| s.heap_bytes()).sum(); + println!( + "fixture heap payload {payload} bytes; old worker clones it plus 24 section Arcs; old application clones current payload and 98304 returned light bytes. New worker clones zero section payload; new application clones current payload only when shared." + ); + } } diff --git a/crates/horizon-client/src/streaming.rs b/crates/horizon-client/src/streaming.rs index 4d9bac937..299b153dc 100644 --- a/crates/horizon-client/src/streaming.rs +++ b/crates/horizon-client/src/streaming.rs @@ -5,7 +5,7 @@ use crate::fast_hash::{FxHashMap, FxHashSet}; use crate::{ chunk::{Chunk, SECTIONS}, - light::{LightTables, light_chunk}, + light::{LightTables, apply_lighting, light_chunk}, mesher::{MeshTables, Mesher, Region, SectionMesh, borrow}, world::World, }; @@ -63,7 +63,7 @@ pub enum Done { Generated(Chunk), Proto(i32, i32, Proto), Decorated(i32, i32, Box<[Proto; 9]>), - Lit(i32, i32, Vec>, u64), + Lit(i32, i32, Vec, u64), Meshed(i32, i32, i32, SectionMesh, u64), } struct Queued { @@ -426,11 +426,7 @@ impl Streaming { if let Some(chunk) = world.chunks.get_mut(&(x, z)) { let chunk = Arc::make_mut(chunk); // Keep blocks edited since the snapshot; take only light. - for (target, lit) in chunk.sections.iter_mut().zip(sections) { - let mut section = (**target).clone(); - section.light = lit.light.clone(); - *target = Arc::new(section); - } + apply_lighting(chunk, sections); chunk.lit = true; self.lit.insert((x, z)); self.replay_light_edits(world, x, z, snapshot); diff --git a/docs/performance/lighting-worker-results.md b/docs/performance/lighting-worker-results.md new file mode 100644 index 000000000..7c52b1276 --- /dev/null +++ b/docs/performance/lighting-worker-results.md @@ -0,0 +1,56 @@ +# Lighting worker result packaging + +`light_chunk` now returns only `Vec`. `apply_lighting` moves each light +into the current section through `Arc::make_mut`, preserving current block and +biome edits and snapshots held by other workers. Streaming still rejects stale +sequences before applying results and replays edits after applying valid light. +All direct examples use the same application function. + +## Reproduce + +```sh +CARGO_INCREMENTAL=0 CARGO_TARGET_DIR=/home/bob/Documents/horizon/target cargo test -p horizon-client --lib --profile fast benchmark_worker_light_results -- --ignored --nocapture +``` + +The ignored test invokes the production `pack_lighting` and `apply_lighting` +functions and compares them to original main's packaging/application loops. +It checks every resulting block, biome, and light value before timing. Each +measurement uses 500 columns per batch, one discarded warm-up batch, and ten +measured batches with alternating baseline/optimized order and `black_box`. +The reported median is the upper middle of the ten samples. Both implementations +receive identical precomputed propagation arrays. The fixture contains 24 +sections with 16-state block palettes, four-biome palettes, and existing full +light arrays. A second case retains a fresh snapshot each iteration to force +copy-on-write during application. Fixtures are synthetic, not loaded saves. + +AMD Ryzen 5 5600X, Linux x86_64, rustc 1.99.0, optimized `fast` profile, +nonincremental, no LTO: + +| Packaging + application | Original main | New | Speedup | +| --- | ---: | ---: | ---: | +| Sections uniquely owned | 63.948 us/column | 44.397 us/column | 1.44x | +| Snapshot retained | 65.332 us/column | 53.025 us/column | 1.23x | + +These measurements exclude propagation, region snapshot creation, outer chunk +copy-on-write, channels, replay, and remeshing. They establish savings in the +actual worker output/application paths, not a whole lighting runtime or FPS gain. + +## Copy and allocation scope + +`Section::heap_bytes` reports 149,760 bytes of fixture payload per column. +Original packaging clones that payload and allocates 24 section Arcs. Original +application clones the current section payload, allocates another 24 section +Arcs, and clones 98,304 bytes of returned light. New packaging clones no section +payload and allocates no section Arcs. New application moves the returned light; +with unique sections it clones no payload and allocates no section Arcs. With a +retained snapshot it still copies the current section payload and allocates 24 +Arcs, as required to preserve the snapshot. New light arrays and the result Vec +still allocate. These are structural copy/allocation observations, not global +allocator instrumentation; byte figures exclude Arc headers, Vec headers, and +allocator overhead. + +Focused tests cover moved light buffer identity, current block/biome edits, +retained snapshots, forced replay versus fresh full relighting, empty chunks, +missing neighbours, no-sky dimensions, light attenuation, occlusion, and +incremental/full equivalence. The stale-sequence guard and missing-current-chunk +handling in streaming are unchanged. From dd5a361a58753e4287f1f604a284f504a11664cb Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:48:32 +0100 Subject: [PATCH 10/97] bench(client): measure state reuse after slice reader changes --- benchmarks/model-state-parse-2026-10-14.md | 21 ++++++++++++------- .../examples/model_states_bench.rs | 6 +++--- 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/benchmarks/model-state-parse-2026-10-14.md b/benchmarks/model-state-parse-2026-10-14.md index ad04acc6f..15a50e8ff 100644 --- a/benchmarks/model-state-parse-2026-10-14.md +++ b/benchmarks/model-state-parse-2026-10-14.md @@ -3,8 +3,8 @@ `models::prepare` parsed `model-states.json` to select blocks, then `StateModels::load` reopened and parsed the same document for binding and baking. `StateModels::from_facts` now borrows the first parsed map. The public `load` -entry point still reads, parses and validates its own document. Neither path -changes the unbuffered `serde_json::from_reader(File)` strategy. +entry point still reads, parses and validates its own document. Both paths retain +the `fs::read` + `serde_json::from_slice` strategy merged in PR #205. The shared map uses `BTreeMap`, preserving the original catalog loader's JSON validation, including rejection of top-level `null`. The old selection map was @@ -15,10 +15,10 @@ cache or extra clones were added. ## Measurement -The committed `model_states_bench` example runs the original two-parse sequence +The committed `model_states_bench` example runs main's two-parse sequence after PR #205 (first a serde JSON map, then `StateModels::load`) and the new one-parse sequence (first a BTreeMap, then `StateModels::from_facts`). Both select blocks from the -same generated document and call the actual catalog binding/baking code. Timing +same generated document with slice parsing and call the actual catalog binding/baking code. Timing includes file reads, parsing, filtering, binding, baking and result destruction. Fixture generation and equality checks run outside the timed region. @@ -35,13 +35,19 @@ On AMD Ryzen 5 5600X, Linux 7.2.8-zen1-2-zen x86_64, rustc 1.99.0 | Path | Median (15 samples) | | --- | ---: | -| Before: parse twice | 2732.004 ms | -| After: reuse first parse | 1386.060 ms | +| Before: parse twice, with #205 slice readers | 96.080 ms | +| After: reuse first parse, with #205 slice readers | 73.585 ms | -**1.971x speedup; 49.27% less elapsed time** for this loading segment. Each path +**1.306x speedup; 23.41% less elapsed time** for this loading segment after PR #205. Each path has two warmups, sample order alternates, and inputs/results use `black_box`. This excludes gallery placements, GPU work and overall application startup. +These measurements supersede the original unbuffered-reader timings +(2732.004 ms → 1386.060 ms, 1.971x) after rebasing onto main at +`e96e1571`. The reviewer measured approximately 1.05x with real prepared resources; +the generated fixture's balance of parsing and binding differs from production. +The change still removes one complete document read, parse and JSON tree. + Equality validation compares every state's selected variants and baked geometry at three positions, plus sprite layers and opacity/translucency flags. The focused test also checks matching schema/registry errors, malformed/missing @@ -52,6 +58,7 @@ source file has been deleted. ```sh export CARGO_TARGET_DIR=/home/bob/Documents/horizon/target +export CARGO_INCREMENTAL=0 cargo run -p horizon-client --profile fast --example model_states_bench -- 15 cargo test -p horizon-client --profile fast --example model_states_bench cargo clippy -p horizon-client --all-targets --profile fast -- -D warnings diff --git a/crates/horizon-client/examples/model_states_bench.rs b/crates/horizon-client/examples/model_states_bench.rs index 884f59923..577ff649e 100644 --- a/crates/horizon-client/examples/model_states_bench.rs +++ b/crates/horizon-client/examples/model_states_bench.rs @@ -79,7 +79,7 @@ impl Fixture { }) } fn facts(&self) -> Result> { - Ok(serde_json::from_reader(fs::File::open( + Ok(serde_json::from_slice(&fs::read( self.root.join("model-states.json"), )?)?) } @@ -98,7 +98,7 @@ impl Fixture { StateModels::from_facts(&self.root, &self.registry, &blocks, &mut sprites, &facts)? } else { let facts: serde_json::Map = - serde_json::from_reader(fs::File::open(self.root.join("model-states.json"))?)?; + serde_json::from_slice(&fs::read(self.root.join("model-states.json"))?)?; let blocks = self.block_names(facts.keys()); StateModels::load(&self.root, &self.registry, &blocks, &mut sprites)? }; @@ -165,7 +165,7 @@ fn main() -> Result<()> { let mut before = Vec::new(); let mut after = Vec::new(); for iteration in 0..repetitions { - // Alternate order to limit cache/order bias. File reads remain unbuffered. + // Alternate order to limit cache/order bias. Both paths use slice parsing. for reuse in if iteration % 2 == 0 { [false, true] } else { From 8177726f70d57e1a3485c5db582d1b8a83435c42 Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:47:08 +0100 Subject: [PATCH 11/97] perf: reuse validated resource-pack overlays --- Cargo.lock | 3 + crates/horizon-client/Cargo.toml | 2 + crates/horizon-client/src/packs.rs | 30 +- crates/horizon-client/src/packs/cache.rs | 911 +++++++++++++++++++++++ docs/reuse-pack-overlays.md | 69 ++ 5 files changed, 1014 insertions(+), 1 deletion(-) create mode 100644 crates/horizon-client/src/packs/cache.rs create mode 100644 docs/reuse-pack-overlays.md diff --git a/Cargo.lock b/Cargo.lock index 0753fc7d0..0e0f15c62 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -918,7 +918,9 @@ dependencies = [ "naga", "png", "pollster", + "serde", "serde_json", + "sha2", "symphonia", "ureq", "wgpu", @@ -2313,6 +2315,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" dependencies = [ "serde_core", + "serde_derive", ] [[package]] diff --git a/crates/horizon-client/Cargo.toml b/crates/horizon-client/Cargo.toml index 12aeaae4a..f537bb415 100644 --- a/crates/horizon-client/Cargo.toml +++ b/crates/horizon-client/Cargo.toml @@ -18,6 +18,8 @@ pollster = "0.4" bytemuck = { version = "1.24", features = ["derive"] } glam = "0.30" png = "0.18" +sha2 = "0.10.9" +serde = { version = "1", features = ["derive"] } serde_json = { version = "1.0.151", features = ["raw_value"] } cpal = "0.16" symphonia = { version = "0.5", default-features = false, features = ["ogg", "vorbis"] } diff --git a/crates/horizon-client/src/packs.rs b/crates/horizon-client/src/packs.rs index 2dee3206e..917bad561 100644 --- a/crates/horizon-client/src/packs.rs +++ b/crates/horizon-client/src/packs.rs @@ -3,6 +3,7 @@ //! and High Contrast packs, `pack.mcmeta` metadata and format compatibility, //! and an overlay resource root that layers the enabled packs over the //! vanilla resources (later packs win), so every loader sees one tree. +mod cache; pub mod pattern; use crate::text::Style; use crate::{text::Text, zip::Zip}; @@ -381,6 +382,15 @@ fn link(target: &Path, at: &Path) -> io::Result<()> { /// Build `out` as `vanilla` with the packs' files layered on top (packs in /// load order, last wins). Untouched directories are symlinks into vanilla. pub fn build_overlay(vanilla: &Path, packs: &[Pack], out: &Path) -> io::Result<()> { + cache::build(vanilla, packs, out) +} + +fn build_overlay_uncached( + vanilla: &Path, + packs: &[Pack], + out: &Path, + dependencies: &mut cache::Dependencies, +) -> io::Result<()> { if out.exists() { fs::remove_dir_all(out)?; } @@ -426,6 +436,7 @@ pub fn build_overlay(vanilla: &Path, packs: &[Pack], out: &Path) -> io::Result<( let mut merged: BTreeMap> = BTreeMap::new(); for (name, stack) in &stacks { let mut layers = Vec::new(); + dependencies.file(&vanilla.join(name)); if !filters.iter().any(|f| f.blocks(name)) && let Ok(bytes) = fs::read(vanilla.join(name)) { @@ -457,6 +468,7 @@ pub fn build_overlay(vanilla: &Path, packs: &[Pack], out: &Path) -> io::Result<( merged: &BTreeMap>, filters: &[&Filter], zips: &[Option], + dependencies: &mut cache::Dependencies, ) -> io::Result<()> { let src = if rel.is_empty() { vanilla.to_path_buf() @@ -469,6 +481,7 @@ pub fn build_overlay(vanilla: &Path, packs: &[Pack], out: &Path) -> io::Result<( out.join(rel) }; fs::create_dir_all(&dst)?; + dependencies.directory(&src); let mut names: BTreeSet = BTreeSet::new(); if let Ok(entries) = fs::read_dir(&src) { names.extend( @@ -502,10 +515,24 @@ pub fn build_overlay(vanilla: &Path, packs: &[Pack], out: &Path) -> io::Result<( } else if touched.contains(&child) || (vanilla.join(&child).is_dir() && !filters.is_empty()) { - mirror(&child, vanilla, out, touched, files, merged, filters, zips)?; + mirror( + &child, + vanilla, + out, + touched, + files, + merged, + filters, + zips, + dependencies, + )?; } else if filters.iter().any(|f| f.blocks(&child)) { // Hidden by a pack's filter. } else { + #[cfg(not(unix))] + if vanilla.join(&child).is_file() { + dependencies.file(&vanilla.join(&child)); + } link(&vanilla.join(&child), &out.join(&child))?; } } @@ -520,6 +547,7 @@ pub fn build_overlay(vanilla: &Path, packs: &[Pack], out: &Path) -> io::Result<( &merged, &filters, &zips, + dependencies, ) } /// Files vanilla loads from every pack in turn (`getResourceStack`) rather diff --git a/crates/horizon-client/src/packs/cache.rs b/crates/horizon-client/src/packs/cache.rs new file mode 100644 index 000000000..a49f9f704 --- /dev/null +++ b/crates/horizon-client/src/packs/cache.rs @@ -0,0 +1,911 @@ +//! Content-validated overlay reuse. Live symlink files/subtrees need no content +//! scan; merged, extracted and copied bytes do. Topology and link targets are +//! always checked, including vanilla directories materialized by mirror. +use super::{Pack, Source, build_overlay_uncached}; +use serde::{Deserialize, Serialize}; +use sha2::{Digest, Sha256}; +use std::{collections::BTreeSet, fs, io, io::Read, path::Path, path::PathBuf}; + +// Bump when overlay/merge semantics change. Markers are disposable cache data. +const VERSION: u32 = 1; + +#[derive(Default, Serialize, Deserialize)] +pub(super) struct Dependencies { + entries: Vec<(PathBuf, bool, String)>, + #[serde(skip)] + failed: bool, + #[serde(skip)] + tracking: bool, +} +impl Dependencies { + fn record(&mut self, path: &Path, directory: bool) { + if !self.tracking { + return; + } + match dependency_signature(path, directory) { + Ok(signature) => self.entries.push((path.into(), directory, signature)), + Err(_) => self.failed = true, + } + } + pub(super) fn file(&mut self, path: &Path) { + self.record(path, false); + } + pub(super) fn directory(&mut self, path: &Path) { + self.record(path, true); + } + fn valid(&self) -> bool { + !self.failed + && self.entries.iter().all(|(path, directory, signature)| { + dependency_signature(path, *directory).is_ok_and(|s| s == *signature) + }) + } +} + +#[derive(Serialize, Deserialize)] +struct Marker { + version: u32, + vanilla: PathBuf, + packs: String, + dependencies: Dependencies, + output: String, +} + +fn finish(hash: Sha256) -> String { + format!("{:x}", hash.finalize()) +} +// Length framing keeps distinct paths/configurations unambiguous. +fn field(hash: &mut Sha256, bytes: &[u8]) { + hash.update((bytes.len() as u64).to_le_bytes()); + hash.update(bytes); +} +fn content(hash: &mut Sha256, path: &Path) -> io::Result<()> { + let mut file = fs::File::open(path)?; + hash.update(file.metadata()?.len().to_le_bytes()); + let mut buffer = [0; 64 * 1024]; + loop { + let n = file.read(&mut buffer)?; + if n == 0 { + break; + } + hash.update(&buffer[..n]); + } + Ok(()) +} +fn entries(path: &Path) -> io::Result> { + let mut entries = fs::read_dir(path)? + .map(|e| e.map(|e| e.path())) + .collect::>>()?; + entries.sort(); + Ok(entries) +} +fn dependency_signature(path: &Path, directory: bool) -> io::Result { + let mut hash = Sha256::new(); + match fs::metadata(path) { + Err(e) if e.kind() == io::ErrorKind::NotFound => field(&mut hash, b"missing"), + Err(e) => return Err(e), + Ok(meta) if directory && meta.is_dir() => { + field(&mut hash, b"directory"); + for entry in entries(path)? { + field(&mut hash, entry.file_name().unwrap().as_encoded_bytes()); + // mirror's decisions use the followed file type, including symlinks. + field(&mut hash, &[u8::from(entry.is_dir())]); + } + } + Ok(_) if directory => field(&mut hash, b"not-directory"), + Ok(_) => content(&mut hash, path)?, + } + Ok(finish(hash)) +} +fn tree(hash: &mut Sha256, path: &Path, pack: Option<&Pack>) -> io::Result<()> { + tree_inner(hash, path, pack, &mut BTreeSet::new()) +} + +fn needs_content(path: &Path, pack: Option<&Pack>) -> bool { + let Some(pack) = pack.filter(|_| cfg!(unix)) else { + return true; + }; + let Source::Dir(root) = &pack.source else { + return true; + }; + let relative = path + .strip_prefix(root) + .unwrap() + .to_string_lossy() + .replace('\\', "/"); + // Ordinary folder resources are live Unix file symlinks. Rewrites and + // replacements at that path are visible without rebuilding. Merged JSON + // and configuration bytes are materialized and need content validation. + relative == "pack.mcmeta" + || super::merge_kind(&relative).is_some() + || pack.overlays.iter().any(|overlay| { + path.strip_prefix(root.join(overlay.trim_end_matches('/'))) + .ok() + .is_some_and(|name| { + super::merge_kind(&name.to_string_lossy().replace('\\', "/")).is_some() + }) + }) +} +fn tree_inner( + hash: &mut Sha256, + path: &Path, + pack: Option<&Pack>, + active: &mut BTreeSet, +) -> io::Result<()> { + let meta = fs::symlink_metadata(path)?; + if meta.is_symlink() { + field(hash, b"link"); + field(hash, fs::read_link(path)?.as_os_str().as_encoded_bytes()); + if pack.is_none() { + return Ok(()); + } + } + if path.is_dir() { + let canonical = if pack.is_some() { + let canonical = fs::canonicalize(path)?; + if !active.insert(canonical.clone()) { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "pack symlink cycle", + )); + } + Some(canonical) + } else { + None + }; + field(hash, b"directory"); + for entry in entries(path)? { + field(hash, entry.file_name().unwrap().as_encoded_bytes()); + tree_inner(hash, &entry, pack, active)?; + } + field(hash, b"end-directory"); + if let Some(canonical) = canonical { + active.remove(&canonical); + } + } else { + field(hash, b"file"); + if needs_content(path, pack) { + content(hash, path)?; + } + } + Ok(()) +} +fn output_signature(out: &Path) -> io::Result { + let mut hash = Sha256::new(); + tree(&mut hash, out, None)?; + Ok(finish(hash)) +} +fn pack_signature(packs: &[Pack]) -> io::Result { + let mut hash = Sha256::new(); + field(&mut hash, &[u8::from(cfg!(unix))]); + for pack in packs { + if matches!(pack.source, Source::Dir(_)) + && pack.overlays.iter().any(|overlay| { + Path::new(overlay).components().any(|component| { + matches!( + component, + std::path::Component::ParentDir + | std::path::Component::RootDir + | std::path::Component::Prefix(_) + ) + }) + }) + { + // The builder historically accepts external overlay roots. Preserve + // that behavior, but don't cache dependencies outside this pack tree. + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + "external pack overlay", + )); + } + field(&mut hash, pack.id.as_bytes()); + // Includes source kind/path, overlay order and compiled filter settings. + field(&mut hash, format!("{:?}", pack.source).as_bytes()); + field(&mut hash, format!("{:?}", pack.overlays).as_bytes()); + field(&mut hash, format!("{:?}", pack.filter).as_bytes()); + match &pack.source { + Source::Dir(path) => tree(&mut hash, path, Some(pack))?, + Source::Zip(path) => content(&mut hash, path)?, + } + } + Ok(finish(hash)) +} + +pub(super) fn marker_path(out: &Path) -> PathBuf { + // Outside the resource tree: no resource-name collisions or mirror changes. + let mut name = out.as_os_str().to_os_string(); + name.push(".overlay-cache.json"); + PathBuf::from(name) +} + +fn absolute(path: &Path) -> io::Result { + if path.is_absolute() { + Ok(path.into()) + } else { + std::env::current_dir().map(|cwd| cwd.join(path)) + } +} + +fn lock_path(out: &Path) -> PathBuf { + marker_path(out).with_extension("lock") +} + +pub(super) fn build(vanilla: &Path, packs: &[Pack], out: &Path) -> io::Result<()> { + if let Some(parent) = out.parent().filter(|p| !p.as_os_str().is_empty()) { + fs::create_dir_all(parent)?; + } + // Keep this inode persistent: deleting it would let waiters and new callers + // acquire different locks. Closing the file releases the advisory OS lock. + let lock = fs::OpenOptions::new() + .read(true) + .write(true) + .create(true) + .truncate(false) + .open(lock_path(out))?; + lock.lock()?; + // Absolute paths also prevent cwd changes from reusing relative symlinks. + // Keep root symlink aliases live, as mirror does for individual resources. + let vanilla = absolute(vanilla)?; + let packs: Vec = packs + .iter() + .map(|pack| { + let mut pack = pack.clone(); + match &mut pack.source { + Source::Dir(path) | Source::Zip(path) => { + *path = absolute(path)?; + } + } + Ok(pack) + }) + .collect::>()?; + let marker_path = marker_path(out); + let signature = pack_signature(&packs); + if let Ok(signature) = &signature + && let Ok(bytes) = fs::read(&marker_path) + && let Ok(marker) = serde_json::from_slice::(&bytes) + && marker.version == VERSION + && marker.vanilla == vanilla + && marker.packs == *signature + && marker.dependencies.valid() + && output_signature(out).is_ok_and(|s| s == marker.output) + { + return Ok(()); + } + // An interrupted/failed rebuild must never leave a reusable marker. + match fs::remove_file(&marker_path) { + Ok(()) => {} + Err(e) if e.kind() == io::ErrorKind::NotFound => {} + Err(e) => return Err(e), + } + let mut dependencies = Dependencies { + tracking: signature.is_ok(), + ..Dependencies::default() + }; + build_overlay_uncached(&vanilla, &packs, out, &mut dependencies)?; + if let Ok(signature) = signature + && dependencies.valid() + && pack_signature(&packs).is_ok_and(|s| s == signature) + { + let marker = Marker { + version: VERSION, + vanilla, + packs: signature, + dependencies, + output: output_signature(out)?, + }; + // PathBuf serialization requires UTF-8; unusual resource root names + // can still build normally without a reusable marker. + let Ok(bytes) = serde_json::to_vec(&marker) else { + return Ok(()); + }; + // Publish only a complete marker, after all output writes succeeded. + let temporary = marker_path.with_extension("tmp"); + fs::write(&temporary, bytes)?; + fs::rename(&temporary, &marker_path)?; + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::{packs, text::Text}; + use std::sync::atomic::{AtomicUsize, Ordering}; + + struct Fixture(PathBuf); + impl Fixture { + fn new() -> Self { + static NEXT: AtomicUsize = AtomicUsize::new(0); + let path = std::env::temp_dir().join(format!( + "horizon-overlay-cache-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); + let _ = fs::remove_dir_all(&path); + fs::create_dir_all(&path).unwrap(); + Self(path) + } + fn write(&self, name: &str, bytes: &[u8]) { + let path = self.0.join(name); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(path, bytes).unwrap(); + } + fn dir_pack(&self, name: &str) -> Pack { + self.write( + &format!("{name}/pack.mcmeta"), + br#"{"pack":{"description":"test","pack_format":97}}"#, + ); + packs::pack(name.into(), Text::empty(), Source::Dir(self.0.join(name))).unwrap() + } + fn rebuild_matches(&self, selected: &[Pack]) { + let vanilla = self.0.join("vanilla"); + let cached = self.0.join("cached"); + packs::build_overlay(&vanilla, selected, &cached).unwrap(); + build_overlay_uncached( + &vanilla, + selected, + &self.0.join("reference"), + &mut Dependencies::default(), + ) + .unwrap(); + assert_eq!( + output_signature(&cached).unwrap(), + output_signature(&self.0.join("reference")).unwrap() + ); + } + } + impl Drop for Fixture { + fn drop(&mut self) { + let _ = fs::remove_dir_all(&self.0); + } + } + + // Stored/deflated ZIP fixture using the production reader, no zip dependency. + fn archive(files: &[(&str, Vec)], deflate: bool) -> Vec { + let mut out = Vec::new(); + let mut central = Vec::new(); + for (name, body) in files { + let data = if deflate { + miniz_oxide::deflate::compress_to_vec(body, 6) + } else { + body.clone() + }; + let offset = out.len() as u32; + out.extend(0x0403_4b50u32.to_le_bytes()); + out.extend([20, 0, 0, 0]); + out.extend((if deflate { 8u16 } else { 0 }).to_le_bytes()); + out.extend([0; 8]); + out.extend((data.len() as u32).to_le_bytes()); + out.extend((body.len() as u32).to_le_bytes()); + out.extend((name.len() as u16).to_le_bytes()); + out.extend(0u16.to_le_bytes()); + out.extend(name.as_bytes()); + out.extend(&data); + central.extend(0x0201_4b50u32.to_le_bytes()); + central.extend([20, 0, 20, 0, 0, 0]); + central.extend((if deflate { 8u16 } else { 0 }).to_le_bytes()); + central.extend([0; 8]); + central.extend((data.len() as u32).to_le_bytes()); + central.extend((body.len() as u32).to_le_bytes()); + central.extend((name.len() as u16).to_le_bytes()); + central.extend([0; 12]); + central.extend(offset.to_le_bytes()); + central.extend(name.as_bytes()); + } + let start = out.len() as u32; + out.extend(¢ral); + out.extend(0x0605_4b50u32.to_le_bytes()); + out.extend([0; 4]); + out.extend((files.len() as u16).to_le_bytes()); + out.extend((files.len() as u16).to_le_bytes()); + out.extend((central.len() as u32).to_le_bytes()); + out.extend(start.to_le_bytes()); + out.extend([0; 2]); + out + } + + #[test] + fn directory_inputs_config_and_output_invalidate() { + let f = Fixture::new(); + let resource = "assets/minecraft/lang/en_us.json"; + f.write(&format!("vanilla/{resource}"), br#"{"v":"a"}"#); + f.write("vanilla/assets/minecraft/textures/untouched/a", b"live"); + let mut low = f.dir_pack("low"); + let high = f.dir_pack("high"); + f.write(&format!("low/{resource}"), br#"{"p":"a"}"#); + f.write(&format!("high/{resource}"), br#"{"p":"b"}"#); + f.rebuild_matches(&[low.clone(), high.clone()]); + let out = f.0.join("cached"); + let marker = marker_path(&out); + // A hit keeps the actual merged file (and marker) in place. + let time = fs::metadata(out.join(resource)) + .unwrap() + .modified() + .unwrap(); + let marker_time = fs::metadata(&marker).unwrap().modified().unwrap(); + f.rebuild_matches(&[low.clone(), high.clone()]); + assert_eq!( + fs::metadata(out.join(resource)) + .unwrap() + .modified() + .unwrap(), + time + ); + assert_eq!( + fs::metadata(&marker).unwrap().modified().unwrap(), + marker_time + ); + // Same-length rewrites cannot hide behind file size or preserved mtime. + let path = f.0.join(format!("high/{resource}")); + let original_time = fs::metadata(&path).unwrap().modified().unwrap(); + fs::write(&path, br#"{"p":"c"}"#).unwrap(); + fs::File::open(path) + .unwrap() + .set_times(fs::FileTimes::new().set_modified(original_time)) + .unwrap(); + f.rebuild_matches(&[low.clone(), high.clone()]); + f.write(&format!("vanilla/{resource}"), br#"{"v":"b"}"#); + f.rebuild_matches(&[low.clone(), high.clone()]); + f.write("vanilla/assets/minecraft/lang/new.json", b"new"); + f.rebuild_matches(&[low.clone(), high.clone()]); + fs::remove_file(f.0.join("vanilla/assets/minecraft/lang/new.json")).unwrap(); + f.rebuild_matches(&[low.clone(), high.clone()]); + f.write("high/assets/minecraft/lang/added.json", br#"{"a":1}"#); + f.rebuild_matches(&[low.clone(), high.clone()]); + fs::remove_file(f.0.join("high/assets/minecraft/lang/added.json")).unwrap(); + f.rebuild_matches(&[low.clone(), high.clone()]); + f.rebuild_matches(&[high.clone(), low.clone()]); + f.rebuild_matches(std::slice::from_ref(&low)); + low.overlays.push("extra".into()); + f.write(&format!("low/extra/{resource}"), br#"{"p":"overlay"}"#); + f.rebuild_matches(std::slice::from_ref(&low)); + low.filter = packs::filter_of(&serde_json::json!({"filter":{"block":[{"path":"lang"}]}})); + f.rebuild_matches(std::slice::from_ref(&low)); + fs::write(out.join(resource), b"corrupt").unwrap(); + f.rebuild_matches(std::slice::from_ref(&low)); + fs::remove_file(out.join(resource)).unwrap(); + f.rebuild_matches(std::slice::from_ref(&low)); + fs::write(&marker, b"corrupt").unwrap(); + f.rebuild_matches(std::slice::from_ref(&low)); + fs::remove_file(&marker).unwrap(); + f.rebuild_matches(std::slice::from_ref(&low)); + fs::remove_dir_all(&out).unwrap(); + f.rebuild_matches(std::slice::from_ref(&low)); + #[cfg(unix)] + { + low.filter.clear(); + f.rebuild_matches(std::slice::from_ref(&low)); + // Unrelated vanilla content remains live through the directory symlink. + let before = fs::read(&marker).unwrap(); + f.write("vanilla/assets/minecraft/textures/untouched/a", b"new live"); + f.write( + "vanilla/assets/minecraft/textures/untouched/b", + b"added live", + ); + f.rebuild_matches(std::slice::from_ref(&low)); + assert_eq!(fs::read(&marker).unwrap(), before); + assert_eq!( + fs::read(out.join("assets/minecraft/textures/untouched/b")).unwrap(), + b"added live" + ); + } + // Missing selected source disables reuse; the original directory builder + // still tolerates it, and does not publish a marker for an incomplete input. + fs::remove_dir_all(f.0.join("low")).unwrap(); + f.rebuild_matches(&[low]); + assert!(!marker.exists()); + } + + #[test] + fn zip_content_and_failed_build_invalidate() { + let f = Fixture::new(); + f.write("vanilla/facts.json", b"[]"); + let name = "assets/minecraft/textures/a"; + let files = |data: &[u8]| { + vec![ + ( + "pack.mcmeta", + br#"{"pack":{"description":"test","pack_format":97}}"#.to_vec(), + ), + (name, data.to_vec()), + ] + }; + f.write("pack.zip", &archive(&files(b"aaa"), false)); + let pack = packs::pack( + "zip".into(), + Text::empty(), + Source::Zip(f.0.join("pack.zip")), + ) + .unwrap(); + f.rebuild_matches(std::slice::from_ref(&pack)); + f.rebuild_matches(std::slice::from_ref(&pack)); + f.write("pack.zip", &archive(&files(b"bbb"), false)); + f.rebuild_matches(std::slice::from_ref(&pack)); + assert_eq!(fs::read(f.0.join("cached").join(name)).unwrap(), b"bbb"); + // The ZIP opens and enumerates, then its unsupported method fails after + // mirror has created directories. No reusable marker survives. + let mut broken = archive(&files(b"ccc"), false); + let central = broken + .windows(4) + .position(|s| s == [0x50, 0x4b, 0x01, 0x02]) + .unwrap(); + let second = central + 46 + "pack.mcmeta".len(); + broken[second + 10..second + 12].copy_from_slice(&99u16.to_le_bytes()); + f.write("pack.zip", &broken); + let out = f.0.join("cached"); + assert!( + packs::build_overlay(&f.0.join("vanilla"), std::slice::from_ref(&pack), &out).is_err() + ); + assert!(!marker_path(&out).exists()); + f.write("pack.zip", &archive(&files(b"ddd"), true)); + f.rebuild_matches(std::slice::from_ref(&pack)); + fs::remove_file(f.0.join("pack.zip")).unwrap(); + assert!(packs::build_overlay(&f.0.join("vanilla"), &[pack], &out).is_err()); + assert!(!marker_path(&out).exists()); + } + + #[cfg(unix)] + #[test] + fn unrelated_directory_pack_symlink_cycle_disables_reuse() { + let f = Fixture::new(); + f.write("vanilla/facts.json", b"[]"); + let pack = f.dir_pack("pack"); + f.write("pack/assets/minecraft/textures/a", b"pack"); + fs::create_dir_all(f.0.join("pack/docs")).unwrap(); + std::os::unix::fs::symlink(f.0.join("pack"), f.0.join("pack/docs/back")).unwrap(); + f.rebuild_matches(std::slice::from_ref(&pack)); + assert!(!marker_path(&f.0.join("cached")).exists()); + } + + #[cfg(unix)] + #[test] + fn linked_pack_bytes_stay_live_and_topology_invalidates() { + let f = Fixture::new(); + f.write("vanilla/facts.json", b"[]"); + let pack = f.dir_pack("pack"); + let name = "assets/minecraft/textures/a"; + f.write(&format!("pack/{name}"), b"aaa"); + f.rebuild_matches(std::slice::from_ref(&pack)); + let out = f.0.join("cached"); + let marker = marker_path(&out); + let before = fs::metadata(&marker).unwrap().modified().unwrap(); + let path = f.0.join("pack").join(name); + let original_time = fs::metadata(&path).unwrap().modified().unwrap(); + fs::write(&path, b"bbb").unwrap(); + fs::File::open(&path) + .unwrap() + .set_times(fs::FileTimes::new().set_modified(original_time)) + .unwrap(); + f.rebuild_matches(std::slice::from_ref(&pack)); + assert_eq!(fs::read(out.join(name)).unwrap(), b"bbb"); + assert_eq!(fs::metadata(&marker).unwrap().modified().unwrap(), before); + // Replacing a regular file at the same linked path is also already live. + f.write("replacement", b"ccc"); + fs::rename(f.0.join("replacement"), &path).unwrap(); + f.rebuild_matches(std::slice::from_ref(&pack)); + assert_eq!(fs::read(out.join(name)).unwrap(), b"ccc"); + assert_eq!(fs::metadata(&marker).unwrap().modified().unwrap(), before); + // A changed source symlink identity is fingerprinted, and a corrupt + // output symlink is repaired even when its target bytes happen to match. + fs::remove_file(&path).unwrap(); + f.write("other", b"ddd"); + std::os::unix::fs::symlink(f.0.join("other"), &path).unwrap(); + f.rebuild_matches(std::slice::from_ref(&pack)); + assert_eq!(fs::read(out.join(name)).unwrap(), b"ddd"); + fs::remove_file(out.join(name)).unwrap(); + std::os::unix::fs::symlink(f.0.join("other"), out.join(name)).unwrap(); + f.rebuild_matches(std::slice::from_ref(&pack)); + assert_eq!(fs::read_link(out.join(name)).unwrap(), path); + fs::remove_file(&path).unwrap(); + f.rebuild_matches(std::slice::from_ref(&pack)); + assert!(fs::symlink_metadata(out.join(name)).is_err()); + } + + #[test] + fn normalized_and_external_overlay_roots_keep_merged_bytes_current() { + let f = Fixture::new(); + let name = "assets/minecraft/lang/en_us.json"; + f.write(&format!("vanilla/{name}"), br#"{"v":1}"#); + let mut pack = f.dir_pack("pack"); + f.write(&format!("pack/extra/{name}"), br#"{"p":1}"#); + for overlay in ["extra/", "./extra", "extra/./", "extra//"] { + pack.overlays = vec![overlay.into()]; + f.rebuild_matches(std::slice::from_ref(&pack)); + let marker = marker_path(&f.0.join("cached")); + assert!(marker.exists()); + f.write(&format!("pack/extra/{name}"), br#"{"p":2}"#); + f.rebuild_matches(std::slice::from_ref(&pack)); + assert_eq!( + fs::read(f.0.join("cached").join(name)).unwrap(), + br#"{"p":2,"v":1}"# + ); + f.write(&format!("pack/extra/{name}"), br#"{"p":1}"#); + } + f.write(&format!("outside/{name}"), br#"{"p":3}"#); + for overlay in [ + "../outside".into(), + f.0.join("outside").to_string_lossy().into_owned(), + ] { + pack.overlays = vec![overlay]; + f.rebuild_matches(std::slice::from_ref(&pack)); + assert!(!marker_path(&f.0.join("cached")).exists()); + f.write(&format!("outside/{name}"), br#"{"p":4}"#); + f.rebuild_matches(std::slice::from_ref(&pack)); + assert_eq!( + fs::read(f.0.join("cached").join(name)).unwrap(), + br#"{"p":4,"v":1}"# + ); + f.write(&format!("outside/{name}"), br#"{"p":3}"#); + } + } + + #[cfg(unix)] + #[test] + fn root_symlink_aliases_stay_live_and_retargeted_merges_invalidate() { + let f = Fixture::new(); + let name = "assets/minecraft/lang/en_us.json"; + f.write("vanilla-a/facts.json", b"a"); + f.write("vanilla-b/facts.json", b"b"); + f.write(&format!("vanilla-a/{name}"), br#"{"v":"a"}"#); + f.write(&format!("vanilla-b/{name}"), br#"{"v":"b"}"#); + let mut pack = f.dir_pack("pack-a"); + f.dir_pack("pack-b"); + f.write("pack-a/assets/minecraft/textures/a", b"a"); + f.write("pack-b/assets/minecraft/textures/a", b"b"); + f.write(&format!("pack-a/{name}"), br#"{"p":"a"}"#); + f.write(&format!("pack-b/{name}"), br#"{"p":"b"}"#); + let vanilla = f.0.join("vanilla"); + let source = f.0.join("pack"); + std::os::unix::fs::symlink(f.0.join("vanilla-a"), &vanilla).unwrap(); + std::os::unix::fs::symlink(f.0.join("pack-a"), &source).unwrap(); + pack.source = Source::Dir(source.clone()); + f.rebuild_matches(std::slice::from_ref(&pack)); + fs::remove_file(&vanilla).unwrap(); + fs::remove_file(&source).unwrap(); + std::os::unix::fs::symlink(f.0.join("vanilla-b"), &vanilla).unwrap(); + std::os::unix::fs::symlink(f.0.join("pack-b"), &source).unwrap(); + let out = f.0.join("cached"); + assert_eq!(fs::read(out.join("facts.json")).unwrap(), b"b"); + assert_eq!( + fs::read(out.join("assets/minecraft/textures/a")).unwrap(), + b"b" + ); + f.rebuild_matches(std::slice::from_ref(&pack)); + assert_eq!(fs::read(out.join(name)).unwrap(), br#"{"p":"b","v":"b"}"#); + } + + #[test] + fn concurrent_selections_wait_and_never_publish_mismatched_markers() { + use std::{sync::mpsc, time::Duration}; + let f = Fixture::new(); + let name = "assets/minecraft/lang/en_us.json"; + f.write(&format!("vanilla/{name}"), br#"{"v":1}"#); + let a = f.dir_pack("a"); + let b = f.dir_pack("b"); + f.write(&format!("a/{name}"), br#"{"p":"a"}"#); + f.write(&format!("b/{name}"), br#"{"p":"b"}"#); + let out = f.0.join("cached"); + let held = fs::OpenOptions::new() + .read(true) + .write(true) + .create(true) + .truncate(false) + .open(lock_path(&out)) + .unwrap(); + held.lock().unwrap(); + let (started, starts) = mpsc::channel(); + let (done, finishes) = mpsc::channel(); + std::thread::scope(|scope| { + for pack in [&a, &b] { + let started = started.clone(); + let done = done.clone(); + let vanilla = f.0.join("vanilla"); + let out = &out; + scope.spawn(move || { + started.send(()).unwrap(); + for _ in 0..20 { + packs::build_overlay(&vanilla, std::slice::from_ref(pack), out).unwrap(); + } + done.send(()).unwrap(); + }); + } + starts.recv().unwrap(); + starts.recv().unwrap(); + assert!(matches!( + finishes.recv_timeout(Duration::from_millis(50)), + Err(mpsc::RecvTimeoutError::Timeout) + )); + drop(held); + }); + finishes.recv().unwrap(); + finishes.recv().unwrap(); + for pack in [&a, &b, &a, &b] { + f.rebuild_matches(std::slice::from_ref(pack)); + let expected = if pack.id == "a" { + br#"{"p":"a","v":1}"# + } else { + br#"{"p":"b","v":1}"# + }; + assert_eq!(fs::read(out.join(name)).unwrap(), expected); + } + assert!(lock_path(&out).exists()); + } + + #[test] + #[ignore = "reproducible overlay benchmark; run with --ignored --nocapture"] + fn benchmark_overlay_reuse() { + use std::{hint::black_box, time::Instant}; + let f = Fixture::new(); + let pack = f.dir_pack("pack"); + let mut files = vec![( + "pack.mcmeta".to_owned(), + fs::read(f.0.join("pack/pack.mcmeta")).unwrap(), + )]; + // 2,048 overrides (32 MiB), 32 merged language files, 8,192 live + // vanilla textures (128 MiB). Synthetic incompressible payloads approximate + // already-compressed PNG bytes; texture decoding is outside this benchmark. + let mut random = 0x1234_5678u32; + let texture: Vec = (0..16384) + .map(|_| { + random ^= random << 13; + random ^= random >> 17; + random ^= random << 5; + (random >> 24) as u8 + }) + .collect(); + for i in 0..8192 { + let name = format!("assets/minecraft/textures/block/{i}.png"); + f.write(&format!("vanilla/{name}"), &texture); + if i < 2048 { + f.write(&format!("pack/{name}"), &texture); + files.push((name, texture.clone())); + } + } + for i in 0..32 { + let name = format!("assets/minecraft/lang/{i}.json"); + let vanilla = serde_json::to_vec(&serde_json::Value::Object( + (0..2000) + .map(|j| { + ( + format!("key{j}"), + serde_json::json!(format!("Vanilla translation {j}")), + ) + }) + .collect(), + )) + .unwrap(); + let body = serde_json::to_vec(&serde_json::Value::Object( + (0..1000) + .map(|j| { + ( + format!("key{j}"), + serde_json::json!(format!("Pack translation {j}")), + ) + }) + .collect(), + )) + .unwrap(); + f.write(&format!("vanilla/{name}"), &vanilla); + f.write(&format!("pack/{name}"), &body); + files.push((name, body)); + } + let borrowed: Vec<_> = files + .iter() + .map(|(name, body)| (name.as_str(), body.clone())) + .collect(); + f.write("pack.zip", &archive(&borrowed, true)); + println!( + "fixture ZIP bytes={}", + fs::metadata(f.0.join("pack.zip")).unwrap().len() + ); + let zip = packs::pack( + "zip".into(), + Text::empty(), + Source::Zip(f.0.join("pack.zip")), + ) + .unwrap(); + let median = |mut times: Vec| { + times.sort_by(f64::total_cmp); + times[times.len() / 2] + }; + for (kind, pack) in [("directory", pack), ("deflated zip", zip)] { + f.rebuild_matches(std::slice::from_ref(&pack)); + let vanilla = f.0.join("vanilla"); + let out = f.0.join("cached"); + let mut baseline = Vec::new(); + let mut cold = Vec::new(); + let mut hit = Vec::new(); + for _ in 0..11 { + let start = Instant::now(); + build_overlay_uncached( + black_box(&vanilla), + black_box(std::slice::from_ref(&pack)), + black_box(&f.0.join("reference")), + &mut Dependencies::default(), + ) + .unwrap(); + baseline.push(start.elapsed().as_secs_f64() * 1000.0); + fs::remove_file(marker_path(&out)).unwrap(); + let start = Instant::now(); + packs::build_overlay( + black_box(&vanilla), + black_box(std::slice::from_ref(&pack)), + black_box(&out), + ) + .unwrap(); + cold.push(start.elapsed().as_secs_f64() * 1000.0); + let start = Instant::now(); + packs::build_overlay( + black_box(&vanilla), + black_box(std::slice::from_ref(&pack)), + black_box(&out), + ) + .unwrap(); + hit.push(start.elapsed().as_secs_f64() * 1000.0); + assert_eq!( + output_signature(&out).unwrap(), + output_signature(&f.0.join("reference")).unwrap() + ); + } + println!( + "{kind}: baseline={:.3} ms cold={:.3} ms unchanged={:.3} ms (11 medians, full validation)", + median(baseline), + median(cold), + median(hit) + ); + } + } + + #[test] + #[ignore = "content-heavy few-file directory benchmark"] + fn benchmark_content_heavy_directory() { + use std::{hint::black_box, time::Instant}; + let f = Fixture::new(); + f.write("vanilla/facts.json", b"[]"); + let pack = f.dir_pack("pack"); + let bytes = vec![42; 8 * 1024 * 1024]; + for i in 0..4 { + f.write(&format!("pack/assets/minecraft/textures/{i}.png"), &bytes); + } + let vanilla = f.0.join("vanilla"); + let out = f.0.join("cached"); + f.rebuild_matches(std::slice::from_ref(&pack)); + let mut timings = [Vec::new(), Vec::new(), Vec::new()]; + for _ in 0..11 { + let start = Instant::now(); + build_overlay_uncached( + black_box(&vanilla), + black_box(std::slice::from_ref(&pack)), + &f.0.join("reference"), + &mut Dependencies::default(), + ) + .unwrap(); + timings[0].push(start.elapsed().as_secs_f64() * 1000.0); + fs::remove_file(marker_path(&out)).unwrap(); + for times in &mut timings[1..] { + let start = Instant::now(); + packs::build_overlay( + black_box(&vanilla), + black_box(std::slice::from_ref(&pack)), + black_box(&out), + ) + .unwrap(); + times.push(start.elapsed().as_secs_f64() * 1000.0); + } + assert_eq!( + output_signature(&out).unwrap(), + output_signature(&f.0.join("reference")).unwrap() + ); + } + let medians: Vec<_> = timings + .into_iter() + .map(|mut times| { + times.sort_by(f64::total_cmp); + times[5] + }) + .collect(); + println!( + "4 x 8 MiB directory textures: baseline={:.3} ms cold={:.3} ms unchanged={:.3} ms (11 medians, full validation)", + medians[0], medians[1], medians[2] + ); + } +} diff --git a/docs/reuse-pack-overlays.md b/docs/reuse-pack-overlays.md new file mode 100644 index 000000000..9fa1e948c --- /dev/null +++ b/docs/reuse-pack-overlays.md @@ -0,0 +1,69 @@ +# Reusing resource-pack overlays + +`packs::build_overlay` reuses an overlay after validating a versioned sibling +JSON marker. The marker covers pack source paths/order, active overlay roots, +compiled filters, resource topology, merged inputs and the materialized output. +SHA-256 checks content rather than relying on file size or timestamps. + +On Unix, ordinary directory-pack resources and untouched vanilla resources are +live symlinks. Their bytes stay current on edits/replacements, so validation +checks topology and link targets without reading those bytes. Merged language, +sound, font and atlas JSON inputs are hashed. Vanilla directories that were +materialized by the builder are checked for additions/removals/type changes; +untouched directory symlinks stay live without a recursive vanilla scan. + +ZIP archives and extracted output files are fully hashed. On platforms where +`link` copies files, directory-pack contents and copied vanilla files are also +hashed. Existing merge order and filter behavior are unchanged. + +A persistent sibling `.overlay-cache.lock` uses an advisory OS file lock to +serialize validation, rebuilding and publication for the same output directory. +The lock inode is never removed by the builder. The old marker is removed before +rebuilding; its replacement is renamed into place only after a successful build +and stable input checks. Missing/corrupt markers or output trigger rebuilding. +Directory packs with absolute/parent-traversal overlay paths or symlink cycles +build through the original path without publishing a reusable marker. External +overlay paths retain their previous behavior. + +## Reproduce the benchmark + +```sh +CARGO_TARGET_DIR=/home/bob/Documents/horizon/target cargo test -p horizon-client --lib --profile fast packs::cache::tests::benchmark -- --ignored --nocapture --test-threads=1 +``` + +The ignored tests compare the original builder body (dependency recording +disabled) with the production cache path on identical inputs. They warm both +paths, collect 11 repetitions and compare output signatures after each pair. +The unchanged timing includes locking and all input/output validation. Cold +means the marker is absent but filesystem caches are warm; it is not a +cold-disk measurement. + +Fixtures are synthetic because prepared game assets were unavailable in this +workspace: 8,192 vanilla texture files (128 MiB), 2,048 overrides (32 MiB), and +32 merged language files with 2,000 vanilla/1,000 pack keys each. Texture bytes +are deterministic incompressible payloads approximating already-compressed PNG +data; this benchmark does not decode images. The directory and deflated ZIP +cases contain equivalent resources. A separate four-file/32 MiB directory case +checks that live content does not impose a large hashing cost. + +Measured on 2026-10-14: Linux 7.2.8-zen1-2-zen x86_64, ext4/NVMe, +AMD Ryzen 5 5600X (6 cores/12 threads), Rust 1.99.0, `fast` profile. +The deflated ZIP is 34,030,189 bytes (32.45 MiB). + +| Fixture | Original rebuild | Cached cold/rebuild | Unchanged validated hit | Hit speedup | +| --- | ---: | ---: | ---: | ---: | +| Directory pack | 107.129 ms | 184.868 ms | 50.484 ms | 2.12× | +| Deflated ZIP pack | 152.032 ms | 271.798 ms | 88.416 ms | 1.72× | +| Directory, four 8 MiB files | 0.112 ms | 0.316 ms | 0.122 ms | ~10 µs overhead | + +The two larger cold paths are 73–79% slower because they also establish and +verify cache dependencies/output. The large-file/few-file case adds about +0.2 ms cold and 0.01 ms on an unchanged call; reading all of its live texture +bytes would instead cost tens of milliseconds, so those bytes are excluded. + +The cache adds a small marker and persistent empty lock file per overlay. Hashes +stream through a 64 KiB buffer rather than retaining archive/resource contents +on cache hits. Initial/rebuilt overlays do extra validation and marker work; +tiny overlays can have a small unchanged-call overhead. Measurements cover +overlay construction only, not total startup time or frame rate. Non-Unix +copy behavior is covered in the implementation but was not runtime-tested here. From 1295fccd17d4bab9e95b320085f78373701d9482 Mon Sep 17 00:00:00 2001 From: rdbtCVS <87152661+rdbtCVS@users.noreply.github.com> Date: Thu, 15 Oct 2026 01:04:48 +0100 Subject: [PATCH 12/97] perf(client): validate overlay reuse with source stamps and benchmark real packs --- benchmarks/overlay-real-packs-2026-10-15.json | 54 ++++ crates/horizon-client/src/packs/cache.rs | 243 +++++++++++++++--- docs/reuse-pack-overlays.md | 99 +++---- 3 files changed, 296 insertions(+), 100 deletions(-) create mode 100644 benchmarks/overlay-real-packs-2026-10-15.json diff --git a/benchmarks/overlay-real-packs-2026-10-15.json b/benchmarks/overlay-real-packs-2026-10-15.json new file mode 100644 index 000000000..f664be6c4 --- /dev/null +++ b/benchmarks/overlay-real-packs-2026-10-15.json @@ -0,0 +1,54 @@ +{ + "date": "2026-10-15", + "environment": "Linux x86_64/ext4/NVMe, Ryzen5 5600X, Rust1.99.0, Cargo fast", + "scope": "actual resource_root vs original wrapper/builder; warmed storage; output equivalence outside timing", + "warmups": 2, + "median_samples": 11, + "prepared_minecraft": "26.3", + "prepared_schema": 7, + "prepared_manifest_sha256": "fd03c686302748748e132ef3978b7b0bcf42024257e802985a5cc7175cc74298", + "packs": [ + { + "project": "faithful-32x", + "version": "lDYpMiqk", + "version_name": "[26.3] Faithful 32x \u2013 September 2026 Release", + "publisher_page": "https://modrinth.com/resourcepack/faithful-32x/version/lDYpMiqk", + "download_url": "https://cdn.modrinth.com/data/w0TnApzs/versions/lDYpMiqk/Faithful%2032x%20-%2026.3.zip", + "zip_bytes": 13116019, + "zip_sha512": "e90ec63af7f239dbb99aa20c98b23d830e76898f65d3e31b7f0b53bb36db12dcd8c38d6930c743237c9c3db7bf708423fa1d1b2fd497dd6c281dbe216b779db9", + "asset_files": 5063, + "assets_uncompressed_bytes": 12524266, + "original_ms": 159.827, + "cold_ms": 162.711, + "hit_ms": 0.707 + }, + { + "project": "default-hd-128x", + "version": "rErHu3BE", + "version_name": "Default HD 128x Demo/Alpha 1.8.2.7", + "publisher_page": "https://modrinth.com/resourcepack/default-hd-128x/version/rErHu3BE", + "download_url": "https://cdn.modrinth.com/data/orfTV6nk/versions/rErHu3BE/Default%20HD%20128x%20Demo%201.8.2.7.zip", + "zip_bytes": 16876419, + "zip_sha512": "f5f9606e92b986cd9c8b8e5ff2bb52db720cc7b38e013355bdc90089e01975a08d09750ef2fd727f753d88ec3fbcd067355179b490587f667b2995f8be81640f", + "asset_files": 2318, + "assets_uncompressed_bytes": 17315416, + "original_ms": 111.501, + "cold_ms": 114.386, + "hit_ms": 0.31 + }, + { + "project": "fpbr", + "version": "dynf82xk", + "version_name": "support 1.21.9 and newer", + "publisher_page": "https://modrinth.com/resourcepack/fpbr/version/dynf82xk", + "download_url": "https://cdn.modrinth.com/data/nvEpbd8t/versions/dynf82xk/FPBR-Main-1.21.9-R1.3.zip", + "zip_bytes": 46737770, + "zip_sha512": "64f1bbd036e205118f1d9c49a79558db2c1356ee988fb939c0023db1967d78e1bd05047f341ce6d65355717ba7ddb1330af57edbb4d5b8713c96ae62987274c5", + "asset_files": 7001, + "assets_uncompressed_bytes": 56356903, + "original_ms": 347.639, + "cold_ms": 348.012, + "hit_ms": 0.448 + } + ] +} diff --git a/crates/horizon-client/src/packs/cache.rs b/crates/horizon-client/src/packs/cache.rs index a49f9f704..6931a3871 100644 --- a/crates/horizon-client/src/packs/cache.rs +++ b/crates/horizon-client/src/packs/cache.rs @@ -1,13 +1,14 @@ -//! Content-validated overlay reuse. Live symlink files/subtrees need no content -//! scan; merged, extracted and copied bytes do. Topology and link targets are -//! always checked, including vanilla directories materialized by mirror. +//! Overlay reuse validated by source topology and filesystem stamps. +//! Published output is an owned cache artifact; hits do not traverse its tree. use super::{Pack, Source, build_overlay_uncached}; use serde::{Deserialize, Serialize}; use sha2::{Digest, Sha256}; -use std::{collections::BTreeSet, fs, io, io::Read, path::Path, path::PathBuf}; +#[cfg(any(test, not(unix)))] +use std::io::Read; +use std::{collections::BTreeSet, fs, io, path::Path, path::PathBuf}; // Bump when overlay/merge semantics change. Markers are disposable cache data. -const VERSION: u32 = 1; +const VERSION: u32 = 2; #[derive(Default, Serialize, Deserialize)] pub(super) struct Dependencies { @@ -47,7 +48,6 @@ struct Marker { vanilla: PathBuf, packs: String, dependencies: Dependencies, - output: String, } fn finish(hash: Sha256) -> String { @@ -58,6 +58,7 @@ fn field(hash: &mut Sha256, bytes: &[u8]) { hash.update((bytes.len() as u64).to_le_bytes()); hash.update(bytes); } +#[cfg(any(test, not(unix)))] fn content(hash: &mut Sha256, path: &Path) -> io::Result<()> { let mut file = fs::File::open(path)?; hash.update(file.metadata()?.len().to_le_bytes()); @@ -71,6 +72,31 @@ fn content(hash: &mut Sha256, path: &Path) -> io::Result<()> { } Ok(()) } +fn stamp(hash: &mut Sha256, path: &Path) -> io::Result<()> { + let meta = fs::metadata(path)?; + hash.update(meta.len().to_le_bytes()); + field(hash, format!("{:?}", meta.modified()?).as_bytes()); + #[cfg(unix)] + { + use std::os::unix::fs::MetadataExt; + hash.update(meta.dev().to_le_bytes()); + hash.update(meta.ino().to_le_bytes()); + hash.update(meta.ctime().to_le_bytes()); + hash.update(meta.ctime_nsec().to_le_bytes()); + } + #[cfg(not(unix))] + { + // Portable metadata lacks a change timestamp. Preserve content-based + // validation for materialized files on those platforms. + if meta.is_file() { + return content(hash, path); + } + if let Ok(created) = meta.created() { + field(hash, format!("{created:?}").as_bytes()); + } + } + Ok(()) +} fn entries(path: &Path) -> io::Result> { let mut entries = fs::read_dir(path)? .map(|e| e.map(|e| e.path())) @@ -85,14 +111,10 @@ fn dependency_signature(path: &Path, directory: bool) -> io::Result { Err(e) => return Err(e), Ok(meta) if directory && meta.is_dir() => { field(&mut hash, b"directory"); - for entry in entries(path)? { - field(&mut hash, entry.file_name().unwrap().as_encoded_bytes()); - // mirror's decisions use the followed file type, including symlinks. - field(&mut hash, &[u8::from(entry.is_dir())]); - } + stamp(&mut hash, path)?; } Ok(_) if directory => field(&mut hash, b"not-directory"), - Ok(_) => content(&mut hash, path)?, + Ok(_) => stamp(&mut hash, path)?, } Ok(finish(hash)) } @@ -114,7 +136,7 @@ fn needs_content(path: &Path, pack: Option<&Pack>) -> bool { .replace('\\', "/"); // Ordinary folder resources are live Unix file symlinks. Rewrites and // replacements at that path are visible without rebuilding. Merged JSON - // and configuration bytes are materialized and need content validation. + // and configuration bytes are materialized and need stamp validation. relative == "pack.mcmeta" || super::merge_kind(&relative).is_some() || pack.overlays.iter().any(|overlay| { @@ -164,11 +186,16 @@ fn tree_inner( } else { field(hash, b"file"); if needs_content(path, pack) { - content(hash, path)?; + #[cfg(test)] + if pack.is_none() { + return content(hash, path); + } + stamp(hash, path)?; } } Ok(()) } +#[cfg(test)] fn output_signature(out: &Path) -> io::Result { let mut hash = Sha256::new(); tree(&mut hash, out, None)?; @@ -203,8 +230,14 @@ fn pack_signature(packs: &[Pack]) -> io::Result { field(&mut hash, format!("{:?}", pack.overlays).as_bytes()); field(&mut hash, format!("{:?}", pack.filter).as_bytes()); match &pack.source { - Source::Dir(path) => tree(&mut hash, path, Some(pack))?, - Source::Zip(path) => content(&mut hash, path)?, + Source::Dir(path) => { + field(&mut hash, absolute(path)?.as_os_str().as_encoded_bytes()); + tree(&mut hash, path, Some(pack))?; + } + Source::Zip(path) => { + field(&mut hash, absolute(path)?.as_os_str().as_encoded_bytes()); + stamp(&mut hash, path)?; + } } } Ok(finish(hash)) @@ -242,31 +275,18 @@ pub(super) fn build(vanilla: &Path, packs: &[Pack], out: &Path) -> io::Result<() .truncate(false) .open(lock_path(out))?; lock.lock()?; - // Absolute paths also prevent cwd changes from reusing relative symlinks. - // Keep root symlink aliases live, as mirror does for individual resources. - let vanilla = absolute(vanilla)?; - let packs: Vec = packs - .iter() - .map(|pack| { - let mut pack = pack.clone(); - match &mut pack.source { - Source::Dir(path) | Source::Zip(path) => { - *path = absolute(path)?; - } - } - Ok(pack) - }) - .collect::>()?; + // Resolve marker identity only; preserve the builder's original link targets. + let vanilla_key = absolute(vanilla)?; let marker_path = marker_path(out); - let signature = pack_signature(&packs); + let signature = pack_signature(packs); if let Ok(signature) = &signature && let Ok(bytes) = fs::read(&marker_path) && let Ok(marker) = serde_json::from_slice::(&bytes) && marker.version == VERSION - && marker.vanilla == vanilla + && marker.vanilla == vanilla_key && marker.packs == *signature && marker.dependencies.valid() - && output_signature(out).is_ok_and(|s| s == marker.output) + && out.is_dir() { return Ok(()); } @@ -280,17 +300,16 @@ pub(super) fn build(vanilla: &Path, packs: &[Pack], out: &Path) -> io::Result<() tracking: signature.is_ok(), ..Dependencies::default() }; - build_overlay_uncached(&vanilla, &packs, out, &mut dependencies)?; + build_overlay_uncached(vanilla, packs, out, &mut dependencies)?; if let Ok(signature) = signature && dependencies.valid() - && pack_signature(&packs).is_ok_and(|s| s == signature) + && pack_signature(packs).is_ok_and(|s| s == signature) { let marker = Marker { version: VERSION, - vanilla, + vanilla: vanilla_key, packs: signature, dependencies, - output: output_signature(out)?, }; // PathBuf serialization requires UTF-8; unusual resource root names // can still build normally without a reusable marker. @@ -404,7 +423,7 @@ mod tests { } #[test] - fn directory_inputs_config_and_output_invalidate() { + fn directory_inputs_config_and_owned_output_recovery() { let f = Fixture::new(); let resource = "assets/minecraft/lang/en_us.json"; f.write(&format!("vanilla/{resource}"), br#"{"v":"a"}"#); @@ -461,8 +480,14 @@ mod tests { low.filter = packs::filter_of(&serde_json::json!({"filter":{"block":[{"path":"lang"}]}})); f.rebuild_matches(std::slice::from_ref(&low)); fs::write(out.join(resource), b"corrupt").unwrap(); + // Published output is trusted; clearing the marker explicitly repairs + // a cache tree changed outside the builder. + packs::build_overlay(&f.0.join("vanilla"), std::slice::from_ref(&low), &out).unwrap(); + assert_eq!(fs::read(out.join(resource)).unwrap(), b"corrupt"); + fs::remove_file(&marker).unwrap(); f.rebuild_matches(std::slice::from_ref(&low)); fs::remove_file(out.join(resource)).unwrap(); + fs::remove_file(&marker).unwrap(); f.rebuild_matches(std::slice::from_ref(&low)); fs::write(&marker, b"corrupt").unwrap(); f.rebuild_matches(std::slice::from_ref(&low)); @@ -584,8 +609,8 @@ mod tests { f.rebuild_matches(std::slice::from_ref(&pack)); assert_eq!(fs::read(out.join(name)).unwrap(), b"ccc"); assert_eq!(fs::metadata(&marker).unwrap().modified().unwrap(), before); - // A changed source symlink identity is fingerprinted, and a corrupt - // output symlink is repaired even when its target bytes happen to match. + // A changed source symlink identity is fingerprinted. Output is trusted + // until its marker is cleared explicitly. fs::remove_file(&path).unwrap(); f.write("other", b"ddd"); std::os::unix::fs::symlink(f.0.join("other"), &path).unwrap(); @@ -593,6 +618,7 @@ mod tests { assert_eq!(fs::read(out.join(name)).unwrap(), b"ddd"); fs::remove_file(out.join(name)).unwrap(); std::os::unix::fs::symlink(f.0.join("other"), out.join(name)).unwrap(); + fs::remove_file(&marker).unwrap(); f.rebuild_matches(std::slice::from_ref(&pack)); assert_eq!(fs::read_link(out.join(name)).unwrap(), path); fs::remove_file(&path).unwrap(); @@ -908,4 +934,139 @@ mod tests { medians[0], medians[1], medians[2] ); } + + #[cfg(unix)] + #[test] + fn relative_builder_targets_are_preserved() { + let f = Fixture::new(); + f.write("vanilla/facts.json", b"[]"); + let mut pack = f.dir_pack("pack"); + let name = "assets/minecraft/textures/a"; + f.write(&format!("pack/{name}"), b"pack"); + let cwd = std::env::current_dir().unwrap(); + let mut relative = PathBuf::new(); + for component in cwd.components() { + if matches!(component, std::path::Component::Normal(_)) { + relative.push(".."); + } + } + relative.push(f.0.strip_prefix("/").unwrap()); + pack.source = Source::Dir(relative.join("pack")); + let vanilla = relative.join("vanilla"); + let out = f.0.join("cached"); + let reference = f.0.join("reference"); + packs::build_overlay(&vanilla, std::slice::from_ref(&pack), &out).unwrap(); + build_overlay_uncached(&vanilla, &[pack], &reference, &mut Dependencies::default()) + .unwrap(); + let expected = relative.join("pack").join(name); + assert_eq!(fs::read_link(out.join(name)).unwrap(), expected); + assert_eq!(fs::read_link(reference.join(name)).unwrap(), expected); + assert_eq!( + fs::read_link(out.join("facts.json")).unwrap(), + vanilla.join("facts.json") + ); + } + + #[test] + #[ignore = "requires prepared resources and real pack paths in environment"] + fn benchmark_real_resource_root() { + use std::{hint::black_box, time::Instant}; + let vanilla = PathBuf::from(std::env::var("HORIZON_OVERLAY_BENCH_VANILLA").unwrap()); + assert!(vanilla.join("horizon-resources.json").is_file()); + let paths: Vec = + serde_json::from_str(&std::env::var("HORIZON_OVERLAY_BENCH_PACKS").unwrap()).unwrap(); + // The original resource_root selection/cache-key path, with its original builder. + fn original(vanilla: &Path, packs: &[Pack], cache: &Path) -> PathBuf { + let key = packs + .iter() + .map(|p| p.id.as_str()) + .collect::>() + .join("|"); + let hash = key.bytes().fold(0xcbf2_9ce4_8422_2325u64, |h, b| { + (h ^ u64::from(b)).wrapping_mul(0x100_0000_01b3) + }); + let out = cache.join(format!("{hash:016x}")); + build_overlay_uncached(vanilla, packs, &out, &mut Dependencies::default()).unwrap(); + out + } + let median = |mut times: Vec| { + times.sort_by(f64::total_cmp); + times[times.len() / 2] + }; + for path in paths { + let f = Fixture::new(); + let pack = packs::pack( + path.to_string_lossy().into_owned(), + Text::empty(), + Source::Zip(path.clone()), + ) + .unwrap(); + let selected = std::slice::from_ref(&pack); + let reference_cache = f.0.join("reference"); + let cached_cache = f.0.join("cached"); + fs::create_dir_all(&reference_cache).unwrap(); + let reference = original(&vanilla, selected, &reference_cache); + let out = packs::resource_root(&vanilla, selected, &cached_cache); + assert_ne!(out, vanilla, "resource_root must not fall back to vanilla"); + assert!(marker_path(&out).exists()); + let expected = output_signature(&reference).unwrap(); + assert_eq!(output_signature(&out).unwrap(), expected); + for _ in 0..2 { + original(&vanilla, selected, &reference_cache); + assert_eq!(packs::resource_root(&vanilla, selected, &cached_cache), out); + } + let mut baseline = Vec::new(); + let mut cold = Vec::new(); + let mut hit = Vec::new(); + for iteration in 0..11 { + for operation in if iteration % 2 == 0 { + [0, 1, 2] + } else { + [1, 2, 0] + } { + if operation == 1 { + fs::remove_file(marker_path(&out)).unwrap(); + } + let started = Instant::now(); + let result = if operation == 0 { + original( + black_box(&vanilla), + black_box(selected), + black_box(&reference_cache), + ) + } else { + packs::resource_root( + black_box(&vanilla), + black_box(selected), + black_box(&cached_cache), + ) + }; + black_box(&result); + let ms = started.elapsed().as_secs_f64() * 1000.0; + match operation { + 0 => baseline.push(ms), + 1 => cold.push(ms), + _ => hit.push(ms), + } + if operation != 0 { + assert_eq!(result, out); + } + } + // Verify full materialized bytes and symlink identities outside timing. + assert_eq!(output_signature(&out).unwrap(), expected); + assert_eq!(output_signature(&reference).unwrap(), expected); + } + let baseline = median(baseline); + let cold = median(cold); + let hit = median(hit); + println!( + "real pack={} ZIP={} bytes: original={baseline:.3} ms cold={cold:.3} ms hit={hit:.3} ms speedup={:.2}x saved={:.3} ms cold_overhead={:.2}% (11 medians, 2 warmups)", + path.display(), + fs::metadata(&path).unwrap().len(), + baseline / hit, + baseline - hit, + (cold / baseline - 1.0) * 100.0 + ); + } + } } diff --git a/docs/reuse-pack-overlays.md b/docs/reuse-pack-overlays.md index 9fa1e948c..2a5235553 100644 --- a/docs/reuse-pack-overlays.md +++ b/docs/reuse-pack-overlays.md @@ -1,69 +1,50 @@ # Reusing resource-pack overlays -`packs::build_overlay` reuses an overlay after validating a versioned sibling -JSON marker. The marker covers pack source paths/order, active overlay roots, -compiled filters, resource topology, merged inputs and the materialized output. -SHA-256 checks content rather than relying on file size or timestamps. +`packs::build_overlay` reuses a completed overlay through a versioned sibling JSON marker and persistent OS lock. Pack sources/order, overlay roots, filters, source topology and materialized vanilla inputs determine validity. The marker is removed before rebuilding and published only after a successful build and stable input checks. -On Unix, ordinary directory-pack resources and untouched vanilla resources are -live symlinks. Their bytes stay current on edits/replacements, so validation -checks topology and link targets without reading those bytes. Merged language, -sound, font and atlas JSON inputs are hashed. Vanilla directories that were -materialized by the builder are checked for additions/removals/type changes; -untouched directory symlinks stay live without a recursive vanilla scan. +On Unix, ZIPs and materialized inputs use length, modification time, device/inode and change-time stamps. Cache hits do not read archive bytes or traverse generated output. Directory packs still validate their topology; ordinary linked files and untouched vanilla subtrees remain live. Materialized vanilla directory stamps detect membership changes without listing them again. Only marker identity resolves paths; the builder retains the caller's original symlink targets and root aliases. -ZIP archives and extracted output files are fully hashed. On platforms where -`link` copies files, directory-pack contents and copied vanilla files are also -hashed. Existing merge order and filter behavior are unchanged. +On non-Unix platforms, materialized files retain content hashing because portable metadata lacks a change timestamp. That path was not runtime-tested. External folder overlays and symlink cycles retain uncached behavior. Missing/corrupt markers and a missing output root rebuild. Generated output is owned cache data: external edits to individual output files are deliberately not detected; delete the sibling marker or overlay directory to rebuild it. -A persistent sibling `.overlay-cache.lock` uses an advisory OS file lock to -serialize validation, rebuilding and publication for the same output directory. -The lock inode is never removed by the builder. The old marker is removed before -rebuilding; its replacement is renamed into place only after a successful build -and stable input checks. Missing/corrupt markers or output trigger rebuilding. -Directory packs with absolute/parent-traversal overlay paths or symlink cycles -build through the original path without publishing a reusable marker. External -overlay paths retain their previous behavior. +## Real pack measurements -## Reproduce the benchmark +The ignored test measures the actual production `resource_root` entry point against its original selection/key/build sequence. Two warmups and 11 alternating samples use identical prepared Minecraft 26.3 resources (manifest schema 7). Complete materialized output bytes and symlink identities are compared outside timing. Cold means an absent marker with warm filesystem caches, rather than cold storage. + +Linux x86_64/ext4/NVMe, Ryzen 5 5600X, Rust 1.99.0, Cargo `fast`, measured 2026-10-15: + +| ZIP pack | Original rebuild | Cached cold | Unchanged hit | Saved per hit | +| --- | ---: | ---: | ---: | ---: | +| Faithful 32x, 26.3 September 2026 | 159.827 ms | 162.711 ms | 0.707 ms | 159.120 ms | +| Default HD 128x demo, 1.8.2.7 | 111.501 ms | 114.386 ms | 0.310 ms | 111.191 ms | +| FPBR, 1.21.9 R1.3 | 347.639 ms | 348.012 ms | 0.448 ms | 347.191 ms | + +Unchanged speedups are approximately 226x, 359x and 775x. Cold overhead on these ZIPs is 0.1–2.6%, replacing the original cache implementation's 73–79% synthetic overhead. This measures overlay assembly and cache validation, excluding scan, texture decoding, total startup and FPS. + +Pack downloads were verified against publisher SHA-512 metadata. Exact versions, URLs, sizes, asset counts, hashes and prepared-manifest identity are recorded in `benchmarks/overlay-real-packs-2026-10-15.json`. Sources: [Faithful](https://modrinth.com/resourcepack/faithful-32x/version/lDYpMiqk), [Default HD](https://modrinth.com/resourcepack/default-hd-128x/version/rErHu3BE), [FPBR](https://modrinth.com/resourcepack/fpbr/version/dynf82xk). FPBR targets older 1.21.9 snapshots; it is measured as a large real 128x archive over prepared 26.3 resources, without claiming visual/version compatibility. Default HD is the publisher's free demo. Downloaded pack contents are not committed. + +## Synthetic coverage + +The existing fixtures contain 8,192 vanilla textures (128 MiB), 2,048 overrides (32 MiB) and 32 merged language files; equivalent directory/ZIP payloads are incompressible bytes. Eleven median samples compare identical output outside timing: + +| Fixture | Original | Cached cold | Hit | +| --- | ---: | ---: | ---: | +| Directory | 108.487 ms | 126.438 ms | 7.438 ms | +| Deflated ZIP, 32.45 MiB | 155.540 ms | 155.453 ms | 0.128 ms | +| Directory, four 8 MiB files | 0.115 ms | 0.271 ms | 0.076 ms | + +Directory topology scans remain a cost: the larger directory fixture adds about 17% cold overhead and gains 14.6x on hits. Tiny cold overlays add about 0.16 ms. No overall startup gain is inferred from either table. + +## Reproduce and validate ```sh -CARGO_TARGET_DIR=/home/bob/Documents/horizon/target cargo test -p horizon-client --lib --profile fast packs::cache::tests::benchmark -- --ignored --nocapture --test-threads=1 +export CARGO_INCREMENTAL=0 +export HORIZON_OVERLAY_BENCH_VANILLA=/path/to/prepared/26.3 +export HORIZON_OVERLAY_BENCH_PACKS='["/path/to/Faithful.zip","/path/to/DefaultHD.zip","/path/to/FPBR.zip"]' +cargo test -p horizon-client --lib --profile fast packs::cache::tests::benchmark_real_resource_root -- --ignored --nocapture --test-threads=1 +cargo test -p horizon-client --lib --profile fast packs::cache::tests::benchmark -- --ignored --nocapture --test-threads=1 --skip benchmark_real_resource_root +cargo test -p horizon-client --lib --profile fast packs:: -- --nocapture +cargo clippy -p horizon-client --lib --tests --profile fast -- -D warnings +cargo fmt --all -- --check ``` -The ignored tests compare the original builder body (dependency recording -disabled) with the production cache path on identical inputs. They warm both -paths, collect 11 repetitions and compare output signatures after each pair. -The unchanged timing includes locking and all input/output validation. Cold -means the marker is absent but filesystem caches are warm; it is not a -cold-disk measurement. - -Fixtures are synthetic because prepared game assets were unavailable in this -workspace: 8,192 vanilla texture files (128 MiB), 2,048 overrides (32 MiB), and -32 merged language files with 2,000 vanilla/1,000 pack keys each. Texture bytes -are deterministic incompressible payloads approximating already-compressed PNG -data; this benchmark does not decode images. The directory and deflated ZIP -cases contain equivalent resources. A separate four-file/32 MiB directory case -checks that live content does not impose a large hashing cost. - -Measured on 2026-10-14: Linux 7.2.8-zen1-2-zen x86_64, ext4/NVMe, -AMD Ryzen 5 5600X (6 cores/12 threads), Rust 1.99.0, `fast` profile. -The deflated ZIP is 34,030,189 bytes (32.45 MiB). - -| Fixture | Original rebuild | Cached cold/rebuild | Unchanged validated hit | Hit speedup | -| --- | ---: | ---: | ---: | ---: | -| Directory pack | 107.129 ms | 184.868 ms | 50.484 ms | 2.12× | -| Deflated ZIP pack | 152.032 ms | 271.798 ms | 88.416 ms | 1.72× | -| Directory, four 8 MiB files | 0.112 ms | 0.316 ms | 0.122 ms | ~10 µs overhead | - -The two larger cold paths are 73–79% slower because they also establish and -verify cache dependencies/output. The large-file/few-file case adds about -0.2 ms cold and 0.01 ms on an unchanged call; reading all of its live texture -bytes would instead cost tens of milliseconds, so those bytes are excluded. - -The cache adds a small marker and persistent empty lock file per overlay. Hashes -stream through a 64 KiB buffer rather than retaining archive/resource contents -on cache hits. Initial/rebuilt overlays do extra validation and marker work; -tiny overlays can have a small unchanged-call overhead. Measurements cover -overlay construction only, not total startup time or frame rate. Non-Unix -copy behavior is covered in the implementation but was not runtime-tested here. +Thirteen focused tests pass, covering source edits/replacements, Unix preserved-mtime edits, pack order/removal, overlays/filters, vanilla membership, marker/output-root recovery, failed ZIP rebuilds, symlink aliases/cycles, contention and unchanged relative link targets. All three opt-in benchmarks pass; strict Clippy, formatting and whitespace checks pass. Each overlay retains a small marker and empty lock file; cache hits retain no archive byte buffer. From 43138159b2fb9576e4bb71ef3fda9cf93fce5ce3 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 02:13:46 +0200 Subject: [PATCH 13/97] Opt-in data collection (1/5): consent, payloads, outbox and a gated uploader horizon-telemetry, shared by the launcher, the game and the ingest server: - consent.json in the game folder: four switches, all off until the player answers, a consent version that re-asks when what is collected changes, the answer's time, and a random install ID made at the first yes. - Payloads: perf summaries (percentiles + 14 frame-time buckets from a fixed-size Timings recorder), crash and bug reports, and benchmark reports carried as docs/benchmark-report.md defines them; size caps per kind. - A scrubber for user folders, user names, e-mail and IP addresses, UUIDs and caller-known private terms. - The outbox: only allowed kinds get in, daily caps, 200 items / 2 MiB. - zstd batches with bounded decoding; the uploader re-reads the consent and drops withdrawn items before connecting, backs off and caps batches a day. - tests/consent_gating.rs: a local mock server sees zero connections with the consent missing, outdated or withdrawn. No server is set (DEFAULT_ENDPOINT is None): nothing is sent yet. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 27 ++ Cargo.toml | 2 +- crates/horizon-telemetry/Cargo.toml | 28 ++ crates/horizon-telemetry/src/batch.rs | 198 ++++++++ crates/horizon-telemetry/src/consent.rs | 191 ++++++++ crates/horizon-telemetry/src/lib.rs | 97 ++++ crates/horizon-telemetry/src/outbox.rs | 236 ++++++++++ crates/horizon-telemetry/src/payload.rs | 421 ++++++++++++++++++ crates/horizon-telemetry/src/scrub.rs | 354 +++++++++++++++ crates/horizon-telemetry/src/system.rs | 124 ++++++ crates/horizon-telemetry/src/upload.rs | 141 ++++++ .../horizon-telemetry/tests/consent_gating.rs | 231 ++++++++++ docs/README.md | 1 + docs/telemetry.md | 55 +++ 14 files changed, 2105 insertions(+), 1 deletion(-) create mode 100644 crates/horizon-telemetry/Cargo.toml create mode 100644 crates/horizon-telemetry/src/batch.rs create mode 100644 crates/horizon-telemetry/src/consent.rs create mode 100644 crates/horizon-telemetry/src/lib.rs create mode 100644 crates/horizon-telemetry/src/outbox.rs create mode 100644 crates/horizon-telemetry/src/payload.rs create mode 100644 crates/horizon-telemetry/src/scrub.rs create mode 100644 crates/horizon-telemetry/src/system.rs create mode 100644 crates/horizon-telemetry/src/upload.rs create mode 100644 crates/horizon-telemetry/tests/consent_gating.rs create mode 100644 docs/telemetry.md diff --git a/Cargo.lock b/Cargo.lock index 0753fc7d0..b8052e8b9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -955,6 +955,17 @@ dependencies = [ "sha1", ] +[[package]] +name = "horizon-telemetry" +version = "0.1.0" +dependencies = [ + "getrandom 0.3.4", + "ruzstd", + "serde", + "serde_json", + "ureq", +] + [[package]] name = "horizon-theme" version = "0.1.0" @@ -2266,6 +2277,15 @@ version = "1.0.23" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" +[[package]] +name = "ruzstd" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69e4ce4a039f42bf25920b95667e4d789e98749ab11bbb8d2c2936f788421bb5" +dependencies = [ + "twox-hash", +] + [[package]] name = "same-file" version = "1.0.6" @@ -2313,6 +2333,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" dependencies = [ "serde_core", + "serde_derive", ] [[package]] @@ -2758,6 +2779,12 @@ version = "0.25.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d2df906b07856748fa3f6e0ad0cbaa047052d4a7dd609e231c4f72cee8c36f31" +[[package]] +name = "twox-hash" +version = "2.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86a801b3cea342a06d468c8710662aa29e5e05e4f5c0d62f00bbb7f2ad7941c2" + [[package]] name = "typenum" version = "1.20.1" diff --git a/Cargo.toml b/Cargo.toml index 2af3d37a4..c8e81b0af 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [workspace] exclude = ["launcher"] -members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "xtask"] +members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "xtask"] resolver = "2" [workspace.package] diff --git a/crates/horizon-telemetry/Cargo.toml b/crates/horizon-telemetry/Cargo.toml new file mode 100644 index 000000000..ea54b079d --- /dev/null +++ b/crates/horizon-telemetry/Cargo.toml @@ -0,0 +1,28 @@ +[package] +name = "horizon-telemetry" +version = "0.1.0" +edition.workspace = true +license.workspace = true +rust-version = "1.90" +description = "Opt-in data collection: the player's consent, the payloads, the local outbox and its upload" + +[dependencies] +serde = { version = "1", features = ["derive"] } +serde_json = "1" +# zstd in pure Rust: batches are compressed before they leave and checked when they arrive. +ruzstd = "0.9" +# The random install ID and outbox file names. +getrandom = "0.3" +# Sending, for the launcher; the ingest server builds without it. +ureq = { version = "2", default-features = false, features = ["tls"], optional = true } + +[features] +default = ["upload"] +upload = ["dep:ureq"] + +[[test]] +name = "consent_gating" +required-features = ["upload"] + +[lints] +workspace = true diff --git a/crates/horizon-telemetry/src/batch.rs b/crates/horizon-telemetry/src/batch.rs new file mode 100644 index 000000000..5baf36871 --- /dev/null +++ b/crates/horizon-telemetry/src/batch.rs @@ -0,0 +1,198 @@ +//! What goes over the wire: an install's items as one JSON object, zstd-compressed +//! (`Content-Encoding: zstd`). The server decodes with [`decode`], which bounds what it inflates. +use std::io::Read; + +use serde::{Deserialize, Serialize}; + +use crate::Item; +use crate::consent::is_install_id; + +/// A batch on the wire, compressed. +pub const MAX_COMPRESSED: usize = 256 * 1024; +/// A batch's JSON: more than the largest item, so any item fits on its own. +pub const MAX_JSON: usize = 1024 * 1024; +pub const MAX_ITEMS: usize = 64; + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +pub struct Batch { + pub schema: u32, + pub install_id: String, + pub items: Vec, +} + +impl Batch { + pub fn new(install_id: &str, items: Vec) -> Self { + Self { + schema: crate::SCHEMA, + install_id: install_id.to_owned(), + items, + } + } + + pub fn json(&self) -> Vec { + serde_json::to_vec(self).unwrap_or_default() + } +} + +pub fn encode(batch: &Batch) -> Vec { + ruzstd::encoding::compress_to_vec( + batch.json().as_slice(), + ruzstd::encoding::CompressionLevel::Fastest, + ) +} + +/// Inflates and checks a batch: its size before and after, its schema and install ID, and +/// every item. +pub fn decode(bytes: &[u8]) -> Result { + if bytes.len() > MAX_COMPRESSED { + return Err(format!("over {MAX_COMPRESSED} bytes")); + } + let decoder = ruzstd::decoding::StreamingDecoder::new(bytes).map_err(|e| e.to_string())?; + let mut json = Vec::new(); + decoder + .take(MAX_JSON as u64 + 1) + .read_to_end(&mut json) + .map_err(|e| e.to_string())?; + if json.len() > MAX_JSON { + return Err(format!("over {MAX_JSON} bytes inflated")); + } + let batch: Batch = serde_json::from_slice(&json).map_err(|e| e.to_string())?; + if batch.schema == 0 || batch.schema > crate::SCHEMA { + return Err(format!("unknown schema {}", batch.schema)); + } + if !is_install_id(&batch.install_id) { + return Err("not an install ID".into()); + } + if batch.items.is_empty() || batch.items.len() > MAX_ITEMS { + return Err(format!("1 to {MAX_ITEMS} items")); + } + batch.items.iter().try_for_each(Item::validate)?; + Ok(batch) +} + +/// Splits items into batches of at most [`MAX_ITEMS`] and [`MAX_JSON`] bytes, in order. +pub fn split(items: Vec<(T, Item)>) -> Vec> { + let mut batches: Vec> = Vec::new(); + let mut size = 0; + for (tag, item) in items { + let len = serde_json::to_vec(&item).map_or(0, |j| j.len()) + 1; + let full = batches + .last() + .is_none_or(|b| b.len() >= MAX_ITEMS || size + len > MAX_JSON - 1024); + if full { + batches.push(Vec::new()); + size = 0; + } + size += len; + if let Some(batch) = batches.last_mut() { + batch.push((tag, item)); + } + } + batches +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::payload::{Crash, Payload, Perf, Source, Timings}; + + const ID: &str = "0123456789abcdef0123456789abcdef"; + + fn perf() -> Item { + let mut t = Timings::new(); + (0..50_000).for_each(|i| t.record(6.0 + (i % 97) as f32 / 10.0)); + Item::new( + Source::Game, + "v0.4.2", + Payload::Perf(Perf { + frames: t.summary(), + seconds: 600, + ..Perf::default() + }), + ) + } + + #[test] + fn a_batch_round_trips_and_compresses() { + let batch = Batch::new(ID, vec![perf(); 12]); + let bytes = encode(&batch); + assert_eq!(decode(&bytes).unwrap(), batch); + let json = batch.json().len(); + assert!(bytes.len() * 4 < json, "{} of {json} bytes", bytes.len()); + assert!( + bytes.len() < 2048, + "a day's sessions: {} bytes", + bytes.len() + ); + } + + #[test] + fn bad_batches_are_refused() { + assert!(decode(b"not zstd").is_err()); + assert!( + decode(&vec![0; MAX_COMPRESSED + 1]) + .unwrap_err() + .contains("over") + ); + let mut batch = Batch::new("someone", vec![perf()]); + assert!(decode(&encode(&batch)).unwrap_err().contains("install ID")); + batch.install_id = ID.into(); + batch.schema = crate::SCHEMA + 1; + assert!(decode(&encode(&batch)).unwrap_err().contains("schema")); + batch.schema = crate::SCHEMA; + batch.items.clear(); + assert!(decode(&encode(&batch)).is_err()); + let huge = Item::new( + Source::Game, + "v1", + Payload::Crash(Crash { + stack: "x".repeat(40_000), + ..Crash::default() + }), + ); + assert!( + decode(&encode(&Batch::new(ID, vec![huge]))) + .unwrap_err() + .contains("over its") + ); + } + + #[test] + fn a_zip_bomb_stops_at_the_limit() { + // Compresses to a few kilobytes, inflates past the limit. + let json = format!( + r#"{{"schema":1,"install_id":"{ID}","items":[],"pad":"{}"}}"#, + " ".repeat(MAX_JSON * 4) + ); + let bytes = ruzstd::encoding::compress_to_vec( + json.as_bytes(), + ruzstd::encoding::CompressionLevel::Fastest, + ); + assert!(bytes.len() < MAX_COMPRESSED); + assert!(decode(&bytes).unwrap_err().contains("inflated")); + } + + #[test] + fn items_split_into_batches_by_count_and_size() { + let items: Vec<(usize, Item)> = (0..150).map(|i| (i, perf())).collect(); + let batches = split(items); + assert_eq!( + batches.iter().map(Vec::len).collect::>(), + [64, 64, 22] + ); + assert_eq!(batches[2].last().unwrap().0, 149); + let big = || { + Item::new( + Source::Launcher, + "0.1.5", + Payload::Benchmark(serde_json::json!({"pad": "x".repeat(120_000)})), + ) + }; + let batches = split((0..20).map(|i| (i, big())).collect()); + assert!(batches.len() >= 3); + for batch in batches { + let json = Batch::new(ID, batch.into_iter().map(|b| b.1).collect()).json(); + assert!(json.len() <= MAX_JSON); + } + } +} diff --git a/crates/horizon-telemetry/src/consent.rs b/crates/horizon-telemetry/src/consent.rs new file mode 100644 index 000000000..df1fb3368 --- /dev/null +++ b/crates/horizon-telemetry/src/consent.rs @@ -0,0 +1,191 @@ +//! The player's answer, kept in `telemetry/consent.json` in the game folder: one switch per +//! kind of data, all off until they turn one on, with the consent version and when they answered. +use std::path::{Path, PathBuf}; + +use serde::{Deserialize, Serialize}; + +use crate::{CONSENT_VERSION, Kind}; + +/// What the player allows, kind by kind. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +pub struct Choices { + /// Performance summaries: frame-time percentiles and buckets, tick times, memory, startup. + pub performance: bool, + /// Crash reports, without paths, names or addresses. + pub crashes: bool, + /// Bug reports the player writes and sends themselves. + pub bugs: bool, + /// Benchmark reports from the launcher and the game. + pub benchmarks: bool, +} + +impl Choices { + pub const NONE: Self = Self { + performance: false, + crashes: false, + bugs: false, + benchmarks: false, + }; + pub const ALL: Self = Self { + performance: true, + crashes: true, + bugs: true, + benchmarks: true, + }; + + pub fn allows(self, kind: Kind) -> bool { + match kind { + Kind::Perf => self.performance, + Kind::Crash => self.crashes, + Kind::Bug => self.bugs, + Kind::Benchmark => self.benchmarks, + } + } + + pub fn set(&mut self, kind: Kind, on: bool) { + match kind { + Kind::Perf => self.performance = on, + Kind::Crash => self.crashes = on, + Kind::Bug => self.bugs = on, + Kind::Benchmark => self.benchmarks = on, + } + } + + pub fn any(self) -> bool { + Kind::ALL.into_iter().any(|k| self.allows(k)) + } +} + +#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +pub struct Consent { + /// The [`CONSENT_VERSION`] the player answered; 0 if they never did. + pub version: u32, + /// When they answered, in seconds since 1970 (UTC). + pub answered: u64, + pub choices: Choices, + /// Random, made at the first yes and replaced on reset; it ties a player's items together + /// so they can be deleted, and nothing else. Empty until then. + #[serde(skip_serializing_if = "String::is_empty")] + pub install_id: String, +} + +impl Consent { + pub fn path(home: &Path) -> PathBuf { + crate::dir(home).join("consent.json") + } + + /// The saved answer; a missing or unreadable file is "never asked", which allows nothing. + pub fn load(home: &Path) -> Self { + std::fs::read(Self::path(home)) + .ok() + .and_then(|b| serde_json::from_slice(&b).ok()) + .unwrap_or_default() + } + + pub fn save(&self, home: &Path) -> std::io::Result<()> { + let json = serde_json::to_vec_pretty(self).map_err(std::io::Error::other)?; + crate::write_atomic(&Self::path(home), &json) + } + + /// Whether the launcher should ask: never answered, or what is collected has changed since. + pub fn needs_asking(&self) -> bool { + self.version < CONSENT_VERSION + } + + /// Whether items of `kind` may be kept and sent. Never before an answer to the current + /// question (a newer launcher's answer covers an older game's). + pub fn allows(&self, kind: Kind) -> bool { + !self.needs_asking() && !self.install_id.is_empty() && self.choices.allows(kind) + } + + /// Records the player's answer now. The install ID is made at the first yes and kept when + /// they turn everything off, so "Delete my data" can still name it. + pub fn answer(&mut self, choices: Choices) { + self.version = CONSENT_VERSION; + self.answered = crate::now_secs(); + self.choices = choices; + if choices.any() && self.install_id.is_empty() { + self.install_id = new_install_id(); + } + } + + /// A new install ID (after "Delete my data"): nothing sent later links to what came before. + pub fn reset_install_id(&mut self) { + self.install_id = if self.choices.any() { + new_install_id() + } else { + String::new() + }; + } +} + +/// 128 random bits in hex. +pub fn new_install_id() -> String { + crate::random_hex(16) +} + +/// Whether `id` looks like one of ours: 32 lowercase hex digits. +pub fn is_install_id(id: &str) -> bool { + id.len() == 32 && id.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f')) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn nothing_is_allowed_before_the_player_answers() { + let home = crate::test_home::new("consent-default"); + let consent = Consent::load(&home); + assert!(consent.needs_asking()); + assert!(Kind::ALL.iter().all(|&k| !consent.allows(k))); + // A broken file is the same as none. + std::fs::create_dir_all(crate::dir(&home)).unwrap(); + std::fs::write(Consent::path(&home), b"{not json").unwrap(); + assert_eq!(Consent::load(&home), Consent::default()); + } + + #[test] + fn an_answer_allows_only_what_was_chosen_and_is_saved() { + let home = crate::test_home::new("consent-answer"); + let mut consent = Consent::load(&home); + consent.answer(Choices { + crashes: true, + ..Choices::NONE + }); + consent.save(&home).unwrap(); + let back = Consent::load(&home); + assert_eq!(back, consent); + assert!(!back.needs_asking()); + assert!(back.allows(Kind::Crash)); + assert!(!back.allows(Kind::Perf) && !back.allows(Kind::Bug)); + assert!(!back.allows(Kind::Benchmark)); + assert!(is_install_id(&back.install_id)); + assert!(back.answered > 1_700_000_000); + } + + #[test] + fn an_older_answer_allows_nothing_until_asked_again() { + let mut consent = Consent::default(); + consent.answer(Choices::ALL); + consent.version = CONSENT_VERSION - 1; + assert!(consent.needs_asking()); + assert!(Kind::ALL.iter().all(|&k| !consent.allows(k))); + } + + #[test] + fn no_id_is_made_for_a_no_and_a_reset_changes_it() { + let mut consent = Consent::default(); + consent.answer(Choices::NONE); + assert!(consent.install_id.is_empty()); + consent.answer(Choices::ALL); + let first = consent.install_id.clone(); + consent.answer(Choices::NONE); + assert_eq!(consent.install_id, first, "kept so the data can be deleted"); + consent.answer(Choices::ALL); + consent.reset_install_id(); + assert!(is_install_id(&consent.install_id) && consent.install_id != first); + } +} diff --git a/crates/horizon-telemetry/src/lib.rs b/crates/horizon-telemetry/src/lib.rs new file mode 100644 index 000000000..e903936db --- /dev/null +++ b/crates/horizon-telemetry/src/lib.rs @@ -0,0 +1,97 @@ +//! Opt-in data collection, shared by the launcher, the game and the ingest server. +//! +//! Nothing is collected or sent until the player says yes, kind by kind ([`Consent`]): the +//! game and the launcher only [`outbox::push`] items whose kind is allowed, and the launcher's +//! [`upload::flush`] drops anything the player has since turned off before it opens a +//! connection. Items are small summaries (percentiles and histogram buckets, never raw streams), +//! dated to the day, with no account, world, server or address in them ([`scrub`]); they leave +//! in zstd batches ([`batch`]). `docs/telemetry.md` lists every field. +use std::path::{Path, PathBuf}; +use std::time::{SystemTime, UNIX_EPOCH}; + +pub mod batch; +pub mod consent; +pub mod outbox; +pub mod payload; +pub mod scrub; +pub mod system; +#[cfg(feature = "upload")] +pub mod upload; + +pub use consent::{Choices, Consent}; +pub use payload::{Item, Kind, Payload, Source}; + +/// The payload format. New optional fields keep it; a field that changes meaning or goes +/// bumps it, and the server keeps reading the older ones. +pub const SCHEMA: u32 = 1; + +/// What players agree to. Bumped when what is collected changes: the launcher then asks again, +/// and until the player answers nothing new is kept or sent. +pub const CONSENT_VERSION: u32 = 1; + +/// The ingest server, or none while there isn't one: then nothing is ever sent and the outbox +/// stays within its caps. `HORIZON_TELEMETRY_URL` overrides it (tests, a local server). +pub const DEFAULT_ENDPOINT: Option<&str> = None; + +/// Where items are sent, if anywhere. +pub fn endpoint() -> Option { + match std::env::var("HORIZON_TELEMETRY_URL") { + Ok(url) if !url.trim().is_empty() => Some(url.trim().trim_end_matches('/').to_owned()), + _ => DEFAULT_ENDPOINT.map(str::to_owned), + } +} + +/// `telemetry/` in the game folder: the consent, the outbox and the upload state, read by the +/// launcher and the game alike. +pub fn dir(home: &Path) -> PathBuf { + home.join("telemetry") +} + +/// Days since 1970-01-01 (UTC): the only time an item carries. +pub fn today() -> u32 { + (now_secs() / 86_400) as u32 +} + +pub(crate) fn now_secs() -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |d| d.as_secs()) +} + +/// `bytes` random bytes in lowercase hex. +pub(crate) fn random_hex(bytes: usize) -> String { + let mut buf = vec![0u8; bytes]; + // Without the OS's randomness the time still makes names that don't collide in practice. + if getrandom::fill(&mut buf).is_err() { + let nanos = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |d| d.as_nanos()); + for (i, b) in buf.iter_mut().enumerate() { + *b = (nanos >> (8 * (i % 16))) as u8; + } + } + buf.iter().map(|b| format!("{b:02x}")).collect() +} + +/// Writes `bytes` through a temporary file, so a reader never sees half of it. +pub(crate) fn write_atomic(path: &Path, bytes: &[u8]) -> std::io::Result<()> { + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent)?; + } + let tmp = path.with_extension(format!("tmp-{}", random_hex(4))); + std::fs::write(&tmp, bytes)?; + std::fs::rename(&tmp, path) +} + +#[cfg(test)] +pub(crate) mod test_home { + use std::path::PathBuf; + + /// An empty folder of its own under the system's temporary folder. + pub fn new(name: &str) -> PathBuf { + let dir = + std::env::temp_dir().join(format!("horizon-telemetry-{name}-{}", super::random_hex(6))); + std::fs::create_dir_all(&dir).unwrap(); + dir + } +} diff --git a/crates/horizon-telemetry/src/outbox.rs b/crates/horizon-telemetry/src/outbox.rs new file mode 100644 index 000000000..3464b177b --- /dev/null +++ b/crates/horizon-telemetry/src/outbox.rs @@ -0,0 +1,236 @@ +//! Items waiting to be sent: one small JSON file each in `telemetry/outbox/`, written by the game +//! and the launcher, sent and removed by the launcher's [`crate::upload::flush`]. Only kinds the +//! player allows get in, each within its daily cap, and the folder never holds more than +//! [`MAX_FILES`] items or [`MAX_BYTES`]. +use std::path::{Path, PathBuf}; + +use serde::{Deserialize, Serialize}; + +use crate::{Consent, Item, Kind}; + +pub const MAX_FILES: usize = 200; +pub const MAX_BYTES: u64 = 2 * 1024 * 1024; + +pub fn dir(home: &Path) -> PathBuf { + crate::dir(home).join("outbox") +} + +/// How many items of each kind were kept today, so a crash loop doesn't fill the outbox. +#[derive(Default, Serialize, Deserialize)] +#[serde(default)] +struct Kept { + day: u32, + counts: [u32; 4], +} + +fn kept_path(home: &Path) -> PathBuf { + crate::dir(home).join("kept.json") +} + +/// Keeps `item` to be sent later if the player allows its kind and today's cap for it isn't +/// reached; returns whether it was kept. An invalid item (too large…) is an error. +pub fn push(home: &Path, item: &Item) -> std::io::Result { + let kind = item.kind(); + if !Consent::load(home).allows(kind) { + return Ok(false); + } + item.validate().map_err(std::io::Error::other)?; + let today = crate::today(); + let mut kept: Kept = std::fs::read(kept_path(home)) + .ok() + .and_then(|b| serde_json::from_slice(&b).ok()) + .filter(|k: &Kept| k.day == today) + .unwrap_or(Kept { + day: today, + ..Kept::default() + }); + let slot = Kind::ALL.iter().position(|&k| k == kind).unwrap_or(0); + if kept.counts[slot] >= kind.daily_cap() { + return Ok(false); + } + let json = serde_json::to_vec(item).map_err(std::io::Error::other)?; + let dir = dir(home); + std::fs::create_dir_all(&dir)?; + make_room(&dir, json.len() as u64)?; + // Names sort by day, so the oldest go first when there is no room. + let name = format!( + "{:06}-{}-{}.json", + item.day, + kind.name(), + crate::random_hex(6) + ); + crate::write_atomic(&dir.join(name), &json)?; + kept.counts[slot] += 1; + let kept = serde_json::to_vec(&kept).map_err(std::io::Error::other)?; + crate::write_atomic(&kept_path(home), &kept)?; + Ok(true) +} + +fn files(dir: &Path) -> Vec<(PathBuf, u64)> { + let mut files: Vec<(PathBuf, u64)> = std::fs::read_dir(dir) + .into_iter() + .flatten() + .flatten() + .filter(|e| e.path().extension().is_some_and(|x| x == "json")) + .map(|e| (e.path(), e.metadata().map_or(0, |m| m.len()))) + .collect(); + files.sort(); + files +} + +/// Removes the oldest items until one more of `incoming` bytes fits. +fn make_room(dir: &Path, incoming: u64) -> std::io::Result<()> { + let files = files(dir); + let mut count = files.len(); + let mut bytes: u64 = files.iter().map(|f| f.1).sum(); + for (path, size) in files { + if count < MAX_FILES && bytes + incoming <= MAX_BYTES { + break; + } + std::fs::remove_file(path)?; + count -= 1; + bytes -= size; + } + Ok(()) +} + +/// The items waiting, oldest first, with their files. Unreadable files are removed. +pub fn pending(home: &Path) -> Vec<(PathBuf, Item)> { + files(&dir(home)) + .into_iter() + .filter_map(|(path, _)| { + let item = std::fs::read(&path) + .ok() + .and_then(|b| serde_json::from_slice::(&b).ok()); + if item.is_none() { + let _ = std::fs::remove_file(&path); + } + item.map(|i| (path, i)) + }) + .collect() +} + +/// The waiting items the player still allows, oldest first; the others are deleted, never sent. +pub fn retain_allowed(home: &Path) -> Vec<(PathBuf, Item)> { + let consent = Consent::load(home); + pending(home) + .into_iter() + .filter(|(path, item)| { + let allowed = consent.allows(item.kind()); + if !allowed { + let _ = std::fs::remove_file(path); + } + allowed + }) + .collect() +} + +/// Removes every waiting item ("Delete my data", or everything turned off). +pub fn clear(home: &Path) -> std::io::Result<()> { + match std::fs::remove_dir_all(dir(home)) { + Err(e) if e.kind() != std::io::ErrorKind::NotFound => Err(e), + _ => Ok(()), + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::payload::{Bug, Crash, Payload, Source}; + use crate::{Choices, test_home}; + + fn allow(home: &Path, choices: Choices) { + let mut consent = Consent::load(home); + consent.answer(choices); + consent.save(home).unwrap(); + } + + fn crash() -> Item { + Item::new(Source::Game, "v1", Payload::Crash(Crash::default())) + } + + #[test] + fn nothing_is_kept_without_consent_for_its_kind() { + let home = test_home::new("outbox-consent"); + assert!(!push(&home, &crash()).unwrap()); + allow( + &home, + Choices { + bugs: true, + ..Choices::NONE + }, + ); + assert!(!push(&home, &crash()).unwrap()); + assert!(pending(&home).is_empty()); + assert!(!dir(&home).exists()); + allow( + &home, + Choices { + crashes: true, + ..Choices::NONE + }, + ); + assert!(push(&home, &crash()).unwrap()); + assert_eq!(pending(&home).len(), 1); + assert_eq!(pending(&home)[0].1, crash()); + } + + #[test] + fn each_kind_has_a_daily_cap() { + let home = test_home::new("outbox-cap"); + allow(&home, Choices::ALL); + let kept = (0..20).filter(|_| push(&home, &crash()).unwrap()).count(); + assert_eq!(kept as u32, Kind::Crash.daily_cap()); + // Another kind still gets in. + let bug = Item::new( + Source::Launcher, + "0.1.5", + Payload::Bug(Bug { + text: "x".into(), + ..Bug::default() + }), + ); + assert!(push(&home, &bug).unwrap()); + } + + #[test] + fn the_oldest_items_make_room() { + let home = test_home::new("outbox-room"); + allow(&home, Choices::ALL); + let dir = dir(&home); + std::fs::create_dir_all(&dir).unwrap(); + let old = serde_json::to_vec(&crash()).unwrap(); + for i in 0..MAX_FILES { + std::fs::write(dir.join(format!("000001-crash-{i:04}.json")), &old).unwrap(); + } + assert!(push(&home, &crash()).unwrap()); + let files = files(&dir); + assert_eq!(files.len(), MAX_FILES); + assert!(!dir.join("000001-crash-0000.json").exists()); + assert!( + files + .last() + .unwrap() + .0 + .file_name() + .unwrap() + .to_str() + .unwrap() + .starts_with(&format!("{:06}", crate::today())) + ); + } + + #[test] + fn invalid_items_and_broken_files_are_refused() { + let home = test_home::new("outbox-invalid"); + allow(&home, Choices::ALL); + let empty_bug = Item::new(Source::Game, "v1", Payload::Bug(Bug::default())); + assert!(push(&home, &empty_bug).is_err()); + std::fs::create_dir_all(dir(&home)).unwrap(); + std::fs::write(dir(&home).join("000001-bug-x.json"), b"{").unwrap(); + assert!(pending(&home).is_empty()); + assert!(files(&dir(&home)).is_empty()); + clear(&home).unwrap(); + clear(&home).unwrap(); + } +} diff --git a/crates/horizon-telemetry/src/payload.rs b/crates/horizon-telemetry/src/payload.rs new file mode 100644 index 000000000..1429a7116 --- /dev/null +++ b/crates/horizon-telemetry/src/payload.rs @@ -0,0 +1,421 @@ +//! What an item holds. Summaries only: a session's frame times become a few percentiles and +//! [`BUCKET_EDGES_MS`] counts; benchmark reports are the documented report +//! (`docs/benchmark-report.md`) as it is. +use serde::{Deserialize, Serialize}; + +/// The four kinds of data a player can allow, one switch each. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Kind { + Perf, + Crash, + Bug, + Benchmark, +} + +impl Kind { + pub const ALL: [Kind; 4] = [Kind::Perf, Kind::Crash, Kind::Bug, Kind::Benchmark]; + + pub fn name(self) -> &'static str { + match self { + Kind::Perf => "perf", + Kind::Crash => "crash", + Kind::Bug => "bug", + Kind::Benchmark => "benchmark", + } + } + + pub fn from_name(name: &str) -> Option { + Kind::ALL.into_iter().find(|k| k.name() == name) + } + + /// The largest an item of this kind may be, as JSON. + pub fn max_bytes(self) -> usize { + match self { + Kind::Perf => 4 * 1024, + Kind::Crash => 32 * 1024, + Kind::Bug => 80 * 1024, + Kind::Benchmark => 128 * 1024, + } + } + + /// How many items of this kind one install keeps a day; the rest are dropped. + pub fn daily_cap(self) -> u32 { + match self { + Kind::Perf => 12, + Kind::Crash => 5, + Kind::Bug => 5, + Kind::Benchmark => 10, + } + } +} + +/// What made the item. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Source { + Launcher, + Game, +} + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +pub struct Item { + /// Days since 1970 (UTC): no finer time is kept. + pub day: u32, + pub source: Source, + /// The Horizon release (`v0.4.2`), or the launcher's version. + pub version: String, + #[serde(flatten)] + pub payload: Payload, +} + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(tag = "kind", content = "data", rename_all = "snake_case")] +pub enum Payload { + Perf(Perf), + Crash(Crash), + Bug(Bug), + /// A benchmark report as `docs/benchmark-report.md` defines it, with its own schema field. + Benchmark(serde_json::Value), +} + +impl Item { + pub fn new(source: Source, version: impl Into, payload: Payload) -> Self { + Self { + day: crate::today(), + source, + version: version.into(), + payload, + } + } + + pub fn kind(&self) -> Kind { + match self.payload { + Payload::Perf(_) => Kind::Perf, + Payload::Crash(_) => Kind::Crash, + Payload::Bug(_) => Kind::Bug, + Payload::Benchmark(_) => Kind::Benchmark, + } + } + + /// Checks what the client and the server both refuse: an item over its kind's size, an + /// overlong text, a benchmark report that is not an object. + pub fn validate(&self) -> Result<(), String> { + let size = serde_json::to_vec(self).map_or(usize::MAX, |j| j.len()); + let kind = self.kind(); + if size > kind.max_bytes() { + return Err(format!( + "a {} item of {size} bytes is over its {} bytes", + kind.name(), + kind.max_bytes() + )); + } + if self.version.len() > 64 { + return Err("the version is too long".into()); + } + match &self.payload { + Payload::Bug(bug) if bug.text.trim().is_empty() => { + Err("a bug report needs text".into()) + } + Payload::Bug(bug) if bug.text.chars().count() > Bug::MAX_TEXT => Err(format!( + "a bug report is at most {} characters", + Bug::MAX_TEXT + )), + Payload::Benchmark(report) if !report.is_object() => { + Err("a benchmark report is a JSON object".into()) + } + _ => Ok(()), + } + } +} + +/// The machine, as coarse as is useful: no serial numbers, names or exact memory. +#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +pub struct System { + /// `linux`, `macos` or `windows`. + pub os: String, + /// The distribution or system version (`macOS 26.0`, `Fedora Linux 43`). + pub os_version: String, + pub arch: String, + pub cpu: String, + pub threads: u16, + /// Installed memory, rounded to the GiB. + pub ram_gb: u16, + pub gpu: String, + pub driver: String, + /// `Metal`, `Vulkan`, `Dx12`… + pub backend: String, +} + +/// The settings that change performance. +#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +pub struct Settings { + pub render_distance: u8, + pub simulation_distance: u8, + /// 0: unlimited. + pub max_fps: u16, + pub vsync: bool, + pub fullscreen: bool, + /// `fast`, `fancy` or `fabulous`. + pub graphics: String, +} + +/// One play session's performance. +#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)] +#[serde(default)] +pub struct Perf { + pub system: System, + pub settings: Settings, + /// Seconds of play measured (menus and loading screens excluded). + pub seconds: u32, + pub frames: Summary, + /// The integrated server's milliseconds per tick, in single player. + #[serde(skip_serializing_if = "Option::is_none")] + pub ticks: Option, + /// The game's peak resident memory. + pub peak_ram_mb: u32, + /// From start to the title screen. + #[serde(skip_serializing_if = "Option::is_none")] + pub to_title_ms: Option, + /// From choosing a world to playing in it, the first time this session. + #[serde(skip_serializing_if = "Option::is_none")] + pub to_world_ms: Option, +} + +/// A crash, scrubbed: the error and its stack, the thread, and the details that say what the +/// game was doing (graphics adapter, settings), never its log, world or server. +#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +pub struct Crash { + pub system: System, + pub error: String, + /// One frame a line, `function (file:line:col)`. + pub stack: String, + pub thread: String, + pub details: Vec<(String, String)>, +} + +/// A bug report the player wrote, with the log only if they chose to add it after reading it. +#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +pub struct Bug { + pub system: System, + pub text: String, + #[serde(skip_serializing_if = "Option::is_none")] + pub log: Option, +} + +impl Bug { + pub const MAX_TEXT: usize = 4000; +} + +/// Durations at a glance: percentiles and how many fell in each of [`BUCKET_EDGES_MS`]. +#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)] +#[serde(default)] +pub struct Summary { + pub count: u64, + pub p50_ms: f32, + pub p95_ms: f32, + pub p99_ms: f32, + pub max_ms: f32, + /// One count a bucket: under 4 ms, 4–6 ms, … 100–250 ms, 250 ms and more. + pub buckets: Vec, +} + +/// The upper edges of [`Summary::buckets`] in milliseconds, around the usual refresh rates +/// (240, 165, 144, 120, 60, 30 Hz…); the last bucket has no edge. +pub const BUCKET_EDGES_MS: [f32; 13] = [ + 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.7, 20.0, 25.0, 33.3, 50.0, 100.0, 250.0, +]; + +/// Records durations in tenths of a millisecond up to [`Timings::FINE_MS`] (beyond, they count +/// at the top) for percentiles finer than the buckets; 20 KB whatever the session's length. +#[derive(Clone, Debug)] +pub struct Timings { + tenths: Vec, + count: u64, + max_ms: f32, +} + +impl Default for Timings { + fn default() -> Self { + Self::new() + } +} + +impl Timings { + pub const FINE_MS: usize = 500; + + pub fn new() -> Self { + Self { + tenths: vec![0; Self::FINE_MS * 10 + 1], + count: 0, + max_ms: 0.0, + } + } + + pub fn record(&mut self, ms: f32) { + if !ms.is_finite() || ms < 0.0 { + return; + } + let bin = ((ms * 10.0) as usize).min(self.tenths.len() - 1); + self.tenths[bin] = self.tenths[bin].saturating_add(1); + self.count += 1; + self.max_ms = self.max_ms.max(ms); + } + + pub fn count(&self) -> u64 { + self.count + } + + /// The duration under which a fraction `p` of them fell, to the tenth of a millisecond. + fn percentile(&self, p: f64) -> f32 { + let rank = ((self.count as f64 * p).ceil() as u64).max(1); + let mut seen = 0u64; + for (bin, &n) in self.tenths.iter().enumerate() { + seen += u64::from(n); + if seen >= rank { + return if bin + 1 == self.tenths.len() { + self.max_ms + } else { + ((bin + 1) as f32 / 10.0).min(self.max_ms) + }; + } + } + self.max_ms + } + + pub fn summary(&self) -> Summary { + let mut buckets = vec![0u32; BUCKET_EDGES_MS.len() + 1]; + for (bin, &n) in self.tenths.iter().enumerate() { + let ms = bin as f32 / 10.0; + let bucket = BUCKET_EDGES_MS + .iter() + .position(|&edge| ms < edge - 0.01) + .unwrap_or(BUCKET_EDGES_MS.len()); + buckets[bucket] = buckets[bucket].saturating_add(n); + } + let round = |ms: f32| (ms * 10.0).round() / 10.0; + Summary { + count: self.count, + p50_ms: round(self.percentile(0.50)), + p95_ms: round(self.percentile(0.95)), + p99_ms: round(self.percentile(0.99)), + max_ms: round(self.max_ms), + buckets, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn items_are_tagged_by_kind_and_read_back() { + let item = Item::new( + Source::Game, + "v0.4.2", + Payload::Bug(Bug { + text: "Water flickers".into(), + ..Bug::default() + }), + ); + let json = serde_json::to_value(&item).unwrap(); + assert_eq!(json["kind"], "bug"); + assert_eq!(json["source"], "game"); + assert_eq!(json["data"]["text"], "Water flickers"); + assert_eq!(serde_json::from_value::(json).unwrap(), item); + } + + #[test] + fn a_benchmark_report_is_carried_as_it_is() { + let report = serde_json::json!({"schema": "horizon-benchmark-report/1", "scenes": []}); + let item = Item::new( + Source::Launcher, + "0.1.5", + Payload::Benchmark(report.clone()), + ); + let json = serde_json::to_value(&item).unwrap(); + assert_eq!(json["data"], report); + assert!(item.validate().is_ok()); + let not_object = Item::new(Source::Launcher, "0.1.5", Payload::Benchmark(1.into())); + assert!(not_object.validate().is_err()); + } + + #[test] + fn oversized_items_are_refused() { + let bug = |text: String| { + Item::new( + Source::Game, + "v1", + Payload::Bug(Bug { + text, + ..Bug::default() + }), + ) + }; + assert!(bug("x".repeat(Bug::MAX_TEXT)).validate().is_ok()); + assert!(bug("x".repeat(Bug::MAX_TEXT + 1)).validate().is_err()); + assert!(bug(" ".into()).validate().is_err()); + let huge = Item::new( + Source::Game, + "v1", + Payload::Crash(Crash { + stack: "frame\n".repeat(10_000), + ..Crash::default() + }), + ); + assert!(huge.validate().unwrap_err().contains("over its")); + } + + #[test] + fn timings_give_percentiles_and_buckets() { + let mut t = Timings::new(); + // 90 frames at 16.6 ms (60 Hz), 9 at 30 ms, one 400 ms hitch. + (0..90).for_each(|_| t.record(16.6)); + (0..9).for_each(|_| t.record(30.0)); + t.record(400.0); + t.record(f32::NAN); + let s = t.summary(); + assert_eq!(s.count, 100); + assert_eq!(s.p50_ms, 16.7); + assert_eq!(s.p95_ms, 30.1); + assert_eq!(s.p99_ms, 30.1); + assert_eq!(s.max_ms, 400.0); + assert_eq!(s.buckets.len(), 14); + assert_eq!(s.buckets[6], 90, "14–16.7 ms"); + assert_eq!(s.buckets[9], 9, "25–33.3 ms"); + assert_eq!(s.buckets[13], 1, "250 ms and more"); + assert_eq!(s.buckets.iter().sum::(), 100); + } + + #[test] + fn hitches_beyond_the_fine_range_keep_their_maximum() { + let mut t = Timings::new(); + t.record(2_000.0); + let s = t.summary(); + assert_eq!((s.p50_ms, s.max_ms), (2_000.0, 2_000.0)); + assert_eq!(s.buckets[13], 1); + } + + #[test] + fn a_session_summary_is_small() { + let mut t = Timings::new(); + (0..200_000).for_each(|i| t.record(5.0 + (i % 300) as f32 / 10.0)); + let perf = Item::new( + Source::Game, + "v0.4.2", + Payload::Perf(Perf { + frames: t.summary(), + ticks: Some(t.summary()), + ..Perf::default() + }), + ); + let size = serde_json::to_vec(&perf).unwrap().len(); + assert!(size < 1024, "{size} bytes"); + assert!(perf.validate().is_ok()); + } +} diff --git a/crates/horizon-telemetry/src/scrub.rs b/crates/horizon-telemetry/src/scrub.rs new file mode 100644 index 000000000..559846bb8 --- /dev/null +++ b/crates/horizon-telemetry/src/scrub.rs @@ -0,0 +1,354 @@ +//! Takes out of text what could say who or where a player is, before it is kept to be sent: +//! the user folder's name in paths, the user name, e-mail and IP addresses, UUIDs (accounts), +//! and the terms the caller knows are private (world names, server addresses, account names). + +/// What replaces each kind of match. +pub const USER: &str = ""; +pub const EMAIL: &str = ""; +pub const IP: &str = ""; +pub const UUID: &str = ""; +pub const PRIVATE: &str = ""; + +#[derive(Clone, Debug, Default)] +pub struct Scrubber { + /// Exact terms to hide, longest first. + terms: Vec, + user: Option, +} + +impl Scrubber { + /// A scrubber that also knows this machine's user name. + pub fn new() -> Self { + let user = ["USER", "USERNAME", "LOGNAME"] + .iter() + .find_map(|k| std::env::var(k).ok().filter(|u| u.trim().len() >= 3)); + Self { + terms: Vec::new(), + user, + } + } + + /// Without the machine's user name (tests). + pub fn bare() -> Self { + Self::default() + } + + pub fn with_user(mut self, user: impl Into) -> Self { + self.user = Some(user.into()).filter(|u| u.trim().len() >= 3); + self + } + + /// Hides `term` wherever it appears. Terms under 3 characters are ignored: they would + /// blank out ordinary words. + pub fn term(mut self, term: impl Into) -> Self { + let term = term.into(); + if term.trim().len() >= 3 && !self.terms.contains(&term) { + self.terms.push(term); + self.terms.sort_by_key(|t| std::cmp::Reverse(t.len())); + } + self + } + + pub fn scrub(&self, text: &str) -> String { + let mut out = text.to_owned(); + for term in &self.terms { + out = out.replace(term.as_str(), PRIVATE); + } + out = user_folders(&out); + out = replace_tokens(&out, email_at); + out = replace_tokens(&out, ipv4_at); + out = replace_tokens(&out, ipv6_at); + out = replace_tokens(&out, uuid_at); + if let Some(user) = &self.user { + out = replace_word(&out, user, USER); + } + out + } +} + +/// `/Users/ana/…`, `/home/ana/…`, `C:\Users\Ana Silva\…` (also JSON-escaped): the folder after +/// `Users` or `home` becomes [`USER`], the rest of the path stays. Windows names have spaces, so +/// the name runs to the next separator, quote, bracket or line end. +fn user_folders(text: &str) -> String { + let mut out = String::with_capacity(text.len()); + let mut rest = text; + 'scan: while !rest.is_empty() { + for parent in ["Users", "home"] { + for sep in ["/", "\\\\", "\\"] { + let head = format!("{sep}{parent}{sep}"); + if let Some(after) = rest.strip_prefix(head.as_str()) { + let name_len = after + .find(|c: char| { + matches!( + c, + '/' | '\\' | '"' | '\'' | '\n' | '\r' | ')' | ']' | ',' | ';' + ) + }) + .unwrap_or(after.len()); + out.push_str(&head); + if name_len > 0 { + out.push_str(USER); + } + rest = &after[name_len..]; + continue 'scan; + } + } + } + let c = rest.chars().next().unwrap_or_default(); + out.push(c); + rest = &rest[c.len_utf8()..]; + } + out +} + +/// Replaces every match of `matcher` (which returns the length of a match starting at a byte +/// offset, if one does) with its label. +fn replace_tokens( + text: &str, + matcher: fn(&[u8], usize) -> Option<(usize, &'static str)>, +) -> String { + let bytes = text.as_bytes(); + let mut out = String::with_capacity(text.len()); + let mut i = 0; + let mut copied = 0; + while i < bytes.len() { + if text.is_char_boundary(i) + && let Some((len, label)) = matcher(bytes, i) + { + out.push_str(&text[copied..i]); + out.push_str(label); + i += len; + copied = i; + } else { + i += 1; + } + } + out.push_str(&text[copied..]); + out +} + +fn word_byte(b: u8) -> bool { + b.is_ascii_alphanumeric() || b == b'_' +} + +/// Whether a token may start at `i`: not in the middle of a word, number or address. +fn starts_token(bytes: &[u8], i: usize) -> bool { + i == 0 || !(word_byte(bytes[i - 1]) || matches!(bytes[i - 1], b'.' | b':' | b'-' | b'@')) +} + +fn ends_token(bytes: &[u8], end: usize) -> bool { + end == bytes.len() || !word_byte(bytes[end]) +} + +fn email_at(bytes: &[u8], i: usize) -> Option<(usize, &'static str)> { + let local = |b: u8| word_byte(b) || matches!(b, b'.' | b'%' | b'+' | b'-'); + if !starts_token(bytes, i) || !local(bytes[i]) { + return None; + } + let at = i + bytes[i..].iter().position(|&b| !local(b))?; + if bytes.get(at) != Some(&b'@') { + return None; + } + let domain = |b: u8| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'-'); + let end = at + 1 + bytes[at + 1..].iter().take_while(|&&b| domain(b)).count(); + let host = &bytes[at + 1..end]; + let dot = host.iter().rposition(|&b| b == b'.')?; + (dot > 0 && host.len() - dot > 2).then_some((end - i, EMAIL)) +} + +fn ipv4_at(bytes: &[u8], i: usize) -> Option<(usize, &'static str)> { + if !starts_token(bytes, i) { + return None; + } + let mut end = i; + for part in 0..4 { + if part > 0 { + if bytes.get(end) != Some(&b'.') { + return None; + } + end += 1; + } + let digits = bytes[end..] + .iter() + .take_while(|b| b.is_ascii_digit()) + .count(); + if digits == 0 || digits > 3 { + return None; + } + let n: u32 = std::str::from_utf8(&bytes[end..end + digits]) + .ok()? + .parse() + .ok()?; + if n > 255 { + return None; + } + end += digits; + } + // A fifth part makes it a version number (`10.0.19045.1`), not an address. + if bytes.get(end) == Some(&b'.') && bytes.get(end + 1).is_some_and(u8::is_ascii_digit) { + return None; + } + // A port goes with it. + if bytes.get(end) == Some(&b':') { + let digits = bytes[end + 1..] + .iter() + .take_while(|b| b.is_ascii_digit()) + .count(); + if (1..=5).contains(&digits) { + end += 1 + digits; + } + } + ends_token(bytes, end).then_some((end - i, IP)) +} + +/// Eight hex groups with colons, or fewer around a `::` (at least three groups, so a Rust path +/// such as `a::b` is left alone). +fn ipv6_at(bytes: &[u8], i: usize) -> Option<(usize, &'static str)> { + if !starts_token(bytes, i) { + return None; + } + let len = bytes[i..] + .iter() + .take_while(|b| b.is_ascii_hexdigit() || **b == b':') + .count(); + let token = std::str::from_utf8(&bytes[i..i + len]).ok()?; + let token = token.trim_end_matches(':'); + let groups: Vec<&str> = token.split(':').collect(); + let filled = groups.iter().filter(|g| !g.is_empty()).count(); + let ok = groups.iter().all(|g| g.len() <= 4) + && (filled == 8 || (token.contains("::") && filled >= 3)) + && groups.iter().any(|g| g.bytes().any(|b| b.is_ascii_digit())); + (ok && ends_token(bytes, i + token.len())).then_some((token.len(), IP)) +} + +/// `0f8c…-…` (8-4-4-4-12) or the same 32 hex digits without dashes, as accounts are named. +fn uuid_at(bytes: &[u8], i: usize) -> Option<(usize, &'static str)> { + if !starts_token(bytes, i) { + return None; + } + let hex = |range: std::ops::Range| { + bytes + .get(range) + .is_some_and(|s| s.iter().all(u8::is_ascii_hexdigit)) + }; + let dashed = [8usize, 13, 18, 23] + .iter() + .all(|&d| bytes.get(i + d) == Some(&b'-')) + && [(0, 8), (9, 13), (14, 18), (19, 23), (24, 36)] + .iter() + .all(|&(a, b)| hex(i + a..i + b)); + if dashed && ends_token(bytes, i + 36) { + return Some((36, UUID)); + } + (hex(i..i + 32) && ends_token(bytes, i + 32)).then_some((32, UUID)) +} + +/// Whole-word occurrences of `word`, in any case. +fn replace_word(text: &str, word: &str, label: &str) -> String { + let lower = text.to_lowercase(); + let needle = word.to_lowercase(); + // Lowercasing can change byte lengths outside ASCII: then match exactly instead. + let (hay, needle) = if lower.len() == text.len() && needle.len() == word.len() { + (lower.as_str(), needle.as_str()) + } else { + (text, word) + }; + let bytes = text.as_bytes(); + let mut out = String::with_capacity(text.len()); + let mut copied = 0; + let mut from = 0; + while let Some(found) = hay[from..].find(needle) { + let start = from + found; + let end = start + needle.len(); + let alone = (start == 0 || !word_byte(bytes[start - 1])) && ends_token(bytes, end); + if alone { + out.push_str(&text[copied..start]); + out.push_str(label); + copied = end; + } + from = end; + } + out.push_str(&text[copied..]); + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn user_folders_lose_their_name() { + let s = Scrubber::bare(); + assert_eq!( + s.scrub("at /Users/ana.b/code/horizon/src/main.rs:10"), + "at /Users//code/horizon/src/main.rs:10" + ); + assert_eq!( + s.scrub("/home/ana/.local/share/horizon"), + "/home//.local/share/horizon" + ); + assert_eq!( + s.scrub("C:\\Users\\Ana Silva\\x\nnext"), + "C:\\Users\\\\x\nnext" + ); + assert_eq!(s.scrub(r"C:\Users\ana\AppData"), r"C:\Users\\AppData"); + assert_eq!( + s.scrub(r#"{"path":"C:\\Users\\ana\\AppData"}"#), + r#"{"path":"C:\\Users\\\\AppData"}"# + ); + assert_eq!(s.scrub("/usr/home/"), "/usr/home/"); + } + + #[test] + fn the_user_name_goes_wherever_it_stands_alone() { + let s = Scrubber::bare().with_user("ludo"); + assert_eq!( + s.scrub("Ludo's machine, user ludo"), + "'s machine, user " + ); + assert_eq!(s.scrub("ludovic"), "ludovic"); + assert_eq!(Scrubber::bare().with_user("al").scrub("al"), "al"); + } + + #[test] + fn addresses_and_accounts_are_hidden() { + let s = Scrubber::bare(); + assert_eq!(s.scrub("joined 192.168.1.20:25565 ok"), "joined ok"); + assert_eq!(s.scrub("from 10.0.0.1."), "from ."); + assert_eq!(s.scrub("[2a01:e0a:1f2::5]"), "[]"); + assert_eq!(s.scrub("mail ana.b+mc@example.org now"), "mail now"); + assert_eq!( + s.scrub( + "uuid 069a79f4-44e9-4726-a5be-fca90e38aaf5 and 069a79f444e94726a5befca90e38aaf5" + ), + "uuid and " + ); + } + + #[test] + fn code_and_versions_are_left_alone() { + let s = Scrubber::bare(); + for text in [ + "std::panicking::begin_panic (src/game.rs:12:5)", + "a::b::c", + "driver 31.0.15.3623, Windows 10.0.19045.1", + "wgpu 30.0.1", + "commit 9fceb02d0ae598e95dc970b74767f19372d61af8", + "user@host", + ] { + assert_eq!(s.scrub(text), text); + } + } + + #[test] + fn known_private_terms_go_first() { + let s = Scrubber::bare() + .term("My World") + .term("play.example.net") + .term("ab"); + assert_eq!( + s.scrub("Saving My World; joined play.example.net:25565, ab"), + "Saving ; joined :25565, ab" + ); + } +} diff --git a/crates/horizon-telemetry/src/system.rs b/crates/horizon-telemetry/src/system.rs new file mode 100644 index 000000000..5993e5862 --- /dev/null +++ b/crates/horizon-telemetry/src/system.rs @@ -0,0 +1,124 @@ +//! The machine as an item describes it ([`System`]): what the OS says, read the same way on +//! every start. The game adds the GPU, its driver and the graphics backend. +use crate::payload::System; + +fn command_output(program: &str, args: &[&str]) -> Option { + let out = std::process::Command::new(program) + .args(args) + .output() + .ok()?; + let text = String::from_utf8_lossy(&out.stdout).trim().to_owned(); + (out.status.success() && !text.is_empty()).then_some(text) +} + +fn read(path: &str) -> Option { + std::fs::read_to_string(path).ok() +} + +/// The value after `key` in a `key: value` or `key=value` listing. +fn field(text: &str, key: &str) -> Option { + text.lines().find_map(|l| { + let rest = l.strip_prefix(key)?; + let value = rest.trim_start().strip_prefix([':', '='])?; + Some(value.trim().trim_matches('"').to_owned()) + }) +} + +fn os_version() -> Option { + if cfg!(target_os = "linux") { + read("/etc/os-release").and_then(|t| field(&t, "PRETTY_NAME")) + } else if cfg!(target_os = "macos") { + command_output("sw_vers", &["-productVersion"]).map(|v| format!("macOS {v}")) + } else if cfg!(windows) { + command_output("cmd", &["/C", "ver"]) + } else { + None + } +} + +fn cpu() -> Option { + if cfg!(target_os = "linux") { + read("/proc/cpuinfo").and_then(|t| field(&t, "model name")) + } else if cfg!(target_os = "macos") { + command_output("sysctl", &["-n", "machdep.cpu.brand_string"]) + } else { + std::env::var("PROCESSOR_IDENTIFIER").ok() + } +} + +fn ram_bytes() -> Option { + if cfg!(target_os = "linux") { + let kib = read("/proc/meminfo").and_then(|t| field(&t, "MemTotal"))?; + kib.split_whitespace() + .next()? + .parse::() + .ok() + .map(|k| k * 1024) + } else if cfg!(target_os = "macos") { + command_output("sysctl", &["-n", "hw.memsize"])? + .parse() + .ok() + } else if cfg!(windows) { + command_output( + "powershell", + &[ + "-NoProfile", + "-Command", + "(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory", + ], + )? + .parse() + .ok() + } else { + None + } +} + +impl System { + /// This machine, without the GPU. + pub fn detect() -> Self { + const GIB: f64 = (1u64 << 30) as f64; + Self { + os: std::env::consts::OS.to_owned(), + os_version: os_version().unwrap_or_default(), + arch: std::env::consts::ARCH.to_owned(), + cpu: cpu().unwrap_or_default(), + threads: std::thread::available_parallelism().map_or(0, |n| n.get() as u16), + ram_gb: ram_bytes().map_or(0, |b| (b as f64 / GIB).round() as u16), + ..Self::default() + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn fields_are_read_from_listings() { + let os_release = + "NAME=\"Fedora Linux\"\nPRETTY_NAME=\"Fedora Linux 43 (Workstation Edition)\"\n"; + assert_eq!( + field(os_release, "PRETTY_NAME").as_deref(), + Some("Fedora Linux 43 (Workstation Edition)") + ); + let cpuinfo = "processor\t: 0\nmodel name\t: AMD Ryzen 9 7950X 16-Core Processor\n"; + assert_eq!( + field(cpuinfo, "model name").as_deref(), + Some("AMD Ryzen 9 7950X 16-Core Processor") + ); + assert_eq!( + field("MemTotal: 32788148 kB", "MemTotal").as_deref(), + Some("32788148 kB") + ); + assert_eq!(field("NAME=x", "PRETTY_NAME"), None); + } + + #[test] + fn this_machine_is_described() { + let system = System::detect(); + assert_eq!(system.os, std::env::consts::OS); + assert!(system.threads > 0); + assert!(system.gpu.is_empty(), "the game fills the GPU in"); + } +} diff --git a/crates/horizon-telemetry/src/upload.rs b/crates/horizon-telemetry/src/upload.rs new file mode 100644 index 000000000..1621628fa --- /dev/null +++ b/crates/horizon-telemetry/src/upload.rs @@ -0,0 +1,141 @@ +//! Sends the outbox, from the launcher at start and exit. Before anything else it reads the +//! consent again and deletes what the player no longer allows, so with everything off it +//! returns without opening a connection. Failures back off (a minute, doubling, at most a day) +//! and at most [`MAX_BATCHES_A_DAY`] batches leave a day. +use std::path::{Path, PathBuf}; +use std::time::Duration; + +use serde::{Deserialize, Serialize}; + +use crate::batch::{self, Batch}; +use crate::{Consent, outbox}; + +pub const MAX_BATCHES_A_DAY: u32 = 8; +const TIMEOUT: Duration = Duration::from_secs(10); + +#[derive(Debug, PartialEq, Eq)] +pub enum Flush { + /// Nothing to send, or nothing allowed: no connection was made. + Nothing, + /// Waiting after a failure, or for tomorrow's allowance. + Later, + Sent { + items: usize, + batches: usize, + }, + /// The server could not be reached or failed; tried again later. + Failed(String), +} + +/// The uploader's own state, beside the consent. +#[derive(Default, Serialize, Deserialize)] +#[serde(default)] +struct State { + day: u32, + batches: u32, + failures: u32, + retry_at: u64, +} + +fn state_path(home: &Path) -> PathBuf { + crate::dir(home).join("upload.json") +} + +fn load(home: &Path) -> State { + std::fs::read(state_path(home)) + .ok() + .and_then(|b| serde_json::from_slice(&b).ok()) + .unwrap_or_default() +} + +fn save(home: &Path, state: &State) { + if let Ok(json) = serde_json::to_vec(state) { + let _ = crate::write_atomic(&state_path(home), &json); + } +} + +fn agent() -> ureq::Agent { + ureq::AgentBuilder::new().timeout(TIMEOUT).build() +} + +/// Sends what the player allows to `endpoint` (`https://host`, without a trailing slash). +pub fn flush(home: &Path, endpoint: &str) -> Flush { + let consent = Consent::load(home); + // What was turned off since it was kept never leaves. + let allowed = outbox::retain_allowed(home); + if allowed.is_empty() { + return Flush::Nothing; + } + let mut state = load(home); + let today = crate::today(); + if state.day != today { + state.day = today; + state.batches = 0; + } + if crate::now_secs() < state.retry_at || state.batches >= MAX_BATCHES_A_DAY { + return Flush::Later; + } + let agent = agent(); + let url = format!("{endpoint}/v1/batch"); + let (mut items, mut batches) = (0, 0); + for group in batch::split(allowed) { + if state.batches >= MAX_BATCHES_A_DAY { + break; + } + let (paths, list): (Vec, Vec) = group.into_iter().unzip(); + let body = batch::encode(&Batch::new(&consent.install_id, list)); + let sent = agent + .post(&url) + .set("Content-Type", "application/json") + .set("Content-Encoding", "zstd") + .send_bytes(&body); + match sent { + Ok(_) => { + state.batches += 1; + state.failures = 0; + items += paths.len(); + batches += 1; + paths.iter().for_each(|p| drop(std::fs::remove_file(p))); + } + // Refused for what it is (not for load): sending it again would not help. + Err(ureq::Error::Status(code, _)) if (400..500).contains(&code) && code != 429 => { + state.batches += 1; + paths.iter().for_each(|p| drop(std::fs::remove_file(p))); + } + Err(e) => { + state.failures = (state.failures + 1).min(16); + state.retry_at = crate::now_secs() + (60u64 << (state.failures - 1)).min(86_400); + save(home, &state); + return Flush::Failed(e.to_string()); + } + } + } + save(home, &state); + if batches == 0 { + Flush::Later + } else { + Flush::Sent { items, batches } + } +} + +/// Asks the server to delete everything sent under `install_id`. +pub fn delete_remote(endpoint: &str, install_id: &str) -> Result<(), String> { + if !crate::consent::is_install_id(install_id) { + return Err("no install ID: nothing was sent".into()); + } + agent() + .delete(&format!("{endpoint}/v1/installs/{install_id}")) + .call() + .map(|_| ()) + .map_err(|e| e.to_string()) +} + +/// The batch the next [`flush`] would send, as readable JSON ("View what would be sent"). +pub fn preview(home: &Path) -> String { + let consent = Consent::load(home); + let items = outbox::retain_allowed(home) + .into_iter() + .map(|(_, item)| item) + .collect(); + serde_json::to_string_pretty(&Batch::new(&consent.install_id, items)).unwrap_or_default() +} diff --git a/crates/horizon-telemetry/tests/consent_gating.rs b/crates/horizon-telemetry/tests/consent_gating.rs new file mode 100644 index 000000000..68c5b4f6e --- /dev/null +++ b/crates/horizon-telemetry/tests/consent_gating.rs @@ -0,0 +1,231 @@ +//! Nothing leaves the machine without consent: a local mock server counts every connection the +//! uploader opens, and with the player's consent missing, outdated or withdrawn there are none. +use std::io::{BufRead, BufReader, Read, Write}; +use std::net::TcpListener; +use std::path::{Path, PathBuf}; +use std::sync::{Arc, Mutex}; + +use horizon_telemetry::batch; +use horizon_telemetry::payload::{Bug, Crash, Payload, Perf, Source}; +use horizon_telemetry::upload::{self, Flush}; +use horizon_telemetry::{Choices, Consent, Item, Kind, outbox}; + +/// What the mock server saw: one entry a connection, `METHOD path` and the body. +type Seen = Arc)>>>; + +/// An HTTP server on a free local port answering every request with `status`. +fn mock_server(status: u16) -> (String, Seen) { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let url = format!("http://{}", listener.local_addr().unwrap()); + let seen: Seen = Arc::default(); + let log = seen.clone(); + std::thread::spawn(move || { + for stream in listener.incoming() { + let Ok(mut stream) = stream else { continue }; + let mut reader = BufReader::new(stream.try_clone().unwrap()); + let mut request = String::new(); + reader.read_line(&mut request).unwrap(); + let mut length = 0; + loop { + let mut line = String::new(); + reader.read_line(&mut line).unwrap(); + if line.trim().is_empty() { + break; + } + if let Some((k, v)) = line.split_once(':') + && k.eq_ignore_ascii_case("content-length") + { + length = v.trim().parse().unwrap(); + } + } + let mut body = vec![0; length]; + reader.read_exact(&mut body).unwrap(); + let line = request + .split_whitespace() + .take(2) + .collect::>() + .join(" "); + log.lock().unwrap().push((line, body)); + let _ = write!( + stream, + "HTTP/1.1 {status} X\r\nContent-Length: 0\r\nConnection: close\r\n\r\n" + ); + } + }); + (url, seen) +} + +fn home(name: &str) -> PathBuf { + let mut bytes = [0u8; 6]; + getrandom::fill(&mut bytes).unwrap(); + let suffix: String = bytes.iter().map(|b| format!("{b:02x}")).collect(); + let dir = std::env::temp_dir().join(format!("horizon-telemetry-gating-{name}-{suffix}")); + std::fs::create_dir_all(&dir).unwrap(); + dir +} + +fn answer(home: &Path, choices: Choices) -> Consent { + let mut consent = Consent::load(home); + consent.answer(choices); + consent.save(home).unwrap(); + consent +} + +fn crash() -> Item { + Item::new( + Source::Game, + "v0.4.2", + Payload::Crash(Crash { + error: "panicked at src/game.rs:1:1".into(), + ..Crash::default() + }), + ) +} + +fn perf() -> Item { + Item::new(Source::Game, "v0.4.2", Payload::Perf(Perf::default())) +} + +/// Puts an item straight into the outbox, as a game from before a withdrawal left it. +fn leftover(home: &Path, item: &Item, name: &str) { + let dir = outbox::dir(home); + std::fs::create_dir_all(&dir).unwrap(); + std::fs::write(dir.join(name), serde_json::to_vec(item).unwrap()).unwrap(); +} + +#[test] +fn never_asked_sends_nothing() { + let (url, seen) = mock_server(204); + let home = home("never"); + for item in [crash(), perf()] { + assert!(!outbox::push(&home, &item).unwrap()); + } + leftover(&home, &crash(), "000001-crash-a.json"); + assert_eq!(upload::flush(&home, &url), Flush::Nothing); + assert!(seen.lock().unwrap().is_empty()); + assert!( + outbox::pending(&home).is_empty(), + "the leftover is deleted, not kept" + ); +} + +#[test] +fn everything_off_sends_nothing_and_deletes_what_waited() { + let (url, seen) = mock_server(204); + let home = home("withdrawn"); + answer(&home, Choices::ALL); + assert!(outbox::push(&home, &crash()).unwrap()); + assert!(outbox::push(&home, &perf()).unwrap()); + answer(&home, Choices::NONE); + assert_eq!(upload::flush(&home, &url), Flush::Nothing); + assert!(seen.lock().unwrap().is_empty()); + assert!(outbox::pending(&home).is_empty()); +} + +#[test] +fn an_outdated_consent_sends_nothing() { + let (url, seen) = mock_server(204); + let home = home("outdated"); + let mut consent = answer(&home, Choices::ALL); + assert!(outbox::push(&home, &crash()).unwrap()); + consent.version = 0; + consent.save(&home).unwrap(); + assert_eq!(upload::flush(&home, &url), Flush::Nothing); + assert!(seen.lock().unwrap().is_empty()); +} + +#[test] +fn only_the_allowed_kinds_leave_in_one_compressed_batch() { + let (url, seen) = mock_server(204); + let home = home("partial"); + let consent = answer(&home, Choices::ALL); + for item in [crash(), perf(), crash()] { + assert!(outbox::push(&home, &item).unwrap()); + } + answer( + &home, + Choices { + crashes: true, + ..Choices::NONE + }, + ); + assert_eq!( + upload::flush(&home, &url), + Flush::Sent { + items: 2, + batches: 1 + } + ); + let seen = seen.lock().unwrap(); + assert_eq!(seen.len(), 1); + assert_eq!(seen[0].0, "POST /v1/batch"); + let batch = batch::decode(&seen[0].1).unwrap(); + assert_eq!(batch.install_id, consent.install_id); + assert!(batch.items.iter().all(|i| i.kind() == Kind::Crash)); + assert_eq!(batch.items.len(), 2); + assert!(outbox::pending(&home).is_empty()); + drop(seen); + assert_eq!(upload::flush(&home, &url), Flush::Nothing); +} + +#[test] +fn a_failing_server_is_retried_later_and_keeps_the_items() { + let (url, seen) = mock_server(503); + let home = home("failing"); + answer(&home, Choices::ALL); + assert!(outbox::push(&home, &crash()).unwrap()); + assert!(matches!(upload::flush(&home, &url), Flush::Failed(_))); + assert_eq!(upload::flush(&home, &url), Flush::Later); + assert_eq!( + seen.lock().unwrap().len(), + 1, + "no second try inside the back-off" + ); + assert_eq!(outbox::pending(&home).len(), 1); +} + +#[test] +fn a_refused_batch_is_dropped() { + let (url, seen) = mock_server(400); + let home = home("refused"); + answer(&home, Choices::ALL); + assert!(outbox::push(&home, &crash()).unwrap()); + assert_eq!(upload::flush(&home, &url), Flush::Later); + assert_eq!(seen.lock().unwrap().len(), 1); + assert!(outbox::pending(&home).is_empty()); +} + +#[test] +fn the_preview_is_what_would_be_sent_and_deletion_names_the_install() { + let (url, seen) = mock_server(204); + let home = home("preview"); + let consent = answer( + &home, + Choices { + bugs: true, + ..Choices::NONE + }, + ); + let bug = Item::new( + Source::Launcher, + "0.1.5", + Payload::Bug(Bug { + text: "The sky is green".into(), + ..Bug::default() + }), + ); + assert!(outbox::push(&home, &bug).unwrap()); + leftover(&home, &crash(), "000001-crash-a.json"); + let preview: serde_json::Value = serde_json::from_str(&upload::preview(&home)).unwrap(); + assert_eq!(preview["items"].as_array().unwrap().len(), 1); + assert_eq!(preview["items"][0]["data"]["text"], "The sky is green"); + assert!(seen.lock().unwrap().is_empty(), "previewing sends nothing"); + upload::delete_remote(&url, &consent.install_id).unwrap(); + assert!(upload::delete_remote(&url, "").is_err()); + let seen = seen.lock().unwrap(); + assert_eq!(seen.len(), 1); + assert_eq!( + seen[0].0, + format!("DELETE /v1/installs/{}", consent.install_id) + ); +} diff --git a/docs/README.md b/docs/README.md index 54e8187b8..2beb67f6c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,6 +9,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor - [Graphics](graphics.md): the Simple and Advanced graphics settings, the graphics benchmark and what it measured. - [Extras](extras.md): optional zoom, minimap, FPS and keystroke overlays and auto-reconnect, all off by default. - [Launcher](../launcher/README.md): installs, updates and starts builds; its CLI and MCP server; releasing it. +- [Opt-in data collection](telemetry.md): the consent, exactly what is sent, how it is stored and sent. - Menus: the title, world list, create world, multiplayer, options and pause screens share the launcher's design tokens and fonts (`crates/horizon-theme`), drawn by `ui_theme` over a live frozen backdrop (`game/backdrop.rs`, blurred and graded by `post.rs`). Options → Interface → Menu style switches to vanilla's screens (Classic, kept in `horizon.txt`; `HORIZON_MENU_STYLE=horizon|classic` overrides it, and scripted runs default to Classic). [Title](media/menu-title.png) ([webm](media/menu-title.webm)), [worlds](media/menu-worlds.png), [options](media/menu-options.png), [pause](media/menu-pause.png). ## Parity diff --git a/docs/telemetry.md b/docs/telemetry.md new file mode 100644 index 000000000..6ac1438a5 --- /dev/null +++ b/docs/telemetry.md @@ -0,0 +1,55 @@ +# Opt-in data collection + +Horizon collects nothing unless the player says yes. The launcher asks once, with four separate switches that are all off until the player turns one on, and the same switches stay in Settings. The game and the launcher obey the same answer. The code is in `crates/horizon-telemetry`. + +## Consent + +`telemetry/consent.json` in the game folder (`HORIZON_HOME`, else `horizon` in the platform data folder): + +```json +{ "version": 1, "answered": 1792060800, "choices": { "performance": true, "crashes": true, "bugs": false, "benchmarks": false }, "install_id": "3f2c…" } +``` + +- `version` is the consent version the player answered (`CONSENT_VERSION`). It goes up when what is collected changes. The launcher then asks again, and until the player answers nothing new is kept or sent. +- `answered` is when they answered, in seconds since 1970 (UTC). +- `install_id` is 128 random bits, made the first time the player says yes to anything. It ties their items together so they can be deleted, and nothing else. "Delete my data" asks the server to delete everything under it, then replaces it. + +Nothing leaves the machine without consent: + +- `outbox::push` keeps an item only if its kind is allowed. +- `upload::flush` reads the consent again before sending and deletes any waiting item whose kind the player has turned off since, so with everything off it never opens a connection. + +`tests/consent_gating.rs` checks this against a local mock server that counts connections. + +## What is sent + +Every item has `day` (days since 1970, UTC: no finer time), `source` (`launcher` or `game`), `version` (the release), `kind` and `data`. + +| Kind | Switch | `data` | Largest | A day | +|---|---|---|---|---| +| `perf` | performance | `system`, `settings` (render and simulation distance, max FPS, vsync, fullscreen, graphics mode), `seconds` played, `frames` and `ticks` summaries, `peak_ram_mb`, `to_title_ms`, `to_world_ms` | 4 KiB | 12 | +| `crash` | crash reports | `system`, `error`, `stack` (one frame a line), `thread`, the graphics and settings details, all scrubbed. No log, no world, no server | 32 KiB | 5 | +| `bug` | bug reports | `system`, the player's `text` (up to 4000 characters), and the `log` only if they add it after reading it | 80 KiB | 5 | +| `benchmark` | benchmark uploads | the benchmark report as `docs/benchmark-report.md` defines it, as it is, with its own schema field | 128 KiB | 10 | + +`system` is the OS and its version, the architecture, the CPU model and thread count, installed memory rounded to the GiB, and the GPU, driver and graphics backend. + +A summary (`frames`, `ticks`) is the count, the 50th, 95th and 99th percentile and the maximum in milliseconds (to the tenth), and 14 bucket counts: under 4 ms, 4–6, 6–8, 8–10, 10–12, 12–14, 14–16.7, 16.7–20, 20–25, 25–33.3, 33.3–50, 50–100, 100–250, and 250 ms and more. Raw frame times never leave: `Timings` records them in tenths of a millisecond (20 KB however long the session) and only its summary is kept. A perf item is under 1 KiB. + +Never sent: account names or UUIDs, world names, server or LAN addresses, chat, file paths with the user's name, IP addresses. `scrub::Scrubber` replaces the user folder in paths (`/Users//…`, `C:\Users\\…`), the user name, e-mail and IP addresses and UUIDs. It also replaces the terms the caller passes (the world's name, the server's address, account names). The server does not store the sender's IP address. + +## Storage and sending + +- `telemetry/outbox/` holds one JSON file per item, `--.json`. It never holds more than 200 items or 2 MiB, and the oldest go first. `kept.json` counts today's items per kind against the caps above. +- The launcher sends the outbox when it starts and when it closes. Items go as one JSON batch (`{"schema":1,"install_id":…,"items":[…]}`, up to 64 items and 1 MiB), compressed with zstd: `POST /v1/batch` with `Content-Encoding: zstd`. A day's perf summaries are under 2 KB on the wire. +- After a failure the launcher waits a minute, doubling up to a day, and sends at most 8 batches a day. A batch the server refuses with a 4xx (not 429) is dropped. +- `HORIZON_TELEMETRY_URL` sets the server. There is none by default: until there is, nothing is sent and the outbox stays within its caps. +- `SCHEMA` versions the format. New optional fields keep it. A field that changes meaning or goes bumps it, and the server keeps reading the older ones. + +## Server + +- `POST /v1/batch` +- `DELETE /v1/installs/`: deletes everything sent under that ID. +- `GET /v1/aggregate`: the anonymous totals the website's results page reads. + +Retention, rate limits and storage are described with the server. From 02296155602906f31224be9c065970326ee560ed Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:18:52 +0200 Subject: [PATCH 14/97] Battery mode: an opt-in frame cap and fewer worker threads A Horizon graphics setting (Performance, off by default, batteryMode in horizon-graphics.txt): at most 60 frames per second in a world, 30 in menus without a world or behind other windows, and half the automatic worker threads. It only changes when frames are drawn; ticks and what frames show are untouched. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/game/options.rs | 5 ++- crates/horizon-client/src/graphics.rs | 38 +++++++++++++++++++-- crates/horizon-client/src/graphics_ui.rs | 40 ++++++++++++++--------- docs/graphics.md | 4 ++- 4 files changed, 67 insertions(+), 20 deletions(-) diff --git a/crates/horizon-client/src/game/options.rs b/crates/horizon-client/src/game/options.rs index fa631e114..a2409f169 100644 --- a/crates/horizon-client/src/game/options.rs +++ b/crates/horizon-client/src/game/options.rs @@ -240,7 +240,10 @@ impl Game<'_> { has_screen: self.title.is_some() || self.screen != super::Screen::Playing, has_overlay: false, }; - framerate_limit(self.settings.max_fps as i32, context) + let limit = framerate_limit(self.settings.max_fps as i32, context); + self.settings + .horizon + .battery_limit(limit, self.title.is_none(), self.focused) } /// `Minecraft.runTick`'s frame limiter: `FramerateLimiter.limitDisplayFPS` /// below 260 frames per second, sleeping then spin-waiting until the diff --git a/crates/horizon-client/src/graphics.rs b/crates/horizon-client/src/graphics.rs index cd9d5cd4a..5ef24247e 100644 --- a/crates/horizon-client/src/graphics.rs +++ b/crates/horizon-client/src/graphics.rs @@ -136,6 +136,10 @@ pub struct Graphics { pub fxaa: bool, /// The settings level last shown: Advanced, or Simple. pub advanced: bool, + /// Battery mode: at most 60 frames per second in a world and 30 in menus + /// or behind other windows, and half the worker threads. Off by default; + /// it changes when frames are drawn, never what they show or the ticks. + pub battery: bool, } impl Default for Graphics { fn default() -> Self { @@ -155,6 +159,7 @@ impl Default for Graphics { resolution_scale: 100, fxaa: false, advanced: false, + battery: false, } } } @@ -201,6 +206,7 @@ impl Graphics { "resolutionScale" => g.resolution_scale = number(g.resolution_scale).clamp(50, 200), "fxaa" => g.fxaa = flag(g.fxaa), "level" => g.advanced = value == "advanced", + "batteryMode" => g.battery = flag(g.battery), "overlay" => { g.overlay = match value { "fps" => Overlay::Fps, @@ -215,7 +221,7 @@ impl Graphics { } pub fn serialize(&self) -> String { format!( - "preset:{}\ncaveCulling:{}\nchunkUpdates:{}\nuploadBudgetKiB:{}\nsky:{}\nfog:{}\nweather:{}\nanimatedTextures:{}\npresentMode:{}\nframePacing:{}\nworkers:{}\noverlay:{}\nresolutionScale:{}\nfxaa:{}\nlevel:{}\n", + "preset:{}\ncaveCulling:{}\nchunkUpdates:{}\nuploadBudgetKiB:{}\nsky:{}\nfog:{}\nweather:{}\nanimatedTextures:{}\npresentMode:{}\nframePacing:{}\nworkers:{}\noverlay:{}\nresolutionScale:{}\nfxaa:{}\nlevel:{}\nbatteryMode:{}\n", self.preset.name(), bool_text(self.cave_culling), self.chunk_updates, @@ -238,6 +244,7 @@ impl Graphics { self.resolution_scale, bool_text(self.fxaa), if self.advanced { "advanced" } else { "simple" }, + bool_text(self.battery), ) } pub fn save(&self, dir: &Path) { @@ -248,10 +255,22 @@ impl Graphics { if self.workers > 0 { return self.workers as usize; } - std::thread::available_parallelism() + let auto = std::thread::available_parallelism() .map_or(2, |n| n.get()) .saturating_sub(1) - .max(1) + .max(1); + if self.battery { auto.div_ceil(2) } else { auto } + } + /// The frame cap battery mode adds: 60 in a world, 30 in menus without a + /// world or while another window has focus. + pub fn battery_limit(&self, limit: i32, in_world: bool, focused: bool) -> i32 { + if !self.battery { + limit + } else if in_world && focused { + limit.min(60) + } else { + limit.min(30) + } } } @@ -309,6 +328,7 @@ mod tests { resolution_scale: 75, fxaa: true, advanced: true, + battery: true, }; assert_eq!(Graphics::parse(&g.serialize()), g); assert_eq!(Graphics::parse(""), Graphics::default()); @@ -317,4 +337,16 @@ mod tests { Graphics::default() ); } + + #[test] + fn battery_mode_only_lowers_the_frame_cap() { + let mut g = Graphics::default(); + assert_eq!(g.battery_limit(260, true, true), 260); + g.battery = true; + assert_eq!(g.battery_limit(260, true, true), 60); + assert_eq!(g.battery_limit(30, true, true), 30); + assert_eq!(g.battery_limit(260, false, true), 30); + assert_eq!(g.battery_limit(260, true, false), 30); + assert_eq!(g.battery_limit(10, true, false), 10); + } } diff --git a/crates/horizon-client/src/graphics_ui.rs b/crates/horizon-client/src/graphics_ui.rs index d72f8de86..0f9ac56a7 100644 --- a/crates/horizon-client/src/graphics_ui.rs +++ b/crates/horizon-client/src/graphics_ui.rs @@ -34,6 +34,7 @@ pub enum H { Overlay, ResolutionScale, Antialiasing, + BatteryMode, } #[derive(Clone, Copy, Debug, PartialEq, Eq)] @@ -219,6 +220,11 @@ pub fn rows(level: Level) -> Vec { v(Opt::Autosave, None, "Shows when the world saves."), v(Opt::AttackIndicator, None, "Shows attack cooldown."), Row::Header("Performance"), + h( + H::BatteryMode, + None, + "At most 60 FPS (30 in menus or behind other windows), half the worker threads: less power, slower loading.", + ), h( H::Workers, None, @@ -297,6 +303,7 @@ impl H { }, H::ResolutionScale => labelled("Resolution Scale", format!("{}%", g.resolution_scale)), H::Antialiasing => labelled("Anti-aliasing", if g.fxaa { "FXAA" } else { "Off" }), + H::BatteryMode => labelled("Battery Mode", on_off(g.battery)), H::Overlay => labelled( "Performance Overlay", match g.overlay { @@ -341,6 +348,7 @@ impl H { H::AnimatedTextures => g.animated_textures = !g.animated_textures, H::PresentMode => g.present_mode = step(&PresentMode::ALL, g.present_mode, back), H::Antialiasing => g.fxaa = !g.fxaa, + H::BatteryMode => g.battery = !g.battery, H::Pacing => { g.pacing = match g.pacing { Pacing::Efficient => Pacing::Precise, @@ -373,6 +381,7 @@ impl Item { Item::Horizon(H::Weather) => g.weather, Item::Horizon(H::AnimatedTextures) => g.animated_textures, Item::Horizon(H::Antialiasing) => g.fxaa, + Item::Horizon(H::BatteryMode) => g.battery, Item::Vanilla(Opt::ViewBobbing) => s.view_bobbing, Item::Vanilla(Opt::Vsync) => s.vsync, Item::Vanilla(Opt::Fullscreen) => s.fullscreen, @@ -423,21 +432,22 @@ impl Item { fn touched(self, s: &mut Settings) { let presetless = matches!( self, - Item::Horizon(H::Preset | H::Overlay | H::Pacing | H::PresentMode | H::Workers) - | Item::Vanilla( - Opt::GuiScale - | Opt::Fullscreen - | Opt::Vsync - | Opt::MaxFps - | Opt::Fov - | Opt::Gamma - | Opt::InactivityFps - | Opt::ViewBobbing - | Opt::ChunkFade - | Opt::Vignette - | Opt::Autosave - | Opt::AttackIndicator - ) + Item::Horizon( + H::Preset | H::Overlay | H::Pacing | H::PresentMode | H::Workers | H::BatteryMode + ) | Item::Vanilla( + Opt::GuiScale + | Opt::Fullscreen + | Opt::Vsync + | Opt::MaxFps + | Opt::Fov + | Opt::Gamma + | Opt::InactivityFps + | Opt::ViewBobbing + | Opt::ChunkFade + | Opt::Vignette + | Opt::Autosave + | Opt::AttackIndicator + ) ); if !presetless { s.horizon.preset = Preset::Custom; diff --git a/docs/graphics.md b/docs/graphics.md index c2f8675a9..a55313bea 100644 --- a/docs/graphics.md +++ b/docs/graphics.md @@ -22,11 +22,13 @@ Every row has a one-line description and its cost in frame time (none, low, medi | | sky, fog, weather, animated textures | `horizon-graphics.txt` | | Display | FOV, max framerate, VSync, fullscreen, GUI scale | `options.txt` | | | resolution scale, anti-aliasing (FXAA), present mode, frame pacing | `horizon-graphics.txt` | -| Performance | worker threads, upload budget per frame | `horizon-graphics.txt` | +| Performance | battery mode, worker threads, upload budget per frame | `horizon-graphics.txt` | | Overlay | performance overlay: FPS, frame/CPU/GPU times, frame-time graph | `horizon-graphics.txt` | `options.txt` keeps exactly vanilla's keys and values, so the options harness still compares it with vanilla; Horizon's settings live in `horizon-graphics.txt` beside it. Their defaults render as vanilla does: cave culling on, no upload budgets, sky, fog and weather on, 100% resolution, no FXAA, the present mode following VSync. Frame pacing defaults to Efficient: the limiter sleeps through the last half millisecond where vanilla spins, which changes timing, not pixels. +**Battery mode** (Performance, off by default) is for laptops and handhelds: at most 60 frames per second in a world, 30 in menus without a world or while another window has focus, and half the automatic worker threads (chunks load slower). It changes only when frames are drawn: what they show and the game's 20 ticks per second stay as they are. + Which settings each level shows, their descriptions and costs are in `crates/horizon-client/src/graphics_ui.rs` (`rows`); the Horizon shell draws them in `options_horizon.rs` with `ui_theme::described_row`, and the Classic screens use `graphics_style.rs`. Not implemented: distant-terrain LOD, anisotropic filtering (wgpu needs linear magnification for it, which blurs close blocks), MSAA (FXAA instead) and exclusive fullscreen (fullscreen is borderless). From cc8744a06bbbdd46ea5378e45dba9c2499165de8 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 02:26:46 +0200 Subject: [PATCH 15/97] Trim synthetic overlay benchmarks; record Mac real-pack numbers The real-pack benchmark on the production resource_root path stays as the reproducible measurement. On the Mac mini it saves 1.18 s (Faithful 32x) and 5.29 s (FPBR) per startup with the pack enabled. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/packs/cache.rs | 179 ----------------------- docs/reuse-pack-overlays.md | 24 ++- 2 files changed, 10 insertions(+), 193 deletions(-) diff --git a/crates/horizon-client/src/packs/cache.rs b/crates/horizon-client/src/packs/cache.rs index 6931a3871..1f17c018b 100644 --- a/crates/horizon-client/src/packs/cache.rs +++ b/crates/horizon-client/src/packs/cache.rs @@ -756,185 +756,6 @@ mod tests { assert!(lock_path(&out).exists()); } - #[test] - #[ignore = "reproducible overlay benchmark; run with --ignored --nocapture"] - fn benchmark_overlay_reuse() { - use std::{hint::black_box, time::Instant}; - let f = Fixture::new(); - let pack = f.dir_pack("pack"); - let mut files = vec![( - "pack.mcmeta".to_owned(), - fs::read(f.0.join("pack/pack.mcmeta")).unwrap(), - )]; - // 2,048 overrides (32 MiB), 32 merged language files, 8,192 live - // vanilla textures (128 MiB). Synthetic incompressible payloads approximate - // already-compressed PNG bytes; texture decoding is outside this benchmark. - let mut random = 0x1234_5678u32; - let texture: Vec = (0..16384) - .map(|_| { - random ^= random << 13; - random ^= random >> 17; - random ^= random << 5; - (random >> 24) as u8 - }) - .collect(); - for i in 0..8192 { - let name = format!("assets/minecraft/textures/block/{i}.png"); - f.write(&format!("vanilla/{name}"), &texture); - if i < 2048 { - f.write(&format!("pack/{name}"), &texture); - files.push((name, texture.clone())); - } - } - for i in 0..32 { - let name = format!("assets/minecraft/lang/{i}.json"); - let vanilla = serde_json::to_vec(&serde_json::Value::Object( - (0..2000) - .map(|j| { - ( - format!("key{j}"), - serde_json::json!(format!("Vanilla translation {j}")), - ) - }) - .collect(), - )) - .unwrap(); - let body = serde_json::to_vec(&serde_json::Value::Object( - (0..1000) - .map(|j| { - ( - format!("key{j}"), - serde_json::json!(format!("Pack translation {j}")), - ) - }) - .collect(), - )) - .unwrap(); - f.write(&format!("vanilla/{name}"), &vanilla); - f.write(&format!("pack/{name}"), &body); - files.push((name, body)); - } - let borrowed: Vec<_> = files - .iter() - .map(|(name, body)| (name.as_str(), body.clone())) - .collect(); - f.write("pack.zip", &archive(&borrowed, true)); - println!( - "fixture ZIP bytes={}", - fs::metadata(f.0.join("pack.zip")).unwrap().len() - ); - let zip = packs::pack( - "zip".into(), - Text::empty(), - Source::Zip(f.0.join("pack.zip")), - ) - .unwrap(); - let median = |mut times: Vec| { - times.sort_by(f64::total_cmp); - times[times.len() / 2] - }; - for (kind, pack) in [("directory", pack), ("deflated zip", zip)] { - f.rebuild_matches(std::slice::from_ref(&pack)); - let vanilla = f.0.join("vanilla"); - let out = f.0.join("cached"); - let mut baseline = Vec::new(); - let mut cold = Vec::new(); - let mut hit = Vec::new(); - for _ in 0..11 { - let start = Instant::now(); - build_overlay_uncached( - black_box(&vanilla), - black_box(std::slice::from_ref(&pack)), - black_box(&f.0.join("reference")), - &mut Dependencies::default(), - ) - .unwrap(); - baseline.push(start.elapsed().as_secs_f64() * 1000.0); - fs::remove_file(marker_path(&out)).unwrap(); - let start = Instant::now(); - packs::build_overlay( - black_box(&vanilla), - black_box(std::slice::from_ref(&pack)), - black_box(&out), - ) - .unwrap(); - cold.push(start.elapsed().as_secs_f64() * 1000.0); - let start = Instant::now(); - packs::build_overlay( - black_box(&vanilla), - black_box(std::slice::from_ref(&pack)), - black_box(&out), - ) - .unwrap(); - hit.push(start.elapsed().as_secs_f64() * 1000.0); - assert_eq!( - output_signature(&out).unwrap(), - output_signature(&f.0.join("reference")).unwrap() - ); - } - println!( - "{kind}: baseline={:.3} ms cold={:.3} ms unchanged={:.3} ms (11 medians, full validation)", - median(baseline), - median(cold), - median(hit) - ); - } - } - - #[test] - #[ignore = "content-heavy few-file directory benchmark"] - fn benchmark_content_heavy_directory() { - use std::{hint::black_box, time::Instant}; - let f = Fixture::new(); - f.write("vanilla/facts.json", b"[]"); - let pack = f.dir_pack("pack"); - let bytes = vec![42; 8 * 1024 * 1024]; - for i in 0..4 { - f.write(&format!("pack/assets/minecraft/textures/{i}.png"), &bytes); - } - let vanilla = f.0.join("vanilla"); - let out = f.0.join("cached"); - f.rebuild_matches(std::slice::from_ref(&pack)); - let mut timings = [Vec::new(), Vec::new(), Vec::new()]; - for _ in 0..11 { - let start = Instant::now(); - build_overlay_uncached( - black_box(&vanilla), - black_box(std::slice::from_ref(&pack)), - &f.0.join("reference"), - &mut Dependencies::default(), - ) - .unwrap(); - timings[0].push(start.elapsed().as_secs_f64() * 1000.0); - fs::remove_file(marker_path(&out)).unwrap(); - for times in &mut timings[1..] { - let start = Instant::now(); - packs::build_overlay( - black_box(&vanilla), - black_box(std::slice::from_ref(&pack)), - black_box(&out), - ) - .unwrap(); - times.push(start.elapsed().as_secs_f64() * 1000.0); - } - assert_eq!( - output_signature(&out).unwrap(), - output_signature(&f.0.join("reference")).unwrap() - ); - } - let medians: Vec<_> = timings - .into_iter() - .map(|mut times| { - times.sort_by(f64::total_cmp); - times[5] - }) - .collect(); - println!( - "4 x 8 MiB directory textures: baseline={:.3} ms cold={:.3} ms unchanged={:.3} ms (11 medians, full validation)", - medians[0], medians[1], medians[2] - ); - } - #[cfg(unix)] #[test] fn relative_builder_targets_are_preserved() { diff --git a/docs/reuse-pack-overlays.md b/docs/reuse-pack-overlays.md index 2a5235553..53e8bbc3a 100644 --- a/docs/reuse-pack-overlays.md +++ b/docs/reuse-pack-overlays.md @@ -20,20 +20,17 @@ Linux x86_64/ext4/NVMe, Ryzen 5 5600X, Rust 1.99.0, Cargo `fast`, measured 2026- Unchanged speedups are approximately 226x, 359x and 775x. Cold overhead on these ZIPs is 0.1–2.6%, replacing the original cache implementation's 73–79% synthetic overhead. This measures overlay assembly and cache validation, excluding scan, texture decoding, total startup and FPS. +Mac mini (M4 Pro, APFS, Rust stable, Cargo `fast`), same harness and packs, measured 2026-10-15 during review while the machine ran other builds: + +| ZIP pack | Original rebuild | Cached cold | Unchanged hit | Saved per hit | +| --- | ---: | ---: | ---: | ---: | +| Faithful 32x, 26.3 September 2026 | 1,184.400 ms | 1,295.069 ms | 0.571 ms | 1,183.829 ms | +| FPBR, 1.21.9 R1.3 | 5,292.149 ms | 5,503.965 ms | 0.391 ms | 5,291.758 ms | + +Creating thousands of files and links costs far more on macOS than on Linux, so the saving there is seconds per startup with a pack enabled. + Pack downloads were verified against publisher SHA-512 metadata. Exact versions, URLs, sizes, asset counts, hashes and prepared-manifest identity are recorded in `benchmarks/overlay-real-packs-2026-10-15.json`. Sources: [Faithful](https://modrinth.com/resourcepack/faithful-32x/version/lDYpMiqk), [Default HD](https://modrinth.com/resourcepack/default-hd-128x/version/rErHu3BE), [FPBR](https://modrinth.com/resourcepack/fpbr/version/dynf82xk). FPBR targets older 1.21.9 snapshots; it is measured as a large real 128x archive over prepared 26.3 resources, without claiming visual/version compatibility. Default HD is the publisher's free demo. Downloaded pack contents are not committed. -## Synthetic coverage - -The existing fixtures contain 8,192 vanilla textures (128 MiB), 2,048 overrides (32 MiB) and 32 merged language files; equivalent directory/ZIP payloads are incompressible bytes. Eleven median samples compare identical output outside timing: - -| Fixture | Original | Cached cold | Hit | -| --- | ---: | ---: | ---: | -| Directory | 108.487 ms | 126.438 ms | 7.438 ms | -| Deflated ZIP, 32.45 MiB | 155.540 ms | 155.453 ms | 0.128 ms | -| Directory, four 8 MiB files | 0.115 ms | 0.271 ms | 0.076 ms | - -Directory topology scans remain a cost: the larger directory fixture adds about 17% cold overhead and gains 14.6x on hits. Tiny cold overlays add about 0.16 ms. No overall startup gain is inferred from either table. - ## Reproduce and validate ```sh @@ -41,10 +38,9 @@ export CARGO_INCREMENTAL=0 export HORIZON_OVERLAY_BENCH_VANILLA=/path/to/prepared/26.3 export HORIZON_OVERLAY_BENCH_PACKS='["/path/to/Faithful.zip","/path/to/DefaultHD.zip","/path/to/FPBR.zip"]' cargo test -p horizon-client --lib --profile fast packs::cache::tests::benchmark_real_resource_root -- --ignored --nocapture --test-threads=1 -cargo test -p horizon-client --lib --profile fast packs::cache::tests::benchmark -- --ignored --nocapture --test-threads=1 --skip benchmark_real_resource_root cargo test -p horizon-client --lib --profile fast packs:: -- --nocapture cargo clippy -p horizon-client --lib --tests --profile fast -- -D warnings cargo fmt --all -- --check ``` -Thirteen focused tests pass, covering source edits/replacements, Unix preserved-mtime edits, pack order/removal, overlays/filters, vanilla membership, marker/output-root recovery, failed ZIP rebuilds, symlink aliases/cycles, contention and unchanged relative link targets. All three opt-in benchmarks pass; strict Clippy, formatting and whitespace checks pass. Each overlay retains a small marker and empty lock file; cache hits retain no archive byte buffer. +Thirteen focused tests pass, covering source edits/replacements, Unix preserved-mtime edits, pack order/removal, overlays/filters, vanilla membership, marker/output-root recovery, failed ZIP rebuilds, symlink aliases/cycles, contention and unchanged relative link targets. The opt-in real-pack benchmark passes; strict Clippy, formatting and whitespace checks pass. Each overlay retains a small marker and empty lock file; cache hits retain no archive byte buffer. From a2b2b3f7761bffb6230ae52e6b737744454948d2 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 02:45:07 +0200 Subject: [PATCH 16/97] Player water on #59: bubble columns, swim sounds, drown bubbles, vanilla fixes Builds on Cosmic's #59 (player fluid travel, swimming, air supply) and changes only what differs from vanilla 26.3 or what it lacks: - BubbleColumnBlock.entityInside for the player (isPrecise, onAbove / onInsideBubbleColumn, not while flying) with its splash/bubble particles. - LocalPlayer.goDownInWater before LivingEntity.aiStep's velocity cleanup. - The aiStep jump phase as vanilla: nothing while flying, the fluid jump threshold from the eye height (also in travelInLava). - Player.travel: swim steering samples y + 1.0 - 0.1, and LivingEntity.travel checks fluids before gliding; water and lava no longer end a glide. - LocalPlayer.isUnderWater is wasUnderwater; sprint conditions get shallow water, flight and gliding; no flight toggle while swimming; the base tick runs before local crouching; the desired pose puts swimming before gliding. - decreaseAirSupply creates the oxygen_bonus instance (getAttribute). - Swim sounds and muffled steps in water; entity event 67 drown bubbles. - Scene motion harness: swim_corpus (player travel in water and lava, bubble columns, air supply) and sprint-swim cases for --sprint-input. Co-Authored-By: Claude Opus 5.5 --- .../examples/scene_motion_probe.rs | 64 +++++++- crates/horizon-client/src/game.rs | 55 ++++++- crates/horizon-client/src/game/remote.rs | 24 ++- crates/horizon-client/src/health.rs | 3 + crates/horizon-client/src/motion.rs | 132 +++++++++------ .../horizon-client/src/motion/environment.rs | 101 +++++++++++- crates/horizon-client/src/motion/fluids.rs | 6 +- crates/horizon-client/src/pose.rs | 9 +- .../parity/VanillaSceneMotionOracle.java | 85 ++++++++-- .../parity/VanillaSprintInputOracle.java | 9 +- tools/test_native_scene_motion.py | 155 +++++++++++++++++- 11 files changed, 547 insertions(+), 96 deletions(-) diff --git a/crates/horizon-client/examples/scene_motion_probe.rs b/crates/horizon-client/examples/scene_motion_probe.rs index d5ef55d37..726ac278b 100644 --- a/crates/horizon-client/examples/scene_motion_probe.rs +++ b/crates/horizon-client/examples/scene_motion_probe.rs @@ -199,6 +199,28 @@ fn snapshot(out: &mut impl Write, player: &PlayerMotion) -> Result<()> { velocity.z.to_bits() )), MotionEvent::SplashEvent => Some("splash-event".into()), + MotionEvent::Swim { volume, pitch } => Some(format!( + "sound swim entity {:08x} {:08x}", + volume.to_bits(), + pitch.to_bits() + )), + MotionEvent::Emission { + state, + in_water: true, + .. + } => Some(format!("muffled-step {}", state.0)), + MotionEvent::BubbleColumnParticle { bubble, position } => Some(format!( + "column-particle {} {:016x},{:016x},{:016x} 1 {:016x},{:016x},{:016x} {:016x}", + if *bubble { "bubble" } else { "splash" }, + position.x.to_bits(), + position.y.to_bits(), + position.z.to_bits(), + 0f64.to_bits(), + if *bubble { 0.01f64 } else { 0.0 }.to_bits(), + 0f64.to_bits(), + if *bubble { 0.2f64 } else { 1.0 }.to_bits() + )), + MotionEvent::Drown => Some("broadcast 67".into()), // The oracle marks every getAdvancements call (ENTER_BLOCK.trigger) so. MotionEvent::EnterBlock { .. } => Some("hurt-criterion".into()), MotionEvent::Waypoint { receiver, enabled } => Some(format!( @@ -399,7 +421,8 @@ fn main() -> Result<()> { Some(vector(&op["value"])) }, ), - "block" => { + // A block, or every block of the box from position to "to". + "block" | "fill" => { let p = &op["position"]; let mut state = assets .registry @@ -417,12 +440,15 @@ fn main() -> Result<()> { .id(&definition) .ok_or("missing fixture state")?; } - world.scene.set( - p[0].as_i64().unwrap() as i32, - p[1].as_i64().unwrap() as i32, - p[2].as_i64().unwrap() as i32, - state, - )?; + let at = |v: &Value, i: usize| v[i].as_i64().unwrap() as i32; + let to = if op["to"].is_array() { &op["to"] } else { p }; + for x in at(p, 0)..=at(to, 0) { + for y in at(p, 1)..=at(to, 1) { + for z in at(p, 2)..=at(to, 2) { + world.scene.set(x, y, z, state)?; + } + } + } } "landing" => { let p = &op["position"]; @@ -443,6 +469,23 @@ fn main() -> Result<()> { // Entity.baseTick's fluid phase alone (wasEyeInWater, // updateFluidInteraction, lava fall halving, firstTick). "fluid_tick" => world.fluid_base_tick()?, + // LivingEntity.baseTick's air supply alone. + "air_tick" => world.tick_environment_damage()?, + "air" => world.player.air = op["value"].as_i64().unwrap() as i32, + "pitch" => world.player.pitch = single(&op["value"]), + "swimming" => world.player.swimming = op["value"].as_bool().unwrap(), + "effect" => { + let on = op["value"].as_bool().unwrap(); + let status = &mut world.player.status; + match op["name"].as_str().unwrap() { + "minecraft:dolphins_grace" => status.dolphins_grace = on, + "minecraft:water_breathing" | "minecraft:conduit_power" => { + status.water_breathing = on + } + "minecraft:breath_of_the_nautilus" => status.breath_of_the_nautilus = on, + other => return Err(format!("unknown fixture effect {other}").into()), + } + } "travel" => world.travel_in_air(vector(&op["value"]))?, "tick" => { let v = vector(&op["value"]); @@ -569,7 +612,7 @@ fn main() -> Result<()> { let stuck = player.stuck_multiplier; writeln!( out, - "block {} frozen {} {} {} {:016x},{:016x},{:016x} fluid {} {} {} {} {:016x} {:016x}", + "block {} frozen {} {} {} {:016x},{:016x},{:016x} fluid {} {} {} {} {:016x} {:016x} swim {} {} air {}", check_block.0, player.ticks_frozen, player.in_powder_snow, @@ -582,7 +625,10 @@ fn main() -> Result<()> { player.is_eye_in_fluid(WATER), player.fluids.first_tick, player.fluid_height(WATER).to_bits(), - player.fluid_height(LAVA).to_bits() + player.fluid_height(LAVA).to_bits(), + player.swimming, + player.fluids.was_eye_in_water, + player.air )?; writeln!( out, diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index f87d974e0..0bf16d5bd 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -2970,6 +2970,7 @@ impl Game<'_> { elytra.damage += glider_wear; } let feet = [player.position.x, player.position.y, player.position.z]; + let player_velocity = [player.velocity.x, player.velocity.y, player.velocity.z]; self.previous_eye = self.eye; self.eye += (camera_eye.unwrap_or(player.dimensions.eye_height) - self.eye) * 0.5; let crouching = player.pose == horizon_client::pose::Pose::Crouching; @@ -2979,13 +2980,59 @@ impl Game<'_> { match event { MotionEvent::HurtSound(sound) => self.player_hurt_sound(sound, feet), MotionEvent::Emission { - position, state, .. + state, in_water, .. } if !crouching => { - // Entity.playStepSound: the block's step sound at 0.15 volume. let sounds = self.res.facts.get(state).sounds.clone(); + // Entity.playStepSound: the block's step sound at 0.15 volume, + // muffled under the swim sound in water. + let (volume, pitch) = if in_water { + (sounds.volume * 0.05, sounds.pitch * 0.8) + } else { + (sounds.volume * 0.15, sounds.pitch) + }; + self.audio.play(&sounds.step, Some(feet), volume, pitch); + } + MotionEvent::Swim { volume, pitch } => { self.audio - .play(&sounds.step, Some(feet), sounds.volume * 0.15, sounds.pitch); - let _ = position; + .play("minecraft:entity.player.swim", Some(feet), volume, pitch); + } + MotionEvent::Drown => { + // LivingEntity.makeDrownParticles: eight bubbles moving + // with the player. + use horizon_client::particles::{ParticleOptions, ParticleType}; + for _ in 0..8 { + let mut triangle = || { + let r = self.particles.random(); + r.next_double() - r.next_double() + }; + let p = [ + feet[0] + triangle(), + feet[1] + triangle(), + feet[2] + triangle(), + ]; + self.particles.add( + &ParticleOptions::simple(ParticleType::Bubble), + p, + player_velocity, + ); + } + } + MotionEvent::BubbleColumnParticle { bubble, position } => { + // ServerLevel.sendParticles: SPLASH (speed 1) or BUBBLE + // (y spread 0.01, speed 0.2), one each. + use horizon_client::particles::{ParticleOptions, ParticleType}; + let (kind, spread, speed) = if bubble { + (ParticleType::Bubble, [0.0, 0.01, 0.0], 0.2) + } else { + (ParticleType::Splash, [0.0; 3], 1.0) + }; + self.particles.send_particles( + &ParticleOptions::simple(kind), + [position.x, position.y, position.z], + spread, + speed, + 1, + ); } MotionEvent::Fall(horizon_client::landing::FallEvent::Sound { sound, diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs index 61115df1f..4ca3fbb9d 100644 --- a/crates/horizon-client/src/game/remote.rs +++ b/crates/horizon-client/src/game/remote.rs @@ -1754,12 +1754,24 @@ impl Game<'_> { let crouching = player.pose == horizon_client::pose::Pose::Crouching; let feet = [player.position.x, player.position.y, player.position.z]; for event in events { - if let horizon_client::motion::MotionEvent::Emission { state, .. } = event - && !crouching - { - let sounds = self.res.facts.get(state).sounds.clone(); - self.audio - .play(&sounds.step, Some(feet), sounds.volume * 0.15, sounds.pitch); + match event { + horizon_client::motion::MotionEvent::Emission { + state, in_water, .. + } if !crouching => { + let sounds = self.res.facts.get(state).sounds.clone(); + // Player.playStepSound: muffled under the swim sound in water. + let (volume, pitch) = if in_water { + (sounds.volume * 0.05, sounds.pitch * 0.8) + } else { + (sounds.volume * 0.15, sounds.pitch) + }; + self.audio.play(&sounds.step, Some(feet), volume, pitch); + } + horizon_client::motion::MotionEvent::Swim { volume, pitch } => { + self.audio + .play("minecraft:entity.player.swim", Some(feet), volume, pitch); + } + _ => {} } } // The server owns health and hunger: undo local food/fall changes. diff --git a/crates/horizon-client/src/health.rs b/crates/horizon-client/src/health.rs index c5d9c2c0b..a9a4864ce 100644 --- a/crates/horizon-client/src/health.rs +++ b/crates/horizon-client/src/health.rs @@ -95,6 +95,8 @@ pub enum HealthEvent { FreezeDamage(f32), /// `SweetBerryBushBlock.entityInside` pricking a moving entity. SweetBerryBushDamage(f32), + /// `LivingEntity.baseTick` drowning an entity out of air. + DrownDamage(f32), Updated { id: u8, value: f32, @@ -128,6 +130,7 @@ impl HealthEvent { Self::SweetBerryBushDamage(amount) => { format!("damage sweet_berry_bush {:08x}", amount.to_bits()) } + Self::DrownDamage(amount) => format!("damage drown {:08x}", amount.to_bits()), Self::Updated { id, value, dirty } => { format!("updated {id} {:08x} {dirty}", value.to_bits()) } diff --git a/crates/horizon-client/src/motion.rs b/crates/horizon-client/src/motion.rs index 1be338e2c..dce1f2adc 100644 --- a/crates/horizon-client/src/motion.rs +++ b/crates/horizon-client/src/motion.rs @@ -125,10 +125,17 @@ pub enum MotionEvent { state: BlockStateId, position: BlockPos, }, - /// `Entity.walkingStepSound` on this block. + /// `Entity.walkingStepSound` on this block: `Player.playStepSound` + /// muffles it under a swim sound when `in_water`. Emission { position: BlockPos, state: BlockStateId, + in_water: bool, + }, + /// `Entity.waterSwimSound`: `entity.player.swim`. + Swim { + volume: f32, + pitch: f32, }, Bounce { position: BlockPos, @@ -172,6 +179,15 @@ pub enum MotionEvent { }, /// ...and the SPLASH game event. SplashEvent, + /// `Entity.sendBubbleColumnParticles`: a SPLASH (or BUBBLE) particle + /// over the top of a bubble column the player rides. + BubbleColumnParticle { + bubble: bool, + position: Vec3, + }, + /// Entity event 67 (`LivingEntity.makeDrownParticles`): eight bubbles + /// around a drowning player. + Drown, } pub struct PlayerMotion { pub swimming: bool, @@ -514,13 +530,18 @@ impl PlayerMotion { .map_err(attribute_error)?; Ok(()) } - /// Local input sprint phase for the resident dry, standing, empty-equipment - /// player. Fluid, pose, vehicle, ability-flight and effect bindings remain - /// separate; hunger and collision conditions use this actor's actual state. + /// Local input sprint phase (`LocalPlayer.aiStep`'s sprint decisions). + /// Vehicle, item-use and effect bindings remain separate; hunger, flight, + /// water and collision conditions use this actor's actual state. pub fn sprint_input_tick(&mut self, keys: crate::sprint::Keys) -> Result<()> { let conditions = crate::sprint::Conditions { sprinting: self.sprinting, enough_food: self.health.food.has_enough_food(), + may_fly: self.may_fly, + flying: self.flying, + // Entity.isInShallowWater. + shallow_water: self.fluids.was_touching_water && !self.is_under_water(), + fall_flying: self.fall_flying, on_ground: self.ground.on_ground, horizontal_collision: self.collision.horizontal, minor_horizontal_collision: self.collision.minor, @@ -680,7 +701,7 @@ impl MotionWorld<'_, '_, '_> { } else if !was_jumping && jumping && !self.player.was_auto_jump { if self.player.jump_trigger_time == 0 { self.player.jump_trigger_time = 7; - } else { + } else if !self.player.swimming { self.player.flying = !self.player.flying; if self.player.flying && self.player.ground.on_ground { self.jump_from_ground()?; @@ -689,7 +710,8 @@ impl MotionWorld<'_, '_, '_> { } } let toggled = flying_before != self.player.flying; - // Player.tryToStartFallFlying (canGlide: airborne, not flying, a glider). + // Player.tryToStartFallFlying (canGlide: airborne, not flying, a glider; + // never from inside a liquid). let can_glide = self.player.glider && !self.player.ground.on_ground && !self.player.flying @@ -701,11 +723,8 @@ impl MotionWorld<'_, '_, '_> { // LivingEntity.tick fallFlyTicks, then updateFallFlying. if self.player.fall_flying { self.player.fall_fly_ticks += 1; - let still = self.player.glider - && !self.player.ground.on_ground - && !self.player.flying - && !self.player.fluids.was_touching_water - && !self.player.is_in_lava(); + // canGlide alone: water and lava don't end a glide. + let still = self.player.glider && !self.player.ground.on_ground && !self.player.flying; if !still { self.player.fall_flying = false; } else if (self.player.fall_fly_ticks + 1) % 10 == 0 @@ -716,6 +735,13 @@ impl MotionWorld<'_, '_, '_> { } else { self.player.fall_fly_ticks = 0; } + // LocalPlayer.goDownInWater, before LivingEntity.aiStep's velocity cleanup. + if self.player.fluids.was_touching_water + && self.player.shift_key_down + && !self.player.flying + { + self.player.velocity.y += f64::from(-0.04f32); + } if self.player.flying { // Vertical flight: jump up, shift down, three times the flying speed. let ya = i32::from(jumping) - i32::from(self.player.shift_key_down); @@ -762,6 +788,9 @@ impl MotionWorld<'_, '_, '_> { .food_tick(&self.resources.health, self.scene.health_rules) } pub fn controlled_simulation_tick(&mut self, keys: crate::sprint::Keys) -> Result<()> { + // The base tick (fluids, swimming) precedes LocalPlayer.aiStep. + self.player.health.advance_clock(); + self.fluid_base_tick()?; self.update_local_crouching()?; let mut keys = keys; // LocalPlayer.aiStep: a pending auto-jump presses jump for this tick @@ -771,8 +800,6 @@ impl MotionWorld<'_, '_, '_> { self.player.auto_jump_time -= 1; keys.jump = true; } - self.player.health.advance_clock(); - self.fluid_base_tick()?; self.player.sprint_input_tick(keys)?; self.player.shift_key_down = keys.shift; let direction = keys.direction(); @@ -821,34 +848,16 @@ impl MotionWorld<'_, '_, '_> { input.x = 0.0; input.z = 0.0; } - if self.player.shift_key_down - && !self.player.flying - && self.player.fluids.was_touching_water - { - self.player.velocity.y -= f64::from(0.04f32); - } - if self.player.jumping { - let in_lava = self.player.is_in_lava(); - let height = self.player.fluid_height(if in_lava { LAVA } else { WATER }); - let water_jump = self.player.fluids.was_touching_water - && height > 0.0 - && (!self.player.ground.on_ground || height > 0.4); - let lava_jump = in_lava && (!self.player.ground.on_ground || height > 0.4); - if !self.player.flying && (water_jump || lava_jump) { - self.player.velocity.y += f64::from(0.04f32); - } else if self.player.ground.on_ground && self.player.no_jump_delay == 0 { - self.jump_from_ground()?; - self.player.no_jump_delay = 10; - } - } else { - self.player.no_jump_delay = 0; - } + self.jump_phase()?; + // Player.travel: swim steering, then LivingEntity.travel (fluids + // first, then gliding, then air), keeping 0.6 of the vertical speed + // while flying. if self.player.swimming { let look_y = horizon_world::view_direction::view_vector(self.player.pitch, self.player.yaw).y; let near_surface = BlockPos::containing(Vec3::new( self.player.position.x, - self.player.position.y + 0.9, + self.player.position.y + 1.0 - 0.1, self.player.position.z, )); if look_y <= 0.0 @@ -859,20 +868,19 @@ impl MotionWorld<'_, '_, '_> { self.player.velocity.y += (look_y - self.player.velocity.y) * blend; } } - if self.player.fall_flying { - self.travel_fall_flying()?; - } else if self.player.flying { - // Player.travel while flying: keep 0.6 of the vertical speed. - let y = self.player.velocity.y; - self.travel_in_air(input)?; - self.player.velocity.y = y * 0.6; - } else if !self.player.flying + let flying_y = self.player.flying.then_some(self.player.velocity.y); + if !self.player.flying && (self.player.fluids.was_touching_water || self.player.is_in_lava()) { horizon_world::living_fluid::travel_in_fluid(self, input)?; + } else if self.player.fall_flying { + self.travel_fall_flying()?; } else { self.travel_in_air(input)?; } + if let Some(y) = flying_y { + self.player.velocity.y = y * 0.6; + } if self.player.block_effects { self.apply_effects_from_blocks()?; } @@ -1028,6 +1036,10 @@ impl MotionWorld<'_, '_, '_> { f64::from(1.0e-5_f32), f64::from(1.0e-5_f32), )); + // Mth.square(0.9999900000002526): a long move counts every block it + // crosses as precise. + let far = 0.999_990_000_000_252_6_f64; + let moved_far = from.distance_squared(to) > far * far; let mut hits = Vec::new(); let mut iterations = 0; let alive = !self.player.health.dead_or_dying(); @@ -1101,6 +1113,10 @@ impl MotionWorld<'_, '_, '_> { } "minecraft:cobweb" => self.web_inside(), "minecraft:sweet_berry_bush" => self.sweet_berry_bush_inside(state)?, + "minecraft:bubble_column" => { + let precise = moved_far || deflated.intersects(Aabb::block(p)); + self.bubble_column_inside(state, p, precise)? + } "minecraft:nether_portal" => self .player .events @@ -1596,8 +1612,8 @@ impl EntityMoveWorld for MotionWorld<'_, '_, '_> { Ok(block + efficiency * (1.0 - block)) } } -// The player's footsteps. Swimming, flapping and the step game event are -// not bound here (the sculk listeners track the player's steps themselves). +// The player's footsteps and swim sounds. Flapping and the step game event +// are not bound here (the sculk listeners track the player's steps themselves). impl MovementEmissionWorld for MotionWorld<'_, '_, '_> { type Error = Box; type State = BlockStateId; @@ -1664,10 +1680,17 @@ impl MovementEmissionWorld for MotionWorld<'_, '_, '_> { fn in_water(&mut self) -> Result { Ok(self.player.fluids.was_touching_water) } + /// `Player.playStepSound`: in water a swim sound, then the step muffled. fn walking_step_sound(&mut self, position: BlockPos, state: BlockStateId) -> Result<()> { - self.player - .events - .push(MotionEvent::Emission { position, state }); + let in_water = self.player.fluids.was_touching_water; + if in_water { + self.water_swim_sound()?; + } + self.player.events.push(MotionEvent::Emission { + position, + state, + in_water, + }); Ok(()) } fn step_event(&mut self, _: BlockStateId) -> Result<()> { @@ -1676,7 +1699,18 @@ impl MovementEmissionWorld for MotionWorld<'_, '_, '_> { fn next_step(&mut self) -> Result { Ok(self.player.steps.next_step()) } + /// `Entity.waterSwimSound` and `playSwimSound` (the level random stands + /// in for the entity's, as for the splash). fn water_swim_sound(&mut self) -> Result<()> { + let v = self.player.velocity; + let volume = 1.0_f32.min( + (v.x * v.x * f64::from(0.2_f32) + v.y * v.y + v.z * v.z * f64::from(0.2_f32)).sqrt() + as f32 + * 0.35, + ); + let random = &mut self.scene.random; + let pitch = 1.0 + (random.next_float() - random.next_float()) * 0.4; + self.player.events.push(MotionEvent::Swim { volume, pitch }); Ok(()) } fn entity_event(&mut self, _: MovementEvent) -> Result<()> { diff --git a/crates/horizon-client/src/motion/environment.rs b/crates/horizon-client/src/motion/environment.rs index 7f1dca470..4ba5e7099 100644 --- a/crates/horizon-client/src/motion/environment.rs +++ b/crates/horizon-client/src/motion/environment.rs @@ -38,7 +38,8 @@ impl MotionWorld<'_, '_, '_> { } Ok(()) } - pub(super) fn tick_environment_damage(&mut self) -> Result<()> { + /// `LivingEntity.baseTick`'s air supply and drowning, then lava. + pub fn tick_environment_damage(&mut self) -> Result<()> { let eye = BlockPos::containing(self.player.position.add_vector(Vec3::new( 0.0, f64::from(self.player.dimensions.eye_height), @@ -56,6 +57,13 @@ impl MotionWorld<'_, '_, '_> { && !self.player.invulnerable && !self.player.spectator { + // decreaseAirSupply's getAttribute: the instance exists from now + // on, even unmodified. + let key = self.player.attributes.key("minecraft:oxygen_bonus"); + self.player + .attributes + .get_instance(key) + .map_err(|e| format!("oxygen bonus: {e:?}"))?; let oxygen = self .player .attribute("minecraft:oxygen_bonus")? @@ -65,6 +73,10 @@ impl MotionWorld<'_, '_, '_> { } if self.player.air <= -20 { self.player.air = 0; + self.player.events.push(MotionEvent::Drown); + self.player.events.push(MotionEvent::Health( + crate::health::HealthEvent::DrownDamage(2.0), + )); self.environment_hurt("minecraft:drown", 2.0)?; } } else if !submerged @@ -153,7 +165,7 @@ impl LivingFluidWorld for MotionWorld<'_, '_, '_> { })) } fn fluid_jump_threshold(&mut self) -> Result { - Ok(0.4) + Ok(self.player.fluid_jump_threshold()) } fn is_free(&mut self, v: Vec3) -> Result { let b = self.player.bounds().move_by(v); @@ -166,7 +178,92 @@ impl LivingFluidWorld for MotionWorld<'_, '_, '_> { Ok(false) } } +impl PlayerMotion { + /// `Entity.getFluidJumpThreshold`: 0.4, or 0 under eyes lower than that. + pub fn fluid_jump_threshold(&self) -> f64 { + horizon_world::swimming::fluid_jump_threshold(self.dimensions.eye_height) + } +} impl MotionWorld<'_, '_, '_> { + /// `LivingEntity.aiStep`'s jump phase: rise in water or lava, else jump + /// from the ground (or from shallow fluid); nothing while flying. + pub(super) fn jump_phase(&mut self) -> Result<()> { + if !self.player.jumping || self.player.flying { + self.player.no_jump_delay = 0; + return Ok(()); + } + let in_lava = self.player.is_in_lava(); + let height = self.player.fluid_height(if in_lava { LAVA } else { WATER }); + let in_water = self.player.fluids.was_touching_water && height > 0.0; + let threshold = self.player.fluid_jump_threshold(); + let on_ground = self.player.ground.on_ground; + if in_water && !(on_ground && height <= threshold) { + // jumpInLiquid(WATER) + self.player.velocity.y += f64::from(0.04f32); + } else if in_lava && !(on_ground && self.player.fluid_height(LAVA) <= threshold) { + // jumpInLiquid(LAVA) + self.player.velocity.y += f64::from(0.04f32); + } else if (on_ground || in_water && height <= threshold) && self.player.no_jump_delay == 0 { + self.jump_from_ground()?; + self.player.no_jump_delay = 10; + } + Ok(()) + } + /// `BubbleColumnBlock.entityInside` with `Player.onAboveBubbleColumn` / + /// `onInsideBubbleColumn`: pushed up (or dragged down), faster at the + /// surface, never while flying. + pub(super) fn bubble_column_inside( + &mut self, + state: BlockStateId, + p: BlockPos, + precise: bool, + ) -> Result<()> { + if !precise { + return Ok(()); + } + let drag = self + .assets + .registry + .state(state) + .and_then(|s| s.properties.get("drag")) + .is_some_and(|d| d == "true"); + let above = self.block(p.offset(0, 1, 0)); + // stateAbove.getCollisionShape(level, pos): the shape is asked at the + // column's own position. + let binding = self.collision_binding; + let context = CollisionContext::empty(false); + let empty = binding + .collision_shape_with_context(&mut self.collisions(), above, p, &context)? + .is_empty() + && self.resources.fluids.fluid(above).kind() == FluidKind::Empty; + if self.player.flying { + return Ok(()); + } + let v = self.player.velocity; + let y = match (empty, drag) { + (true, true) => (-0.9_f64).max(v.y - 0.03), + (true, false) => 1.8_f64.min(v.y + 0.1), + (false, true) => (-0.3_f64).max(v.y - 0.03), + (false, false) => 0.7_f64.min(v.y + 0.06), + }; + self.player.velocity = Vec3::new(v.x, y, v.z); + if empty { + // Entity.sendBubbleColumnParticles: two splashes and two bubbles + // over the column's top, from the level random. + let random = &mut self.scene.random; + for bubble in [false, true, false, true] { + let x = f64::from(p.x) + random.next_double(); + let z = f64::from(p.z) + random.next_double(); + self.player.events.push(MotionEvent::BubbleColumnParticle { + bubble, + position: Vec3::new(x, f64::from(p.y + 1), z), + }); + } + } else { + self.player.fall_distance = 0.0; + } + Ok(()) + } fn has_liquid(&self, b: Aabb) -> Result { for x in b.min_position().x.floor() as i32..=b.max_position().x.floor() as i32 { for y in b.min_position().y.floor() as i32..=b.max_position().y.floor() as i32 { diff --git a/crates/horizon-client/src/motion/fluids.rs b/crates/horizon-client/src/motion/fluids.rs index f8afca24e..f85f755a9 100644 --- a/crates/horizon-client/src/motion/fluids.rs +++ b/crates/horizon-client/src/motion/fluids.rs @@ -109,9 +109,11 @@ impl PlayerMotion { pub fn is_eye_in_fluid(&self, tag: FluidTagId) -> bool { self.fluids.interaction.is_eye_in_fluid(&Membership, tag) } - /// `Player.isUnderWater`: the eye sample from the start of the base tick. + /// `LocalPlayer.isUnderWater`: `wasUnderwater`, the eye sample `Player.tick` + /// takes before the base tick (`Entity.isUnderWater` also needs the body + /// still in water). pub fn is_under_water(&self) -> bool { - self.fluids.was_eye_in_water && self.fluids.was_touching_water + self.fluids.was_eye_in_water } /// `Entity.isInLava`. pub fn is_in_lava(&self) -> bool { diff --git a/crates/horizon-client/src/pose.rs b/crates/horizon-client/src/pose.rs index a296546cc..9c8124b0e 100644 --- a/crates/horizon-client/src/pose.rs +++ b/crates/horizon-client/src/pose.rs @@ -98,16 +98,17 @@ impl MotionWorld<'_, '_, '_> { if !self.can_fit_pose(Pose::Swimming)? { return Ok(()); } - let desired = if self.player.fall_flying { - Pose::FallFlying - } else if self.player.swimming { + // Player.getDesiredPose: swimming before gliding. + let desired = if self.player.swimming { Pose::Swimming + } else if self.player.fall_flying { + Pose::FallFlying } else if self.player.shift_key_down && !self.player.flying { Pose::Crouching } else { Pose::Standing }; - let pose = if self.can_fit_pose(desired)? { + let pose = if self.player.spectator || self.can_fit_pose(desired)? { desired } else if self.can_fit_pose(Pose::Crouching)? { Pose::Crouching diff --git a/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaSceneMotionOracle.java b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaSceneMotionOracle.java index 9f1ea2af3..5fb2443d8 100644 --- a/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaSceneMotionOracle.java +++ b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaSceneMotionOracle.java @@ -71,11 +71,12 @@ public final class VanillaSceneMotionOracle { static String vectorBits(Vec3 p){return String.format("%016x,%016x,%016x",Double.doubleToLongBits(p.x),Double.doubleToLongBits(p.y),Double.doubleToLongBits(p.z));} static String soundName(SoundEvent s){ if(s==SoundEvents.PLAYER_SMALL_FALL)return "small";if(s==SoundEvents.PLAYER_BIG_FALL)return "big"; - if(s==SoundEvents.PLAYER_SPLASH)return "splash";if(s==SoundEvents.PLAYER_SPLASH_HIGH_SPEED)return "splash-high"; + if(s==SoundEvents.PLAYER_SPLASH)return "splash";if(s==SoundEvents.PLAYER_SPLASH_HIGH_SPEED)return "splash-high";if(s==SoundEvents.PLAYER_SWIM)return "swim"; return VanillaBlockLandingOracle.sound(s); } static final class Sources extends DamageSources { - DamageSource fall,stalagmite,starve,freeze,sweetBerryBush;Sources(){super(null);} + DamageSource fall,stalagmite,starve,freeze,sweetBerryBush,drown;Sources(){super(null);} + @Override public DamageSource drown(){return drown;} @Override public DamageSource freeze(){return freeze;} @Override public DamageSource sweetBerryBush(){return sweetBerryBush;} @Override public DamageSource starve(){return starve;} @@ -104,6 +105,13 @@ public final class VanillaSceneMotionOracle { @Override public long getGameTime(){return time;} @Override public void broadcastDamageEvent(Entity actor,DamageSource source){this.actor.events.add("broadcast-damage");} Level(){super(null,null,null,null,null,null,false,0L,List.of(),false);} + // LevelReader.containsAnyLiquid over the scene chunks (its section scan + // needs level chunks): any fluid from the box's minimum block to its + // maximum block, both included. + @Override public boolean containsAnyLiquid(AABB b){ + for(var p:BlockPos.betweenClosed(BlockPos.containing(b.minX,b.minY,b.minZ),BlockPos.containing(b.maxX,b.maxY,b.maxZ)))if(!getBlockState(p).getFluidState().isEmpty())return true; + return false; + } @Override public boolean isClientSide(){return false;} @Override public BlockGetter getChunkForCollisions(int x,int z){return chunks.get(key(x,z));} @Override public BlockState getBlockState(BlockPos p){var c=chunks.get(key(p.getX()>>4,p.getZ()>>4));return c==null?Blocks.AIR.defaultBlockState():c.getBlockState(p);} @@ -132,6 +140,10 @@ public final class VanillaSceneMotionOracle { actor.events.add("snowflake "+vectorBits(new Vec3(x,y,z))+" "+vectorBits(new Vec3(xs,ys,zs)));return 0; } @Override public int sendParticles(T particle,double x,double y,double z,int count,double dx,double dy,double dz,double speed){ + // Entity.sendBubbleColumnParticles. + if(particle==net.minecraft.core.particles.ParticleTypes.SPLASH||particle==net.minecraft.core.particles.ParticleTypes.BUBBLE){ + actor.events.add(String.format("column-particle %s %s %d %s %016x",particle==net.minecraft.core.particles.ParticleTypes.BUBBLE?"bubble":"splash",vectorBits(new Vec3(x,y,z)),count,vectorBits(new Vec3(dx,dy,dz)),Double.doubleToLongBits(speed)));return 0; + } var b=(net.minecraft.core.particles.BlockParticleOption)particle;if(dx!=0||dy!=0||dz!=0)throw new AssertionError(); actor.events.add(String.format("particles %d %s %d %016x",Block.getId(b.getState()),vectorBits(new Vec3(x,y,z)),count,Double.doubleToLongBits(speed)));return 0; } @@ -186,7 +198,14 @@ public final class VanillaSceneMotionOracle { @Override public BlockState getInBlockState(){return level().getBlockState(blockPosition());} @Override public ItemStack getMainHandItem(){return ItemStack.EMPTY;} @Override public boolean isPassenger(){return statisticsFlags!=null&&statFlag(0);} - @Override public boolean isSwimming(){return statisticsFlags!=null&&statFlag(1);} + @Override public boolean isSwimming(){return statisticsFlags!=null?statFlag(1):super.isSwimming();} + // LocalPlayer.isUnderWater: the resident player is the local one. + @Override public boolean isUnderWater(){return wasUnderwater;} + // The synchronized air supply as a plain field (no data item here). + int air; + @Override public int getAirSupply(){return air;} + @Override public void setAirSupply(int value){air=value;} + String swimState(){return "swim "+getSharedFlag(4)+" "+wasUnderwater+" air "+air;} @Override public boolean isEyeInFluid(net.minecraft.tags.TagKey tag){return statisticsFlags!=null?statFlag(2):super.isEyeInFluid(tag);} @Override public boolean isInWater(){return statisticsFlags!=null?statFlag(3):super.isInWater();} @Override public boolean onClimbable(){return statisticsFlags!=null?statFlag(4):super.onClimbable();} @@ -197,14 +216,15 @@ public final class VanillaSceneMotionOracle { @Override public boolean isAutoSpinAttack(){return false;} @Override public boolean isSpectator(){return false;} @Override public boolean isNoGravity(){return false;} - // No effects but Weaving (WebBlock.entityInside), set without the effect's callbacks. - boolean weaving; - @Override public boolean hasEffect(Holder effect){return weaving&&effect==net.minecraft.world.effect.MobEffects.WEAVING;} + // Effects as flags (Weaving for WebBlock.entityInside, water effects for + // travel and breathing), set without the effects' callbacks. + boolean weaving;Set> effectFlags; + @Override public boolean hasEffect(Holder effect){return weaving&&effect==net.minecraft.world.effect.MobEffects.WEAVING||effectFlags.contains(effect);} @Override public MobEffectInstance getEffect(Holder effect){return null;} @Override public MoveSimulationType getMoveSimulationType(){return MoveSimulationType.SERVER_AND_CLIENT;} @Override public boolean isClientAuthoritative(){return false;} @Override public void recordMovement(MoverType mover,Vec3 movement){} - @Override public void playSound(SoundEvent sound,float volume,float pitch){events.add(String.format("sound %s entity %08x %08x",soundName(sound),Float.floatToIntBits(volume),Float.floatToIntBits(pitch)));} + @Override public void playSound(SoundEvent sound,float volume,float pitch){if(stepping!=null&&sound!=SoundEvents.PLAYER_SWIM){events.add("muffled-step "+Block.getId(stepping));return;}events.add(String.format("sound %s entity %08x %08x",soundName(sound),Float.floatToIntBits(volume),Float.floatToIntBits(pitch)));} @Override protected void playBlockFallSound(){events.add("block-fall-sound");} @Override public void awardStat(net.minecraft.stats.Stat stat,int value){ if(stat.getValue()!=net.minecraft.stats.Stats.JUMP)throw new AssertionError(stat); @@ -215,12 +235,14 @@ public final class VanillaSceneMotionOracle { String name=stat==net.minecraft.stats.Stats.DAMAGE_ABSORBED?"absorbed":stat==net.minecraft.stats.Stats.DAMAGE_TAKEN?"taken":stat==net.minecraft.stats.Stats.DAMAGE_RESISTED?"resisted":null; if(name==null){name=stat.getPath();if(!Set.of("swim_one_cm","walk_under_water_one_cm","walk_on_water_one_cm","climb_one_cm","sprint_one_cm","crouch_one_cm","walk_one_cm","aviate_one_cm","fly_one_cm").contains(name))throw new AssertionError(stat);}events.add("health-stat "+name+" "+value); } - @Override public boolean hurtServer(net.minecraft.server.level.ServerLevel level,DamageSource source,float damage){var sources=((Level)level).sources;events.add(String.format("damage %s %08x",source==sources.fall?"fall":source==sources.stalagmite?"stalagmite":source==sources.starve?"starve":source==sources.freeze?"freeze":source==sources.sweetBerryBush?"sweet_berry_bush":"unknown",Float.floatToIntBits(damage)));return super.hurtServer(level,source,damage);} + @Override public boolean hurtServer(net.minecraft.server.level.ServerLevel level,DamageSource source,float damage){var sources=((Level)level).sources;events.add(String.format("damage %s %08x",source==sources.fall?"fall":source==sources.stalagmite?"stalagmite":source==sources.starve?"starve":source==sources.freeze?"freeze":source==sources.sweetBerryBush?"sweet_berry_bush":source==sources.drown?"drown":"unknown",Float.floatToIntBits(damage)));return super.hurtServer(level,source,damage);} @Override public void teleportRelative(double x,double y,double z){setPos(getX()+x,getY()+y,getZ()+z);} - @Override protected void playStepSound(BlockPos p,BlockState state){} + // Footsteps stay a controlled consumer; in water Player.playStepSound + // swims (its sound is compared) and muffles the step (marked here). + BlockState stepping; + @Override protected void playStepSound(BlockPos p,BlockState state){if(isInWater()){stepping=state;try{super.playStepSound(p,state);}finally{stepping=null;}}} @Override public void gameEvent(Holder event,Entity source){} @Override public LivingEntity getControllingPassenger(){return null;} - @Override public double getFluidJumpThreshold(){return .4;} // Block-inside effects and frozen ticks run only in "snow_tick" operations. boolean effects;int frozen;Vec3 tickStart; @Override public int getTicksFrozen(){return frozen;} @@ -251,10 +273,28 @@ public final class VanillaSceneMotionOracle { void clock()throws Exception{sceneLevel.time++;tickCount++;if(cooldown.getInt(this)>0)cooldown.setInt(this,cooldown.getInt(this)-1);if(hurtTime>0)hurtTime--;} // Entity.baseTick's fluid phase: wasEyeInWater, the real // updateFluidInteraction, lava's fall halving and the first tick's end. - void fluidTick(){wasEyeInWater=isEyeInFluid(net.minecraft.tags.FluidTags.WATER);updateFluidInteraction();if(isInLava())fallDistance*=0.5;firstTick=false;} + // Player.tick's updateIsUnderwater, then Entity.baseTick's fluid phase: + // wasEyeInWater, the real updateFluidInteraction and updateSwimming, + // lava's fall halving and the first tick's end. + void fluidTick(){updateIsUnderwater();wasEyeInWater=isEyeInFluid(net.minecraft.tags.FluidTags.WATER);updateFluidInteraction();updateSwimming();if(isInLava())fallDistance*=0.5;firstTick=false;} + // LivingEntity.baseTick's air supply (server): the real decrease / + // increase / drowning methods in its order. + void airTick(){ + if(!isAlive())return; + if(isEyeInFluid(net.minecraft.tags.FluidTags.WATER)&&!level().getBlockState(BlockPos.containing(getX(),getEyeY(),getZ())).is(Blocks.BUBBLE_COLUMN)){ + boolean canDrown=!canBreatheUnderwater()&&!MobEffectUtil.hasWaterBreathing(this)&&!getAbilities().invulnerable; + if(canDrown){ + setAirSupply(decreaseAirSupply(getAirSupply())); + if(shouldTakeDrowningDamage()){setAirSupply(0);level().broadcastEntityEvent(this,(byte)67);hurtServer((net.minecraft.server.level.ServerLevel)level(),damageSources().drown(),2.0F);} + }else if(getAirSupply())lines::iterator){ - var row=JsonParser.parseString(line).getAsJsonObject();var p=(Actor)allocate.invoke(unsafe,Actor.class);p.configure(level);p.events=new ArrayList<>();level.actor=p; + var row=JsonParser.parseString(line).getAsJsonObject();var p=(Actor)allocate.invoke(unsafe,Actor.class);p.configure(level);p.events=new ArrayList<>();level.actor=p;p.effectFlags=new HashSet<>();p.air=300; + // Entity.nextStep's initializer (allocation skips it): the first footstep or swim sound after a metre. + field(Entity.class,"nextStep").setFloat(p,1.0F); write(field(Entity.class,"type"),p,EntityTypes.PLAYER); p.scenePose=Pose.STANDING; write(field(Entity.class,"passengers"),p,com.google.common.collect.ImmutableList.of());write(field(Entity.class,"dimensions"),p,p.getDefaultDimensions(Pose.STANDING));write(field(Entity.class,"eyeHeight"),p,1.62f); @@ -357,9 +399,12 @@ public final class VanillaSceneMotionOracle { case "refresh_attributes"->p.attributeTick(); case "pose"->p.setPose(Pose.valueOf(op.get("value").getAsString())); case "controlled_tick"->{ + // Player.tick: the base tick (fluids, swimming, air supply), + // then LocalPlayer.aiStep's prefix and the actor's aiStep. if(p.sprintController==null)p.sprintController=Class.forName("dev.horizonlab.parity.VanillaSprintInputOracle$Controller").getConstructor(ServerPlayer.class).newInstance(p); + p.clock();var before=p.position();p.fluidTick();p.airTick(); int mask=op.get("value").getAsInt();var direction=(net.minecraft.world.phys.Vec2)p.sprintController.getClass().getMethod("step",int.class).invoke(p.sprintController,mask); - p.clock();var before=p.position();p.playerMovementTick(new Vec3(direction.x,0,direction.y),(mask&16)!=0);p.attributeTick();p.poseTick();p.checkMovementStatistics(p.getX()-before.x,p.getY()-before.y,p.getZ()-before.z);p.getFoodData().tick(p); + p.aiStepWith(new Vec3(direction.x,0,direction.y),(mask&16)!=0);p.attributeTick();p.poseTick();p.checkMovementStatistics(p.getX()-before.x,p.getY()-before.y,p.getZ()-before.z);p.getFoodData().tick(p); } case "health"->p.setHealth(single(op.get("value"))); case "absorption"->p.setAbsorptionAmount(single(op.get("value"))); @@ -372,7 +417,7 @@ public final class VanillaSceneMotionOracle { case "eat"->p.getFoodData().eat(op.get("nutrition").getAsInt(),single(op.get("value"))); case "food_tick"->p.getFoodData().tick(p); case "peaceful"->p.peaceful(); - case "simulation_tick"->{p.clock();var before=p.position();p.playerMovementTick(VanillaSceneCollisionOracle.vector(op.get("value")),op.get("jumping").getAsBoolean());p.attributeTick();p.poseTick();p.checkMovementStatistics(p.getX()-before.x,p.getY()-before.y,p.getZ()-before.z);p.getFoodData().tick(p);} + case "simulation_tick"->{p.clock();var before=p.position();p.fluidTick();p.airTick();p.aiStepWith(VanillaSceneCollisionOracle.vector(op.get("value")),op.get("jumping").getAsBoolean());p.attributeTick();p.poseTick();p.checkMovementStatistics(p.getX()-before.x,p.getY()-before.y,p.getZ()-before.z);p.getFoodData().tick(p);} case "movement_statistics"->{var delta=VanillaSceneCollisionOracle.vector(op.get("value"));p.checkMovementStatistics(delta.x,delta.y,delta.z);} case "statistics_context"->{ p.statisticsFlags=op.get("flags").getAsInt();p.getAbilities().invulnerable=op.get("invulnerable").getAsBoolean(); @@ -381,9 +426,15 @@ public final class VanillaSceneMotionOracle { } case "seed"->level.rng.setSeed(op.get("value").getAsLong()); case "impulse"->p.setIgnoreFallDamageFromCurrentImpulse(op.get("ignore").getAsBoolean(),op.get("value").isJsonNull()?null:VanillaSceneCollisionOracle.vector(op.get("value"))); - case "block"->{var v=op.getAsJsonArray("position");var pos=new BlockPos(v.get(0).getAsInt(),v.get(1).getAsInt(),v.get(2).getAsInt());var state=VanillaSceneCollisionOracle.state(op.get("name").getAsString());if(op.has("properties"))for(var property:op.getAsJsonObject("properties").entrySet())state=VanillaSceneCollisionOracle.property(state,state.getBlock().getStateDefinition().getProperty(property.getKey()),property.getValue().getAsString());level.chunks.get(key(pos.getX()>>4,pos.getZ()>>4)).write(pos,Block.getId(state));} + case "block","fill"->{var v=op.getAsJsonArray("position");var to=op.has("to")?op.getAsJsonArray("to"):v;var state=VanillaSceneCollisionOracle.state(op.get("name").getAsString());if(op.has("properties"))for(var property:op.getAsJsonObject("properties").entrySet())state=VanillaSceneCollisionOracle.property(state,state.getBlock().getStateDefinition().getProperty(property.getKey()),property.getValue().getAsString()); + for(int x=v.get(0).getAsInt();x<=to.get(0).getAsInt();x++)for(int y=v.get(1).getAsInt();y<=to.get(1).getAsInt();y++)for(int z=v.get(2).getAsInt();z<=to.get(2).getAsInt();z++){var pos=new BlockPos(x,y,z);level.chunks.get(key(pos.getX()>>4,pos.getZ()>>4)).write(pos,Block.getId(state));}} case "landing"->{var v=op.getAsJsonArray("position");p.land(number(op.get("value")),op.get("ground").getAsBoolean(),new BlockPos(v.get(0).getAsInt(),v.get(1).getAsInt(),v.get(2).getAsInt()));} case "fluid_tick"->p.fluidTick(); + case "air_tick"->p.airTick(); + case "air"->p.air=op.get("value").getAsInt(); + case "pitch"->p.setXRot(single(op.get("value"))); + case "swimming"->p.setSwimming(op.get("value").getAsBoolean()); + case "effect"->{var e=BuiltInRegistries.MOB_EFFECT.wrapAsHolder(BuiltInRegistries.MOB_EFFECT.getValue(Identifier.parse(op.get("name").getAsString())));if(op.get("value").getAsBoolean())p.effectFlags.add(e);else p.effectFlags.remove(e);} case "travel"->p.travel(VanillaSceneCollisionOracle.vector(op.get("value"))); case "tick"->p.movementTick(VanillaSceneCollisionOracle.vector(op.get("value"))); case "player_tick"->p.playerMovementTick(VanillaSceneCollisionOracle.vector(op.get("value")),op.get("jumping").getAsBoolean()); diff --git a/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaSprintInputOracle.java b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaSprintInputOracle.java index 43ca12714..636a6a038 100644 --- a/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaSprintInputOracle.java +++ b/mods/horizon/src/test/java/dev/horizonlab/parity/VanillaSprintInputOracle.java @@ -66,7 +66,11 @@ public final class VanillaSprintInputOracle { @Override public boolean isEyeInFluid(TagKey tag){return false;} @Override public boolean onClimbable(){return false;} @Override public boolean tryToStartFallFlying(){return false;} - @Override protected void goDownInWater(){} + // The controlled actor sinks (LivingEntity.goDownInWater on it). + @Override protected void goDownInWater(){ + if(controlled==null)return; + try{var method=LivingEntity.class.getDeclaredMethod("goDownInWater");method.setAccessible(true);method.invoke(controlled);}catch(ReflectiveOperationException e){throw new AssertionError(e);} + } @Override protected boolean isControlledCamera(){return false;} @Override public void onUpdateAbilities(){} @Override public void jumpFromGround(){} // post-sprint ability-flight callback @@ -95,7 +99,8 @@ public final class VanillaSprintInputOracle { modify=LocalPlayer.class.getDeclaredMethod("modifyInput",net.minecraft.world.phys.Vec2.class);modify.setAccessible(true); } public net.minecraft.world.phys.Vec2 step(int mask)throws Exception{ - p.flags=(p.controlled.onGround()?1<<14:0)|(p.controlled.horizontalCollision?1<<15:0)|(p.controlled.minorHorizontalCollision?1<<16:0); + p.flags=(p.controlled.onGround()?1<<14:0)|(p.controlled.horizontalCollision?1<<15:0)|(p.controlled.minorHorizontalCollision?1<<16:0) + |(p.controlled.isInShallowWater()?1<<6:0)|(p.controlled.isUnderWater()?1<<10:0)|(p.controlled.isSwimming()?1<<12:0)|(p.controlled.isInWater()?1<<13:0); p.horizontalCollision=p.controlled.horizontalCollision;p.minorHorizontalCollision=p.controlled.minorHorizontalCollision; p.calls.clear();for(int i=0;i Date: Thu, 15 Oct 2026 02:51:02 +0200 Subject: [PATCH 17/97] Opt-in data collection (3/5): the game obeys the player's consent The game never sends anything itself; it keeps items in the outbox for the launcher, and only for kinds the player allows: - Crash reports: crash::deliver keeps a scrubbed copy (error, stack, thread, Horizon version, graphics adapter and render settings; never the log, world, server or resource packs; the world's name and folder and the server address are scrubbed wherever they appear). Without consent crash-reports/ stays local, as before. - Performance: a Session records frame times while playing and the integrated server's tick times into fixed-size Timings, with the time to the title screen and to the world; on leaving a world or quitting, a session of a minute or more becomes a summary (under 1 KiB) when the player allows it. - The GPU, its driver and backend come from the wgpu adapter. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 1 + crates/horizon-client/Cargo.toml | 2 + crates/horizon-client/src/crash.rs | 6 +- crates/horizon-client/src/game.rs | 37 +++ crates/horizon-client/src/game/remote.rs | 2 + crates/horizon-client/src/gfx.rs | 7 + crates/horizon-client/src/lib.rs | 1 + crates/horizon-client/src/main.rs | 1 + crates/horizon-client/src/telemetry.rs | 373 +++++++++++++++++++++++ 9 files changed, 428 insertions(+), 2 deletions(-) create mode 100644 crates/horizon-client/src/telemetry.rs diff --git a/Cargo.lock b/Cargo.lock index b8052e8b9..0c37a850a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -911,6 +911,7 @@ dependencies = [ "horizon-assets", "horizon-core", "horizon-protocol", + "horizon-telemetry", "horizon-theme", "horizon-world", "log", diff --git a/crates/horizon-client/Cargo.toml b/crates/horizon-client/Cargo.toml index 12aeaae4a..838e56ace 100644 --- a/crates/horizon-client/Cargo.toml +++ b/crates/horizon-client/Cargo.toml @@ -27,6 +27,8 @@ log = "0.4" chrono = { version = "0.4.42", default-features = false, features = ["clock", "std"] } flate2 = { version = "1.1.10", default-features = false, features = ["rust_backend"] } horizon-theme = { path = "../horizon-theme" } +# Opt-in data collection: the game keeps, the launcher sends (docs/telemetry.md). +horizon-telemetry = { path = "../horizon-telemetry", default-features = false } arboard = { version = "3.6.1", default-features = false, features = ["wayland-data-control"] } zip = { version = "2", default-features = false, features = ["deflate"] } # Controllers (evdev + libudev on Linux, IOKit on macOS, Windows.Gaming.Input). diff --git a/crates/horizon-client/src/crash.rs b/crates/horizon-client/src/crash.rs index 7e57355f2..e0ece85f2 100644 --- a/crates/horizon-client/src/crash.rs +++ b/crates/horizon-client/src/crash.rs @@ -1,7 +1,8 @@ //! Crash reports, laid out like vanilla's CrashReport.getFriendlyReport: a comment, the time, //! a description, the error with its stack, then the details of the game and the machine. //! Written to `crash-reports/crash--client.txt` in the game folder when -//! the main thread panics or `main` gets an error back. Nothing is sent anywhere. +//! the main thread panics or `main` gets an error back. It leaves the machine only scrubbed, and +//! only if the player allows crash reports (`telemetry`). use std::fmt::Write as _; use std::path::{Path, PathBuf}; use std::sync::Mutex; @@ -105,7 +106,7 @@ impl Report { } /// The release this binary came with: launcher installs live in a folder named after the tag. -fn release_tag() -> Option { +pub fn release_tag() -> Option { let exe = std::env::current_exe().ok()?; let folder = exe.parent()?.file_name()?.to_str()?; (folder.starts_with('v') && folder[1..].starts_with(|c: char| c.is_ascii_digit())) @@ -270,6 +271,7 @@ fn deliver(home: &Path, report: Report) -> Option { ), ); crate::logging::flush(); + crate::telemetry::keep_crash(home, &report); match report.save(home) { Ok(path) => { eprintln!("Horizon: crash report saved to {}", path.display()); diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index 4771c3322..950a504fe 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -901,6 +901,8 @@ struct Game<'a> { creative_screen: Creative, control: Option, frame_stats: horizon_client::control::FrameStats, + /// This play session's frame and tick times, for opt-in performance statistics. + perf: horizon_client::telemetry::Session, /// Control replies waiting for a rendered frame or a benchmark deadline. pending_screenshot: Option>, pending_bench: Option<(Instant, std::sync::mpsc::Sender)>, @@ -5708,6 +5710,7 @@ impl Game<'_> { seed: Option, creative: bool, ) -> Result<()> { + self.perf.world_opening(); let save_root = std::env::current_dir()?.join("saves").join(folder); horizon_client::save::upgrade_older_world(&save_root)?; horizon_client::save::migrate_legacy(&save_root)?; @@ -6136,6 +6139,27 @@ impl Game<'_> { /// Leaving the game with a world open (window closed, Quit, `quit`): /// menu items go back (Player.closeContainer), then the world is saved, /// once. + /// Keeps this play session's performance summary for the launcher to send, if the player + /// allows performance statistics (`horizon_client::telemetry`), and starts the next one. + pub(super) fn finish_perf(&mut self) { + let s = &self.settings; + let settings = horizon_telemetry::payload::Settings { + render_distance: s.render_distance.clamp(0, 255) as u8, + simulation_distance: s.simulation_distance.clamp(0, 255) as u8, + // 260 is the slider's "unlimited". + max_fps: if s.max_fps >= 260 { + 0 + } else { + s.max_fps.min(u32::from(u16::MAX)) as u16 + }, + vsync: s.vsync, + fullscreen: s.fullscreen, + graphics: s.graphics_preset.clone(), + }; + self.perf + .finish(&horizon_client::logging::game_home(), settings); + } + pub(super) fn save_for_exit(&mut self) -> Result<()> { if self.title.is_some() || self.saved_for_exit { return Ok(()); @@ -6157,6 +6181,7 @@ impl Game<'_> { if self.remote.is_some() { return self.leave_server(None); } + self.finish_perf(); self.stats.custom("leave_game", 1); self.save_game()?; self.lan_close(false); @@ -8879,7 +8904,12 @@ impl ApplicationHandler for Game<'_> { for _ in 0..steps { let started = Instant::now(); if self.title.is_none() && !self.pause { + let tick = Instant::now(); horizon_client::spans::time("tick", || self.tick())?; + // In single player the tick is the integrated server's. + if self.remote.is_none() { + self.perf.tick(tick.elapsed().as_secs_f32() * 1000.0); + } self.tick_ambience(); self.tick_fov(); } else if self.title.is_some() { @@ -8965,6 +8995,11 @@ impl ApplicationHandler for Game<'_> { } if rendered { self.frame_stats.record(elapsed.as_secs_f32() * 1000.0); + if self.title.is_some() { + self.perf.title_shown(); + } else if self.screen == Screen::Playing && self.player.is_some() { + self.perf.frame(elapsed.as_secs_f32() * 1000.0); + } self.frames += 1; self.fps_frames += 1; horizon_client::crash::debug_crash_tick(); @@ -9019,6 +9054,7 @@ impl ApplicationHandler for Game<'_> { if let Err(e) = self.save_for_exit() { log::warn!("Horizon: failed to save the world on exit: {e}"); } + self.finish_perf(); } } /// clouds.png as filled cells (`CloudRenderer.prepare`: alpha 10 or more). @@ -9397,6 +9433,7 @@ pub fn run() -> Result<()> { creative_screen: Creative::load(&game_root)?, control: None, frame_stats: Default::default(), + perf: Default::default(), pending_screenshot: None, pending_bench: None, flight: None, diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs index 61115df1f..24a2d0e3a 100644 --- a/crates/horizon-client/src/game/remote.rs +++ b/crates/horizon-client/src/game/remote.rs @@ -151,6 +151,7 @@ fn number_format(f: &play::NumberFormat) -> horizon_client::scoreboard::NumberFo impl Game<'_> { /// Leave the title for a server (ConnectScreen): an empty world fed by the connection. pub(super) fn connect_server(&mut self, address: &str, name: &str) -> Result<()> { + self.perf.world_opening(); let root = self.options.resources.clone(); let builtin = Builtin::find(&root) .and_then(|p| Builtin::load(&p).ok()) @@ -262,6 +263,7 @@ impl Game<'_> { /// Disconnect and return to the multiplayer screen (DisconnectedScreen). pub(super) fn leave_server(&mut self, reason: Option) -> Result<()> { + self.finish_perf(); if reason.is_none() { // Leaving on purpose: nothing for auto-reconnect to retry. self.extras_left(); diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs index 2b47e2a89..6cc4d5df2 100644 --- a/crates/horizon-client/src/gfx.rs +++ b/crates/horizon-client/src/gfx.rs @@ -432,6 +432,13 @@ impl Renderer { info.backend, info.device_type ); + crate::telemetry::set_gpu( + &info.name, + format!("{} {}", info.driver, info.driver_info) + .trim() + .to_owned(), + format!("{:?}", info.backend), + ); crate::crash::set_detail( "Graphics Adapter", format!( diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs index 07ba1af2a..a7e3913bb 100644 --- a/crates/horizon-client/src/lib.rs +++ b/crates/horizon-client/src/lib.rs @@ -143,6 +143,7 @@ pub mod stopwatches; pub mod streaming; pub mod structure_blocks; pub mod tab_list; +pub mod telemetry; pub mod testgen; pub mod text; pub mod title; diff --git a/crates/horizon-client/src/main.rs b/crates/horizon-client/src/main.rs index 30ccd26a4..8004b2fa7 100644 --- a/crates/horizon-client/src/main.rs +++ b/crates/horizon-client/src/main.rs @@ -5,6 +5,7 @@ mod game; use horizon_client::{crash, logging}; fn main() { + horizon_client::telemetry::mark_start(); let args: Vec = std::env::args().skip(1).collect(); let game_args = args.iter().take_while(|a| *a != "--dedicated"); let help = game_args.clone().any(|a| a == "--help" || a == "-h"); diff --git a/crates/horizon-client/src/telemetry.rs b/crates/horizon-client/src/telemetry.rs new file mode 100644 index 000000000..5abc3bd89 --- /dev/null +++ b/crates/horizon-client/src/telemetry.rs @@ -0,0 +1,373 @@ +//! The game's part in opt-in data collection (`horizon_telemetry`, docs/telemetry.md). When the +//! player allows it, the game keeps a scrubbed crash report, or a play session's performance +//! summary, in the outbox. It never sends anything itself: the launcher does, at its next start. +//! Without the player's yes for that kind nothing is kept, and crash-reports/ stays local. +use std::path::Path; +use std::sync::{Mutex, OnceLock}; +use std::time::Instant; + +use horizon_telemetry::payload::{Crash, Perf, Settings, System, Timings}; +use horizon_telemetry::scrub::Scrubber; +use horizon_telemetry::{Item, Payload, Source, outbox}; + +/// A session shorter than this says too little to keep. +const MIN_SECONDS: f32 = 60.0; + +/// The details of a crash report that say what the game was doing, and only those: not the +/// world, the server or the resource packs. +const CRASH_DETAILS: [&str; 3] = ["Horizon Version", "Graphics Adapter", "Render Settings"]; + +static STARTED: OnceLock = OnceLock::new(); +/// The GPU's name, driver and backend, once the renderer has its adapter. +static GPU: Mutex> = Mutex::new(None); + +/// When the game started, for the time to the title screen. Call first thing in `main`. +pub fn mark_start() { + STARTED.get_or_init(Instant::now); +} + +pub fn set_gpu(name: &str, driver: String, backend: String) { + *GPU.lock().unwrap_or_else(|e| e.into_inner()) = Some((name.to_owned(), driver, backend)); +} + +/// This machine, with the GPU once the renderer knows it. +pub fn system() -> System { + let mut system = System::detect(); + if let Some((gpu, driver, backend)) = GPU.lock().unwrap_or_else(|e| e.into_inner()).clone() { + system.gpu = gpu; + system.driver = driver; + system.backend = backend; + } + system +} + +/// The release (`v2026.10.15`), or the client's crate version for a build from source. +pub fn version() -> String { + crate::crash::release_tag().unwrap_or_else(|| format!("dev {}", env!("CARGO_PKG_VERSION"))) +} + +/// What a crash report becomes when it may leave: the error and stack, the thread, and the +/// details in [`CRASH_DETAILS`], with the world's name and folder and the server's address +/// scrubbed wherever they appear. No log lines. +pub fn crash_item(report: &crate::crash::Report) -> Item { + let mut scrubber = Scrubber::new(); + for (key, value) in &report.details { + match key.as_str() { + // `Name (saves/folder)`, as game.rs sets it. + "World" => { + let (name, folder) = value.rsplit_once(" (saves/").unwrap_or((value, "")); + scrubber = scrubber.term(name).term(folder.trim_end_matches(')')); + } + "Server" => { + let host = value.rsplit_once(':').map_or(value.as_str(), |(h, _)| h); + scrubber = scrubber.term(value.as_str()).term(host); + } + _ => {} + } + } + let crash = Crash { + system: system(), + error: scrubber.scrub(&report.error), + stack: scrubber.scrub(&report.stack), + thread: report.thread.clone(), + details: report + .details + .iter() + .filter(|(k, _)| CRASH_DETAILS.contains(&k.as_str())) + .map(|(k, v)| (k.clone(), scrubber.scrub(v))) + .collect(), + }; + let mut item = Item::new(Source::Game, version(), Payload::Crash(crash)); + // A huge stack keeps its top, where the error is. + while item.validate().is_err() { + let Payload::Crash(crash) = &mut item.payload else { + break; + }; + let keep = crash.stack.lines().count() * 3 / 4; + if keep == 0 { + crash.stack.clear(); + break; + } + crash.stack = crash + .stack + .lines() + .take(keep) + .map(|l| format!("{l}\n")) + .collect(); + } + item +} + +/// Keeps the crash for the launcher to send, if the player allows crash reports. +pub fn keep_crash(home: &Path, report: &crate::crash::Report) { + if let Err(e) = outbox::push(home, &crash_item(report)) { + log::warn!("Horizon: could not keep the crash report to send: {e}"); + } +} + +/// One play session's performance, from entering a world to leaving it: frame and tick +/// times as [`Timings`] (fixed size whatever the length), never the frames themselves. +#[derive(Default)] +pub struct Session { + frames: Timings, + ticks: Timings, + played_ms: f32, + to_title_ms: Option, + /// The start was measured: only the first session carries it. + title_measured: bool, + to_world_ms: Option, + opening: Option, +} + +impl Session { + /// The title screen drew a frame: the first time, how long the start took. + pub fn title_shown(&mut self) { + if !self.title_measured { + self.title_measured = true; + self.to_title_ms = STARTED.get().map(|s| s.elapsed().as_millis() as u32); + } + } + + /// A world starts loading. + pub fn world_opening(&mut self) { + self.opening.get_or_insert_with(Instant::now); + } + + /// A frame drawn while playing (not in menus or loading). + pub fn frame(&mut self, ms: f32) { + if let Some(opening) = self.opening.take() + && self.to_world_ms.is_none() + { + self.to_world_ms = Some(opening.elapsed().as_millis() as u32); + } + self.frames.record(ms); + self.played_ms += ms; + } + + /// One tick of the integrated server, in single player. + pub fn tick(&mut self, ms: f32) { + self.ticks.record(ms); + } + + /// The session's summary, if it was long enough to say something. + pub fn summary(&self, settings: Settings) -> Option { + let seconds = self.played_ms / 1000.0; + (seconds >= MIN_SECONDS).then(|| Perf { + system: system(), + settings, + seconds: seconds as u32, + frames: self.frames.summary(), + ticks: (self.ticks.count() > 0).then(|| self.ticks.summary()), + peak_ram_mb: peak_ram_mb(), + to_title_ms: self.to_title_ms, + to_world_ms: self.to_world_ms, + }) + } + + /// Keeps the session's summary for the launcher to send, if the player allows performance + /// statistics, and starts the next session (the time to the title goes with the first). + pub fn finish(&mut self, home: &Path, settings: Settings) { + if horizon_telemetry::Consent::load(home).allows(horizon_telemetry::Kind::Perf) + && let Some(perf) = self.summary(settings) + { + let item = Item::new(Source::Game, version(), Payload::Perf(perf)); + if let Err(e) = outbox::push(home, &item) { + log::warn!("Horizon: could not keep the session's performance summary: {e}"); + } + } + *self = Self { + title_measured: self.title_measured, + ..Self::default() + }; + } +} + +/// The game's resident memory: the peak on Linux, what it uses now elsewhere. +fn peak_ram_mb() -> u32 { + let kib = if cfg!(target_os = "linux") { + std::fs::read_to_string("/proc/self/status") + .ok() + .and_then(|t| { + t.lines() + .find(|l| l.starts_with("VmHWM:"))? + .split_whitespace() + .nth(1)? + .parse::() + .ok() + }) + } else if cfg!(target_os = "macos") { + std::process::Command::new("ps") + .args(["-o", "rss=", "-p", &std::process::id().to_string()]) + .output() + .ok() + .and_then(|o| { + String::from_utf8_lossy(&o.stdout) + .trim() + .parse::() + .ok() + }) + } else { + None + }; + kib.map_or(0, |k| (k / 1024) as u32) +} + +#[cfg(test)] +mod tests { + use super::*; + use horizon_telemetry::{Choices, Consent, Kind}; + + fn home(name: &str) -> std::path::PathBuf { + let dir = std::env::temp_dir().join(format!( + "horizon-client-telemetry-{name}-{}", + std::process::id() + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + dir + } + + fn allow(home: &Path, choices: Choices) { + let mut consent = Consent::load(home); + consent.answer(choices); + consent.save(home).unwrap(); + } + + fn report() -> crate::crash::Report { + crate::crash::Report { + time: chrono::Local::now(), + description: "Unexpected error".into(), + error: + "panicked at src/save.rs:10:5:\nno level.dat in /Users/ana/horizon/saves/Ana's Base" + .into(), + stack: "horizon_client::save::load (crates/horizon-client/src/save.rs:10:5)\n".into(), + thread: "Render thread".into(), + side: "client", + details: vec![ + ( + "Horizon Version".into(), + "v2026.10.15 (client 0.1.0)".into(), + ), + ( + "Operating System".into(), + "macos (aarch64) version macOS 26.0".into(), + ), + ("World".into(), "Castle Ana (saves/Ana's Base)".into()), + ("Server".into(), "play.example.net:25565".into()), + ("Resource Packs".into(), "Ana's pack".into()), + ], + log: vec!["[CHAT] hi".into()], + } + } + + #[test] + fn a_crash_keeps_only_what_says_what_happened() { + let item = crash_item(&report()); + let Payload::Crash(crash) = &item.payload else { + panic!("a crash item"); + }; + assert_eq!( + crash.error, + "panicked at src/save.rs:10:5:\nno level.dat in /Users//horizon/saves/" + ); + assert_eq!( + crash.details, + [( + "Horizon Version".to_owned(), + "v2026.10.15 (client 0.1.0)".to_owned() + )] + ); + let json = serde_json::to_string(&item).unwrap(); + for private in [ + "Castle Ana", + "Ana's Base", + "example.net", + "Ana's pack", + "CHAT", + ] { + assert!(!json.contains(private), "{private} in {json}"); + } + assert!(item.validate().is_ok()); + } + + #[test] + fn a_huge_stack_is_cut_to_fit() { + let mut report = report(); + report.stack = + "horizon_client::game::deep (crates/horizon-client/src/game.rs:1:1)\n".repeat(2000); + let item = crash_item(&report); + assert!(item.validate().is_ok()); + let Payload::Crash(crash) = item.payload else { + panic!("a crash item"); + }; + assert!(crash.stack.lines().count() > 100); + } + + #[test] + fn crashes_stay_local_without_consent() { + let home = home("crash"); + keep_crash(&home, &report()); + assert!(outbox::pending(&home).is_empty()); + allow( + &home, + Choices { + performance: true, + ..Choices::NONE + }, + ); + keep_crash(&home, &report()); + assert!(outbox::pending(&home).is_empty()); + allow( + &home, + Choices { + crashes: true, + ..Choices::NONE + }, + ); + keep_crash(&home, &report()); + let pending = outbox::pending(&home); + assert_eq!(pending.len(), 1); + assert_eq!(pending[0].1.kind(), Kind::Crash); + } + + #[test] + fn a_session_is_kept_only_with_consent_and_once_long_enough() { + let home = home("session"); + let mut session = Session::default(); + session.world_opening(); + (0..2000).for_each(|_| session.frame(16.6)); + session.finish(&home, Settings::default()); + assert!(outbox::pending(&home).is_empty(), "33 s, and no consent"); + allow( + &home, + Choices { + performance: true, + ..Choices::NONE + }, + ); + (0..2000).for_each(|_| session.frame(16.6)); + session.finish(&home, Settings::default()); + assert!(outbox::pending(&home).is_empty(), "33 s is too short"); + session.world_opening(); + (0..4000).for_each(|_| session.frame(16.6)); + (0..1200).for_each(|_| session.tick(4.0)); + session.finish( + &home, + Settings { + render_distance: 12, + ..Settings::default() + }, + ); + let pending = outbox::pending(&home); + assert_eq!(pending.len(), 1); + let Payload::Perf(perf) = &pending[0].1.payload else { + panic!("a perf item"); + }; + assert_eq!(perf.seconds, 66); + assert_eq!(perf.frames.count, 4000); + assert_eq!(perf.ticks.as_ref().unwrap().p50_ms, 4.0); + assert_eq!(perf.settings.render_distance, 12); + assert!(perf.to_world_ms.is_some()); + assert!(serde_json::to_vec(&pending[0].1).unwrap().len() < 1024); + } +} From 12c1af0261529901209c807cd6e5bf1b9458fc29 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 02:53:59 +0200 Subject: [PATCH 18/97] Opt-in data collection (4/5): the ingest server crates/horizon-telemetry-server, its own workspace like the launcher's (the game's workspace never builds a web server): - POST /v1/batch (zstd, decoded and checked by horizon-telemetry), DELETE /v1/installs/, GET /v1/aggregate (cached 10 min, CORS for the website), GET /healthz. - SQLite: machine descriptions stored once, one row of columns per session with 80-byte summary blobs, zstd bodies for crash/bug/benchmark, daily totals rebuilt when a day changes and kept after raw rows expire (180 days). About 190 bytes per session on disk. - Per-address token bucket (addresses in memory only), per-install daily cap, groups under 5 install-days hidden from the totals. - Tests: refusals, rate limit, daily cap, deletion (rows and totals), retention, storage size, and end to end with the launcher's uploader. - Dockerfile and a path-filtered CI workflow. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/telemetry-server.yml | 34 + Cargo.toml | 2 +- crates/horizon-telemetry-server/.gitignore | 1 + crates/horizon-telemetry-server/Cargo.lock | 1106 +++++++++++++++++ crates/horizon-telemetry-server/Cargo.toml | 31 + crates/horizon-telemetry-server/Dockerfile | 13 + crates/horizon-telemetry-server/README.md | 58 + crates/horizon-telemetry-server/src/lib.rs | 307 +++++ crates/horizon-telemetry-server/src/main.rs | 40 + crates/horizon-telemetry-server/src/store.rs | 428 +++++++ .../horizon-telemetry-server/tests/server.rs | 393 ++++++ docs/telemetry.md | 2 +- 12 files changed, 2413 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/telemetry-server.yml create mode 100644 crates/horizon-telemetry-server/.gitignore create mode 100644 crates/horizon-telemetry-server/Cargo.lock create mode 100644 crates/horizon-telemetry-server/Cargo.toml create mode 100644 crates/horizon-telemetry-server/Dockerfile create mode 100644 crates/horizon-telemetry-server/README.md create mode 100644 crates/horizon-telemetry-server/src/lib.rs create mode 100644 crates/horizon-telemetry-server/src/main.rs create mode 100644 crates/horizon-telemetry-server/src/store.rs create mode 100644 crates/horizon-telemetry-server/tests/server.rs diff --git a/.github/workflows/telemetry-server.yml b/.github/workflows/telemetry-server.yml new file mode 100644 index 000000000..e543721f9 --- /dev/null +++ b/.github/workflows/telemetry-server.yml @@ -0,0 +1,34 @@ +name: telemetry-server +# The ingest server is its own workspace (crates/horizon-telemetry-server), so the checks job doesn't build +# it: this one does, when it or the crate it shares with the launcher and the game changes. +on: + push: + branches: [main] + paths: + - 'crates/horizon-telemetry/**' + - 'crates/horizon-telemetry-server/**' + - '.github/workflows/telemetry-server.yml' + pull_request: + paths: + - 'crates/horizon-telemetry/**' + - 'crates/horizon-telemetry-server/**' + - '.github/workflows/telemetry-server.yml' +permissions: + contents: read +jobs: + check: + runs-on: ubuntu-latest + timeout-minutes: 20 + defaults: + run: + working-directory: crates/horizon-telemetry-server + steps: + - uses: actions/checkout@v4 + - run: rustup toolchain install stable --profile minimal --component rustfmt --component clippy + - uses: Swatinem/rust-cache@v2 + with: + workspaces: crates/horizon-telemetry-server + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo +stable fmt --check + - run: cargo +stable clippy --all-targets --locked -- -D warnings + - run: cargo +stable test --locked diff --git a/Cargo.toml b/Cargo.toml index c8e81b0af..6c21e207d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ [workspace] -exclude = ["launcher"] +exclude = ["launcher", "crates/horizon-telemetry-server"] members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "xtask"] resolver = "2" diff --git a/crates/horizon-telemetry-server/.gitignore b/crates/horizon-telemetry-server/.gitignore new file mode 100644 index 000000000..b83d22266 --- /dev/null +++ b/crates/horizon-telemetry-server/.gitignore @@ -0,0 +1 @@ +/target/ diff --git a/crates/horizon-telemetry-server/Cargo.lock b/crates/horizon-telemetry-server/Cargo.lock new file mode 100644 index 000000000..e4e7d060e --- /dev/null +++ b/crates/horizon-telemetry-server/Cargo.lock @@ -0,0 +1,1106 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "atomic-waker" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0" + +[[package]] +name = "axum" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90" +dependencies = [ + "axum-core", + "bytes", + "form_urlencoded", + "futures-util", + "http", + "http-body", + "http-body-util", + "hyper", + "hyper-util", + "itoa", + "matchit", + "memchr", + "mime", + "percent-encoding", + "pin-project-lite", + "serde_core", + "serde_json", + "serde_path_to_error", + "serde_urlencoded", + "sync_wrapper", + "tokio", + "tower", + "tower-layer", + "tower-service", +] + +[[package]] +name = "axum-core" +version = "0.5.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "http-body-util", + "mime", + "pin-project-lite", + "sync_wrapper", + "tower-layer", + "tower-service", +] + +[[package]] +name = "base64" +version = "0.22.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" + +[[package]] +name = "bytes" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" + +[[package]] +name = "cc" +version = "1.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6651c9ed80effdc7db0ff72512157f901af5e3549e341e24b1dd4887d836d838" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "displaydoc" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "errno" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" +dependencies = [ + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "fallible-iterator" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649" + +[[package]] +name = "fallible-streaming-iterator" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a" + +[[package]] +name = "find-msvc-tools" +version = "0.1.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484" + +[[package]] +name = "foldhash" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2" + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "futures-core" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" + +[[package]] +name = "futures-task" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" + +[[package]] +name = "futures-util" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" +dependencies = [ + "futures-core", + "futures-task", + "pin-project-lite", + "slab", +] + +[[package]] +name = "getrandom" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0" +dependencies = [ + "cfg-if", + "libc", + "wasi", +] + +[[package]] +name = "getrandom" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" +dependencies = [ + "cfg-if", + "libc", + "r-efi", + "wasip2", +] + +[[package]] +name = "hashbrown" +version = "0.15.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1" +dependencies = [ + "foldhash", +] + +[[package]] +name = "hashlink" +version = "0.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7382cf6263419f2d8df38c55d7da83da5c18aef87fc7a7fc1fb1e344edfe14c1" +dependencies = [ + "hashbrown", +] + +[[package]] +name = "horizon-telemetry" +version = "0.1.0" +dependencies = [ + "getrandom 0.3.4", + "ruzstd", + "serde", + "serde_json", + "ureq", +] + +[[package]] +name = "horizon-telemetry-server" +version = "0.1.0" +dependencies = [ + "axum", + "horizon-telemetry", + "http-body-util", + "rusqlite", + "ruzstd", + "serde", + "serde_json", + "tokio", + "tower", +] + +[[package]] +name = "http" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0" +dependencies = [ + "bytes", + "itoa", +] + +[[package]] +name = "http-body" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c" +dependencies = [ + "bytes", + "http", +] + +[[package]] +name = "http-body-util" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "pin-project-lite", +] + +[[package]] +name = "httparse" +version = "1.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87" + +[[package]] +name = "httpdate" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9" + +[[package]] +name = "hyper" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c" +dependencies = [ + "atomic-waker", + "bytes", + "futures-core", + "http", + "http-body", + "httparse", + "httpdate", + "itoa", + "pin-project-lite", + "smallvec", + "tokio", +] + +[[package]] +name = "hyper-util" +version = "0.1.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ddc03d96684f9226b8a787cdb71488417b53ab5ea8fdb1dac946cb9431cc8bff" +dependencies = [ + "bytes", + "http", + "http-body", + "hyper", + "pin-project-lite", + "tokio", + "tower-service", +] + +[[package]] +name = "icu_collections" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fa68d21081c4a05d5a901a1c62add574c77048b6a1c67be3b50ce0b60d4ca513" +dependencies = [ + "displaydoc", + "potential_utf", + "utf8_iter", + "yoke", + "zerofrom", + "zerovec", +] + +[[package]] +name = "icu_locale_core" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d56e28588da92eee5c3201a6eff33fabdd49b62269c8938d4ff050ce4d900deb" +dependencies = [ + "displaydoc", + "litemap", + "tinystr", + "writeable", + "zerovec", +] + +[[package]] +name = "icu_normalizer" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "12f9cf5f235641ed274641dd81c3f28d870e276763d0797aeeab72317b1c646f" +dependencies = [ + "icu_collections", + "icu_normalizer_data", + "icu_properties", + "icu_provider", + "smallvec", + "zerovec", +] + +[[package]] +name = "icu_normalizer_data" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1563da1ed3e0b3bf3d74c9b85917ac9c56464d2f57242270c09c9e752f8021a0" + +[[package]] +name = "icu_properties" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e7ca276ad3145661a65914e6daf131ca5120cd3dcee8f8f3214b8875184a148" +dependencies = [ + "displaydoc", + "icu_collections", + "icu_locale_core", + "icu_properties_data", + "icu_provider", + "zerotrie", + "zerovec", +] + +[[package]] +name = "icu_properties_data" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e590f038c1464a96894fd6d10127e90a8be4509f56ff7ecef851b15cee0b7caa" + +[[package]] +name = "icu_provider" +version = "2.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d27bbb9d3abbefac45d55f647c9de1d44aafcd1186eb91879afef17c396c3e73" +dependencies = [ + "displaydoc", + "icu_locale_core", + "writeable", + "yoke", + "zerofrom", + "zerotrie", + "zerovec", +] + +[[package]] +name = "idna" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de" +dependencies = [ + "idna_adapter", + "smallvec", + "utf8_iter", +] + +[[package]] +name = "idna_adapter" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714" +dependencies = [ + "icu_normalizer", + "icu_properties", +] + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "libc" +version = "0.2.190" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78" + +[[package]] +name = "libsqlite3-sys" +version = "0.35.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "133c182a6a2c87864fe97778797e46c7e999672690dc9fa3ee8e241aa4a9c13f" +dependencies = [ + "cc", + "pkg-config", + "vcpkg", +] + +[[package]] +name = "litemap" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae" + +[[package]] +name = "log" +version = "0.4.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6" + +[[package]] +name = "matchit" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "mime" +version = "0.3.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a" + +[[package]] +name = "mio" +version = "1.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee" +dependencies = [ + "libc", + "wasi", + "windows-sys 0.61.2", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "pkg-config" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548" + +[[package]] +name = "potential_utf" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661" +dependencies = [ + "zerovec", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" + +[[package]] +name = "ring" +version = "0.17.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7" +dependencies = [ + "cc", + "cfg-if", + "getrandom 0.2.17", + "libc", + "untrusted", + "windows-sys 0.52.0", +] + +[[package]] +name = "rusqlite" +version = "0.37.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "165ca6e57b20e1351573e3729b958bc62f0e48025386970b6e4d29e7a7e71f3f" +dependencies = [ + "bitflags", + "fallible-iterator", + "fallible-streaming-iterator", + "hashlink", + "libsqlite3-sys", + "smallvec", +] + +[[package]] +name = "rustls" +version = "0.23.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf" +dependencies = [ + "log", + "once_cell", + "ring", + "rustls-pki-types", + "rustls-webpki", + "subtle", + "zeroize", +] + +[[package]] +name = "rustls-pki-types" +version = "1.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96" +dependencies = [ + "zeroize", +] + +[[package]] +name = "rustls-webpki" +version = "0.103.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f3c3cf1d8b1e7d4927e2d154c3fcb02979afb9939629c62cd9048d4f07b60ac2" +dependencies = [ + "ring", + "rustls-pki-types", + "untrusted", +] + +[[package]] +name = "ruzstd" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69e4ce4a039f42bf25920b95667e4d789e98749ab11bbb8d2c2936f788421bb5" +dependencies = [ + "twox-hash", +] + +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_path_to_error" +version = "0.1.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457" +dependencies = [ + "itoa", + "serde", + "serde_core", +] + +[[package]] +name = "serde_urlencoded" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd" +dependencies = [ + "form_urlencoded", + "itoa", + "ryu", + "serde", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "signal-hook-registry" +version = "1.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b" +dependencies = [ + "errno", + "libc", +] + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "smallvec" +version = "1.16.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5b3dc8af474f516a851ff4bd12db780f948b9250ad37211e4eec0bccea54e01b" + +[[package]] +name = "socket2" +version = "0.6.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4" +dependencies = [ + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "stable_deref_trait" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596" + +[[package]] +name = "subtle" +version = "2.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" + +[[package]] +name = "syn" +version = "3.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "sync_wrapper" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263" + +[[package]] +name = "synstructure" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "tinystr" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1e27c91459209c2986af3dcf603a5a74a4368754ce37414f59acc971167f643" +dependencies = [ + "displaydoc", + "zerovec", +] + +[[package]] +name = "tokio" +version = "1.53.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce3335fa71841cda333a58d7615b03901380ecf09d59b3296d21f8bbac0dde4e" +dependencies = [ + "libc", + "mio", + "pin-project-lite", + "signal-hook-registry", + "socket2", + "tokio-macros", + "windows-sys 0.61.2", +] + +[[package]] +name = "tokio-macros" +version = "2.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "tower" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4" +dependencies = [ + "futures-core", + "futures-util", + "pin-project-lite", + "sync_wrapper", + "tokio", + "tower-layer", + "tower-service", +] + +[[package]] +name = "tower-layer" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e" + +[[package]] +name = "tower-service" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3" + +[[package]] +name = "twox-hash" +version = "2.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86a801b3cea342a06d468c8710662aa29e5e05e4f5c0d62f00bbb7f2ad7941c2" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "untrusted" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1" + +[[package]] +name = "ureq" +version = "2.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "02d1a66277ed75f640d608235660df48c8e3c19f3b4edb6a263315626cc3c01d" +dependencies = [ + "base64", + "log", + "once_cell", + "rustls", + "rustls-pki-types", + "url", + "webpki-roots 0.26.11", +] + +[[package]] +name = "url" +version = "2.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed" +dependencies = [ + "form_urlencoded", + "idna", + "percent-encoding", + "serde", +] + +[[package]] +name = "utf8_iter" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be" + +[[package]] +name = "vcpkg" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426" + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "wasip2" +version = "1.0.4+wasi-0.2.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487" +dependencies = [ + "wit-bindgen", +] + +[[package]] +name = "webpki-roots" +version = "0.26.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9" +dependencies = [ + "webpki-roots 1.0.9", +] + +[[package]] +name = "webpki-roots" +version = "1.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a" +dependencies = [ + "rustls-pki-types", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-sys" +version = "0.52.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" +dependencies = [ + "windows-targets", +] + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_gnullvm", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + +[[package]] +name = "wit-bindgen" +version = "0.57.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e" + +[[package]] +name = "writeable" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc" + +[[package]] +name = "yoke" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5" +dependencies = [ + "stable_deref_trait", + "yoke-derive", + "zerofrom", +] + +[[package]] +name = "yoke-derive" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71" +dependencies = [ + "proc-macro2", + "quote", + "syn", + "synstructure", +] + +[[package]] +name = "zerofrom" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272" +dependencies = [ + "zerofrom-derive", +] + +[[package]] +name = "zerofrom-derive" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a" +dependencies = [ + "proc-macro2", + "quote", + "syn", + "synstructure", +] + +[[package]] +name = "zeroize" +version = "1.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879" + +[[package]] +name = "zerotrie" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f" +dependencies = [ + "displaydoc", + "yoke", + "zerofrom", +] + +[[package]] +name = "zerovec" +version = "0.11.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb0464e17806c1d976d5cba29399c7f08e516e279e2ba493f63123b5fca67dd8" +dependencies = [ + "yoke", + "zerofrom", + "zerovec-derive", +] + +[[package]] +name = "zerovec-derive" +version = "0.11.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "34df6fc39dbd26ddc9c10e6a2984476e13acce22e64e4487636ef494369225da" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/crates/horizon-telemetry-server/Cargo.toml b/crates/horizon-telemetry-server/Cargo.toml new file mode 100644 index 000000000..8dbb0b7fd --- /dev/null +++ b/crates/horizon-telemetry-server/Cargo.toml @@ -0,0 +1,31 @@ +[package] +name = "horizon-telemetry-server" +version = "0.1.0" +edition = "2024" +license = "MIT" +rust-version = "1.90" +publish = false +description = "Receives opt-in data collection batches, keeps them compactly in SQLite and serves anonymous totals" + +# Its own workspace, as the launcher's: the game's workspace never builds a web server. +[workspace] + +[dependencies] +horizon-telemetry = { path = "../horizon-telemetry", default-features = false } +axum = { version = "0.8", default-features = false, features = ["http1", "tokio", "json", "query"] } +tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "signal", "time"] } +# SQLite built in: one file on a small volume is the whole database. +rusqlite = { version = "0.37", features = ["bundled"] } +serde = { version = "1", features = ["derive"] } +serde_json = "1" +ruzstd = "0.9" + +[dev-dependencies] +# The uploader the launcher uses, against this server, end to end. +horizon-telemetry = { path = "../horizon-telemetry" } +tower = { version = "0.5", features = ["util"] } +http-body-util = "0.1" + +[profile.release] +strip = true +lto = "thin" diff --git a/crates/horizon-telemetry-server/Dockerfile b/crates/horizon-telemetry-server/Dockerfile new file mode 100644 index 000000000..6a4a53c8d --- /dev/null +++ b/crates/horizon-telemetry-server/Dockerfile @@ -0,0 +1,13 @@ +# Built from the repository root: docker build -f crates/horizon-telemetry-server/Dockerfile . +FROM rust:1-slim AS build +WORKDIR /src +# The root manifest only for the shared crate's workspace settings (edition, lints). +COPY Cargo.toml Cargo.toml +COPY crates/horizon-telemetry crates/horizon-telemetry +COPY crates/horizon-telemetry-server crates/horizon-telemetry-server +RUN cargo build --release --locked --manifest-path crates/horizon-telemetry-server/Cargo.toml + +FROM debian:stable-slim +COPY --from=build /src/crates/horizon-telemetry-server/target/release/horizon-telemetry-server /usr/local/bin/ +ENV HORIZON_TELEMETRY_DB=/data/telemetry.sqlite3 HORIZON_TELEMETRY_TRUST_PROXY=1 +CMD ["horizon-telemetry-server"] diff --git a/crates/horizon-telemetry-server/README.md b/crates/horizon-telemetry-server/README.md new file mode 100644 index 000000000..cf2d52393 --- /dev/null +++ b/crates/horizon-telemetry-server/README.md @@ -0,0 +1,58 @@ +# horizon-telemetry-server + +This server receives what players choose to send (performance summaries, crash and bug reports, benchmark uploads: [docs/telemetry.md](../../docs/telemetry.md)) and stores it in one SQLite file. It serves anonymous totals to the website. It is one small Rust process, about 7 MB of memory when idle. + + cargo run --release # in this folder: its own workspace, like the launcher's + PORT=8080 HORIZON_TELEMETRY_DB=/data/telemetry.sqlite3 horizon-telemetry-server + +The launcher sends to it when `HORIZON_TELEMETRY_URL` is set (and to `DEFAULT_ENDPOINT` in `crates/horizon-telemetry` once there is one). + +## Endpoints + +| | | +|---|---| +| `POST /v1/batch` | A zstd batch (`Content-Encoding: zstd`, at most 256 KiB, 1 MiB inflated, 64 items). Returns 204. Returns 400 for a bad batch, 413 for one too large, 415 if it is not zstd, 429 when over a limit. | +| `DELETE /v1/installs/` | Deletes everything that install sent. Its share of the daily totals is rebuilt at once. | +| `GET /v1/aggregate?days=30` | The totals the website reads. Cached 10 minutes, with `Access-Control-Allow-Origin` set to the website. | +| `GET /healthz` | `ok` | + +The totals are grouped per version, OS, GPU vendor and render distance. Each group has its sessions, install-days, hours played, the 14 frame-time buckets summed, and the mean p50 and p99 frame times. Groups with fewer than 5 install-days are left out. The totals also list crash counts per version and the newest 50 benchmark uploads. + +## Storage + +- `systems`: each distinct machine description once. Sessions point at it. +- `perf`: one row per session, in columns, its frame and tick summaries as 80-byte blobs. +- `reports`: crash and bug reports and benchmarks, their data compressed with zstd. +- `perf_daily`: the totals per day, rebuilt from `perf` when a day changes (new sessions, a deletion). + +Measured: **about 190 bytes per play session** on disk, indexes included (`tests/server.rs`, 10 000 sessions). 1 000 players playing twice a day for 180 days is about 70 MB. + +The day stored is the day the server received an item. The sender's IP address is never written down. The per-address rate limit keeps addresses in memory for an hour at most. + +Raw rows are deleted after `HORIZON_TELEMETRY_RETENTION_DAYS` (180). The daily totals stay; they hold no install ID. + +## Settings + +All are environment variables: + +- `PORT` +- `HORIZON_TELEMETRY_DB` +- `HORIZON_TELEMETRY_RETENTION_DAYS` (180) +- `HORIZON_TELEMETRY_MIN_INSTALL_DAYS` (5) +- `HORIZON_TELEMETRY_REQUESTS_PER_HOUR` per address (60, bursts of 6) +- `HORIZON_TELEMETRY_ITEMS_PER_DAY` per install (100) +- `HORIZON_TELEMETRY_TRUST_PROXY=1` behind a proxy (the client's address is then the first of `X-Forwarded-For`) +- `HORIZON_TELEMETRY_ALLOW_ORIGIN` (`https://playhorizon.dev`) + +## Hosting + +`Dockerfile` builds it from the repository root (`docker build -f crates/horizon-telemetry-server/Dockerfile .`). The database goes on a volume mounted at `/data`. + +At Railway's prices (RAM $10/GB-month, CPU $20/vCPU-month, volumes $0.15/GB-month, egress $0.05/GB), one more service with a 1 GB volume uses about $0.35 a month: + +- RAM about 15 MB: $0.15 +- CPU nearly idle: under $0.05 +- the volume: $0.15 +- egress, the cached totals: cents + +That fits inside the Hobby plan's included $5 of usage. Railway Postgres would cost a few dollars a month for its memory alone and buys nothing at this size. A bucket isn't needed: crash reports are a few KB compressed and live in the same file. diff --git a/crates/horizon-telemetry-server/src/lib.rs b/crates/horizon-telemetry-server/src/lib.rs new file mode 100644 index 000000000..b1521a714 --- /dev/null +++ b/crates/horizon-telemetry-server/src/lib.rs @@ -0,0 +1,307 @@ +//! The ingest server for opt-in data collection (docs/telemetry.md). +//! +//! - `POST /v1/batch`: a zstd batch from the launcher, checked by `horizon_telemetry::batch`. +//! - `DELETE /v1/installs/`: everything an install sent goes. +//! - `GET /v1/aggregate?days=30`: the anonymous totals the website reads, cached. +//! - `GET /healthz`. +//! +//! Abuse limits: a token bucket per IP address (kept in memory for an hour, never stored), a +//! daily item cap per install, and the batch size limits. Raw rows expire after +//! `retention_days`; the daily totals stay. One small process and one SQLite file: see +//! `README.md` for running it. +use std::collections::HashMap; +use std::net::{IpAddr, SocketAddr}; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use axum::Router; +use axum::extract::{ConnectInfo, Path, Query, Request, State}; +use axum::http::{HeaderMap, HeaderValue, StatusCode, header}; +use axum::response::{IntoResponse, Response}; +use axum::routing::{delete, get, post}; +use horizon_telemetry::batch; + +pub mod store; + +use store::Store; + +pub struct Config { + /// Days raw rows are kept. + pub retention_days: u32, + /// Groups in the public totals need at least this many install-days. + pub min_install_days: u64, + /// Requests an IP address may make an hour (with a burst of a tenth of it). + pub requests_per_hour: f64, + /// Items one install may send a day. + pub items_per_day: u32, + /// Behind a proxy (Railway, Fly…): the client's address is the first of X-Forwarded-For. + pub trust_proxy: bool, + /// The website allowed to read the totals from a browser. + pub allow_origin: String, +} + +impl Default for Config { + fn default() -> Self { + Self { + retention_days: 180, + min_install_days: 5, + requests_per_hour: 60.0, + items_per_day: 100, + trust_proxy: false, + allow_origin: "https://playhorizon.dev".into(), + } + } +} + +impl Config { + /// The defaults, with `HORIZON_TELEMETRY_RETENTION_DAYS`, `…_MIN_INSTALL_DAYS`, + /// `…_REQUESTS_PER_HOUR`, `…_ITEMS_PER_DAY`, `…_TRUST_PROXY` (1) and `…_ALLOW_ORIGIN`. + pub fn from_env() -> Self { + let var = |k: &str| std::env::var(format!("HORIZON_TELEMETRY_{k}")).ok(); + let d = Self::default(); + Self { + retention_days: var("RETENTION_DAYS") + .and_then(|v| v.parse().ok()) + .unwrap_or(d.retention_days), + min_install_days: var("MIN_INSTALL_DAYS") + .and_then(|v| v.parse().ok()) + .unwrap_or(d.min_install_days), + requests_per_hour: var("REQUESTS_PER_HOUR") + .and_then(|v| v.parse().ok()) + .unwrap_or(d.requests_per_hour), + items_per_day: var("ITEMS_PER_DAY") + .and_then(|v| v.parse().ok()) + .unwrap_or(d.items_per_day), + trust_proxy: var("TRUST_PROXY").is_some_and(|v| v == "1"), + allow_origin: var("ALLOW_ORIGIN").unwrap_or(d.allow_origin), + } + } +} + +pub struct App { + store: Mutex, + config: Config, + /// Tokens left and when they were counted, per client address. + buckets: Mutex>, + /// `/v1/aggregate` answers by `days`, with when they were made. + cache: Mutex>, + /// Today, in days since 1970 (a test moves it). + today: Box u32 + Send + Sync>, +} + +const CACHE_FOR: Duration = Duration::from_secs(600); + +fn status(code: StatusCode, message: &str) -> Response { + (code, message.to_owned()).into_response() +} + +impl App { + pub fn new(store: Store, config: Config) -> Arc { + Self::with_clock(store, config, Box::new(horizon_telemetry::today)) + } + + pub fn with_clock( + store: Store, + config: Config, + today: Box u32 + Send + Sync>, + ) -> Arc { + Arc::new(Self { + store: Mutex::new(store), + config, + buckets: Mutex::default(), + cache: Mutex::default(), + today, + }) + } + + fn store(&self) -> std::sync::MutexGuard<'_, Store> { + self.store.lock().unwrap_or_else(|e| e.into_inner()) + } + + /// Takes a token for `ip`; false when it has none left. + fn allow(&self, ip: IpAddr) -> bool { + let rate = self.config.requests_per_hour / 3600.0; + let burst = (self.config.requests_per_hour / 10.0).max(1.0); + let mut buckets = self.buckets.lock().unwrap_or_else(|e| e.into_inner()); + let now = Instant::now(); + let (tokens, at) = buckets.entry(ip).or_insert((burst, now)); + *tokens = (*tokens + now.duration_since(*at).as_secs_f64() * rate).min(burst); + *at = now; + if *tokens < 1.0 { + return false; + } + *tokens -= 1.0; + true + } + + fn client(&self, headers: &HeaderMap, peer: Option) -> IpAddr { + let forwarded = self + .config + .trust_proxy + .then(|| { + headers + .get("x-forwarded-for")? + .to_str() + .ok()? + .split(',') + .next()? + .trim() + .parse() + .ok() + }) + .flatten(); + forwarded + .or(peer.map(|p| p.ip())) + .unwrap_or(IpAddr::from([0, 0, 0, 0])) + } + + /// The day an install's newest row came in, if it has any left. + pub fn newest_day(&self, install: &[u8]) -> Option { + self.store().newest_day(install).ok().flatten() + } + + /// Daily upkeep: totals rebuilt, expired rows removed, idle rate-limit entries forgotten. + pub fn maintain(&self) -> rusqlite::Result { + let oldest = (self.today)().saturating_sub(self.config.retention_days); + let removed = self.store().expire(oldest)?; + self.buckets + .lock() + .unwrap_or_else(|e| e.into_inner()) + .retain(|_, (_, at)| at.elapsed() < Duration::from_secs(3600)); + if removed > 0 { + self.cache.lock().unwrap_or_else(|e| e.into_inner()).clear(); + } + Ok(removed) + } +} + +fn peer(req: &Request) -> Option { + req.extensions() + .get::>() + .map(|c| c.0) +} + +async fn receive(State(app): State>, req: Request) -> Response { + let ip = app.client(req.headers(), peer(&req)); + if !app.allow(ip) { + return status(StatusCode::TOO_MANY_REQUESTS, "too many requests"); + } + let zstd = req + .headers() + .get(header::CONTENT_ENCODING) + .is_some_and(|v| v.as_bytes().eq_ignore_ascii_case(b"zstd")); + if !zstd { + return status( + StatusCode::UNSUPPORTED_MEDIA_TYPE, + "send zstd (Content-Encoding: zstd)", + ); + } + let Ok(body) = axum::body::to_bytes(req.into_body(), batch::MAX_COMPRESSED).await else { + return status(StatusCode::PAYLOAD_TOO_LARGE, "a batch is at most 256 KiB"); + }; + let batch = match batch::decode(&body) { + Ok(batch) => batch, + Err(e) => return status(StatusCode::BAD_REQUEST, &e), + }; + let today = (app.today)(); + let install = store::install_key(&batch.install_id).unwrap_or_default(); + let mut store = app.store(); + let sent = store.count_on(&install, today).unwrap_or(u32::MAX); + if sent.saturating_add(batch.items.len() as u32) > app.config.items_per_day { + return status( + StatusCode::TOO_MANY_REQUESTS, + "this install's daily limit is reached", + ); + } + match store.insert(&batch, today) { + Ok(()) => StatusCode::NO_CONTENT.into_response(), + Err(e) => { + eprintln!("horizon-telemetry-server: could not store a batch: {e}"); + status(StatusCode::SERVICE_UNAVAILABLE, "try again later") + } + } +} + +async fn forget(State(app): State>, Path(id): Path, req: Request) -> Response { + if !app.allow(app.client(req.headers(), peer(&req))) { + return status(StatusCode::TOO_MANY_REQUESTS, "too many requests"); + } + let Some(install) = store::install_key(&id) else { + return status(StatusCode::BAD_REQUEST, "not an install ID"); + }; + match app.store().delete_install(&install) { + Ok(_) => { + app.cache.lock().unwrap_or_else(|e| e.into_inner()).clear(); + StatusCode::NO_CONTENT.into_response() + } + Err(e) => { + eprintln!("horizon-telemetry-server: could not delete an install: {e}"); + status(StatusCode::SERVICE_UNAVAILABLE, "try again later") + } + } +} + +#[derive(serde::Deserialize)] +struct Window { + days: Option, +} + +async fn aggregate(State(app): State>, Query(window): Query) -> Response { + let days = window.days.unwrap_or(30).clamp(1, 366); + let cached = app + .cache + .lock() + .unwrap_or_else(|e| e.into_inner()) + .get(&days) + .filter(|(at, _)| at.elapsed() < CACHE_FOR) + .map(|(_, json)| json.clone()); + let json = match cached { + Some(json) => json, + None => { + let to = (app.today)(); + let made = + app.store() + .aggregate(to + 1 - days.min(to + 1), to, app.config.min_install_days); + match made { + Ok(value) => { + let json = value.to_string(); + app.cache + .lock() + .unwrap_or_else(|e| e.into_inner()) + .insert(days, (Instant::now(), json.clone())); + json + } + Err(e) => { + eprintln!("horizon-telemetry-server: could not build the totals: {e}"); + return status(StatusCode::SERVICE_UNAVAILABLE, "try again later"); + } + } + } + }; + let origin = + HeaderValue::from_str(&app.config.allow_origin).unwrap_or(HeaderValue::from_static("*")); + ( + [ + ( + header::CONTENT_TYPE, + HeaderValue::from_static("application/json"), + ), + ( + header::CACHE_CONTROL, + HeaderValue::from_static("public, max-age=600"), + ), + (header::ACCESS_CONTROL_ALLOW_ORIGIN, origin), + ], + json, + ) + .into_response() +} + +pub fn router(app: Arc) -> Router { + Router::new() + .route("/v1/batch", post(receive)) + .route("/v1/installs/{id}", delete(forget)) + .route("/v1/aggregate", get(aggregate)) + .route("/healthz", get(|| async { "ok" })) + .with_state(app) +} diff --git a/crates/horizon-telemetry-server/src/main.rs b/crates/horizon-telemetry-server/src/main.rs new file mode 100644 index 000000000..9b9c702c3 --- /dev/null +++ b/crates/horizon-telemetry-server/src/main.rs @@ -0,0 +1,40 @@ +//! `horizon-telemetry-server`: serves on `PORT` (default 8080), keeps its data in +//! `HORIZON_TELEMETRY_DB` (default `telemetry.sqlite3`), and does its upkeep every ten minutes. +use std::net::SocketAddr; +use std::time::Duration; + +use horizon_telemetry_server::{App, Config, router, store::Store}; + +#[tokio::main(flavor = "multi_thread", worker_threads = 2)] +async fn main() { + let path = std::env::var("HORIZON_TELEMETRY_DB").unwrap_or_else(|_| "telemetry.sqlite3".into()); + let port: u16 = std::env::var("PORT") + .ok() + .and_then(|p| p.parse().ok()) + .unwrap_or(8080); + let store = Store::open(&path).unwrap_or_else(|e| panic!("{path}: {e}")); + let app = App::new(store, Config::from_env()); + let upkeep = app.clone(); + tokio::spawn(async move { + let mut every = tokio::time::interval(Duration::from_secs(600)); + loop { + every.tick().await; + if let Err(e) = upkeep.maintain() { + eprintln!("horizon-telemetry-server: upkeep failed: {e}"); + } + } + }); + let listener = tokio::net::TcpListener::bind(SocketAddr::from(([0, 0, 0, 0], port))) + .await + .unwrap_or_else(|e| panic!("port {port}: {e}")); + eprintln!("horizon-telemetry-server: listening on {port}, data in {path}"); + axum::serve( + listener, + router(app).into_make_service_with_connect_info::(), + ) + .with_graceful_shutdown(async { + let _ = tokio::signal::ctrl_c().await; + }) + .await + .unwrap_or_else(|e| panic!("{e}")); +} diff --git a/crates/horizon-telemetry-server/src/store.rs b/crates/horizon-telemetry-server/src/store.rs new file mode 100644 index 000000000..0bac20e50 --- /dev/null +++ b/crates/horizon-telemetry-server/src/store.rs @@ -0,0 +1,428 @@ +//! The database: one SQLite file, kept small. +//! +//! - `systems`: each distinct machine description once. Rows point at it, so a CPU and GPU +//! name isn't stored again with every session. +//! - `perf`: one row per play session, in columns. A frame or tick summary is an 80-byte blob +//! ([`pack`]), not JSON. +//! - `reports`: crash and bug reports and benchmark uploads, their `data` zstd-compressed. +//! - `perf_daily`: the anonymous totals per day, version, OS, GPU vendor and render distance +//! that `/v1/aggregate` reads. Rebuilt from `perf` when a day changes (new sessions, a +//! deletion), and kept after the raw rows expire. +//! +//! Dates are the day the server received an item (days since 1970, UTC). The sender's IP +//! address is never stored. +use std::collections::{HashMap, HashSet}; + +use horizon_telemetry::Kind; +use horizon_telemetry::batch::Batch; +use horizon_telemetry::payload::{BUCKET_EDGES_MS, Payload, Summary, System}; +use rusqlite::{Connection, OptionalExtension, params}; + +const BUCKETS: usize = BUCKET_EDGES_MS.len() + 1; + +const SCHEMA: &str = " +PRAGMA journal_mode = WAL; +PRAGMA synchronous = NORMAL; +CREATE TABLE IF NOT EXISTS systems ( + id INTEGER PRIMARY KEY, + os TEXT NOT NULL, os_version TEXT NOT NULL, arch TEXT NOT NULL, cpu TEXT NOT NULL, + threads INTEGER NOT NULL, ram_gb INTEGER NOT NULL, + gpu TEXT NOT NULL, driver TEXT NOT NULL, backend TEXT NOT NULL, + UNIQUE (os, os_version, arch, cpu, threads, ram_gb, gpu, driver, backend) +); +CREATE TABLE IF NOT EXISTS perf ( + install BLOB NOT NULL, day INTEGER NOT NULL, version TEXT NOT NULL, system INTEGER NOT NULL, + render_distance INTEGER NOT NULL, simulation_distance INTEGER NOT NULL, max_fps INTEGER NOT NULL, + vsync INTEGER NOT NULL, fullscreen INTEGER NOT NULL, graphics TEXT NOT NULL, + seconds INTEGER NOT NULL, frames BLOB NOT NULL, ticks BLOB, + peak_ram_mb INTEGER NOT NULL, to_title_ms INTEGER, to_world_ms INTEGER +); +CREATE INDEX IF NOT EXISTS perf_install ON perf (install); +CREATE INDEX IF NOT EXISTS perf_day ON perf (day); +CREATE TABLE IF NOT EXISTS reports ( + install BLOB NOT NULL, day INTEGER NOT NULL, kind INTEGER NOT NULL, version TEXT NOT NULL, + system INTEGER, body BLOB NOT NULL +); +CREATE INDEX IF NOT EXISTS reports_install ON reports (install); +CREATE INDEX IF NOT EXISTS reports_kind_day ON reports (kind, day); +CREATE TABLE IF NOT EXISTS perf_daily ( + day INTEGER NOT NULL, version TEXT NOT NULL, os TEXT NOT NULL, gpu_vendor TEXT NOT NULL, + render_distance INTEGER NOT NULL, + sessions INTEGER NOT NULL, installs INTEGER NOT NULL, seconds INTEGER NOT NULL, + buckets TEXT NOT NULL, p50_sum REAL NOT NULL, p99_sum REAL NOT NULL, + PRIMARY KEY (day, version, os, gpu_vendor, render_distance) +) WITHOUT ROWID; +CREATE TABLE IF NOT EXISTS dirty (day INTEGER PRIMARY KEY) WITHOUT ROWID; +"; + +fn kind_code(kind: Kind) -> i64 { + match kind { + Kind::Perf => 0, + Kind::Crash => 1, + Kind::Bug => 2, + Kind::Benchmark => 3, + } +} + +/// An install ID as 16 bytes. +pub fn install_key(id: &str) -> Option> { + horizon_telemetry::consent::is_install_id(id).then(|| { + (0..16) + .map(|i| u8::from_str_radix(&id[2 * i..2 * i + 2], 16).unwrap_or(0)) + .collect() + }) +} + +/// A summary as 80 bytes: the count, four percentiles, then the 14 buckets, little-endian. +pub fn pack(s: &Summary) -> Vec { + let mut out = Vec::with_capacity(8 + 16 + 4 * BUCKETS); + out.extend(s.count.to_le_bytes()); + for ms in [s.p50_ms, s.p95_ms, s.p99_ms, s.max_ms] { + out.extend(ms.to_le_bytes()); + } + for i in 0..BUCKETS { + out.extend(s.buckets.get(i).copied().unwrap_or(0).to_le_bytes()); + } + out +} + +pub fn unpack(bytes: &[u8]) -> Option { + if bytes.len() != 8 + 16 + 4 * BUCKETS { + return None; + } + let u32_at = |i: usize| u32::from_le_bytes(bytes[i..i + 4].try_into().unwrap_or_default()); + let f32_at = |i: usize| f32::from_bits(u32_at(i)); + Some(Summary { + count: u64::from_le_bytes(bytes[..8].try_into().ok()?), + p50_ms: f32_at(8), + p95_ms: f32_at(12), + p99_ms: f32_at(16), + max_ms: f32_at(20), + buckets: (0..BUCKETS).map(|i| u32_at(24 + 4 * i)).collect(), + }) +} + +/// The GPU's maker, the one GPU detail the public totals group by. +pub fn gpu_vendor(gpu: &str) -> &'static str { + let gpu = gpu.to_ascii_lowercase(); + [ + ("apple", "apple"), + ("nvidia", "nvidia"), + ("geforce", "nvidia"), + ("radeon", "amd"), + ("amd", "amd"), + ("intel", "intel"), + ("adreno", "qualcomm"), + ("llvmpipe", "software"), + ] + .into_iter() + .find(|(needle, _)| gpu.contains(needle)) + .map_or(if gpu.is_empty() { "unknown" } else { "other" }, |(_, v)| v) +} + +pub struct Store { + db: Connection, +} + +impl Store { + pub fn open(path: &str) -> rusqlite::Result { + let db = Connection::open(path)?; + db.execute_batch(SCHEMA)?; + Ok(Self { db }) + } + + /// How many items an install has sent on `day`. + pub fn count_on(&self, install: &[u8], day: u32) -> rusqlite::Result { + self.db.query_row( + "SELECT (SELECT count(*) FROM perf WHERE install = ?1 AND day = ?2) + + (SELECT count(*) FROM reports WHERE install = ?1 AND day = ?2)", + params![install, day], + |r| r.get(0), + ) + } + + /// Keeps a decoded batch, received on `day`. + pub fn insert(&mut self, batch: &Batch, day: u32) -> rusqlite::Result<()> { + let install = install_key(&batch.install_id).unwrap_or_default(); + let tx = self.db.transaction()?; + for item in &batch.items { + match &item.payload { + Payload::Perf(p) => { + let system = system_id(&tx, &p.system)?; + tx.execute( + "INSERT INTO perf (install, day, version, system, render_distance, simulation_distance, + max_fps, vsync, fullscreen, graphics, seconds, frames, ticks, peak_ram_mb, + to_title_ms, to_world_ms) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16)", + params![ + install, day, item.version, system, + p.settings.render_distance, p.settings.simulation_distance, p.settings.max_fps, + p.settings.vsync, p.settings.fullscreen, p.settings.graphics, + p.seconds, pack(&p.frames), p.ticks.as_ref().map(pack), p.peak_ram_mb, + p.to_title_ms, p.to_world_ms, + ], + )?; + } + payload => { + let system = match payload { + Payload::Crash(c) => Some(system_id(&tx, &c.system)?), + Payload::Bug(b) => Some(system_id(&tx, &b.system)?), + _ => None, + }; + let data = match payload { + Payload::Crash(c) => serde_json::to_vec(c), + Payload::Bug(b) => serde_json::to_vec(b), + Payload::Benchmark(r) => serde_json::to_vec(r), + Payload::Perf(_) => unreachable!("handled above"), + } + .unwrap_or_default(); + let body = ruzstd::encoding::compress_to_vec( + data.as_slice(), + ruzstd::encoding::CompressionLevel::Fastest, + ); + tx.execute( + "INSERT INTO reports (install, day, kind, version, system, body) VALUES (?1, ?2, ?3, ?4, ?5, ?6)", + params![install, day, kind_code(item.kind()), item.version, system, body], + )?; + } + } + } + tx.execute("INSERT OR IGNORE INTO dirty (day) VALUES (?1)", [day])?; + tx.commit() + } + + /// Deletes everything an install sent; the days it touched get their totals rebuilt. + pub fn delete_install(&mut self, install: &[u8]) -> rusqlite::Result { + let tx = self.db.transaction()?; + tx.execute( + "INSERT OR IGNORE INTO dirty (day) SELECT DISTINCT day FROM perf WHERE install = ?1", + [install], + )?; + let mut deleted = tx.execute("DELETE FROM perf WHERE install = ?1", [install])?; + deleted += tx.execute("DELETE FROM reports WHERE install = ?1", [install])?; + tx.commit()?; + self.rebuild_dirty()?; + Ok(deleted) + } + + /// Removes raw rows received before `oldest_day`; the daily totals stay. + pub fn expire(&mut self, oldest_day: u32) -> rusqlite::Result { + // A day's totals are final before its rows go. + self.rebuild_dirty()?; + let mut n = self + .db + .execute("DELETE FROM perf WHERE day < ?1", [oldest_day])?; + n += self + .db + .execute("DELETE FROM reports WHERE day < ?1", [oldest_day])?; + self.db.execute( + "DELETE FROM systems WHERE id NOT IN (SELECT system FROM perf) + AND id NOT IN (SELECT system FROM reports WHERE system IS NOT NULL)", + [], + )?; + Ok(n) + } + + /// Rebuilds the daily totals of every day marked changed. + pub fn rebuild_dirty(&mut self) -> rusqlite::Result<()> { + let days: Vec = { + let mut q = self.db.prepare("SELECT day FROM dirty")?; + q.query_map([], |r| r.get(0))?.collect::>()? + }; + for day in days { + self.rebuild_day(day)?; + } + Ok(()) + } + + fn rebuild_day(&mut self, day: u32) -> rusqlite::Result<()> { + #[derive(Default)] + struct Group { + sessions: u64, + installs: HashSet>, + seconds: u64, + buckets: [u64; BUCKETS], + p50_sum: f64, + p99_sum: f64, + } + let tx = self.db.transaction()?; + let mut groups: HashMap<(String, String, &'static str, u8), Group> = HashMap::new(); + { + let mut q = tx.prepare( + "SELECT perf.install, perf.version, systems.os, systems.gpu, perf.render_distance, + perf.seconds, perf.frames FROM perf JOIN systems ON systems.id = perf.system + WHERE perf.day = ?1", + )?; + let mut rows = q.query([day])?; + while let Some(r) = rows.next()? { + let gpu: String = r.get(3)?; + let key = (r.get(1)?, r.get(2)?, gpu_vendor(&gpu), r.get(4)?); + let Some(frames) = unpack(&r.get::<_, Vec>(6)?) else { + continue; + }; + let g = groups.entry(key).or_default(); + g.sessions += 1; + g.installs.insert(r.get(0)?); + g.seconds += r.get::<_, u64>(5)?; + for (sum, n) in g.buckets.iter_mut().zip(&frames.buckets) { + *sum += u64::from(*n); + } + g.p50_sum += f64::from(frames.p50_ms); + g.p99_sum += f64::from(frames.p99_ms); + } + } + tx.execute("DELETE FROM perf_daily WHERE day = ?1", [day])?; + for ((version, os, vendor, distance), g) in groups { + tx.execute( + "INSERT INTO perf_daily VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)", + params![ + day, + version, + os, + vendor, + distance, + g.sessions, + g.installs.len(), + g.seconds, + serde_json::to_string(&g.buckets.to_vec()).unwrap_or_default(), + g.p50_sum, + g.p99_sum, + ], + )?; + } + tx.execute("DELETE FROM dirty WHERE day = ?1", [day])?; + tx.commit() + } + + /// The anonymous totals for the days `from..=to`, groups with fewer than `k` install-days + /// left out, and the newest benchmark uploads. + pub fn aggregate(&mut self, from: u32, to: u32, k: u64) -> rusqlite::Result { + self.rebuild_dirty()?; + /// One group's sums over the window. + #[derive(Default)] + struct Totals { + sessions: u64, + install_days: u64, + seconds: u64, + buckets: [u64; BUCKETS], + p50_sum: f64, + p99_sum: f64, + } + let mut groups: HashMap<(String, String, String, u8), Totals> = HashMap::new(); + { + let mut q = self.db.prepare( + "SELECT version, os, gpu_vendor, render_distance, sessions, installs, seconds, buckets, + p50_sum, p99_sum FROM perf_daily WHERE day BETWEEN ?1 AND ?2", + )?; + let mut rows = q.query([from, to])?; + while let Some(r) = rows.next()? { + let g = groups + .entry((r.get(0)?, r.get(1)?, r.get(2)?, r.get(3)?)) + .or_default(); + g.sessions += r.get::<_, u64>(4)?; + g.install_days += r.get::<_, u64>(5)?; + g.seconds += r.get::<_, u64>(6)?; + let buckets: Vec = + serde_json::from_str(&r.get::<_, String>(7)?).unwrap_or_default(); + for (sum, n) in g.buckets.iter_mut().zip(buckets) { + *sum += n; + } + g.p50_sum += r.get::<_, f64>(8)?; + g.p99_sum += r.get::<_, f64>(9)?; + } + } + let (mut sessions, mut hours) = (0, 0.0); + let mut out: Vec = groups + .into_iter() + .filter(|(_, g)| g.install_days >= k) + .map(|((version, os, vendor, distance), g)| { + sessions += g.sessions; + hours += g.seconds as f64 / 3600.0; + let avg = |sum: f64| (sum / g.sessions as f64 * 10.0).round() / 10.0; + serde_json::json!({ + "version": version, "os": os, "gpu_vendor": vendor, "render_distance": distance, + "sessions": g.sessions, "install_days": g.install_days, + "hours": (g.seconds as f64 / 360.0).round() / 10.0, + "frame_buckets": g.buckets.to_vec(), "p50_ms": avg(g.p50_sum), "p99_ms": avg(g.p99_sum), + }) + }) + .collect(); + out.sort_by(|a, b| b["sessions"].as_u64().cmp(&a["sessions"].as_u64())); + let crashes: Vec = { + let mut q = self.db.prepare( + "SELECT version, count(*) FROM reports WHERE kind = ?1 AND day BETWEEN ?2 AND ?3 + GROUP BY version ORDER BY 2 DESC LIMIT 20", + )?; + q.query_map(params![kind_code(Kind::Crash), from, to], |r| { + Ok(serde_json::json!({ "version": r.get::<_, String>(0)?, "crashes": r.get::<_, u64>(1)? })) + })? + .collect::>()? + }; + let benchmarks: Vec = { + let mut q = self.db.prepare( + "SELECT day, version, body FROM reports WHERE kind = ?1 AND day BETWEEN ?2 AND ?3 + ORDER BY rowid DESC LIMIT 50", + )?; + q.query_map(params![kind_code(Kind::Benchmark), from, to], |r| { + let body: Vec = r.get(2)?; + Ok(serde_json::json!({ + "day": r.get::<_, u32>(0)?, "version": r.get::<_, String>(1)?, "report": inflate(&body), + })) + })? + .collect::>()? + }; + Ok(serde_json::json!({ + "from_day": from, "to_day": to, "min_install_days": k, + "bucket_edges_ms": BUCKET_EDGES_MS.map(|e| (f64::from(e) * 10.0).round() / 10.0), + "totals": { "sessions": sessions, "hours": (hours * 10.0).round() / 10.0 }, + "groups": out, "crashes_by_version": crashes, "benchmarks": benchmarks, + })) + } + + /// The day an install's newest row came in, if any (tests, and checking a deletion). + pub fn newest_day(&self, install: &[u8]) -> rusqlite::Result> { + self.db + .query_row( + "SELECT max(day) FROM (SELECT day FROM perf WHERE install = ?1 + UNION ALL SELECT day FROM reports WHERE install = ?1)", + [install], + |r| r.get(0), + ) + .optional() + .map(Option::flatten) + } +} + +fn system_id(tx: &rusqlite::Transaction, s: &System) -> rusqlite::Result { + tx.execute( + "INSERT OR IGNORE INTO systems (os, os_version, arch, cpu, threads, ram_gb, gpu, driver, backend) + VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)", + params![s.os, s.os_version, s.arch, s.cpu, s.threads, s.ram_gb, s.gpu, s.driver, s.backend], + )?; + tx.query_row( + "SELECT id FROM systems WHERE os = ?1 AND os_version = ?2 AND arch = ?3 AND cpu = ?4 + AND threads = ?5 AND ram_gb = ?6 AND gpu = ?7 AND driver = ?8 AND backend = ?9", + params![ + s.os, + s.os_version, + s.arch, + s.cpu, + s.threads, + s.ram_gb, + s.gpu, + s.driver, + s.backend + ], + |r| r.get(0), + ) +} + +/// A stored body back as JSON. +pub fn inflate(body: &[u8]) -> serde_json::Value { + use std::io::Read; + let mut json = Vec::new(); + ruzstd::decoding::StreamingDecoder::new(body) + .ok() + .and_then(|d| d.take(1 << 20).read_to_end(&mut json).ok()) + .and_then(|_| serde_json::from_slice(&json).ok()) + .unwrap_or(serde_json::Value::Null) +} diff --git a/crates/horizon-telemetry-server/tests/server.rs b/crates/horizon-telemetry-server/tests/server.rs new file mode 100644 index 000000000..f8c78f085 --- /dev/null +++ b/crates/horizon-telemetry-server/tests/server.rs @@ -0,0 +1,393 @@ +//! The server through its HTTP interface, and end to end with the launcher's uploader. +use std::sync::Arc; +use std::sync::atomic::{AtomicU32, Ordering}; + +use axum::body::Body; +use axum::http::{Request, StatusCode}; +use horizon_telemetry::batch::{self, Batch}; +use horizon_telemetry::payload::{Crash, Payload, Perf, Settings, Source, System, Timings}; +use horizon_telemetry::{Item, outbox}; +use horizon_telemetry_server::store::{self, Store}; +use horizon_telemetry_server::{App, Config, router}; +use http_body_util::BodyExt; +use tower::ServiceExt; + +const DAY: u32 = 20_741; + +fn install(n: u32) -> String { + format!("{n:032x}") +} + +fn perf(gpu: &str, distance: u8) -> Item { + let mut t = Timings::new(); + (0..30_000).for_each(|i| t.record(8.0 + (i % 50) as f32 / 10.0)); + let mut item = Item::new( + Source::Game, + "v2026.10.15", + Payload::Perf(Perf { + system: System { + os: "linux".into(), + os_version: "Fedora Linux 43".into(), + cpu: "AMD Ryzen 9 7950X".into(), + threads: 32, + ram_gb: 32, + gpu: gpu.into(), + driver: "570.86".into(), + backend: "Vulkan".into(), + ..System::default() + }, + settings: Settings { + render_distance: distance, + simulation_distance: 12, + graphics: "fancy".into(), + ..Settings::default() + }, + seconds: 1800, + frames: t.summary(), + peak_ram_mb: 2300, + ..Perf::default() + }), + ); + item.day = DAY; + item +} + +struct Server { + app: Arc, + day: Arc, +} + +fn server(config: Config) -> Server { + let day = Arc::new(AtomicU32::new(DAY)); + let clock = day.clone(); + let app = App::with_clock( + Store::open(":memory:").unwrap(), + config, + Box::new(move || clock.load(Ordering::SeqCst)), + ); + Server { app, day } +} + +impl Server { + async fn send(&self, req: Request) -> (StatusCode, String) { + let res = router(self.app.clone()).oneshot(req).await.unwrap(); + let code = res.status(); + let body = res.into_body().collect().await.unwrap().to_bytes(); + (code, String::from_utf8_lossy(&body).into_owned()) + } + + async fn post(&self, id: &str, items: Vec) -> StatusCode { + let body = batch::encode(&Batch::new(id, items)); + self.post_raw(body, Some("zstd")).await + } + + async fn post_raw(&self, body: Vec, encoding: Option<&str>) -> StatusCode { + let mut req = Request::post("/v1/batch").header("x-forwarded-for", "203.0.113.9"); + if let Some(e) = encoding { + req = req.header("content-encoding", e); + } + self.send(req.body(Body::from(body)).unwrap()).await.0 + } + + async fn aggregate(&self) -> serde_json::Value { + let (code, body) = self + .send( + Request::get("/v1/aggregate?days=30") + .body(Body::empty()) + .unwrap(), + ) + .await; + assert_eq!(code, StatusCode::OK); + serde_json::from_str(&body).unwrap() + } +} + +fn generous() -> Config { + Config { + requests_per_hour: 100_000.0, + ..Config::default() + } +} + +#[tokio::test] +async fn totals_show_only_groups_with_enough_installs() { + let s = server(generous()); + for n in 0..6 { + assert_eq!( + s.post(&install(n), vec![perf("NVIDIA GeForce RTX 4070", 12); 2]) + .await, + StatusCode::NO_CONTENT + ); + } + for n in 10..12 { + assert_eq!( + s.post(&install(n), vec![perf("Intel(R) Arc A770", 8)]) + .await, + StatusCode::NO_CONTENT + ); + } + let totals = s.aggregate().await; + let groups = totals["groups"].as_array().unwrap(); + assert_eq!( + groups.len(), + 1, + "two installs are too few to show: {totals}" + ); + let g = &groups[0]; + assert_eq!(g["gpu_vendor"], "nvidia"); + assert_eq!( + (g["sessions"].as_u64(), g["install_days"].as_u64()), + (Some(12), Some(6)) + ); + assert_eq!(g["hours"], 6.0); + assert_eq!( + g["frame_buckets"] + .as_array() + .unwrap() + .iter() + .map(|b| b.as_u64().unwrap()) + .sum::(), + 12 * 30_000 + ); + assert_eq!(totals["bucket_edges_ms"].as_array().unwrap().len(), 13); + let text = totals.to_string(); + assert!( + !text.contains(&install(0)) && !text.contains("Ryzen"), + "no install or machine in the totals" + ); +} + +#[tokio::test] +async fn bad_batches_are_refused() { + let s = server(generous()); + let good = batch::encode(&Batch::new(&install(1), vec![perf("x", 8)])); + assert_eq!( + s.post_raw(good.clone(), None).await, + StatusCode::UNSUPPORTED_MEDIA_TYPE + ); + assert_eq!( + s.post_raw(b"garbage".to_vec(), Some("zstd")).await, + StatusCode::BAD_REQUEST + ); + assert_eq!( + s.post_raw(vec![0; batch::MAX_COMPRESSED + 1], Some("zstd")) + .await, + StatusCode::PAYLOAD_TOO_LARGE + ); + assert_eq!( + s.post("not-an-id", vec![perf("x", 8)]).await, + StatusCode::BAD_REQUEST + ); + assert_eq!(s.post_raw(good, Some("zstd")).await, StatusCode::NO_CONTENT); +} + +#[tokio::test] +async fn an_address_is_rate_limited() { + let s = server(Config { + requests_per_hour: 30.0, + trust_proxy: true, + ..Config::default() + }); + for n in 0..3 { + assert_eq!( + s.post(&install(n), vec![perf("x", 8)]).await, + StatusCode::NO_CONTENT + ); + } + assert_eq!( + s.post(&install(9), vec![perf("x", 8)]).await, + StatusCode::TOO_MANY_REQUESTS + ); + // Another address has its own allowance. + let body = batch::encode(&Batch::new(&install(9), vec![perf("x", 8)])); + let req = Request::post("/v1/batch") + .header("x-forwarded-for", "198.51.100.7, 10.0.0.1") + .header("content-encoding", "zstd") + .body(Body::from(body)) + .unwrap(); + assert_eq!(s.send(req).await.0, StatusCode::NO_CONTENT); +} + +#[tokio::test] +async fn an_install_has_a_daily_cap() { + let s = server(Config { + items_per_day: 3, + ..generous() + }); + assert_eq!( + s.post(&install(1), vec![perf("x", 8); 2]).await, + StatusCode::NO_CONTENT + ); + assert_eq!( + s.post(&install(1), vec![perf("x", 8); 2]).await, + StatusCode::TOO_MANY_REQUESTS + ); + assert_eq!( + s.post(&install(1), vec![perf("x", 8)]).await, + StatusCode::NO_CONTENT + ); + s.day.store(DAY + 1, Ordering::SeqCst); + assert_eq!( + s.post(&install(1), vec![perf("x", 8); 3]).await, + StatusCode::NO_CONTENT + ); +} + +#[tokio::test] +async fn deleting_an_install_removes_its_rows_and_its_share_of_the_totals() { + let s = server(Config { + min_install_days: 1, + ..generous() + }); + let crash = Item::new(Source::Game, "v1", Payload::Crash(Crash::default())); + assert_eq!( + s.post(&install(1), vec![perf("Apple M4 Pro", 12), crash]) + .await, + StatusCode::NO_CONTENT + ); + assert_eq!( + s.post(&install(2), vec![perf("Apple M4 Pro", 12)]).await, + StatusCode::NO_CONTENT + ); + assert_eq!(s.aggregate().await["groups"][0]["sessions"], 2); + let (code, _) = s + .send( + Request::delete(format!("/v1/installs/{}", install(1))) + .body(Body::empty()) + .unwrap(), + ) + .await; + assert_eq!(code, StatusCode::NO_CONTENT); + let key = store::install_key(&install(1)).unwrap(); + assert_eq!(s.app.newest_day(&key), None); + let totals = s.aggregate().await; + assert_eq!( + totals["groups"][0]["sessions"], 1, + "the cache was dropped and the day rebuilt" + ); + assert_eq!(totals["crashes_by_version"].as_array().unwrap().len(), 0); + let (code, _) = s + .send( + Request::delete("/v1/installs/nope") + .body(Body::empty()) + .unwrap(), + ) + .await; + assert_eq!(code, StatusCode::BAD_REQUEST); +} + +#[tokio::test] +async fn raw_rows_expire_and_the_totals_stay() { + let s = server(Config { + min_install_days: 1, + retention_days: 180, + ..generous() + }); + assert_eq!( + s.post(&install(1), vec![perf("Apple M4 Pro", 12)]).await, + StatusCode::NO_CONTENT + ); + s.day.store(DAY + 179, Ordering::SeqCst); + assert_eq!(s.app.maintain().unwrap(), 0, "still within retention"); + s.day.store(DAY + 181, Ordering::SeqCst); + assert_eq!(s.app.maintain().unwrap(), 1); + assert_eq!( + s.app.newest_day(&store::install_key(&install(1)).unwrap()), + None + ); + let (_, body) = s + .send( + Request::get("/v1/aggregate?days=366") + .body(Body::empty()) + .unwrap(), + ) + .await; + let totals: serde_json::Value = serde_json::from_str(&body).unwrap(); + assert_eq!(totals["groups"][0]["sessions"], 1); +} + +#[test] +fn a_session_costs_little_storage() { + let dir = std::env::temp_dir().join(format!( + "horizon-telemetry-server-size-{}", + std::process::id() + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + let path = dir.join("t.sqlite3"); + let mut store = Store::open(path.to_str().unwrap()).unwrap(); + let gpus = [ + "Apple M4 Pro", + "NVIDIA GeForce RTX 4070", + "AMD Radeon RX 7800 XT", + "Intel(R) Arc A770", + ]; + let sessions = 10_000; + for n in 0..sessions / 10 { + let items = (0..10) + .map(|i| perf(gpus[(n + i) as usize % 4], 8 + (i % 3) as u8 * 4)) + .collect(); + store + .insert(&Batch::new(&install(n), items), DAY + n % 30) + .unwrap(); + } + store.rebuild_dirty().unwrap(); + drop(store); + let bytes: u64 = std::fs::read_dir(&dir) + .unwrap() + .flatten() + .map(|e| e.metadata().unwrap().len()) + .sum(); + let per = bytes / u64::from(sessions); + eprintln!("{sessions} sessions: {bytes} bytes on disk, {per} bytes a session"); + assert!(per < 250, "{per} bytes a session"); +} + +#[tokio::test] +async fn the_launchers_uploader_reaches_it_end_to_end() { + let s = server(Config { + min_install_days: 1, + ..generous() + }); + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let url = format!("http://{}", listener.local_addr().unwrap()); + let service = + router(s.app.clone()).into_make_service_with_connect_info::(); + tokio::spawn(async move { axum::serve(listener, service).await.unwrap() }); + + let home = std::env::temp_dir().join(format!( + "horizon-telemetry-server-e2e-{}", + std::process::id() + )); + let _ = std::fs::remove_dir_all(&home); + let mut consent = horizon_telemetry::Consent::load(&home); + consent.answer(horizon_telemetry::Choices::ALL); + consent.save(&home).unwrap(); + for _ in 0..3 { + assert!(outbox::push(&home, &perf("Apple M4 Pro", 12)).unwrap()); + } + let (h, u) = (home.clone(), url.clone()); + let sent = tokio::task::spawn_blocking(move || horizon_telemetry::upload::flush(&h, &u)) + .await + .unwrap(); + assert_eq!( + sent, + horizon_telemetry::upload::Flush::Sent { + items: 3, + batches: 1 + } + ); + assert_eq!(s.aggregate().await["groups"][0]["sessions"], 3); + + let id = consent.install_id.clone(); + let deleted = + tokio::task::spawn_blocking(move || horizon_telemetry::upload::delete_remote(&url, &id)) + .await + .unwrap(); + assert_eq!(deleted, Ok(())); + assert_eq!( + s.app + .newest_day(&store::install_key(&consent.install_id).unwrap()), + None + ); +} diff --git a/docs/telemetry.md b/docs/telemetry.md index 6ac1438a5..ca8674588 100644 --- a/docs/telemetry.md +++ b/docs/telemetry.md @@ -52,4 +52,4 @@ Never sent: account names or UUIDs, world names, server or LAN addresses, chat, - `DELETE /v1/installs/`: deletes everything sent under that ID. - `GET /v1/aggregate`: the anonymous totals the website's results page reads. -Retention, rate limits and storage are described with the server. +`crates/horizon-telemetry-server` is the server. Its [README](../crates/horizon-telemetry-server/README.md) covers storage (about 190 bytes per play session), retention (180 days of raw rows, anonymous daily totals kept), rate limits and hosting. From b3755bd6b116cdde91b9e0cfa48218760427b666 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 02:59:29 +0200 Subject: [PATCH 19/97] website: privacy page for opt-in data collection /privacy says what the launcher may send when a player allows it (performance summaries, crash and bug reports, benchmark uploads), why, on what basis, where it is kept and for how long, and how to delete it. The footer links it. Co-Authored-By: Claude Opus 5.5 --- website/Caddyfile | 3 +- website/README.md | 1 + website/build.mjs | 2 +- website/public/sitemap.xml | 1 + website/serve.mjs | 2 ++ website/src/index.html | 4 +-- website/src/privacy.html | 57 ++++++++++++++++++++++++++++++++++++++ website/src/style.css | 5 ++++ 8 files changed, 71 insertions(+), 4 deletions(-) create mode 100644 website/src/privacy.html diff --git a/website/Caddyfile b/website/Caddyfile index f0ba13136..7b919821e 100644 --- a/website/Caddyfile +++ b/website/Caddyfile @@ -27,7 +27,8 @@ header @assets Cache-Control "public, max-age=31536000, immutable" @media path /media/* /fonts/* /og.png /favicon* /apple-touch-icon.png header @media Cache-Control "public, max-age=604800" - @pages path / /index.html /404.html + rewrite /privacy /privacy.html + @pages path / /index.html /404.html /privacy.html header @pages Cache-Control "no-cache" @legal path /LEGAL.md /fonts/*.txt header @legal Content-Type "text/plain; charset=utf-8" diff --git a/website/README.md b/website/README.md index 0d931179d..8d47cf076 100644 --- a/website/README.md +++ b/website/README.md @@ -17,6 +17,7 @@ build.mjs renders dist/ (no dependencies) serve.mjs a tiny static server for local checks src/index.html the page, with {{placeholders}} build.mjs fills src/404.html the not-found page +src/privacy.html what the launcher can send when players allow it, retention, deletion (/privacy) src/tokens.css the design tokens, generated from crates/horizon-theme (do not edit) src/style.css every style, on top of the tokens src/main.js download buttons, patch notes, links, contributors, nav and menu, tabs, lightbox, motion diff --git a/website/build.mjs b/website/build.mjs index 6163d6307..86fbed910 100644 --- a/website/build.mjs +++ b/website/build.mjs @@ -200,7 +200,7 @@ const values = { YEAR: String(new Date().getUTCFullYear()), }; -for (const page of ["index.html", "404.html"]) { +for (const page of ["index.html", "404.html", "privacy.html"]) { let html = await readFile(join(site, "src", page), "utf8"); html = html.replace(/\{\{(\w+)\}\}/g, (all, key) => { if (!(key in values)) throw new Error(`${page}: unknown placeholder ${all}`); diff --git a/website/public/sitemap.xml b/website/public/sitemap.xml index 120b57f45..cd377327b 100644 --- a/website/public/sitemap.xml +++ b/website/public/sitemap.xml @@ -1,4 +1,5 @@ https://playhorizon.dev/ + https://playhorizon.dev/privacy diff --git a/website/serve.mjs b/website/serve.mjs index 210ea0e20..af8cb4a95 100644 --- a/website/serve.mjs +++ b/website/serve.mjs @@ -12,6 +12,8 @@ const port = Number(process.env.PORT) || 4173; createServer(async (req, res) => { let path = normalize(decodeURIComponent(new URL(req.url, "http://x").pathname)).replace(/^(\.\.[/\\])+/, ""); if (path.endsWith("/")) path += "index.html"; + // /privacy is privacy.html, as the Caddyfile rewrites it. + if (!extname(path)) path += ".html"; let file = join(root, path); let status = 200; try { diff --git a/website/src/index.html b/website/src/index.html index 0b6a9d880..0962b1a70 100644 --- a/website/src/index.html +++ b/website/src/index.html @@ -229,11 +229,11 @@ diff --git a/website/src/privacy.html b/website/src/privacy.html new file mode 100644 index 000000000..d3593cb3c --- /dev/null +++ b/website/src/privacy.html @@ -0,0 +1,57 @@ + + + + + + Privacy · Horizon + + + + + + + + + + +
+
+

PrivacyData collection

+

Nothing leaves without your yes.

+

The Horizon launcher can send a few things that help make the game faster and steadier. It asks first, each kind has its own switch, and every switch is off until you turn it on.

+
+

What can be sent

+

Only the kinds you allow, from the launcher's first-run question or Settings → Data collection:

+
    +
  • Performance statistics, after each play session of a minute or more. These are the frame-time and tick-time percentiles and a 14-bucket histogram (never a recording of each frame), the peak memory, how long the game took to start and to load the world, and the settings that change performance (render and simulation distance, frame limit, VSync, fullscreen, graphics mode).
  • +
  • Crash reports, when the game crashes. They hold the error, where it happened in Horizon's code, your graphics adapter and settings. They hold no log, no world, no server and no resource packs.
  • +
  • Bug reports that you write and send yourself. The end of the game's log goes with one only if you add it after reading it, and lines of chat are removed first.
  • +
  • Benchmark uploads of the benchmarks you run. These are shown publicly in the community results.
  • +
+

Each one also carries the Horizon version, the day it was made (not the time), and a description of your machine: the operating system and version, the CPU model and thread count, the memory rounded to the gigabyte, and the GPU, its driver and the graphics backend. It also carries a random install ID. The launcher makes that ID the first time you allow something; it says nothing about you and exists only so that your data can be deleted.

+

Never sent: your Microsoft or Minecraft account name or UUID, world names, server or LAN addresses, chat, and your user name or home folder in file paths. Before anything is kept, those are replaced with placeholders, along with e-mail and IP addresses. The server does not store the IP address requests come from.

+

The launcher shows exactly what would be sent: Settings → Data collection → View what would be sent, or horizon-launcher data show. Every field is listed in docs/telemetry.md.

+ +

Why

+

To find what is slow or crashes on which machines, and fix it. Benchmark uploads also show other players how Horizon runs on hardware like theirs. Nothing is sold, shared for advertising, or used to identify you.

+ +

On what basis

+

Your consent (Article 6(1)(a) of the EU's General Data Protection Regulation). It is given kind by kind, recorded on your computer with the version of the question you answered and when, and withdrawn at any time with the same switches. Withdrawing deletes what was waiting to be sent. When what is collected changes, the launcher asks again, and nothing new is sent until you answer.

+ +

Where and how long

+

Items wait on your computer (telemetry/ in the game folder) and are sent compressed when the launcher starts or closes, to Horizon's own server at Railway. The server keeps them for 180 days, then deletes them. What stays after that are anonymous totals per day, Horizon version, operating system, GPU maker and render distance (for example "120 sessions on macOS with Apple GPUs at render distance 12"). They hold no install ID, and groups too small to be anonymous are never shown.

+ +

Deleting your data

+

Settings → Data collection → Delete my data, or horizon-launcher data delete. The server deletes everything sent under your install ID, your share of the totals is recomputed, anything waiting on your computer is removed, and you get a new install ID. You can also turn everything off, or delete the telemetry/ folder.

+ +

Your rights and contact

+

Horizon is made by Ludovic Marie, who is responsible for this data. To ask for a copy of what was sent under your install ID, have it corrected or deleted, or ask anything about it, write through lu4ovic.com (give your install ID, shown in Settings → Data collection). You can also complain to the data protection authority where you live.

+

This website itself sets no cookies and has no analytics; its footer says what it loads from GitHub.

+
+ +

Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.

+
+
+ + + diff --git a/website/src/style.css b/website/src/style.css index fb4021c05..8be518881 100644 --- a/website/src/style.css +++ b/website/src/style.css @@ -426,3 +426,8 @@ figcaption span { font-family: var(--mono); font-size: var(--text-micro); letter .row > a { grid-template-columns: 28px 1fr auto; padding: 16px 0; } :root { --index: 28px; } } + +/* The privacy page: one long read under the hero type. */ +.privacy h1 { margin-bottom: 16px; } +.privacy .prose { margin: 40px 0; } +.privacy .disclaimer { margin-top: 32px; } From 60ddf3daf8906f0750c2d1a68248b40b9430e90d Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:21:21 +0200 Subject: [PATCH 20/97] Play with friends: invite codes, the relay and the encrypted tunnel horizon-friends: codes (Crockford base32, nameplate + secret), the relay's JSON-line protocol, SPAKE2 then ChaCha20-Poly1305 frames keyed off the code's secret, direct connections (candidates, TCP simultaneous open from a reuse-port socket) with the relay as fallback, and the host and guest ends that carry the game's TCP stream between loopback ports. horizon-relay: the service (codes, rendezvous, byte relay, rate limits, bandwidth caps, idle timeouts, counts only), its Dockerfile and Railway config. Nothing is deployed and nothing in the game uses it yet. Design: docs/play-with-friends.md. Co-Authored-By: Claude Opus 5.5 --- .dockerignore | 8 + Cargo.lock | 187 ++++++++ Cargo.toml | 2 +- crates/horizon-friends/Cargo.toml | 22 + crates/horizon-friends/src/code.rs | 159 +++++++ crates/horizon-friends/src/crypto.rs | 392 ++++++++++++++++ crates/horizon-friends/src/direct.rs | 317 +++++++++++++ crates/horizon-friends/src/guest.rs | 233 +++++++++ crates/horizon-friends/src/host.rs | 401 ++++++++++++++++ crates/horizon-friends/src/lib.rs | 124 +++++ crates/horizon-friends/src/session.rs | 195 ++++++++ crates/horizon-friends/src/wire.rs | 206 ++++++++ crates/horizon-relay/Cargo.toml | 19 + crates/horizon-relay/Dockerfile | 15 + crates/horizon-relay/railway.toml | 13 + crates/horizon-relay/src/lib.rs | 652 ++++++++++++++++++++++++++ crates/horizon-relay/src/limits.rs | 275 +++++++++++ crates/horizon-relay/src/main.rs | 38 ++ crates/horizon-relay/tests/tunnel.rs | 349 ++++++++++++++ docs/play-with-friends.md | 259 ++++++++++ 20 files changed, 3865 insertions(+), 1 deletion(-) create mode 100644 .dockerignore create mode 100644 crates/horizon-friends/Cargo.toml create mode 100644 crates/horizon-friends/src/code.rs create mode 100644 crates/horizon-friends/src/crypto.rs create mode 100644 crates/horizon-friends/src/direct.rs create mode 100644 crates/horizon-friends/src/guest.rs create mode 100644 crates/horizon-friends/src/host.rs create mode 100644 crates/horizon-friends/src/lib.rs create mode 100644 crates/horizon-friends/src/session.rs create mode 100644 crates/horizon-friends/src/wire.rs create mode 100644 crates/horizon-relay/Cargo.toml create mode 100644 crates/horizon-relay/Dockerfile create mode 100644 crates/horizon-relay/railway.toml create mode 100644 crates/horizon-relay/src/lib.rs create mode 100644 crates/horizon-relay/src/limits.rs create mode 100644 crates/horizon-relay/src/main.rs create mode 100644 crates/horizon-relay/tests/tunnel.rs create mode 100644 docs/play-with-friends.md diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 000000000..417a1867c --- /dev/null +++ b/.dockerignore @@ -0,0 +1,8 @@ +# Docker builds (the relay) need the Rust sources only. +target/ +.local/ +**/node_modules/ +website/ +benchmarks/ +packs/ +mods/ diff --git a/Cargo.lock b/Cargo.lock index 0c37a850a..b72a657bb 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -24,6 +24,16 @@ version = "2.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" +[[package]] +name = "aead" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0" +dependencies = [ + "crypto-common", + "generic-array", +] + [[package]] name = "ahash" version = "0.8.12" @@ -322,6 +332,30 @@ version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527" +[[package]] +name = "chacha20" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3613f74bd2eac03dad61bd53dbe620703d4371614fe0bc3b9f04dd36fe4e818" +dependencies = [ + "cfg-if", + "cipher", + "cpufeatures", +] + +[[package]] +name = "chacha20poly1305" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10cd79432192d1c0f4e1a0fef9527696cc039165d729fb41b3f4f4f354c2dc35" +dependencies = [ + "aead", + "chacha20", + "cipher", + "poly1305", + "zeroize", +] + [[package]] name = "chrono" version = "0.4.45" @@ -333,6 +367,17 @@ dependencies = [ "windows-link", ] +[[package]] +name = "cipher" +version = "0.4.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad" +dependencies = [ + "crypto-common", + "inout", + "zeroize", +] + [[package]] name = "clipboard-win" version = "5.4.1" @@ -493,6 +538,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" dependencies = [ "generic-array", + "rand_core", "typenum", ] @@ -502,6 +548,32 @@ version = "1.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f27ae1dd37df86211c42e150270f82743308803d90a6f6e6651cd730d5e1732f" +[[package]] +name = "curve25519-dalek" +version = "4.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "97fb8b7c4503de7d6ae7b42ab72a5a59857b4c937ec27a3d4539dba95b5ab2be" +dependencies = [ + "cfg-if", + "cpufeatures", + "curve25519-dalek-derive", + "fiat-crypto", + "rand_core", + "rustc_version", + "subtle", +] + +[[package]] +name = "curve25519-dalek-derive" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f46882e17999c6cc590af592290432be3bce0428cb0d5f8b6715e4dc7b383eb3" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "dasp_sample" version = "0.11.0" @@ -527,6 +599,7 @@ checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" dependencies = [ "block-buffer", "crypto-common", + "subtle", ] [[package]] @@ -631,6 +704,12 @@ dependencies = [ "simd-adler32", ] +[[package]] +name = "fiat-crypto" +version = "0.2.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d" + [[package]] name = "find-msvc-tools" version = "0.1.14" @@ -886,6 +965,24 @@ version = "0.5.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e17592d60ebacc7d5e169f4663c5f84f9161cc90328abcfe8456f41e4dfcb284" +[[package]] +name = "hkdf" +version = "0.12.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7b5f8eb2ad728638ea2c7d47a21db23b7b58a72ed6a38256b8a1849f15fbbdf7" +dependencies = [ + "hmac", +] + +[[package]] +name = "hmac" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e" +dependencies = [ + "digest", +] + [[package]] name = "horizon-assets" version = "0.1.0" @@ -935,6 +1032,20 @@ dependencies = [ "libm", ] +[[package]] +name = "horizon-friends" +version = "0.1.0" +dependencies = [ + "chacha20poly1305", + "getrandom 0.3.4", + "hkdf", + "serde", + "serde_json", + "sha2", + "socket2", + "spake2", +] + [[package]] name = "horizon-prepare" version = "0.1.0" @@ -956,6 +1067,15 @@ dependencies = [ "sha1", ] +[[package]] +name = "horizon-relay" +version = "0.1.0" +dependencies = [ + "getrandom 0.3.4", + "horizon-friends", + "serde_json", +] + [[package]] name = "horizon-telemetry" version = "0.1.0" @@ -1141,6 +1261,15 @@ dependencies = [ "libc", ] +[[package]] +name = "inout" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01" +dependencies = [ + "generic-array", +] + [[package]] name = "itoa" version = "1.0.18" @@ -1869,6 +1998,12 @@ version = "1.21.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" +[[package]] +name = "opaque-debug" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381" + [[package]] name = "orbclient" version = "0.3.55" @@ -2018,6 +2153,17 @@ version = "0.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2f3a9f18d041e6d0e102a0a46750538147e5e8992d3b4873aaafee2520b00ce3" +[[package]] +name = "poly1305" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8159bd90725d2df49889a078b54f4f79e87f1f8a8444194cdca81d38f5393abf" +dependencies = [ + "cpufeatures", + "opaque-debug", + "universal-hash", +] + [[package]] name = "portable-atomic" version = "1.15.0" @@ -2102,6 +2248,15 @@ version = "6.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" +[[package]] +name = "rand_core" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c" +dependencies = [ + "getrandom 0.2.17", +] + [[package]] name = "raw-window-handle" version = "0.6.2" @@ -2475,6 +2630,28 @@ dependencies = [ "serde", ] +[[package]] +name = "socket2" +version = "0.5.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e22376abed350d73dd1cd119b57ffccad95b4e585a7cda43e286245ce23c0678" +dependencies = [ + "libc", + "windows-sys 0.52.0", +] + +[[package]] +name = "spake2" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c5482afe85a0b6ce956c945401598dbc527593c77ba51d0a87a586938b1b893a" +dependencies = [ + "curve25519-dalek", + "hkdf", + "rand_core", + "sha2", +] + [[package]] name = "spirv" version = "0.4.0+sdk-1.4.341.0" @@ -2810,6 +2987,16 @@ version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254" +[[package]] +name = "universal-hash" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea" +dependencies = [ + "crypto-common", + "subtle", +] + [[package]] name = "untrusted" version = "0.9.0" diff --git a/Cargo.toml b/Cargo.toml index 6c21e207d..eb10100f5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [workspace] exclude = ["launcher", "crates/horizon-telemetry-server"] -members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "xtask"] +members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-friends", "crates/horizon-relay", "xtask"] resolver = "2" [workspace.package] diff --git a/crates/horizon-friends/Cargo.toml b/crates/horizon-friends/Cargo.toml new file mode 100644 index 000000000..2d08a0bdd --- /dev/null +++ b/crates/horizon-friends/Cargo.toml @@ -0,0 +1,22 @@ +[package] +name = "horizon-friends" +version = "0.1.0" +edition.workspace = true +license.workspace = true +rust-version.workspace = true +description = "Play with friends: invite codes, the relay protocol, the end-to-end encrypted tunnel between a host's integrated server and its guests" + +[dependencies] +# The key exchange keyed by the code's secret, then the frames. +spake2 = { version = "0.4", features = ["getrandom"] } +chacha20poly1305 = "0.10" +hkdf = "0.12" +sha2 = "0.10" +getrandom = "0.3" +# SO_REUSEADDR/SO_REUSEPORT for the direct socket (TCP simultaneous open). +socket2 = { version = "0.5", features = ["all"] } +serde = { version = "1", features = ["derive"] } +serde_json = "1.0.151" + +[lints] +workspace = true diff --git a/crates/horizon-friends/src/code.rs b/crates/horizon-friends/src/code.rs new file mode 100644 index 000000000..6ab06ff82 --- /dev/null +++ b/crates/horizon-friends/src/code.rs @@ -0,0 +1,159 @@ +//! Invite codes: eight Crockford base32 symbols shown as `K7QM-3XPD`. The +//! first four are the nameplate the relay finds the host by; the last four +//! are the secret the key exchange uses, which only the players see. +use std::fmt; + +/// Crockford base32: digits and letters without I, L, O and U. +pub const ALPHABET: &[u8; 32] = b"0123456789ABCDEFGHJKMNPQRSTVWXYZ"; +/// Symbols in each half of a code. +pub const HALF: usize = 4; + +/// The value of a symbol as a player may type it: any case, `O` for `0`, +/// `I` and `L` for `1`. +fn value(c: char) -> Option { + 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) +} + +/// Four symbols (20 bits) as their canonical text. +fn symbols(bits: u32) -> String { + (0..HALF) + .rev() + .map(|i| char::from(ALPHABET[(bits >> (5 * i)) as usize & 31])) + .collect() +} + +/// A nameplate drawn from 20 random bits. +pub fn nameplate(bits: u32) -> String { + symbols(bits & 0xF_FFFF) +} + +/// A nameplate as a player or a client sent it, made canonical; None when it +/// isn't four symbols. +pub fn parse_nameplate(text: &str) -> Option { + let symbols: Option> = text.chars().map(value).collect(); + let symbols = symbols?; + (symbols.len() == HALF).then(|| { + symbols + .iter() + .map(|&v| char::from(ALPHABET[v as usize])) + .collect() + }) +} + +#[derive(Clone, PartialEq, Eq)] +pub struct Code { + pub nameplate: String, + pub secret: String, +} +impl Code { + /// A code for a nameplate the relay handed out, with a fresh secret from + /// the OS random generator. + pub fn new(nameplate: &str) -> std::io::Result { + let mut b = [0u8; 4]; + crate::fill_random(&mut b)?; + Ok(Self { + nameplate: nameplate.to_owned(), + secret: symbols(u32::from_le_bytes(b) & 0xF_FFFF), + }) + } + /// A code as a player typed it: spaces, dashes and case don't matter, `O` + /// reads as `0`, `I` and `L` as `1`. + pub fn parse(text: &str) -> Option { + let mut out = String::with_capacity(2 * HALF); + for c in text.chars() { + if c.is_whitespace() || c == '-' { + continue; + } + out.push(char::from(ALPHABET[value(c)? as usize])); + } + if out.len() != 2 * HALF { + return None; + } + let (nameplate, secret) = out.split_at(HALF); + Some(Self { + nameplate: nameplate.to_owned(), + secret: secret.to_owned(), + }) + } +} +impl fmt::Display for Code { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "{}-{}", self.nameplate, self.secret) + } +} +/// The secret stays out of debug output and logs. +impl fmt::Debug for Code { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "Code({}-****)", self.nameplate) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn alphabet_has_no_ambiguous_letters() { + assert_eq!(ALPHABET.len(), 32); + for c in *b"ILOU" { + assert!(!ALPHABET.contains(&c)); + } + let mut sorted = ALPHABET.to_vec(); + sorted.dedup(); + assert_eq!(sorted.len(), 32); + } + + #[test] + fn nameplates_cover_twenty_bits() { + assert_eq!(nameplate(0), "0000"); + assert_eq!(nameplate(0xF_FFFF), "ZZZZ"); + assert_eq!(nameplate(0x8000 | 31), "100Z"); + // High bits beyond 20 are ignored. + assert_eq!(nameplate(0xFFF0_0001), "0001"); + let mut seen = std::collections::HashSet::new(); + for bits in (0..0x10_0000).step_by(997) { + assert!(seen.insert(nameplate(bits))); + } + } + + #[test] + fn parses_what_players_type() { + let code = Code::parse("k7qm-3xpd").unwrap(); + assert_eq!(code.nameplate, "K7QM"); + assert_eq!(code.secret, "3XPD"); + assert_eq!(code.to_string(), "K7QM-3XPD"); + assert_eq!(Code::parse(" K7QM 3XPD ").unwrap(), code); + assert_eq!(Code::parse("K7QM3XPD").unwrap(), code); + // O, I and L are the symbols they look like. + let code = Code::parse("OIL0-1lio").unwrap(); + assert_eq!(code.to_string(), "0110-1110"); + assert!(Code::parse("K7QM-3XP").is_none()); + assert!(Code::parse("K7QM-3XPDA").is_none()); + assert!(Code::parse("K7QM-3XPU").is_none()); + assert!(Code::parse("").is_none()); + } + + #[test] + fn fresh_secrets_are_canonical_and_differ() { + let a = Code::new("K7QM").unwrap(); + assert_eq!(Code::parse(&a.to_string()).unwrap(), a); + let different = (0..8).any(|_| Code::new("K7QM").unwrap().secret != a.secret); + assert!(different); + assert_eq!(format!("{a:?}"), "Code(K7QM-****)"); + } + + #[test] + fn nameplates_parse() { + assert_eq!(parse_nameplate("k7qm").as_deref(), Some("K7QM")); + assert_eq!(parse_nameplate("K7Q"), None); + assert_eq!(parse_nameplate("K7QU"), None); + } +} diff --git a/crates/horizon-friends/src/crypto.rs b/crates/horizon-friends/src/crypto.rs new file mode 100644 index 000000000..837377205 --- /dev/null +++ b/crates/horizon-friends/src/crypto.rs @@ -0,0 +1,392 @@ +//! End-to-end protection between a host and a guest, whatever carries the +//! bytes. SPAKE2 turns the code's short secret into a session key without +//! giving anyone on the path (the relay included) a way to test guesses +//! offline; every stream of the session then derives its own +//! ChaCha20-Poly1305 keys from it and two fresh randoms, and starts with a +//! key confirmation so a wrong code or a changed byte ends it. +use chacha20poly1305::{ + ChaCha20Poly1305, KeyInit, + aead::{Aead, Payload}, +}; +use hkdf::Hkdf; +use sha2::Sha256; +use spake2::{Ed25519Group, Identity, Password, Spake2}; +use std::io::{self, Read, Write}; + +/// The most game bytes in one frame. +pub const MAX_PAYLOAD: usize = 16 * 1024; +const TAG: usize = 16; +const CONFIRM: &[u8] = b"horizon-friends v1 confirm"; + +const DATA: u8 = 0; +const CONTROL: u8 = 1; +const CONFIRMATION: u8 = 2; + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Role { + Host, + Guest, +} + +/// The session key both ends derive from the code. +#[derive(Clone)] +pub struct Key([u8; 32]); + +/// The error a mismatched code produces: the peer's confirmation does not +/// open with our key. +pub fn wrong_code() -> io::Error { + io::Error::new(io::ErrorKind::PermissionDenied, "the code doesn't match") +} +pub fn is_wrong_code(e: &io::Error) -> bool { + e.kind() == io::ErrorKind::PermissionDenied +} + +/// SPAKE2 over a stream: both ends send their message, then read the +/// other's. The identity binds the key to this nameplate and session. +pub fn exchange( + stream: &mut S, + secret: &str, + nameplate: &str, + session: u64, +) -> io::Result { + let identity = format!("horizon-friends v1/{nameplate}/{session}"); + let (state, outbound) = Spake2::::start_symmetric( + &Password::new(secret.as_bytes()), + &Identity::new(identity.as_bytes()), + ); + let len = u8::try_from(outbound.len()).map_err(io::Error::other)?; + let mut message = vec![len]; + message.extend_from_slice(&outbound); + stream.write_all(&message)?; + stream.flush()?; + let mut len = [0u8; 1]; + stream.read_exact(&mut len)?; + let mut inbound = vec![0u8; usize::from(len[0])]; + stream.read_exact(&mut inbound)?; + let key = state + .finish(&inbound) + .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, format!("{e:?}")))?; + let mut out = [0u8; 32]; + let hk = Hkdf::::new(None, &key); + hk.expand(b"horizon-friends v1 session", &mut out) + .expect("32 bytes is a valid HKDF output"); + Ok(Key(out)) +} + +fn nonce(counter: u64) -> [u8; 12] { + let mut n = [0u8; 12]; + n[4..].copy_from_slice(&counter.to_be_bytes()); + n +} + +fn cipher(key: &Key, salt: &[u8], info: &[u8]) -> ChaCha20Poly1305 { + let mut okm = [0u8; 32]; + Hkdf::::new(Some(salt), &key.0) + .expand(info, &mut okm) + .expect("32 bytes is a valid HKDF output"); + ChaCha20Poly1305::new(&okm.into()) +} + +pub enum Frame { + Data(Vec), + Control(Vec), +} + +pub struct SecureWriter { + inner: W, + cipher: ChaCha20Poly1305, + counter: u64, +} +impl SecureWriter { + fn frame(&mut self, kind: u8, payload: &[u8]) -> io::Result<()> { + debug_assert!(payload.len() <= MAX_PAYLOAD); + let mut plain = Vec::with_capacity(1 + payload.len()); + plain.push(kind); + plain.extend_from_slice(payload); + let len = (plain.len() + TAG) as u16; + let header = len.to_be_bytes(); + let sealed = self + .cipher + .encrypt( + &nonce(self.counter).into(), + Payload { + msg: &plain, + aad: &header, + }, + ) + .map_err(|_| io::Error::other("encryption failed"))?; + self.counter = self + .counter + .checked_add(1) + .ok_or_else(|| io::Error::other("frame counter exhausted"))?; + let mut out = Vec::with_capacity(2 + sealed.len()); + out.extend_from_slice(&header); + out.extend_from_slice(&sealed); + self.inner.write_all(&out) + } + /// Game bytes, split into frames. + pub fn write_data(&mut self, bytes: &[u8]) -> io::Result<()> { + for chunk in bytes.chunks(MAX_PAYLOAD) { + self.frame(DATA, chunk)?; + } + self.inner.flush() + } + /// A message between the two tunnel ends. + pub fn write_control(&mut self, message: &[u8]) -> io::Result<()> { + if message.len() > MAX_PAYLOAD { + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + "control message too long", + )); + } + self.frame(CONTROL, message)?; + self.inner.flush() + } + pub fn get_ref(&self) -> &W { + &self.inner + } +} + +pub struct SecureReader { + inner: R, + cipher: ChaCha20Poly1305, + counter: u64, +} +impl SecureReader { + /// The next frame's kind and payload; None at a clean end of stream. + fn open(&mut self) -> io::Result)>> { + let mut header = [0u8; 2]; + let mut got = 0; + while got < 2 { + match self.inner.read(&mut header[got..]) { + Ok(0) if got == 0 => return Ok(None), + Ok(0) => return Err(io::ErrorKind::UnexpectedEof.into()), + Ok(n) => got += n, + Err(e) if e.kind() == io::ErrorKind::Interrupted => {} + Err(e) => return Err(e), + } + } + let len = usize::from(u16::from_be_bytes(header)); + if !(TAG + 1..=TAG + 1 + MAX_PAYLOAD).contains(&len) { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "bad frame length", + )); + } + let mut sealed = vec![0u8; len]; + self.inner.read_exact(&mut sealed)?; + let plain = self + .cipher + .decrypt( + &nonce(self.counter).into(), + Payload { + msg: &sealed, + aad: &header, + }, + ) + .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "frame failed to open"))?; + self.counter += 1; + Ok(Some((plain[0], plain[1..].to_vec()))) + } + pub fn read_frame(&mut self) -> io::Result> { + match self.open()? { + None => Ok(None), + Some((DATA, p)) => Ok(Some(Frame::Data(p))), + Some((CONTROL, p)) => Ok(Some(Frame::Control(p))), + Some(_) => Err(io::Error::new( + io::ErrorKind::InvalidData, + "unexpected frame", + )), + } + } + pub fn get_ref(&self) -> &R { + &self.inner + } +} + +/// Protect one stream of the session: swap randoms, derive the keys for +/// each direction, confirm. Fails with [`wrong_code`] when the peer used +/// another key. +pub fn secure( + mut read: R, + mut write: W, + key: &Key, + role: Role, +) -> io::Result<(SecureReader, SecureWriter)> { + let mut mine = [0u8; 16]; + crate::fill_random(&mut mine)?; + write.write_all(&mine)?; + write.flush()?; + let mut theirs = [0u8; 16]; + read.read_exact(&mut theirs)?; + let (guest, host) = match role { + Role::Guest => (mine, theirs), + Role::Host => (theirs, mine), + }; + let mut salt = [0u8; 32]; + salt[..16].copy_from_slice(&guest); + salt[16..].copy_from_slice(&host); + let to_guest = cipher(key, &salt, b"horizon-friends v1 host->guest"); + let to_host = cipher(key, &salt, b"horizon-friends v1 guest->host"); + let (send, recv) = match role { + Role::Host => (to_guest, to_host), + Role::Guest => (to_host, to_guest), + }; + let mut writer = SecureWriter { + inner: write, + cipher: send, + counter: 0, + }; + let mut reader = SecureReader { + inner: read, + cipher: recv, + counter: 0, + }; + writer.frame(CONFIRMATION, CONFIRM)?; + writer.inner.flush()?; + match reader.open() { + Ok(Some((CONFIRMATION, p))) if p == CONFIRM => Ok((reader, writer)), + Ok(_) => Err(io::Error::new( + io::ErrorKind::InvalidData, + "no confirmation", + )), + Err(e) if e.kind() == io::ErrorKind::InvalidData => Err(wrong_code()), + Err(e) => Err(e), + } +} + +#[cfg(test)] +mod tests { + use super::*; + use std::net::{TcpListener, TcpStream}; + + fn pair() -> (TcpStream, TcpStream) { + let l = TcpListener::bind("127.0.0.1:0").unwrap(); + let a = TcpStream::connect(l.local_addr().unwrap()).unwrap(); + let (b, _) = l.accept().unwrap(); + (a, b) + } + + fn both( + a: impl FnOnce() -> A + Send + 'static, + b: impl FnOnce() -> B + Send + 'static, + ) -> (A, B) { + let t = std::thread::spawn(a); + let rb = b(); + (t.join().unwrap(), rb) + } + + fn keys( + host_secret: &'static str, + guest_secret: &'static str, + ) -> (Key, Key, TcpStream, TcpStream) { + let (mut h, mut g) = pair(); + let (hk, gk) = both( + { + let mut h2 = h.try_clone().unwrap(); + move || exchange(&mut h2, host_secret, "K7QM", 9).unwrap() + }, + { + let mut g2 = g.try_clone().unwrap(); + move || exchange(&mut g2, guest_secret, "K7QM", 9).unwrap() + }, + ); + h.flush().unwrap(); + g.flush().unwrap(); + (hk, gk, h, g) + } + + #[test] + fn same_code_same_key_and_frames_flow() { + let (hk, gk, h, g) = keys("3XPD", "3XPD"); + assert_eq!(hk.0, gk.0); + let ((mut hr, mut hw), (mut gr, mut gw)) = both( + move || secure(h.try_clone().unwrap(), h, &hk, Role::Host).unwrap(), + move || secure(g.try_clone().unwrap(), g, &gk, Role::Guest).unwrap(), + ); + let big: Vec = (0..MAX_PAYLOAD * 2 + 5).map(|i| i as u8).collect(); + gw.write_data(&big).unwrap(); + gw.write_control(b"{\"use\":true}").unwrap(); + hw.write_data(b"pong").unwrap(); + let mut got = Vec::new(); + while got.len() < big.len() { + match hr.read_frame().unwrap().unwrap() { + Frame::Data(d) => got.extend(d), + Frame::Control(_) => panic!("control before data"), + } + } + assert_eq!(got, big); + assert!( + matches!(hr.read_frame().unwrap(), Some(Frame::Control(c)) if c == b"{\"use\":true}") + ); + assert!(matches!(gr.read_frame().unwrap(), Some(Frame::Data(d)) if d == b"pong")); + drop(gw); + drop(gr); + assert!(hr.read_frame().unwrap().is_none()); + } + + #[test] + fn a_wrong_secret_is_refused_on_both_ends() { + let (hk, gk, h, g) = keys("3XPD", "3XPE"); + assert_ne!(hk.0, gk.0); + let (a, b) = both( + move || secure(h.try_clone().unwrap(), h, &hk, Role::Host).err(), + move || secure(g.try_clone().unwrap(), g, &gk, Role::Guest).err(), + ); + assert!(is_wrong_code(&a.unwrap())); + assert!(is_wrong_code(&b.unwrap())); + } + + #[test] + fn the_session_is_part_of_the_key() { + let (mut h, mut g) = pair(); + let (hk, gk) = both( + move || exchange(&mut h, "3XPD", "K7QM", 1).unwrap(), + move || exchange(&mut g, "3XPD", "K7QM", 2).unwrap(), + ); + assert_ne!(hk.0, gk.0); + } + + /// A byte changed in flight, frames replayed or reordered: the reader + /// stops. Built on in-memory buffers to edit the bytes. + #[test] + fn tampering_is_detected() { + let key = Key([7; 32]); + let seal = |frames: &[&[u8]]| { + let mut w = SecureWriter { + inner: Vec::new(), + cipher: cipher(&key, &[1; 32], b"horizon-friends v1 guest->host"), + counter: 0, + }; + for f in frames { + w.write_data(f).unwrap(); + } + w.inner + }; + let reader = |bytes: Vec| SecureReader { + inner: io::Cursor::new(bytes), + cipher: cipher(&key, &[1; 32], b"horizon-friends v1 guest->host"), + counter: 0, + }; + let good = seal(&[b"hello", b"world"]); + let mut r = reader(good.clone()); + assert!(matches!(r.read_frame().unwrap(), Some(Frame::Data(d)) if d == b"hello")); + assert!(matches!(r.read_frame().unwrap(), Some(Frame::Data(d)) if d == b"world")); + assert!(r.read_frame().unwrap().is_none()); + // One flipped bit. + let mut bad = good.clone(); + bad[5] ^= 1; + assert!(reader(bad).read_frame().is_err()); + // Frames swapped: the counter no longer matches. + let first = 2 + usize::from(u16::from_be_bytes([good[0], good[1]])); + let mut swapped = good[first..].to_vec(); + swapped.extend_from_slice(&good[..first]); + assert!(reader(swapped).read_frame().is_err()); + // The first frame twice. + let mut r = reader([&good[..first], &good[..first]].concat()); + r.read_frame().unwrap(); + assert!(r.read_frame().is_err()); + // A header claiming more than a frame can hold. + assert!(reader(vec![0xFF, 0xFF, 0]).read_frame().is_err()); + } +} diff --git a/crates/horizon-friends/src/direct.rs b/crates/horizon-friends/src/direct.rs new file mode 100644 index 000000000..86e155858 --- /dev/null +++ b/crates/horizon-friends/src/direct.rs @@ -0,0 +1,317 @@ +//! Direct connections between a host and a guest: the addresses each end +//! offers, and the race that dials all of the other's at once from the port +//! it also listens on (so two NATs that map a port the same way for every +//! destination let the two SYNs cross: TCP simultaneous open). +use socket2::{Domain, Protocol, SockAddr, Socket, Type}; +use std::{ + io::{self, Read, Write}, + net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, TcpListener, TcpStream, UdpSocket}, + sync::{ + Arc, + atomic::{AtomicBool, Ordering}, + mpsc::Sender, + }, + time::{Duration, Instant}, +}; + +/// How long the ends try to reach each other directly. +pub const RACE: Duration = Duration::from_millis(3000); +const RETRY: Duration = Duration::from_millis(250); +const MAGIC: &[u8; 4] = b"HZF1"; + +fn socket_for(addr: &SocketAddr) -> io::Result { + let s = Socket::new( + Domain::for_address(*addr), + Type::STREAM, + Some(Protocol::TCP), + )?; + s.set_reuse_address(true)?; + #[cfg(all(unix, not(any(target_os = "solaris", target_os = "illumos"))))] + s.set_reuse_port(true)?; + if addr.is_ipv6() { + s.set_only_v6(true)?; + } + Ok(s) +} + +fn unspecified(v6: bool, port: u16) -> SocketAddr { + if v6 { + SocketAddr::new(IpAddr::V6(Ipv6Addr::UNSPECIFIED), port) + } else { + SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), port) + } +} + +/// The direct socket's listeners: IPv4 on `port` (0 picks one), and IPv6 on +/// the same port when the system has it. +pub fn listen(port: u16) -> io::Result<(Vec, u16)> { + let bind = |addr: SocketAddr| -> io::Result { + let s = socket_for(&addr)?; + s.bind(&SockAddr::from(addr))?; + s.listen(16)?; + let l: TcpListener = s.into(); + l.set_nonblocking(true)?; + Ok(l) + }; + let v4 = bind(unspecified(false, port))?; + let port = v4.local_addr()?.port(); + let mut out = vec![v4]; + if let Ok(v6) = bind(unspecified(true, port)) { + out.push(v6); + } + Ok((out, port)) +} + +/// Connect to `to` from local `port` (shared with the listener), or from any +/// port when that one can't be used (the same pair already connected). +pub fn connect_from(port: Option, to: SocketAddr, timeout: Duration) -> io::Result { + if let Some(port) = port { + let s = socket_for(&to)?; + if s.bind(&SockAddr::from(unspecified(to.is_ipv6(), port))) + .is_ok() + { + match s.connect_timeout(&SockAddr::from(to), timeout) { + Ok(()) => return Ok(s.into()), + Err(e) + if e.kind() != io::ErrorKind::AddrInUse + && e.kind() != io::ErrorKind::AddrNotAvailable => + { + return Err(e); + } + Err(_) => {} + } + } + } + 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 { + 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) -> Vec { + let mut targets: Vec = 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). +pub fn candidates( + port: u16, + relay: Option, + observed: Option, +) -> Vec { + let mut out: Vec = local_addresses(relay) + .into_iter() + .map(|ip| SocketAddr::new(ip, port)) + .collect(); + if let Some(o) = observed + && !o.ip().is_unspecified() + && !out.contains(&o) + { + out.push(o); + } + out +} + +/// Both ends open every direct stream the same way, whoever dialled: the +/// magic and the session, then the other's must match. +pub fn introduce(stream: &mut TcpStream, session: u64) -> io::Result<()> { + let mut hello = [0u8; 12]; + hello[..4].copy_from_slice(MAGIC); + hello[4..].copy_from_slice(&session.to_be_bytes()); + stream.set_read_timeout(Some(Duration::from_secs(2)))?; + 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 this session", + )); + } + Ok(()) +} + +/// The session an inbound direct stream belongs to (the host's listener +/// serves every session): reads the other end's introduction. +pub fn read_session(stream: &mut TcpStream) -> io::Result { + stream.set_read_timeout(Some(Duration::from_secs(2)))?; + let mut theirs = [0u8; 12]; + stream.read_exact(&mut theirs)?; + if &theirs[..4] != MAGIC { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "not a direct stream", + )); + } + Ok(u64::from_be_bytes(theirs[4..].try_into().unwrap())) +} +/// Answer an inbound stream's introduction for `session`. +pub fn answer(stream: &mut TcpStream, session: u64) -> io::Result<()> { + let mut hello = [0u8; 12]; + hello[..4].copy_from_slice(MAGIC); + hello[4..].copy_from_slice(&session.to_be_bytes()); + stream.write_all(&hello) +} + +/// Dial each target from `port` until one connects, the deadline passes or +/// `stop` is set; streams that connect are introduced and sent on. +pub fn dial( + port: Option, + targets: Vec, + session: u64, + deadline: Instant, + stop: Arc, + found: Sender, +) { + for target in targets { + let (stop, found) = (stop.clone(), found.clone()); + let _ = std::thread::Builder::new() + .name("horizon-friends-dial".into()) + .spawn(move || { + while !stop.load(Ordering::Relaxed) { + let now = Instant::now(); + if now >= deadline { + return; + } + let tried = Instant::now(); + let wait = (deadline - now).min(Duration::from_millis(600)); + if let Ok(mut s) = connect_from(port, target, wait) + && introduce(&mut s, session).is_ok() + { + let _ = found.send(s); + return; + } + let spent = tried.elapsed(); + if spent < RETRY { + std::thread::sleep(RETRY - spent); + } + } + }); + } +} + +/// Accept on the listeners until the deadline or `stop`; inbound streams for +/// `session` are answered and sent on. +pub fn accept( + listeners: Vec, + session: u64, + deadline: Instant, + stop: Arc, + found: Sender, +) { + let _ = std::thread::Builder::new() + .name("horizon-friends-accept".into()) + .spawn(move || { + while !stop.load(Ordering::Relaxed) && Instant::now() < deadline { + let mut idle = true; + for l in &listeners { + if let Ok((mut s, _)) = l.accept() { + idle = false; + let _ = s.set_nonblocking(false); + if read_session(&mut s).ok() == Some(session) + && answer(&mut s, session).is_ok() + { + let _ = found.send(s); + } + } + } + if idle { + std::thread::sleep(Duration::from_millis(20)); + } + } + }); +} + +#[cfg(test)] +mod tests { + use super::*; + use std::sync::mpsc::channel; + + #[test] + fn candidates_have_the_port_and_the_observed_address() { + let relay = SocketAddr::from(([127, 0, 0, 1], 1)); + let observed = SocketAddr::from(([203, 0, 113, 5], 40000)); + let c = candidates(5555, Some(relay), Some(observed)); + assert!(c.contains(&SocketAddr::from(([127, 0, 0, 1], 5555)))); + assert_eq!(c.last(), Some(&observed)); + let far = candidates(5555, None, None); + assert!( + far.iter() + .all(|a| !a.ip().is_loopback() && a.port() == 5555) + ); + } + + /// Two direct sockets on loopback: each listens on its port and dials + /// the other's from it; the session's streams meet and wrong sessions + /// don't. + #[test] + fn the_race_connects_and_checks_the_session() { + let (la, pa) = listen(0).unwrap(); + let (lb, pb) = listen(0).unwrap(); + assert_ne!(pa, pb); + let stop = Arc::new(AtomicBool::new(false)); + let deadline = Instant::now() + Duration::from_secs(3); + let (ta, ra) = channel(); + let (tb, rb) = channel(); + accept(la, 42, deadline, stop.clone(), ta.clone()); + accept(lb, 42, deadline, stop.clone(), tb.clone()); + dial( + Some(pa), + vec![SocketAddr::from(([127, 0, 0, 1], pb))], + 42, + deadline, + stop.clone(), + ta, + ); + let mut a = ra.recv_timeout(Duration::from_secs(3)).unwrap(); + let mut b = rb.recv_timeout(Duration::from_secs(3)).unwrap(); + a.write_all(b"ping").unwrap(); + let mut got = [0u8; 4]; + b.read_exact(&mut got).unwrap(); + assert_eq!(&got, b"ping"); + stop.store(true, Ordering::Relaxed); + + let (lc, pc) = listen(0).unwrap(); + let (tc, rc) = channel(); + let deadline = Instant::now() + Duration::from_millis(800); + let stop = Arc::new(AtomicBool::new(false)); + accept(lc, 7, deadline, stop.clone(), tc.clone()); + let (td, rd) = channel(); + dial( + None, + vec![SocketAddr::from(([127, 0, 0, 1], pc))], + 8, + deadline, + stop, + td, + ); + assert!(rc.recv_timeout(Duration::from_secs(2)).is_err()); + assert!(rd.recv_timeout(Duration::from_millis(100)).is_err()); + } +} diff --git a/crates/horizon-friends/src/guest.rs b/crates/horizon-friends/src/guest.rs new file mode 100644 index 000000000..a40361acc --- /dev/null +++ b/crates/horizon-friends/src/guest.rs @@ -0,0 +1,233 @@ +//! 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 +//! game's client connects to like to any server. +use crate::{ + Code, PathMode, + crypto::{self, Role}, + direct, resolve_relay, + session::{self, Secure}, + wire::{self, ErrorCode, FromRelay, ToRelay}, +}; +use std::{ + fmt, io, + net::{Ipv4Addr, SocketAddr, TcpListener, TcpStream}, + thread::JoinHandle, + time::Duration, +}; + +pub struct GuestConfig { + pub relay: String, + pub code: Code, + /// The game's protocol number and version name (the relay refuses a + /// guest whose protocol differs from the host's). + pub protocol: i32, + pub game: String, + pub path: PathMode, +} + +/// Why joining failed, in words for the player. +#[derive(Debug)] +pub enum JoinError { + /// No relay is configured in this build. + NotAvailable, + Unreachable(String), + UnknownCode, + Ended, + VersionMismatch { + host: Option, + mine: String, + }, + HostUnreachable, + Full, + RateLimited, + WrongCode, + Failed(String), +} +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::UnknownCode => write!( + f, + "No world uses this code. Check it, or ask your friend for a new one." + ), + Self::Ended => write!( + f, + "This invite has ended: your friend stopped sharing or left the world." + ), + Self::VersionMismatch { + host: Some(v), + mine, + } => { + write!(f, "Your friend plays Minecraft {v}; you have {mine}.") + } + Self::VersionMismatch { host: None, mine } => { + write!( + f, + "Your friend plays another version of Minecraft than {mine}." + ) + } + Self::HostUnreachable => write!(f, "Your friend's game didn't answer."), + Self::Full => write!( + f, + "Your friend's world is full, or the invite service is busy. Try again in a moment." + ), + Self::RateLimited => { + write!(f, "Too many attempts. Wait a few minutes, then try again.") + } + Self::WrongCode => write!(f, "The code doesn't match. Check the last four characters."), + Self::Failed(e) => write!(f, "Couldn't connect to your friend ({e})."), + } + } +} +impl std::error::Error for JoinError {} + +/// A settled session, ready to carry the game's connection. +pub struct Tunnel { + secure: Secure, + /// Whether the stream goes straight to the host (else through the relay). + 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). +pub fn join(config: &GuestConfig) -> Result { + let relays = resolve_relay(&config.relay).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) { + Ok((l, p)) => (l, Some(p)), + Err(_) => (Vec::new(), None), + } + } else { + (Vec::new(), None) + }; + let mut last = io::Error::other("no address"); + let mut stream = None; + for relay in &relays { + match direct::connect_from(port, *relay, Duration::from_secs(5)) { + Ok(s) => { + stream = Some((s, *relay)); + break; + } + Err(e) => last = e, + } + } + let (mut stream, relay) = stream.ok_or_else(|| JoinError::Unreachable(last.to_string()))?; + let failed = |e: io::Error| JoinError::Failed(e.to_string()); + stream + .set_read_timeout(Some(Duration::from_secs(15))) + .map_err(failed)?; + let _ = stream.set_nodelay(true); + wire::send( + &mut stream, + &ToRelay::Join { + v: wire::VERSION, + nameplate: config.code.nameplate.clone(), + protocol: config.protocol, + game: config.game.clone(), + }, + ) + .map_err(failed)?; + let (session, observed) = match wire::recv::<_, FromRelay>(&mut stream).map_err(failed)? { + FromRelay::Bridged { session, observed } => (session, observed), + FromRelay::Error { code, game } => { + return Err(match code { + ErrorCode::UnknownCode => JoinError::UnknownCode, + ErrorCode::Ended => JoinError::Ended, + ErrorCode::VersionMismatch => JoinError::VersionMismatch { + host: game, + mine: config.game.clone(), + }, + ErrorCode::HostUnreachable => JoinError::HostUnreachable, + ErrorCode::Full => JoinError::Full, + ErrorCode::RateLimited => JoinError::RateLimited, + ErrorCode::BadRequest => { + JoinError::Failed("the invite service 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 relayed = session::secure(stream, &key, Role::Guest).map_err(|e| { + if crypto::is_wrong_code(&e) { + JoinError::WrongCode + } else { + JoinError::HostUnreachable + } + })?; + let observed = observed.and_then(|o| o.parse::().ok()); + let candidates = port.map_or_else(Vec::new, |p| direct::candidates(p, Some(relay), observed)); + let settled = session::settle( + relayed, + &key, + Role::Guest, + config.path, + session, + port, + candidates, + Box::new(move |tx, deadline, stop| direct::accept(listeners, session, deadline, stop, tx)), + ) + .map_err(|e| JoinError::Failed(e.to_string()))?; + Ok(Tunnel { + secure: settled.secure, + direct: settled.direct, + }) +} + +impl Tunnel { + /// Offer the session on `127.0.0.1:port` for one connection (the game's + /// client); the returned thread ends when that connection does. + pub fn serve_loopback(self) -> io::Result<(u16, JoinHandle<()>)> { + let listener = TcpListener::bind((Ipv4Addr::LOCALHOST, 0))?; + let port = listener.local_addr()?.port(); + listener.set_nonblocking(true)?; + let thread = std::thread::Builder::new() + .name("horizon-friends-guest".into()) + .spawn(move || { + let deadline = std::time::Instant::now() + Duration::from_secs(30); + let plain = loop { + match listener.accept() { + Ok((s, from)) if from.ip().is_loopback() => break Some(s), + Ok(_) => {} + Err(e) if e.kind() == io::ErrorKind::WouldBlock => { + if std::time::Instant::now() > deadline { + break None; + } + std::thread::sleep(Duration::from_millis(10)); + } + Err(_) => break None, + } + }; + drop(listener); + let (reader, writer) = self.secure; + let Some(plain) = plain else { + let _ = reader.get_ref().shutdown(std::net::Shutdown::Both); + return; + }; + let _ = plain.set_nonblocking(false); + if let Ok(t) = crate::pump(plain, reader, writer) { + let _ = t.join(); + } + })?; + Ok((port, thread)) + } + /// The protected stream itself (tests, or a client that reads it + /// directly). + pub fn into_stream( + self, + ) -> ( + crypto::SecureReader, + crypto::SecureWriter, + ) { + self.secure + } +} diff --git a/crates/horizon-friends/src/host.rs b/crates/horizon-friends/src/host.rs new file mode 100644 index 000000000..567d8ff42 --- /dev/null +++ b/crates/horizon-friends/src/host.rs @@ -0,0 +1,401 @@ +//! 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`]. +use crate::{ + Code, PathMode, + crypto::{self, Role}, + direct, resolve_relay, session, + wire::{self, FromRelay, ToRelay}, +}; +use std::{ + collections::HashMap, + io::{self, BufReader}, + net::{Shutdown, SocketAddr, TcpStream}, + sync::{ + Arc, Mutex, + atomic::{AtomicBool, AtomicU32, Ordering}, + mpsc::{Receiver, Sender, channel}, + }, + thread::JoinHandle, + time::{Duration, Instant}, +}; + +/// Wrong codes tried before the host retires its code for a new one. +pub const MAX_WRONG: u32 = 5; +/// Guests that can be connecting at once (IntegratedServer.MAX_PLAYERS). +pub const MAX_SESSIONS: 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, + pub path: PathMode, +} + +#[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, +} + +#[derive(Debug)] +pub enum HostEvent { + /// A new code (the first, or after the relay restarted or wrong codes). + Code(Code), + /// A guest's session is carried directly or through the relay. + Connected { + session: u64, + direct: bool, + }, + Disconnected { + session: u64, + }, + /// Someone used the nameplate with the wrong secret. + WrongCode { + count: u32, + }, +} + +struct Shared { + config: HostConfig, + stop: AtomicBool, + state: Mutex, + events: Mutex>, + /// The current control connection (shut down to stop). + control: Mutex>, + /// Inbound direct streams waiting for their session. + routes: Mutex, Instant)>>, + sessions: Mutex, + wrong: AtomicU32, +} +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) + } +} + +pub struct Host { + shared: Arc, + events: Receiver, + thread: Option>, + accept: Option>, +} + +impl Host { + /// Start sharing in the background: the code arrives as an event. + pub fn start(config: HostConfig) -> io::Result { + let (tx, events) = channel(); + let listeners = if config.path == PathMode::RelayOnly { + None + } else { + direct::listen(0).ok() + }; + let shared = Arc::new(Shared { + config, + stop: AtomicBool::new(false), + state: Mutex::new(HostState::Registering), + events: Mutex::new(tx), + control: Mutex::new(None), + routes: Mutex::new(HashMap::new()), + sessions: Mutex::new(0), + wrong: AtomicU32::new(0), + }); + 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 s = shared.clone(); + let thread = std::thread::Builder::new() + .name("horizon-friends-host".into()) + .spawn(move || run(s, port))?; + Ok(Self { + shared, + events, + thread: Some(thread), + accept, + }) + } + pub fn state(&self) -> HostState { + self.shared.state.lock().unwrap().clone() + } + pub fn poll(&self) -> Vec { + self.events.try_iter().collect() + } + /// Guests whose sessions are open (connecting or playing). + pub fn sessions(&self) -> usize { + *self.shared.sessions.lock().unwrap() + } + /// End the code. Sessions already playing go on until the integrated + /// server closes them (stopping the LAN server ends 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() { + let _ = t.join(); + } + if let Some(t) = self.accept.take() { + let _ = t.join(); + } + self.shared.set(HostState::Stopped); + } +} +impl Drop for Host { + fn drop(&mut self) { + self.stop(); + } +} + +/// Hand inbound direct streams to the session they introduce themselves for. +fn route_inbound(listeners: Vec, shared: Arc) { + while !shared.stopped() { + let mut idle = true; + for l in &listeners { + let Ok((mut s, _)) = l.accept() else { continue }; + idle = false; + 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); + } + }); + } + if idle { + std::thread::sleep(Duration::from_millis(20)); + } + } +} + +fn connect_relay(config: &HostConfig, port: Option) -> 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)) { + Ok(s) => { + let _ = s.set_nodelay(true); + return Ok((s, relay)); + } + Err(e) => last = e, + } + } + Err(last) +} + +/// Register, serve the control connection, register again when it drops +/// (a new code) until stopped. +fn run(shared: Arc, port: Option) { + let mut backoff = Duration::from_secs(1); + while !shared.stopped() { + match register(&shared, port) { + Ok(()) => backoff = Duration::from_secs(1), + Err(e) => { + if shared.stopped() { + break; + } + shared.set(HostState::Retrying(e.to_string())); + let until = Instant::now() + backoff; + while Instant::now() < until && !shared.stopped() { + std::thread::sleep(Duration::from_millis(50)); + } + backoff = (backoff * 2).min(Duration::from_secs(30)); + } + } + } +} + +fn register(shared: &Arc, port: Option) -> io::Result<()> { + let config = &shared.config; + // 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)?; + control.set_read_timeout(Some(Duration::from_secs(70)))?; + wire::send( + &mut control, + &ToRelay::Host { + v: wire::VERSION, + protocol: config.protocol, + game: config.game.clone(), + }, + )?; + let mut reader = BufReader::new(control.try_clone()?); + let (nameplate, token) = match wire::recv_buffered::<_, FromRelay>(&mut reader)? { + FromRelay::Registered { + nameplate, token, .. + } => (nameplate, token), + FromRelay::Error { code, .. } => { + return Err(io::Error::other(format!( + "the invite service refused: {}", + code.as_str() + ))); + } + other => return Err(io::Error::other(format!("unexpected answer {other:?}"))), + }; + let code = Code::new(&nameplate)?; + *shared.control.lock().unwrap() = Some(control.try_clone()?); + if shared.stopped() { + 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())); + 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 { + Ok(()) + } else { + Err(e) + }; + } + }; + match message { + FromRelay::Ping => wire::send(&mut control, &ToRelay::Pong)?, + FromRelay::Join { session } => { + let mut open = shared.sessions.lock().unwrap(); + if *open >= MAX_SESSIONS { + continue; + } + *open += 1; + drop(open); + let (shared, code, token, control) = ( + shared.clone(), + code.clone(), + token.clone(), + control.try_clone()?, + ); + 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; + }); + } + _ => {} + } + } +} + +/// One guest: attach, agree on the key, settle, connect to the integrated +/// server, carry the session until it ends. +fn serve( + shared: &Arc, + code: &Code, + token: &str, + session: u64, + port: Option, + relay: SocketAddr, + control: &TcpStream, +) { + let config = &shared.config; + let Ok((mut stream, _)) = connect_relay(config, port) else { + return; + }; + let _ = stream.set_read_timeout(Some(Duration::from_secs(15))); + let attach = ToRelay::Attach { + v: wire::VERSION, + session, + token: token.to_owned(), + }; + if wire::send(&mut stream, &attach).is_err() { + return; + } + let observed = match wire::recv::<_, FromRelay>(&mut stream) { + Ok(FromRelay::Bridged { observed, .. }) => { + observed.and_then(|o| o.parse::().ok()) + } + _ => return, + }; + let Ok(key) = crypto::exchange(&mut stream, &code.secret, &code.nameplate, session) else { + return; + }; + let relayed = match session::secure(stream, &key, Role::Host) { + Ok(s) => s, + Err(e) => { + if crypto::is_wrong_code(&e) { + let count = shared.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. + let _ = control.shutdown(Shutdown::Both); + } + } + return; + } + }; + let candidates = port.map_or_else(Vec::new, |p| direct::candidates(p, Some(relay), observed)); + let shared_routes = shared.clone(); + let settled = session::settle( + relayed, + &key, + Role::Host, + config.path, + session, + port, + candidates, + Box::new(move |tx, deadline, _stop| { + shared_routes + .routes + .lock() + .unwrap() + .insert(session, (tx, deadline + Duration::from_millis(500))); + }), + ); + 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(); + } + shared.emit(HostEvent::Disconnected { session }); +} diff --git a/crates/horizon-friends/src/lib.rs b/crates/horizon-friends/src/lib.rs new file mode 100644 index 000000000..9c86b10fa --- /dev/null +++ b/crates/horizon-friends/src/lib.rs @@ -0,0 +1,124 @@ +//! 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 +//! 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 +//! what the relay sees are in docs/play-with-friends.md. +pub mod code; +pub mod crypto; +pub mod direct; +pub mod guest; +pub mod host; +mod session; +pub mod wire; + +pub use code::Code; +pub use guest::{JoinError, Tunnel}; +pub use host::{Host, HostConfig, HostEvent, HostState}; + +use std::{ + io, + net::{SocketAddr, TcpStream, ToSocketAddrs}, + thread::JoinHandle, +}; + +/// Fill `buf` from the OS random generator. +pub(crate) fn fill_random(buf: &mut [u8]) -> io::Result<()> { + getrandom::fill(buf).map_err(|e| io::Error::other(e.to_string())) +} + +/// Which paths a session may take (`HORIZON_FRIENDS_PATH`). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum PathMode { + /// Direct when the ends reach each other, else the relay. + Auto, + /// Never connect directly: the other end doesn't learn this one's address. + RelayOnly, + /// Never fall back to the relay (tests). + DirectOnly, +} +impl PathMode { + pub fn from_env() -> Self { + match std::env::var("HORIZON_FRIENDS_PATH").as_deref() { + Ok("relay") => Self::RelayOnly, + Ok("direct") => Self::DirectOnly, + _ => Self::Auto, + } + } +} + +/// 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. +pub fn relay_url() -> Option { + 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) + .map(|s| s.trim().to_owned()) + .find(|s| !s.is_empty()) +} + +/// `host:port`, optionally written `tcp://host:port`. +pub fn resolve_relay(url: &str) -> io::Result> { + let address = url + .trim() + .trim_start_matches("tcp://") + .trim_end_matches('/'); + let found: Vec = address.to_socket_addrs()?.collect(); + if found.is_empty() { + return Err(io::Error::new( + io::ErrorKind::NotFound, + "the relay's name didn't resolve", + )); + } + Ok(found) +} + +/// Carry one connection both ways between a plain stream (the game's) and a +/// protected one, until either side ends; then both are closed. +pub fn pump( + plain: TcpStream, + mut reader: crypto::SecureReader, + mut writer: crypto::SecureWriter, +) -> io::Result> { + use io::{Read, Write}; + for s in [&plain, reader.get_ref(), writer.get_ref()] { + s.set_read_timeout(None)?; + let _ = s.set_nodelay(true); + } + let mut plain_in = plain.try_clone()?; + let mut plain_out = plain; + let outbound = std::thread::Builder::new() + .name("horizon-friends-out".into()) + .spawn(move || { + let mut buf = vec![0u8; crypto::MAX_PAYLOAD]; + loop { + match plain_in.read(&mut buf) { + Ok(0) | Err(_) => break, + Ok(n) => { + if writer.write_data(&buf[..n]).is_err() { + break; + } + } + } + } + let _ = writer.get_ref().shutdown(std::net::Shutdown::Both); + let _ = plain_in.shutdown(std::net::Shutdown::Both); + })?; + std::thread::Builder::new() + .name("horizon-friends-in".into()) + .spawn(move || { + while let Ok(Some(frame)) = reader.read_frame() { + if let crypto::Frame::Data(d) = frame + && plain_out.write_all(&d).is_err() + { + break; + } + } + let _ = plain_out.shutdown(std::net::Shutdown::Both); + let _ = reader.get_ref().shutdown(std::net::Shutdown::Both); + let _ = outbound.join(); + }) +} diff --git a/crates/horizon-friends/src/session.rs b/crates/horizon-friends/src/session.rs new file mode 100644 index 000000000..389aa85df --- /dev/null +++ b/crates/horizon-friends/src/session.rs @@ -0,0 +1,195 @@ +//! What both ends do once the relay has bridged them and the key is agreed: +//! protect the relayed stream, swap candidates over it, race direct streams +//! for [`direct::RACE`] and settle on one. The guest decides and says so; +//! the host follows. +use crate::{ + PathMode, + crypto::{self, Frame, Key, Role, SecureReader, SecureWriter}, + direct, +}; +use serde::{Deserialize, Serialize}; +use std::{ + io, + net::{SocketAddr, TcpStream}, + sync::{ + Arc, + atomic::{AtomicBool, Ordering}, + mpsc::{Sender, channel}, + }, + time::{Duration, Instant}, +}; + +pub(crate) type Secure = (SecureReader, SecureWriter); + +#[derive(Debug, Serialize, Deserialize)] +#[serde(tag = "t", rename_all = "snake_case")] +enum Control { + /// Where this end can be reached; `direct` false when it won't try. + Hello { + direct: bool, + candidates: Vec, + }, + /// Sent by the guest as the first frame of the direct stream it keeps. + Use, + /// The guest's decision, on the relayed stream. + Path { direct: bool }, +} + +fn send(w: &mut SecureWriter, c: &Control) -> io::Result<()> { + w.write_control(&serde_json::to_vec(c).map_err(io::Error::other)?) +} +fn recv(r: &mut SecureReader) -> io::Result { + match r.read_frame()? { + Some(Frame::Control(c)) => { + serde_json::from_slice(&c).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e)) + } + Some(Frame::Data(_)) => Err(io::Error::new( + io::ErrorKind::InvalidData, + "data before the path", + )), + None => Err(io::ErrorKind::UnexpectedEof.into()), + } +} + +pub(crate) fn secure(stream: TcpStream, key: &Key, role: Role) -> io::Result { + crypto::secure(stream.try_clone()?, stream, key, role) +} + +pub(crate) struct Established { + pub secure: Secure, + pub direct: bool, +} + +/// Start accepting this session's inbound direct streams (already +/// introduced) into the sender until the deadline or the stop flag. +pub(crate) type Listen<'a> = Box, Instant, Arc) + 'a>; + +/// Settle a session on the relayed stream `relay` (already protected) or a +/// direct one. +pub(crate) fn settle( + relay: Secure, + key: &Key, + role: Role, + mode: PathMode, + session: u64, + direct_port: Option, + candidates: Vec, + listen: Listen<'_>, +) -> io::Result { + let (mut rr, mut rw) = relay; + rr.get_ref() + .set_read_timeout(Some(Duration::from_secs(15)))?; + let wants = mode != PathMode::RelayOnly && direct_port.is_some(); + send( + &mut rw, + &Control::Hello { + direct: wants, + candidates: if wants { + candidates.iter().map(SocketAddr::to_string).collect() + } else { + Vec::new() + }, + }, + )?; + let Control::Hello { + direct: they_want, + candidates: theirs, + } = recv(&mut rr)? + else { + return Err(io::Error::new(io::ErrorKind::InvalidData, "expected hello")); + }; + let theirs: Vec = theirs + .iter() + .filter_map(|a| a.parse().ok()) + .take(16) + .collect(); + let stop = Arc::new(AtomicBool::new(false)); + let (atx, arx) = channel::(); + if wants && they_want { + let deadline = Instant::now() + direct::RACE; + let (raw_tx, raw_rx) = channel::(); + listen(raw_tx.clone(), deadline, stop.clone()); + direct::dial(direct_port, theirs, session, deadline, stop.clone(), raw_tx); + let key = key.clone(); + let _ = std::thread::Builder::new() + .name("horizon-friends-auth".into()) + .spawn(move || { + for raw in raw_rx { + let (key, atx) = (key.clone(), atx.clone()); + let _ = std::thread::Builder::new() + .name("horizon-friends-auth".into()) + .spawn(move || { + let Ok(_) = raw.set_read_timeout(Some(Duration::from_secs(6))) else { + return; + }; + let Ok(mut s) = secure(raw, &key, role) else { + return; + }; + // The host only keeps the stream the guest marks. + if role == Role::Host && !matches!(recv(&mut s.0), Ok(Control::Use)) { + return; + } + let _ = atx.send(s); + }); + } + }); + } else { + drop(atx); + } + let finish = |(r, w): Secure, direct: bool| -> io::Result { + r.get_ref().set_read_timeout(None)?; + Ok(Established { + secure: (r, w), + direct, + }) + }; + let fallback = |rr: SecureReader, rw: SecureWriter| { + if mode == PathMode::DirectOnly { + Err(io::Error::new( + io::ErrorKind::TimedOut, + "no direct connection", + )) + } else { + finish((rr, rw), false) + } + }; + match role { + Role::Guest => { + let chosen = if wants && they_want { + let left = direct::RACE + Duration::from_millis(500); + arx.recv_timeout(left).ok() + } else { + None + }; + stop.store(true, Ordering::Relaxed); + if let Some((r, mut w)) = chosen + && send(&mut w, &Control::Use).is_ok() + { + send(&mut rw, &Control::Path { direct: true })?; + let _ = rr.get_ref().shutdown(std::net::Shutdown::Both); + return finish((r, w), true); + } + send(&mut rw, &Control::Path { direct: false })?; + fallback(rr, rw) + } + Role::Host => { + let Control::Path { direct } = recv(&mut rr)? else { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "expected the path", + )); + }; + if direct { + let chosen = arx.recv_timeout(Duration::from_secs(5)); + stop.store(true, Ordering::Relaxed); + let _ = rr.get_ref().shutdown(std::net::Shutdown::Both); + let chosen = chosen.map_err(|_| { + io::Error::new(io::ErrorKind::TimedOut, "the direct stream vanished") + })?; + return finish(chosen, true); + } + stop.store(true, Ordering::Relaxed); + fallback(rr, rw) + } + } +} diff --git a/crates/horizon-friends/src/wire.rs b/crates/horizon-friends/src/wire.rs new file mode 100644 index 000000000..5991bdf2f --- /dev/null +++ b/crates/horizon-friends/src/wire.rs @@ -0,0 +1,206 @@ +//! The relay protocol: one JSON object per line until a connection is +//! bridged, then the raw session stream (see docs/play-with-friends.md). +use serde::{Deserialize, Serialize}; +use std::io::{self, BufRead, Read, Write}; + +/// Protocol version both the relay and the clients speak. +pub const VERSION: u32 = 1; +/// The longest line either side accepts. +pub const MAX_LINE: usize = 4096; + +/// Lines a client sends. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(tag = "op", rename_all = "snake_case")] +pub enum ToRelay { + /// Register a world; the connection stays open as the host's control + /// connection. + Host { + v: u32, + protocol: i32, + game: String, + }, + /// Join the world behind a nameplate. + Join { + v: u32, + nameplate: String, + protocol: i32, + game: String, + }, + /// The host's new connection for a session the relay announced. + Attach { + v: u32, + session: u64, + token: String, + }, + Pong, +} + +/// Lines the relay sends. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(tag = "op", rename_all = "snake_case")] +pub enum FromRelay { + Registered { + nameplate: String, + token: String, + /// The address the relay saw the connection come from. + observed: Option, + }, + /// A guest is joining: attach a new connection for the session. + Join { + session: u64, + }, + /// The connection now carries the session: raw bytes from here on. + Bridged { + session: u64, + observed: Option, + }, + Ping, + Error { + code: ErrorCode, + /// The host's game version, for `version_mismatch`. + #[serde(default, skip_serializing_if = "Option::is_none")] + game: Option, + }, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ErrorCode { + UnknownCode, + Ended, + VersionMismatch, + HostUnreachable, + Full, + RateLimited, + BadRequest, +} +impl ErrorCode { + pub fn as_str(self) -> &'static str { + match self { + Self::UnknownCode => "unknown_code", + Self::Ended => "ended", + Self::VersionMismatch => "version_mismatch", + Self::HostUnreachable => "host_unreachable", + Self::Full => "full", + Self::RateLimited => "rate_limited", + Self::BadRequest => "bad_request", + } + } +} + +/// Write one message as a line. +pub fn send(w: &mut W, message: &T) -> io::Result<()> { + let mut line = serde_json::to_vec(message).map_err(io::Error::other)?; + line.push(b'\n'); + w.write_all(&line)?; + w.flush() +} + +/// Read one line of at most [`MAX_LINE`] bytes, a byte at a time so nothing +/// after it is consumed: the bytes that follow `bridged` belong to the +/// session. None at a clean end of stream. +pub fn read_line(r: &mut R) -> io::Result>> { + let mut line = Vec::new(); + let mut byte = [0u8; 1]; + loop { + match r.read(&mut byte) { + Ok(0) if line.is_empty() => return Ok(None), + Ok(0) => return Err(io::ErrorKind::UnexpectedEof.into()), + Ok(_) if byte[0] == b'\n' => return Ok(Some(line)), + Ok(_) => { + if line.len() == MAX_LINE { + return Err(io::Error::new(io::ErrorKind::InvalidData, "line too long")); + } + line.push(byte[0]); + } + Err(e) if e.kind() == io::ErrorKind::Interrupted => {} + Err(e) => return Err(e), + } + } +} + +/// Read and decode one message; an end of stream is an error. +pub fn recv Deserialize<'de>>(r: &mut R) -> io::Result { + let line = read_line(r)?.ok_or(io::ErrorKind::UnexpectedEof)?; + serde_json::from_slice(&line).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e)) +} + +/// The same over a buffered reader (the host's control connection, where +/// nothing follows the lines). +pub fn recv_buffered Deserialize<'de>>(r: &mut R) -> io::Result { + let mut line = Vec::new(); + let n = r.take(MAX_LINE as u64 + 1).read_until(b'\n', &mut line)?; + if n == 0 { + return Err(io::ErrorKind::UnexpectedEof.into()); + } + if line.last() != Some(&b'\n') { + return Err(io::Error::new(io::ErrorKind::InvalidData, "line too long")); + } + serde_json::from_slice(&line).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn lines_round_trip() { + let mut buf = Vec::new(); + send( + &mut buf, + &ToRelay::Join { + v: VERSION, + nameplate: "K7QM".into(), + protocol: 777, + game: "26.3".into(), + }, + ) + .unwrap(); + assert_eq!( + String::from_utf8(buf.clone()).unwrap(), + "{\"op\":\"join\",\"v\":1,\"nameplate\":\"K7QM\",\"protocol\":777,\"game\":\"26.3\"}\n" + ); + send( + &mut buf, + &FromRelay::Error { + code: ErrorCode::VersionMismatch, + game: Some("26.2".into()), + }, + ) + .unwrap(); + buf.extend_from_slice(b"raw"); + let mut r = &buf[..]; + let first: ToRelay = recv(&mut r).unwrap(); + assert!(matches!(first, ToRelay::Join { protocol: 777, .. })); + let second: FromRelay = recv(&mut r).unwrap(); + assert_eq!( + second, + FromRelay::Error { + code: ErrorCode::VersionMismatch, + game: Some("26.2".into()) + } + ); + // Nothing after the line was consumed. + assert_eq!(r, b"raw"); + } + + #[test] + fn long_lines_and_garbage_are_refused() { + let long = vec![b'a'; MAX_LINE + 1]; + assert!(read_line(&mut &long[..]).is_err()); + let mut exact = vec![b'a'; MAX_LINE]; + exact.push(b'\n'); + assert_eq!(read_line(&mut &exact[..]).unwrap().unwrap().len(), MAX_LINE); + assert!(recv::<_, ToRelay>(&mut &b"{\"op\":\"nope\"}\n"[..]).is_err()); + assert!(recv::<_, ToRelay>(&mut &b""[..]).is_err()); + assert!(read_line(&mut &b""[..]).unwrap().is_none()); + assert!(read_line(&mut &b"partial"[..]).is_err()); + let mut buffered = io::BufReader::new(&long[..]); + assert!(recv_buffered::<_, ToRelay>(&mut buffered).is_err()); + let mut buffered = io::BufReader::new(&b"{\"op\":\"pong\"}\n"[..]); + assert_eq!( + recv_buffered::<_, ToRelay>(&mut buffered).unwrap(), + ToRelay::Pong + ); + } +} diff --git a/crates/horizon-relay/Cargo.toml b/crates/horizon-relay/Cargo.toml new file mode 100644 index 000000000..f6d3edb40 --- /dev/null +++ b/crates/horizon-relay/Cargo.toml @@ -0,0 +1,19 @@ +[package] +name = "horizon-relay" +version = "0.1.0" +edition.workspace = true +license.workspace = true +rust-version.workspace = true +description = "Play with friends' relay: hands out invite codes, introduces hosts and guests, relays the encrypted stream when a direct connection fails" + +[dependencies] +horizon-friends = { path = "../horizon-friends" } +getrandom = "0.3" +serde_json = "1.0.151" + +[[bin]] +name = "horizon-relay" +path = "src/main.rs" + +[lints] +workspace = true diff --git a/crates/horizon-relay/Dockerfile b/crates/horizon-relay/Dockerfile new file mode 100644 index 000000000..7cae743e4 --- /dev/null +++ b/crates/horizon-relay/Dockerfile @@ -0,0 +1,15 @@ +# The Play with friends relay (docs/play-with-friends.md, "Deploying the 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 +WORKDIR /src +COPY . . +RUN cargo build --release --locked -p horizon-relay \ + && cp target/release/horizon-relay /horizon-relay + +FROM debian:bookworm-slim +COPY --from=build /horizon-relay /usr/local/bin/horizon-relay +ENV PORT=7000 +EXPOSE 7000 +USER nobody +CMD ["horizon-relay"] diff --git a/crates/horizon-relay/railway.toml b/crates/horizon-relay/railway.toml new file mode 100644 index 000000000..b6916e4d4 --- /dev/null +++ b/crates/horizon-relay/railway.toml @@ -0,0 +1,13 @@ +# 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 diff --git a/crates/horizon-relay/src/lib.rs b/crates/horizon-relay/src/lib.rs new file mode 100644 index 000000000..48b9ac50e --- /dev/null +++ b/crates/horizon-relay/src/lib.rs @@ -0,0 +1,652 @@ +//! Play with friends' relay. Hosts register and get a nameplate (the +//! relay-visible half of an invite code); guests resolve it; the relay +//! pairs each guest's connection with a fresh one from the host and copies +//! bytes between them. Those bytes are the end-to-end encrypted session +//! (docs/play-with-friends.md): the relay can't read them, only count them. +//! State is in memory; nothing about players is logged. +pub mod limits; + +use horizon_friends::{ + code, + wire::{self, ErrorCode, FromRelay, ToRelay}, +}; +use limits::{Bucket, Limiter, Rates}; +use std::{ + collections::HashMap, + io::{self, Read, Write}, + net::{Shutdown, SocketAddr, TcpListener, TcpStream}, + sync::{ + Arc, Mutex, + atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering}, + mpsc::{Receiver, RecvTimeoutError, Sender, SyncSender, channel, sync_channel}, + }, + thread::JoinHandle, + time::{Duration, Instant}, +}; + +#[derive(Clone, Debug)] +pub struct Config { + pub max_hosts: usize, + pub max_bridges: usize, + pub max_pending_per_host: usize, + /// Bytes a second each way per relayed stream. + pub session_rate: f64, + /// Bytes a second for everything relayed. + pub total_rate: f64, + pub rates: Rates, + /// Count limits per client address (off when every client comes from + /// the same proxy address). + pub per_address: bool, + /// Unknown codes a minute across all clients, and the burst. + pub global_unknown_per_min: f64, + pub global_unknown_burst: f64, + /// Read a PROXY protocol v1 line before anything else. + pub proxy_protocol: bool, + pub idle: Duration, + pub ping_every: Duration, + pub host_timeout: Duration, + pub first_line: Duration, + pub attach_wait: Duration, + pub ended_kept: Duration, +} +impl Default for Config { + fn default() -> Self { + Self { + max_hosts: 1000, + max_bridges: 200, + max_pending_per_host: 8, + session_rate: 1024.0 * 1024.0, + total_rate: 100.0 * 1_000_000.0 / 8.0, + rates: Rates::default(), + per_address: true, + global_unknown_per_min: 120.0, + global_unknown_burst: 30.0, + proxy_protocol: false, + idle: Duration::from_secs(120), + ping_every: Duration::from_secs(20), + host_timeout: Duration::from_secs(60), + first_line: Duration::from_secs(10), + attach_wait: Duration::from_secs(10), + ended_kept: Duration::from_secs(15 * 60), + } + } +} +impl Config { + /// The defaults with the `RELAY_*` environment variables applied. + pub fn from_env() -> Self { + fn var(name: &str) -> Option { + std::env::var(name).ok()?.trim().parse().ok() + } + let mut c = Self::default(); + if let Some(v) = var("RELAY_MAX_HOSTS") { + c.max_hosts = v; + } + if let Some(v) = var("RELAY_MAX_BRIDGES") { + c.max_bridges = v; + } + if let Some(v) = var("RELAY_MAX_PENDING_PER_HOST") { + c.max_pending_per_host = v; + } + if let Some(v) = var::("RELAY_SESSION_KBPS") { + c.session_rate = v * 1024.0; + } + if let Some(v) = var::("RELAY_TOTAL_MBPS") { + c.total_rate = v * 1_000_000.0 / 8.0; + } + if let Some(v) = var::("RELAY_GLOBAL_UNKNOWN_PER_MIN") { + c.global_unknown_per_min = v; + } + if let Some(v) = var::("RELAY_PER_ADDRESS_LIMITS") { + c.per_address = v != 0; + } + if let Some(v) = var::("RELAY_PROXY_PROTOCOL") { + c.proxy_protocol = v != 0; + } + c + } +} + +/// What the relay reports (and logs): counts only. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Counts { + pub hosts: usize, + pub bridges: usize, + pub registrations: u64, + pub joins: u64, + pub unknown: u64, + pub rate_limited: u64, + pub relayed_bytes: u64, +} +impl Counts { + pub fn json(&self) -> String { + format!( + "{{\"ok\":true,\"hosts\":{},\"bridges\":{},\"registrations\":{},\"joins\":{},\"unknown\":{},\"rate_limited\":{},\"relayed_bytes\":{}}}", + self.hosts, + self.bridges, + self.registrations, + self.joins, + self.unknown, + self.rate_limited, + self.relayed_bytes + ) + } +} + +/// What the host's control connection sends next. +enum Out { + Line(FromRelay), + /// The host stopped answering or went away. + Closed, +} +struct HostEntry { + token: String, + protocol: i32, + game: String, + to_host: Sender, + pending: usize, +} +struct Pending { + nameplate: String, + attach: SyncSender<(TcpStream, SocketAddr)>, +} +#[derive(Default)] +struct Inner { + hosts: HashMap, + ended: HashMap, + pending: HashMap, +} + +struct State { + config: Config, + inner: Mutex, + limiter: Mutex, + global_unknown: Mutex, + total: Mutex, + bridges: AtomicUsize, + registrations: AtomicU64, + joins: AtomicU64, + unknown: AtomicU64, + rate_limited: AtomicU64, + relayed_bytes: AtomicU64, + stop: AtomicBool, +} + +#[derive(Clone)] +pub struct Relay { + state: Arc, +} + +fn random_u64() -> u64 { + let mut b = [0u8; 8]; + getrandom::fill(&mut b).expect("OS random generator"); + u64::from_le_bytes(b) +} +fn random_token() -> String { + let mut b = [0u8; 16]; + getrandom::fill(&mut b).expect("OS random generator"); + b.iter().map(|x| format!("{x:02x}")).collect() +} + +impl Relay { + pub fn new(config: Config) -> Self { + let now = Instant::now(); + Self { + state: Arc::new(State { + limiter: Mutex::new(Limiter::new(config.rates.clone(), config.per_address)), + global_unknown: Mutex::new(Bucket::new( + config.global_unknown_per_min / 60.0, + config.global_unknown_burst, + now, + )), + total: Mutex::new(Bucket::new(config.total_rate, config.total_rate / 4.0, now)), + config, + inner: Mutex::new(Inner::default()), + bridges: AtomicUsize::new(0), + registrations: AtomicU64::new(0), + joins: AtomicU64::new(0), + unknown: AtomicU64::new(0), + rate_limited: AtomicU64::new(0), + relayed_bytes: AtomicU64::new(0), + stop: AtomicBool::new(false), + }), + } + } + /// A relay on a free loopback port, served on a thread (tests). + pub fn spawn_local(config: Config) -> io::Result<(Self, SocketAddr, JoinHandle<()>)> { + let listener = TcpListener::bind("127.0.0.1:0")?; + let address = listener.local_addr()?; + let relay = Self::new(config); + let r = relay.clone(); + let t = std::thread::spawn(move || r.serve(listener)); + Ok((relay, address, t)) + } + pub fn counts(&self) -> Counts { + counts(&self.state) + } + pub fn stop(&self) { + self.state.stop.store(true, Ordering::Relaxed); + } + /// Accept connections until [`Relay::stop`]. + pub fn serve(&self, listener: TcpListener) { + let _ = listener.set_nonblocking(true); + while !self.state.stop.load(Ordering::Relaxed) { + match listener.accept() { + Ok((stream, peer)) => { + let state = self.state.clone(); + let _ = + std::thread::Builder::new() + .name("relay-conn".into()) + .spawn(move || { + let _ = stream.set_nonblocking(false); + let _ = handle(&state, stream, peer); + }); + } + Err(e) if e.kind() == io::ErrorKind::WouldBlock => { + std::thread::sleep(Duration::from_millis(10)); + } + Err(_) => std::thread::sleep(Duration::from_millis(50)), + } + } + } +} + +fn counts(s: &State) -> Counts { + Counts { + hosts: s.inner.lock().unwrap().hosts.len(), + bridges: s.bridges.load(Ordering::Relaxed), + registrations: s.registrations.load(Ordering::Relaxed), + joins: s.joins.load(Ordering::Relaxed), + unknown: s.unknown.load(Ordering::Relaxed), + rate_limited: s.rate_limited.load(Ordering::Relaxed), + relayed_bytes: s.relayed_bytes.load(Ordering::Relaxed), + } +} + +fn refuse(stream: &mut TcpStream, code: ErrorCode) -> io::Result<()> { + wire::send(stream, &FromRelay::Error { code, game: None }) +} + +/// `PROXY TCP4 `: the client's address. +fn proxy_line(line: &[u8]) -> Option { + let text = std::str::from_utf8(line).ok()?.trim_end_matches('\r'); + let parts: Vec<&str> = text.split(' ').collect(); + match parts.as_slice() { + ["PROXY", "TCP4" | "TCP6", src, _, sport, _] => { + Some(SocketAddr::new(src.parse().ok()?, sport.parse().ok()?)) + } + _ => None, + } +} + +fn handle(state: &Arc, mut stream: TcpStream, mut peer: SocketAddr) -> io::Result<()> { + if state.stop.load(Ordering::Relaxed) { + return Ok(()); + } + stream.set_read_timeout(Some(state.config.first_line))?; + let _ = stream.set_nodelay(true); + let mut line = wire::read_line(&mut stream)?.ok_or(io::ErrorKind::UnexpectedEof)?; + if state.config.proxy_protocol { + peer = proxy_line(&line) + .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidData, "no PROXY line"))?; + line = wire::read_line(&mut stream)?.ok_or(io::ErrorKind::UnexpectedEof)?; + } + if line.starts_with(b"GET ") { + return http(state, &mut stream, &line, peer); + } + let Ok(hello) = serde_json::from_slice::(&line) else { + return refuse(&mut stream, ErrorCode::BadRequest); + }; + match hello { + ToRelay::Host { v, protocol, game } if v == wire::VERSION => { + host(state, stream, peer, protocol, game) + } + ToRelay::Join { + v, + nameplate, + protocol, + .. + } if v == wire::VERSION => join(state, stream, peer, &nameplate, protocol), + ToRelay::Attach { v, session, token } if v == wire::VERSION => { + attach(state, stream, peer, session, &token) + } + _ => refuse(&mut stream, ErrorCode::BadRequest), + } +} + +fn http(state: &State, stream: &mut TcpStream, line: &[u8], peer: SocketAddr) -> io::Result<()> { + // Drain the request headers (bounded) before answering. + let mut headers = 0; + while let Some(h) = wire::read_line(stream)? { + headers += 1; + if h.is_empty() || h == b"\r" || headers > 64 { + break; + } + } + let path = std::str::from_utf8(line) + .ok() + .and_then(|l| l.split(' ').nth(1)) + .unwrap_or(""); + let (status, body) = match path { + "/health" => ("200 OK", counts(state).json()), + // The address the relay sees for the caller: checks that the hosting + // platform's proxy passes client addresses through. + "/whoami" => ("200 OK", format!("{{\"address\":\"{peer}\"}}")), + _ => ("404 Not Found", "{\"ok\":false}".to_owned()), + }; + let response = format!( + "HTTP/1.1 {status}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", + body.len() + ); + stream.write_all(response.as_bytes()) +} + +fn host( + state: &Arc, + mut stream: TcpStream, + peer: SocketAddr, + protocol: i32, + game: String, +) -> io::Result<()> { + let now = Instant::now(); + if !state.limiter.lock().unwrap().allow_register(peer.ip(), now) { + state.rate_limited.fetch_add(1, Ordering::Relaxed); + return refuse(&mut stream, ErrorCode::RateLimited); + } + let (tx, rx) = channel(); + let token = random_token(); + let nameplate = { + let mut inner = state.inner.lock().unwrap(); + let kept = state.config.ended_kept; + inner + .ended + .retain(|_, t| now.saturating_duration_since(*t) < kept); + let mut found = None; + if inner.hosts.len() < state.config.max_hosts { + for _ in 0..64 { + let n = code::nameplate(random_u64() as u32); + if !inner.hosts.contains_key(&n) && !inner.ended.contains_key(&n) { + found = Some(n); + break; + } + } + } + if let Some(n) = &found { + inner.hosts.insert( + n.clone(), + HostEntry { + token: token.clone(), + protocol, + game: game.chars().take(32).collect(), + to_host: tx.clone(), + pending: 0, + }, + ); + } + found + }; + let Some(nameplate) = nameplate else { + return refuse(&mut stream, ErrorCode::Full); + }; + state.registrations.fetch_add(1, Ordering::Relaxed); + let result = serve_host(state, &mut stream, peer, &nameplate, &token, tx, rx); + { + let mut inner = state.inner.lock().unwrap(); + if inner + .hosts + .get(&nameplate) + .is_some_and(|h| h.token == token) + { + inner.hosts.remove(&nameplate); + inner.ended.insert(nameplate, Instant::now()); + } + } + let _ = stream.shutdown(Shutdown::Both); + result +} + +/// The host's control connection: joins and pings out, pongs in. A host +/// silent for `host_timeout` is gone. +fn serve_host( + state: &Arc, + stream: &mut TcpStream, + peer: SocketAddr, + nameplate: &str, + token: &str, + tx: Sender, + rx: Receiver, +) -> io::Result<()> { + wire::send( + stream, + &FromRelay::Registered { + nameplate: nameplate.to_owned(), + token: token.to_owned(), + observed: Some(peer.to_string()), + }, + )?; + let mut reader = stream.try_clone()?; + reader.set_read_timeout(Some(state.config.host_timeout))?; + std::thread::Builder::new() + .name("relay-host-read".into()) + .spawn(move || { + while let Ok(Some(_)) = wire::read_line(&mut reader) {} + let _ = tx.send(Out::Closed); + })?; + while !state.stop.load(Ordering::Relaxed) { + match rx.recv_timeout(state.config.ping_every) { + Ok(Out::Line(m)) => wire::send(stream, &m)?, + Ok(Out::Closed) | Err(RecvTimeoutError::Disconnected) => break, + Err(RecvTimeoutError::Timeout) => wire::send(stream, &FromRelay::Ping)?, + } + } + Ok(()) +} + +enum Lookup { + Found(Sender), + Unknown, + Ended, + Version(String), + Full, +} + +fn join( + state: &Arc, + mut stream: TcpStream, + peer: SocketAddr, + nameplate: &str, + protocol: i32, +) -> io::Result<()> { + let now = Instant::now(); + state.joins.fetch_add(1, Ordering::Relaxed); + // The global budget for unknown codes is checked before the lookup, so a + // refusal says nothing about whether the nameplate exists. + let allowed = state.limiter.lock().unwrap().allow_join(peer.ip(), now) + && state.global_unknown.lock().unwrap().has(now); + if !allowed { + state.rate_limited.fetch_add(1, Ordering::Relaxed); + return refuse(&mut stream, ErrorCode::RateLimited); + } + let Some(nameplate) = code::parse_nameplate(nameplate) else { + return refuse(&mut stream, ErrorCode::BadRequest); + }; + let session = random_u64(); + let (atx, arx) = sync_channel(1); + let lookup = { + let mut inner = state.inner.lock().unwrap(); + let ended = inner + .ended + .get(&nameplate) + .is_some_and(|t| now.saturating_duration_since(*t) < state.config.ended_kept); + let busy = state.bridges.load(Ordering::Relaxed) >= state.config.max_bridges; + let lookup = match inner.hosts.get_mut(&nameplate) { + None if ended => Lookup::Ended, + None => Lookup::Unknown, + Some(h) if h.protocol != protocol => Lookup::Version(h.game.clone()), + Some(h) if busy || h.pending >= state.config.max_pending_per_host => Lookup::Full, + Some(h) => { + h.pending += 1; + Lookup::Found(h.to_host.clone()) + } + }; + if matches!(lookup, Lookup::Found(_)) { + inner.pending.insert( + session, + Pending { + nameplate: nameplate.clone(), + attach: atx, + }, + ); + } + lookup + }; + let to_host = match lookup { + Lookup::Found(tx) => tx, + Lookup::Unknown => { + state.unknown.fetch_add(1, Ordering::Relaxed); + state.limiter.lock().unwrap().unknown(peer.ip(), now); + state.global_unknown.lock().unwrap().try_take(now); + return refuse(&mut stream, ErrorCode::UnknownCode); + } + Lookup::Ended => return refuse(&mut stream, ErrorCode::Ended), + Lookup::Full => return refuse(&mut stream, ErrorCode::Full), + Lookup::Version(game) => { + return wire::send( + &mut stream, + &FromRelay::Error { + code: ErrorCode::VersionMismatch, + game: Some(game), + }, + ); + } + }; + let _ = to_host.send(Out::Line(FromRelay::Join { session })); + let attached = arx.recv_timeout(state.config.attach_wait); + { + let mut inner = state.inner.lock().unwrap(); + inner.pending.remove(&session); + if let Some(h) = inner.hosts.get_mut(&nameplate) { + h.pending = h.pending.saturating_sub(1); + } + } + match attached { + Ok((host, host_peer)) => bridge(state, stream, peer, host, host_peer, session), + Err(_) => refuse(&mut stream, ErrorCode::HostUnreachable), + } +} + +fn attach( + state: &Arc, + mut stream: TcpStream, + peer: SocketAddr, + session: u64, + token: &str, +) -> io::Result<()> { + let target = { + let inner = state.inner.lock().unwrap(); + inner + .pending + .get(&session) + .filter(|p| { + inner + .hosts + .get(&p.nameplate) + .is_some_and(|h| h.token == token) + }) + .map(|p| p.attach.clone()) + }; + match target { + Some(tx) => match tx.try_send((stream, peer)) { + Ok(()) => Ok(()), + Err( + std::sync::mpsc::TrySendError::Full((mut stream, _)) + | std::sync::mpsc::TrySendError::Disconnected((mut stream, _)), + ) => refuse(&mut stream, ErrorCode::BadRequest), + }, + None => refuse(&mut stream, ErrorCode::BadRequest), + } +} + +/// Tell both ends they are bridged, then copy each way until either ends. +fn bridge( + state: &Arc, + mut guest: TcpStream, + guest_peer: SocketAddr, + mut host: TcpStream, + host_peer: SocketAddr, + session: u64, +) -> io::Result<()> { + state.bridges.fetch_add(1, Ordering::Relaxed); + let result = (|| -> io::Result<()> { + wire::send( + &mut guest, + &FromRelay::Bridged { + session, + observed: Some(guest_peer.to_string()), + }, + )?; + wire::send( + &mut host, + &FromRelay::Bridged { + session, + observed: Some(host_peer.to_string()), + }, + )?; + for s in [&guest, &host] { + s.set_read_timeout(Some(state.config.idle))?; + let _ = s.set_nodelay(true); + } + let (g, h, st) = (guest.try_clone()?, host.try_clone()?, state.clone()); + let up = std::thread::Builder::new() + .name("relay-copy".into()) + .spawn(move || copy(&st, g, h))?; + copy(state, host, guest); + let _ = up.join(); + Ok(()) + })(); + state.bridges.fetch_sub(1, Ordering::Relaxed); + result +} + +fn copy(state: &State, mut from: TcpStream, mut to: TcpStream) { + let rate = state.config.session_rate; + let mut bucket = Bucket::new(rate, (rate / 2.0).max(16384.0), Instant::now()); + let mut buf = vec![0u8; 16 * 1024]; + loop { + let n = match from.read(&mut buf) { + Ok(0) | Err(_) => break, + Ok(n) => n, + }; + let now = Instant::now(); + let wait = bucket + .take(n as f64, now) + .max(state.total.lock().unwrap().take(n as f64, now)); + if !wait.is_zero() { + std::thread::sleep(wait); + } + if to.write_all(&buf[..n]).is_err() { + break; + } + state.relayed_bytes.fetch_add(n as u64, Ordering::Relaxed); + } + let _ = from.shutdown(Shutdown::Both); + let _ = to.shutdown(Shutdown::Both); +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn proxy_lines() { + assert_eq!( + proxy_line(b"PROXY TCP4 203.0.113.7 10.0.0.1 51000 7000\r"), + Some("203.0.113.7:51000".parse().unwrap()) + ); + assert_eq!( + proxy_line(b"PROXY TCP6 2001:db8::1 2001:db8::2 51000 7000"), + Some("[2001:db8::1]:51000".parse().unwrap()) + ); + assert_eq!(proxy_line(b"PROXY UNKNOWN"), None); + assert_eq!(proxy_line(b"{\"op\":\"pong\"}"), None); + } +} diff --git a/crates/horizon-relay/src/limits.rs b/crates/horizon-relay/src/limits.rs new file mode 100644 index 000000000..adf199919 --- /dev/null +++ b/crates/horizon-relay/src/limits.rs @@ -0,0 +1,275 @@ +//! Token buckets for request rates and relayed bandwidth, and the +//! per-address state behind them (kept in memory, forgotten after ten idle +//! minutes). +use std::{ + collections::{HashMap, VecDeque}, + net::IpAddr, + time::{Duration, Instant}, +}; + +/// A token bucket: `rate` tokens a second up to `burst`. +#[derive(Clone, Debug)] +pub struct Bucket { + tokens: f64, + last: Instant, + rate: f64, + burst: f64, +} +impl Bucket { + pub fn new(rate: f64, burst: f64, now: Instant) -> Self { + Self { + tokens: burst, + last: now, + rate, + burst, + } + } + fn refill(&mut self, now: Instant) { + let dt = now.saturating_duration_since(self.last).as_secs_f64(); + self.tokens = (self.tokens + dt * self.rate).min(self.burst); + self.last = now; + } + /// Take one token if there is one. + pub fn try_take(&mut self, now: Instant) -> bool { + self.refill(now); + if self.tokens >= 1.0 { + self.tokens -= 1.0; + true + } else { + false + } + } + pub fn has(&mut self, now: Instant) -> bool { + self.refill(now); + self.tokens >= 1.0 + } + /// Take `n` tokens, going into debt if needed; how long to wait before + /// sending them so the average stays at the rate. + pub fn take(&mut self, n: f64, now: Instant) -> Duration { + self.refill(now); + self.tokens -= n; + if self.tokens >= 0.0 || self.rate <= 0.0 { + Duration::ZERO + } else { + Duration::from_secs_f64(-self.tokens / self.rate) + } + } +} + +/// Addresses are counted by IPv4 address and by IPv6 /64 (one home). +pub fn address_key(ip: IpAddr) -> IpAddr { + match ip { + IpAddr::V6(v6) => match v6.to_ipv4_mapped() { + Some(v4) => IpAddr::V4(v4), + None => { + let s = v6.segments(); + IpAddr::V6(std::net::Ipv6Addr::new(s[0], s[1], s[2], s[3], 0, 0, 0, 0)) + } + }, + v4 => v4, + } +} + +#[derive(Clone, Debug)] +pub struct Rates { + pub register_per_min: f64, + pub register_burst: f64, + pub join_per_min: f64, + pub join_burst: f64, + /// Unknown codes an address may try in `unknown_window` before it is + /// blocked for `block`. + pub unknown_limit: usize, + pub unknown_window: Duration, + pub block: Duration, +} +impl Default for Rates { + fn default() -> Self { + Self { + register_per_min: 6.0, + register_burst: 3.0, + join_per_min: 12.0, + join_burst: 6.0, + unknown_limit: 5, + unknown_window: Duration::from_secs(600), + block: Duration::from_secs(600), + } + } +} + +struct Address { + register: Bucket, + join: Bucket, + unknown: VecDeque, + blocked_until: Option, + seen: Instant, +} + +/// Per-address limits; disabled (everything allowed) when the relay can't +/// see client addresses. +pub struct Limiter { + rates: Rates, + enabled: bool, + addresses: HashMap, + last_sweep: Instant, +} +impl Limiter { + pub fn new(rates: Rates, enabled: bool) -> Self { + Self { + rates, + enabled, + addresses: HashMap::new(), + last_sweep: Instant::now(), + } + } + fn entry(&mut self, ip: IpAddr, now: Instant) -> &mut Address { + if now.saturating_duration_since(self.last_sweep) > Duration::from_secs(60) { + self.last_sweep = now; + let keep = Duration::from_secs(600).max(self.rates.block); + self.addresses.retain(|_, a| { + now.saturating_duration_since(a.seen) < keep + || a.blocked_until.is_some_and(|b| b > now) + }); + } + let r = &self.rates; + let a = self + .addresses + .entry(address_key(ip)) + .or_insert_with(|| Address { + register: Bucket::new(r.register_per_min / 60.0, r.register_burst, now), + join: Bucket::new(r.join_per_min / 60.0, r.join_burst, now), + unknown: VecDeque::new(), + blocked_until: None, + seen: now, + }); + a.seen = now; + a + } + pub fn allow_register(&mut self, ip: IpAddr, now: Instant) -> bool { + !self.enabled || self.entry(ip, now).register.try_take(now) + } + pub fn allow_join(&mut self, ip: IpAddr, now: Instant) -> bool { + if !self.enabled { + return true; + } + let a = self.entry(ip, now); + if a.blocked_until.is_some_and(|b| b > now) { + return false; + } + a.blocked_until = None; + a.join.try_take(now) + } + /// An unknown code from this address; blocks it past the limit. + pub fn unknown(&mut self, ip: IpAddr, now: Instant) { + if !self.enabled { + return; + } + let (limit, window, block) = ( + self.rates.unknown_limit, + self.rates.unknown_window, + self.rates.block, + ); + let a = self.entry(ip, now); + a.unknown.push_back(now); + while a + .unknown + .front() + .is_some_and(|t| now.saturating_duration_since(*t) > window) + { + a.unknown.pop_front(); + } + if a.unknown.len() >= limit { + a.blocked_until = Some(now + block); + a.unknown.clear(); + } + } + pub fn tracked(&self) -> usize { + self.addresses.len() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn buckets_refill_at_their_rate() { + let t = Instant::now(); + let mut b = Bucket::new(1.0, 2.0, t); + assert!(b.try_take(t)); + assert!(b.try_take(t)); + assert!(!b.try_take(t)); + assert!(!b.try_take(t + Duration::from_millis(900))); + assert!(b.try_take(t + Duration::from_millis(1000))); + // Never above the burst. + assert!(b.try_take(t + Duration::from_secs(100))); + assert!(b.try_take(t + Duration::from_secs(100))); + assert!(!b.try_take(t + Duration::from_secs(100))); + } + + #[test] + fn bandwidth_debt_turns_into_a_wait() { + let t = Instant::now(); + let mut b = Bucket::new(1000.0, 500.0, t); + assert_eq!(b.take(500.0, t), Duration::ZERO); + assert_eq!(b.take(1000.0, t), Duration::from_secs(1)); + // After the wait the debt is paid. + assert_eq!(b.take(0.0, t + Duration::from_secs(1)), Duration::ZERO); + } + + #[test] + fn ipv6_counts_by_home() { + let a: IpAddr = "2001:db8:1:2:aaaa::1".parse().unwrap(); + let b: IpAddr = "2001:db8:1:2:bbbb::9".parse().unwrap(); + let c: IpAddr = "2001:db8:1:3::1".parse().unwrap(); + assert_eq!(address_key(a), address_key(b)); + assert_ne!(address_key(a), address_key(c)); + let mapped: IpAddr = "::ffff:203.0.113.7".parse().unwrap(); + assert_eq!( + address_key(mapped), + "203.0.113.7".parse::().unwrap() + ); + } + + #[test] + fn unknown_codes_block_an_address_for_a_while() { + let t = Instant::now(); + let ip: IpAddr = "203.0.113.7".parse().unwrap(); + let other: IpAddr = "203.0.113.8".parse().unwrap(); + let mut l = Limiter::new( + Rates { + join_burst: 100.0, + ..Rates::default() + }, + true, + ); + for _ in 0..4 { + assert!(l.allow_join(ip, t)); + l.unknown(ip, t); + } + assert!(l.allow_join(ip, t)); + l.unknown(ip, t); + assert!(!l.allow_join(ip, t)); + assert!(!l.allow_join(ip, t + Duration::from_secs(599))); + assert!(l.allow_join(other, t)); + assert!(l.allow_join(ip, t + Duration::from_secs(601))); + // Unknown codes spread beyond the window don't add up. + let mut l = Limiter::new(Rates::default(), true); + for i in 0..10 { + l.unknown(ip, t + Duration::from_secs(i * 200)); + } + assert!(l.allow_join(ip, t + Duration::from_secs(2000))); + } + + #[test] + fn join_and_register_rates() { + let t = Instant::now(); + let ip: IpAddr = "198.51.100.1".parse().unwrap(); + let mut l = Limiter::new(Rates::default(), true); + assert_eq!((0..10).filter(|_| l.allow_register(ip, t)).count(), 3); + assert_eq!((0..10).filter(|_| l.allow_join(ip, t)).count(), 6); + assert!(l.allow_join(ip, t + Duration::from_secs(5))); + let mut off = Limiter::new(Rates::default(), false); + assert!((0..100).all(|_| off.allow_join(ip, t))); + assert_eq!(off.tracked(), 0); + } +} diff --git a/crates/horizon-relay/src/main.rs b/crates/horizon-relay/src/main.rs new file mode 100644 index 000000000..f14bdfe05 --- /dev/null +++ b/crates/horizon-relay/src/main.rs @@ -0,0 +1,38 @@ +//! `horizon-relay`: listens on `$PORT` (7000 when unset), limits from the +//! `RELAY_*` variables (docs/play-with-friends.md). Prints counts every five +//! minutes, nothing else. +use horizon_relay::{Config, Relay}; +use std::{net::TcpListener, time::Duration}; + +fn main() { + let port: u16 = std::env::var("PORT") + .ok() + .and_then(|p| p.trim().parse().ok()) + .unwrap_or(7000); + // Dual-stack where the system allows it (Railway's private network is + // IPv6), else IPv4. + let listener = TcpListener::bind(("::", port)) + .or_else(|_| TcpListener::bind(("0.0.0.0", port))) + .unwrap_or_else(|e| { + eprintln!("horizon-relay: can't listen on port {port}: {e}"); + std::process::exit(1); + }); + let config = Config::from_env(); + println!( + "horizon-relay {} listening on port {port} (hosts {}, bridges {}, {} KiB/s per stream, per-address limits {})", + env!("CARGO_PKG_VERSION"), + config.max_hosts, + config.max_bridges, + (config.session_rate / 1024.0) as u64, + if config.per_address { "on" } else { "off" }, + ); + let relay = Relay::new(config); + let r = relay.clone(); + std::thread::spawn(move || { + loop { + std::thread::sleep(Duration::from_secs(300)); + println!("{}", r.counts().json()); + } + }); + relay.serve(listener); +} diff --git a/crates/horizon-relay/tests/tunnel.rs b/crates/horizon-relay/tests/tunnel.rs new file mode 100644 index 000000000..d988edb88 --- /dev/null +++ b/crates/horizon-relay/tests/tunnel.rs @@ -0,0 +1,349 @@ +//! 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. +use horizon_friends::{ + Code, Host, HostConfig, HostEvent, JoinError, PathMode, + guest::{self, GuestConfig}, +}; +use horizon_relay::{Config, Relay, limits::Rates}; +use std::{ + io::{Read, Write}, + net::{SocketAddr, TcpListener, TcpStream}, + time::{Duration, Instant}, +}; + +const PROTOCOL: i32 = 777; + +/// Echoes every connection back until it closes. +fn echo_server() -> SocketAddr { + let l = TcpListener::bind("127.0.0.1:0").unwrap(); + let a = l.local_addr().unwrap(); + std::thread::spawn(move || { + for s in l.incoming() { + let Ok(mut s) = s else { continue }; + std::thread::spawn(move || { + let mut out = s.try_clone().unwrap(); + let _ = std::io::copy(&mut s, &mut out); + }); + } + }); + a +} + +fn relay(config: Config) -> (Relay, String) { + let (relay, address, _) = Relay::spawn_local(config).unwrap(); + (relay, address.to_string()) +} + +fn generous() -> Config { + Config { + rates: Rates { + join_per_min: 600.0, + join_burst: 100.0, + ..Rates::default() + }, + ..Config::default() + } +} + +fn host(relay: &str, lan: SocketAddr, path: PathMode) -> (Host, Code) { + let host = Host::start(HostConfig { + relay: relay.to_owned(), + lan, + protocol: PROTOCOL, + game: "26.3".into(), + path, + }) + .unwrap(); + let code = wait_event(&host, |e| match e { + HostEvent::Code(c) => Some(c.clone()), + _ => None, + }); + (host, code) +} + +thread_local! { + /// Events polled but not yet waited for. + static BACKLOG: std::cell::RefCell> = const { std::cell::RefCell::new(Vec::new()) }; +} + +/// The first event (in order) that `f` picks; the others stay queued. +fn wait_event(host: &Host, mut f: impl FnMut(&HostEvent) -> Option) -> T { + let deadline = Instant::now() + Duration::from_secs(10); + while Instant::now() < deadline { + let found = BACKLOG.with_borrow_mut(|backlog| { + backlog.extend(host.poll()); + let i = backlog.iter().position(|e| f(e).is_some())?; + f(&backlog.remove(i)) + }); + if let Some(t) = found { + return t; + } + std::thread::sleep(Duration::from_millis(10)); + } + panic!("no such host event"); +} + +fn join(relay: &str, code: &Code, path: PathMode) -> Result { + guest::join(&GuestConfig { + relay: relay.to_owned(), + code: code.clone(), + protocol: PROTOCOL, + game: "26.3".into(), + path, + }) +} + +/// What the game's client does: connect to the loopback port, send, read +/// the echo back. +fn round_trip(tunnel: guest::Tunnel, payload: &[u8]) { + let (port, done) = tunnel.serve_loopback().unwrap(); + let mut s = TcpStream::connect(("127.0.0.1", port)).unwrap(); + s.set_read_timeout(Some(Duration::from_secs(20))).unwrap(); + let mut w = s.try_clone().unwrap(); + let send = payload.to_vec(); + let writer = std::thread::spawn(move || w.write_all(&send).unwrap()); + let mut got = vec![0u8; payload.len()]; + s.read_exact(&mut got).unwrap(); + writer.join().unwrap(); + assert!(got == payload, "echo differs"); + drop(s); + done.join().unwrap(); +} + +fn payload(n: usize) -> Vec { + (0..n).map(|i| (i * 7 + i / 251) as u8).collect() +} + +#[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(); + assert!( + tunnel.direct, + "loopback ends should reach each other directly" + ); + let data = payload(1 << 20); + round_trip(tunnel, &data); + 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(); + 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. + assert!(matches!( + join(&address, &code, PathMode::DirectOnly), + Err(JoinError::Failed(_)) + )); +} + +#[test] +fn wrong_secrets_fail_and_retire_the_code() { + let (_relay, address) = relay(generous()); + let (host, code) = host(&address, echo_server(), PathMode::Auto); + let wrong = Code { + nameplate: code.nameplate.clone(), + secret: if code.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(); + 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); + assert!(matches!( + join(&address, &code, PathMode::Auto), + Err(JoinError::Ended) + )); + round_trip(join(&address, &fresh, PathMode::Auto).unwrap(), b"fresh"); +} + +#[test] +fn unknown_codes_versions_and_ended_invites() { + let (relay, address) = relay(generous()); + let (mut host, code) = host(&address, echo_server(), PathMode::Auto); + let other = guest::join(&GuestConfig { + relay: address.clone(), + code: code.clone(), + protocol: PROTOCOL - 1, + game: "26.2".into(), + path: PathMode::Auto, + }); + match other { + Err(e @ JoinError::VersionMismatch { .. }) => { + assert_eq!( + e.to_string(), + "Your friend plays Minecraft 26.3; you have 26.2." + ) + } + other => panic!("{:?}", other.err()), + } + host.stop(); + assert!(matches!( + join(&address, &code, 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) + .unwrap(); + let unknown = Code { + nameplate: free, + secret: "0000".into(), + }; + for _ in 0..5 { + assert!(matches!( + join(&address, &unknown, PathMode::Auto), + Err(JoinError::UnknownCode) + )); + } + assert!(matches!( + join(&address, &code, PathMode::Auto), + Err(JoinError::RateLimited) + )); + let counts = relay.counts(); + assert_eq!(counts.unknown, 5); + assert!(counts.rate_limited >= 1); + assert_eq!(counts.hosts, 0); +} + +#[test] +fn a_host_that_never_attaches_is_unreachable() { + use horizon_friends::wire::{self, FromRelay, ToRelay}; + let (_relay, address) = relay(Config { + attach_wait: Duration::from_millis(500), + ..generous() + }); + let mut control = TcpStream::connect(&address).unwrap(); + wire::send( + &mut control, + &ToRelay::Host { + v: wire::VERSION, + protocol: PROTOCOL, + game: "26.3".into(), + }, + ) + .unwrap(); + let FromRelay::Registered { + nameplate, token, .. + } = wire::recv(&mut control).unwrap() + else { + panic!() + }; + let code = Code { + nameplate, + secret: "0000".into(), + }; + assert!(matches!( + join(&address, &code, PathMode::Auto), + Err(JoinError::HostUnreachable) + )); + // The relay announced the session; attaching late or with another token fails. + let FromRelay::Join { session } = wire::recv(&mut control).unwrap() else { + panic!() + }; + let mut late = TcpStream::connect(&address).unwrap(); + wire::send( + &mut late, + &ToRelay::Attach { + v: wire::VERSION, + session, + token, + }, + ) + .unwrap(); + assert!(matches!( + wire::recv::<_, FromRelay>(&mut late).unwrap(), + FromRelay::Error { .. } + )); +} + +#[test] +fn relayed_bandwidth_is_capped() { + let rate = 200_000.0; + let (_relay, address) = relay(Config { + session_rate: rate, + ..generous() + }); + let (_host, code) = host(&address, echo_server(), PathMode::RelayOnly); + let tunnel = join(&address, &code, 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. + assert!( + started.elapsed() >= Duration::from_secs(2), + "{:?}", + started.elapsed() + ); +} + +#[test] +fn health_and_whoami_answer_http() { + let (_relay, address) = relay(Config::default()); + let get = |path: &str| { + let mut s = TcpStream::connect(&address).unwrap(); + write!(s, "GET {path} HTTP/1.1\r\nHost: relay\r\n\r\n").unwrap(); + let mut out = String::new(); + s.read_to_string(&mut out).unwrap(); + out + }; + let health = get("/health"); + assert!(health.starts_with("HTTP/1.1 200 OK\r\n"), "{health}"); + assert!(health.ends_with("{\"ok\":true,\"hosts\":0,\"bridges\":0,\"registrations\":0,\"joins\":0,\"unknown\":0,\"rate_limited\":0,\"relayed_bytes\":0}")); + assert!(get("/whoami").contains("\"address\":\"127.0.0.1:")); + assert!(get("/").starts_with("HTTP/1.1 404")); +} diff --git a/docs/play-with-friends.md b/docs/play-with-friends.md new file mode 100644 index 000000000..6ea3449c8 --- /dev/null +++ b/docs/play-with-friends.md @@ -0,0 +1,259 @@ +# Play with friends (invite codes) + +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. + +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. + +``` + 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 └──────────────────┘ +``` + +## What vanilla has + +Vanilla 26.3 (read with `tools/rea_vanilla.py`) has two related things, and neither is this: + +- **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. + +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). + +## 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). + +## Codes + +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`. + +- 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. + +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"). + +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. + +## Encryption: SPAKE2, then ChaCha20-Poly1305 + +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): + +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. + +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). + +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). + +## Connecting: direct first, then the relay + +Every session starts through the relay, so the key exchange always has a path. Then: + +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. + +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. + +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. + +`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 + +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. + +| 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 | + +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`. + +After `bridged`, the stream is the session: the SPAKE2 messages, then the encrypted frames. + +## 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:///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. + +## 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`. From 74c1a9098025b0baac2e63225a9100de0de91771 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:23:47 +0200 Subject: [PATCH 21/97] Relay: hand out IPv4 clients' addresses as IPv4 A dual-stack listener reports them as ::ffff:a.b.c.d, which the other end can't dial from an IPv6-only socket. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-relay/src/lib.rs | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/crates/horizon-relay/src/lib.rs b/crates/horizon-relay/src/lib.rs index 48b9ac50e..958e8cd59 100644 --- a/crates/horizon-relay/src/lib.rs +++ b/crates/horizon-relay/src/lib.rs @@ -278,15 +278,29 @@ fn proxy_line(line: &[u8]) -> Option { } } -fn handle(state: &Arc, mut stream: TcpStream, mut peer: SocketAddr) -> io::Result<()> { +/// IPv4 clients of a dual-stack listener show up as `::ffff:a.b.c.d`: +/// their address as IPv4, which is what the other end can dial. +fn unmap(peer: SocketAddr) -> SocketAddr { + match peer { + SocketAddr::V6(v6) => match v6.ip().to_ipv4_mapped() { + Some(v4) => SocketAddr::new(v4.into(), v6.port()), + None => peer, + }, + v4 => v4, + } +} + +fn handle(state: &Arc, mut stream: TcpStream, peer: SocketAddr) -> io::Result<()> { if state.stop.load(Ordering::Relaxed) { return Ok(()); } + let mut peer = unmap(peer); stream.set_read_timeout(Some(state.config.first_line))?; let _ = stream.set_nodelay(true); let mut line = wire::read_line(&mut stream)?.ok_or(io::ErrorKind::UnexpectedEof)?; if state.config.proxy_protocol { peer = proxy_line(&line) + .map(unmap) .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidData, "no PROXY line"))?; line = wire::read_line(&mut stream)?.ok_or(io::ErrorKind::UnexpectedEof)?; } @@ -636,6 +650,16 @@ fn copy(state: &State, mut from: TcpStream, mut to: TcpStream) { mod tests { use super::*; + #[test] + fn mapped_addresses_become_ipv4() { + assert_eq!( + unmap("[::ffff:203.0.113.7]:5000".parse().unwrap()), + "203.0.113.7:5000".parse().unwrap() + ); + let v6: SocketAddr = "[2001:db8::1]:5000".parse().unwrap(); + assert_eq!(unmap(v6), v6); + } + #[test] fn proxy_lines() { assert_eq!( From de464a8fc0b147a8dd281d19c6f18e5532a07af2 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:31:36 +0200 Subject: [PATCH 22/97] 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 --- Cargo.lock | 11 + crates/horizon-friends/Cargo.toml | 2 + crates/horizon-friends/src/direct.rs | 92 +- crates/horizon-friends/src/guest.rs | 126 ++- crates/horizon-friends/src/host.rs | 413 ++++++--- crates/horizon-friends/src/invite.rs | 403 +++++++++ crates/horizon-friends/src/lib.rs | 25 +- crates/horizon-friends/src/portmap.rs | 980 +++++++++++++++++++++ crates/horizon-friends/src/reach.rs | 360 ++++++++ crates/horizon-friends/src/stun.rs | 207 +++++ crates/horizon-relay/Dockerfile | 2 +- crates/horizon-relay/horizon-relay.service | 24 + crates/horizon-relay/railway.toml | 13 - crates/horizon-relay/tests/tunnel.rs | 285 +++--- docs/play-with-friends.md | 400 ++++----- 15 files changed, 2809 insertions(+), 534 deletions(-) create mode 100644 crates/horizon-friends/src/invite.rs create mode 100644 crates/horizon-friends/src/portmap.rs create mode 100644 crates/horizon-friends/src/reach.rs create mode 100644 crates/horizon-friends/src/stun.rs create mode 100644 crates/horizon-relay/horizon-relay.service delete mode 100644 crates/horizon-relay/railway.toml diff --git a/Cargo.lock b/Cargo.lock index b72a657bb..18f4db44a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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" diff --git a/crates/horizon-friends/Cargo.toml b/crates/horizon-friends/Cargo.toml index 2d08a0bdd..afe5dbe62 100644 --- a/crates/horizon-friends/Cargo.toml +++ b/crates/horizon-friends/Cargo.toml @@ -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" diff --git a/crates/horizon-friends/src/direct.rs b/crates/horizon-friends/src/direct.rs index 86e155858..7c80822d5 100644 --- a/crates/horizon-friends/src/direct.rs +++ b/crates/horizon-friends/src/direct.rs @@ -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 { let s = Socket::new( @@ -85,47 +87,16 @@ pub fn connect_from(port: Option, 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 { - 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) -> Vec { - let mut targets: Vec = 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, observed: Option, ) -> Vec { - let mut out: Vec = local_addresses(relay) + let loopback = relay.is_some_and(|r| r.ip().is_loopback()); + let mut out: Vec = 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 { } 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 { + 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]; diff --git a/crates/horizon-friends/src/guest.rs b/crates/horizon-friends/src/guest.rs index a40361acc..4f64bb1cc 100644 --- a/crates/horizon-friends/src/guest.rs +++ b/crates/horizon-friends/src/guest.rs @@ -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, + /// 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 { - 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, 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 { + 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 { &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 { 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 diff --git a/crates/horizon-friends/src/host.rs b/crates/horizon-friends/src/host.rs index 567d8ff42..d7f4ae6c2 100644 --- a/crates/horizon-friends/src/host.rs +++ b/crates/horizon-friends/src/host.rs @@ -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, 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, + /// The relay's short code, when registered with one. + pub short: Option, + /// Who can join, and what to do when friends on the internet can't. + pub summary: String, + pub verdict: Option, + /// Why the relay isn't serving, when one is configured. + pub relay_problem: Option, + 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, events: Mutex>, - /// The current control connection (shut down to stop). + /// The invite (endpoints and secret), rebuilt when the relay part changes. + invite: Mutex>, + /// The current relay control connection (shut down to stop). control: Mutex>, - /// Inbound direct streams waiting for their session. + /// Inbound direct streams waiting for their relayed session. routes: Mutex, Instant)>>, - sessions: Mutex, + sessions: AtomicUsize, + handshakes: AtomicUsize, wrong: AtomicU32, + relay_wrong: AtomicU32, + reach: Mutex>, } 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) { + 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, events: Receiver, - thread: Option>, - accept: Option>, + threads: Vec>, } 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 { 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, shared: Arc) { +/// Find the addresses, publish the code, keep the router mapping alive, +/// serve the relay when there is one. +fn share(shared: Arc, 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, shared: Arc) { 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, shared: Arc) { } } -fn connect_relay(config: &HostConfig, port: Option) -> 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, mut s: TcpStream, session: u64) { + let secret = shared + .invite + .lock() + .unwrap() + .as_ref() + .map(Invite::secret_text); + let secured = (|| -> io::Result { + 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, 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) -> 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) -> io::Result<(TcpStrea } /// Register, serve the control connection, register again when it drops -/// (a new code) until stopped. -fn run(shared: Arc, port: Option) { +/// (a new short code) until stopped. +fn run_relay(shared: Arc, 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, port: Option) { } } -fn register(shared: &Arc, port: Option) -> io::Result<()> { +fn register(shared: &Arc, 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, port: Option) -> 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, port: Option) -> 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, port: Option) -> 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, port: Option) -> 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, + 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 }); } diff --git a/crates/horizon-friends/src/invite.rs b/crates/horizon-friends/src/invite.rs new file mode 100644 index 000000000..be586a57a --- /dev/null +++ b/crates/horizon-friends/src/invite.rs @@ -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, + pub relay: Option, +} +/// 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 { + 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> { + 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 { + 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, + relay: Option, + ) -> std::io::Result { + 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 { + 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::>() + .join("-") + } + fn decode(bytes: &[u8]) -> Result { + 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 { + 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 { + 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 = (0..n).map(|i| (i * 37 + 11) as u8).collect(); + let text = encode32(&bytes); + let symbols: Vec = 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 = 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::>().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")); + } +} diff --git a/crates/horizon-friends/src/lib.rs b/crates/horizon-friends/src/lib.rs index 9c86b10fa..ffc61721d 100644 --- a/crates/horizon-friends/src/lib.rs +++ b/crates/horizon-friends/src/lib.rs @@ -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 { - 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`. diff --git a/crates/horizon-friends/src/portmap.rs b/crates/horizon-friends/src/portmap.rs new file mode 100644 index 000000000..6ad9a2b94 --- /dev/null +++ b/crates/horizon-friends/src/portmap.rs @@ -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, + pub upnp: Vec, +} +impl Targets { + /// The default gateway's port 5351, and the IGDs answering SSDP. + pub fn discover(timeout: Duration) -> Self { + let mut pmp: Vec = 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::() + { + 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 { + 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 { + 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> { + 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 { + 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 `` (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(" Vec { + 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 { + 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 for UpnpError { + fn from(e: io::Error) -> Self { + Self::Io(e) + } +} +impl From 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 { + 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("").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 { + let mut body = format!( + "\n", + self.service + ); + for (k, v) in args { + body.push_str(&format!("<{k}>{v}")); + } + body.push_str(&format!("")); + 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 { + 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 { + #[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 { + 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 { + text.lines().find_map(|l| { + l.trim() + .strip_prefix("gateway:") + .and_then(|g| g.trim().parse().ok()) + }) +} +pub fn windows_gateway(text: &str) -> Option { + 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>>; + + /// 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>>) { + let l = TcpListener::bind("127.0.0.1:0").unwrap(); + let port = l.local_addr().unwrap().port(); + let table: Arc>> = 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, "urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1/wrongurn:schemas-upnp-org:service:WANIPConnection:1/ctl".to_owned()) + } else if text.contains("#GetExternalIPAddress") { + (200, "198.51.100.8".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, "725".to_owned()) + } else if ext == taken { + (500, "718".to_owned()) + } else { + t.lock().unwrap().insert(ext, (int, client, lease)); + (200, "".to_owned()) + } + } else if text.contains("#DeletePortMapping") { + let ext: u16 = tag(&text, "NewExternalPort").unwrap().parse().unwrap(); + t.lock().unwrap().remove(&ext); + (200, "".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(" v ", "Name"), + Some("v") + ); + } +} diff --git a/crates/horizon-friends/src/reach.rs b/crates/horizon-friends/src/reach.rs new file mode 100644 index 000000000..12550a59f --- /dev/null +++ b/crates/horizon-friends/src/reach.rs @@ -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, + /// 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, + pub mapping: Option, + pub mapping_error: Option, + pub public_ip: Option, +} + +#[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 { + 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 { + 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 { + 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 { + 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::().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::().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::().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::().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))); + } +} diff --git a/crates/horizon-friends/src/stun.rs b/crates/horizon-friends/src/stun.rs new file mode 100644 index 000000000..e1716d268 --- /dev/null +++ b/crates/horizon-friends/src/stun.rs @@ -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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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::::new()); + assert_eq!(parse_servers(" a:1 , b:2,"), vec!["a:1", "b:2"]); + } +} diff --git a/crates/horizon-relay/Dockerfile b/crates/horizon-relay/Dockerfile index 7cae743e4..8f41b4ea3 100644 --- a/crates/horizon-relay/Dockerfile +++ b/crates/horizon-relay/Dockerfile @@ -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 diff --git a/crates/horizon-relay/horizon-relay.service b/crates/horizon-relay/horizon-relay.service new file mode 100644 index 000000000..dc67babdd --- /dev/null +++ b/crates/horizon-relay/horizon-relay.service @@ -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 diff --git a/crates/horizon-relay/railway.toml b/crates/horizon-relay/railway.toml deleted file mode 100644 index b6916e4d4..000000000 --- a/crates/horizon-relay/railway.toml +++ /dev/null @@ -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 diff --git a/crates/horizon-relay/tests/tunnel.rs b/crates/horizon-relay/tests/tunnel.rs index d988edb88..99c3eb663 100644 --- a/crates/horizon-relay/tests/tunnel.rs +++ b/crates/horizon-relay/tests/tunnel.rs @@ -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> = const { std::cell::RefCell::new(Vec::new()) }; + static BACKLOG: RefCell> = const { RefCell::new(Vec::new()) }; } /// The first event (in order) that `f` picks; the others stay queued. @@ -83,10 +89,25 @@ fn wait_event(host: &Host, mut f: impl FnMut(&HostEvent) -> Option) -> T { panic!("no such host event"); } -fn join(relay: &str, code: &Code, path: PathMode) -> Result { +/// The invite once ready (and, with a relay, once it holds the short code). +fn invite_of(host: &Host, with_relay: bool) -> (String, Option) { + 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::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 { (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. diff --git a/docs/play-with-friends.md b/docs/play-with-friends.md index 6ea3449c8..08f1ace8d 100644 --- a/docs/play-with-friends.md +++ b/docs/play-with-friends.md @@ -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://
:7000/health` from outside, and give friends `
: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:///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). From 5189a735c71c2c6e461172530cce8fac2a4e5e8e Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:42:02 +0200 Subject: [PATCH 23/97] Invite codes: one address per LAN, no unique-local IPv6, the macOS firewall prompt in the docs Co-Authored-By: Claude Opus 5.5 --- crates/horizon-friends/src/reach.rs | 29 +++++++++++++++-------------- docs/play-with-friends.md | 3 ++- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/crates/horizon-friends/src/reach.rs b/crates/horizon-friends/src/reach.rs index 12550a59f..49e447466 100644 --- a/crates/horizon-friends/src/reach.rs +++ b/crates/horizon-friends/src/reach.rs @@ -64,8 +64,8 @@ fn virtual_interface(name: &str) -> bool { } /// 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. +/// LAN), shared IPv4 (Tailscale's 100.64/10, CGNAT), other IPv4, one global +/// IPv6. No link-local or unique-local; loopback on request. pub fn interface_addresses(loopback: bool) -> Vec { let mut found: Vec<(u8, IpAddr)> = Vec::new(); for i in if_addrs::get_if_addrs().unwrap_or_default() { @@ -88,8 +88,8 @@ pub fn interface_addresses(loopback: bool) -> Vec { 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, + // fc00::/7: VPNs that use it (Tailscale) also give an IPv4 address. + IpAddr::V6(v6) if v6.segments()[0] & 0xfe00 == 0xfc00 => continue, IpAddr::V6(_) => 3, }; if !found.iter().any(|(_, a)| *a == ip) { @@ -97,17 +97,18 @@ pub fn interface_addresses(loopback: bool) -> Vec { } } 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); + // One global IPv6 address is enough (temporary addresses multiply + // them), and one address per /24 (Wi-Fi and Ethernet on the same LAN). + let mut out: Vec = Vec::new(); + for (_, ip) in found { + let same = out.iter().any(|o| match (o, ip) { + (IpAddr::V6(_), IpAddr::V6(_)) => true, + (IpAddr::V4(a), IpAddr::V4(b)) => a.octets()[..3] == b.octets()[..3], + _ => false, + }); + if !same { + out.push(ip); } - out.push(ip); } out } diff --git a/docs/play-with-friends.md b/docs/play-with-friends.md index 08f1ace8d..eae5082da 100644 --- a/docs/play-with-friends.md +++ b/docs/play-with-friends.md @@ -192,7 +192,8 @@ host's version), `host_unreachable`, `full`, `rate_limited`, `bad_request`. 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. + networks (Windows asks the first time; on macOS answer "Allow" when asked whether Horizon may accept + incoming network connections). - **"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. From 61b0aafbf8c3ace061daad2901573301f29a9542 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:42:31 +0200 Subject: [PATCH 24/97] Relay: no hosting platform in its comments Co-Authored-By: Claude Opus 5.5 --- crates/horizon-relay/src/main.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/crates/horizon-relay/src/main.rs b/crates/horizon-relay/src/main.rs index f14bdfe05..600abade5 100644 --- a/crates/horizon-relay/src/main.rs +++ b/crates/horizon-relay/src/main.rs @@ -9,8 +9,7 @@ fn main() { .ok() .and_then(|p| p.trim().parse().ok()) .unwrap_or(7000); - // Dual-stack where the system allows it (Railway's private network is - // IPv6), else IPv4. + // Dual-stack where the system allows it, else IPv4. let listener = TcpListener::bind(("::", port)) .or_else(|_| TcpListener::bind(("0.0.0.0", port))) .unwrap_or_else(|e| { From dbc85822c1654ab7f1b47be329e22e1dcc2c07ec Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 03:07:02 +0200 Subject: [PATCH 25/97] Battery mode: a one-line description Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/graphics_ui.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/horizon-client/src/graphics_ui.rs b/crates/horizon-client/src/graphics_ui.rs index 0f9ac56a7..d8196f478 100644 --- a/crates/horizon-client/src/graphics_ui.rs +++ b/crates/horizon-client/src/graphics_ui.rs @@ -223,7 +223,7 @@ pub fn rows(level: Level) -> Vec { h( H::BatteryMode, None, - "At most 60 FPS (30 in menus or behind other windows), half the worker threads: less power, slower loading.", + "60 FPS cap (30 in menus or unfocused), half the workers: less power.", ), h( H::Workers, From 5d29f316638e66bb77b62ea82164611fe381e94d Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:46:00 +0200 Subject: [PATCH 26/97] Play with friends: Join a friend in game and in the launcher The game joins `friend:CODE` addresses: the network thread resolves the code through the relay, agrees on the key, settles on a direct or relayed stream and connects the client to the tunnel's loopback port; everything after is an ordinary join. Errors (unknown or ended code, wrong secret, host not answering, version mismatch, rate limits) end on the Disconnected screen in plain words. Shown and logged addresses hide the code's secret half. Horizon's multiplayer page gains "Join a friend" (a code field); the classic screens keep vanilla's buttons. The launcher's Play page gains a "Join a friend" row (paste works) that starts the game straight into the join; `horizon-launcher play --join CODE` does the same. tools/test_friends.py runs a relay, a host Horizon sharing a world and a guest Horizon, over plain LAN (--baseline), the direct path and the forced relay path: chat, movement and blocks both ways, then the ended invite. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/front.rs | 47 ++++ crates/horizon-client/src/game/extras.rs | 2 +- crates/horizon-client/src/game/remote.rs | 17 +- crates/horizon-client/src/multiplayer.rs | 46 +++- crates/horizon-client/src/net.rs | 60 ++++- crates/horizon-friends/Cargo.toml | 5 +- crates/horizon-friends/src/lib.rs | 5 + launcher/Cargo.lock | 140 +++++++++- launcher/Cargo.toml | 2 + launcher/src/backend.rs | 9 + launcher/src/cli.rs | 13 +- launcher/src/main.rs | 121 ++++++++- tools/test_friends.py | 327 +++++++++++++++++++++++ 13 files changed, 770 insertions(+), 24 deletions(-) create mode 100644 tools/test_friends.py diff --git a/crates/horizon-client/src/front.rs b/crates/horizon-client/src/front.rs index cc6237ead..75e6547e1 100644 --- a/crates/horizon-client/src/front.rs +++ b/crates/horizon-client/src/front.rs @@ -33,6 +33,7 @@ const MAKE: u64 = id("create.make", 0); const SERVER: u64 = id("mp.row", 0); const JOIN: u64 = id("mp.join", 0); const DIRECT: u64 = id("mp.direct", 0); +const FRIEND: u64 = id("mp.friend", 0); const ADD: u64 = id("mp.add", 0); const EDIT: u64 = id("mp.edit", 0); const DELETE: u64 = id("mp.delete", 0); @@ -435,6 +436,7 @@ impl Title { let id = match hit { JOIN => Some(40), DIRECT => Some(41), + FRIEND => Some(47), ADD => Some(42), EDIT => Some(43), DELETE => Some(44), @@ -443,11 +445,13 @@ impl Title { Screen::List { .. } => 46, Screen::Edit { .. } => 51, Screen::Direct { .. } => 53, + Screen::Friend { .. } => 57, Screen::Disconnected { .. } => 54, }), CANCEL_RETRY => Some(55), DONE => Some(match screen { Screen::Direct { .. } => 52, + Screen::Friend { .. } => 56, _ => 50, }), FIELD_A | FIELD_B => { @@ -803,6 +807,7 @@ fn multiplayer_page(ui: &mut Ui, x: f32, w: f32, screen: &Screen, caret: bool) { let saved = selected.is_some_and(|i| i < servers.len()); let mut items = vec![ (JOIN, "Join", Kind::Primary, has), + (FRIEND, "Join a friend", Kind::Secondary, true), (ADD, "Add server", Kind::Secondary, true), (DIRECT, "Direct connect", Kind::Secondary, true), (REFRESH, "Refresh", Kind::Ghost, true), @@ -955,6 +960,48 @@ fn multiplayer_page(ui: &mut Ui, x: f32, w: f32, screen: &Screen, caret: bool) { ); ui.divider(x, y + rh, w); } + Screen::Friend { code } => { + let y = header( + ui, + x, + "Join a friend", + "Paste the invite code your friend sees in their pause menu.", + ); + let available = horizon_friends::relay_url().is_some(); + let ok = available && horizon_friends::Code::parse(code).is_some(); + actions_right( + ui, + x + w, + y - 24.0 - 58.0, + &[ + (DONE, "Join", Kind::Primary, ok), + (BACK, "Cancel", Kind::Ghost, true), + ], + ); + ui.divider(x, y, w); + let rh = 12.0 + CONTROL + 12.0; + ui.text_line(Face::Regular, BODY, rh, x, y, color::MUTED, "Invite code"); + let fx = x + t::ROW_LABEL + 16.0; + ui.field( + FIELD_A, + [fx, y + 12.0, (w - t::ROW_LABEL - 16.0).min(240.0), CONTROL], + code, + "K7QM-3XPD", + true, + caret, + ); + ui.divider(x, y + rh, w); + if !available { + ui.text( + Face::Regular, + SMALL, + x, + y + rh + 12.0, + color::FAINT, + "Joining friends isn't available yet in this build.", + ); + } + } Screen::Disconnected { reason, retry } => { let mut y = header( ui, diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs index b934f8279..9fd42d5ff 100644 --- a/crates/horizon-client/src/game/extras.rs +++ b/crates/horizon-client/src/game/extras.rs @@ -123,7 +123,7 @@ impl Game<'_> { { log::info!( "Horizon: reconnecting to {} in {} s", - retry.address, + horizon_client::net::shown_address(&retry.address), retry.seconds_left(std::time::Instant::now()) ); *slot = Some(retry); diff --git a/crates/horizon-client/src/game/remote.rs b/crates/horizon-client/src/game/remote.rs index 24a2d0e3a..ad624d67e 100644 --- a/crates/horizon-client/src/game/remote.rs +++ b/crates/horizon-client/src/game/remote.rs @@ -158,7 +158,7 @@ impl Game<'_> { .ok_or("registries.json not found next to the resources; run the data generator reports (horizon-prepare)")?; let lang = Arc::new(horizon_client::net::load_language(&root)); let view = self.settings.render_distance.clamp(2, 32) as i8; - horizon_client::crash::set_detail("Server", address.to_owned()); + horizon_client::crash::set_detail("Server", horizon_client::net::shown_address(address)); // A signed-in account always plays under its own name. let auth = horizon_client::auth::current(); let name = auth.as_ref().map_or(name, |a| a.name.as_str()); @@ -2597,10 +2597,8 @@ impl Game<'_> { let atlas = &self.res.atlas; let (w, h) = (batch.width, batch.height); batch.fill(atlas, 0.0, 0.0, w, h, rgba(20, 20, 20, 255)); - for (i, line) in [r.status.as_str(), r.session.address.as_str()] - .iter() - .enumerate() - { + let shown = horizon_client::net::shown_address(&r.session.address); + for (i, line) in [r.status.as_str(), shown.as_str()].iter().enumerate() { let tw = HudBatch::text_width(atlas, line); batch.text( atlas, @@ -2682,7 +2680,7 @@ impl Game<'_> { pub(super) fn remote_status(&self) -> Option { let r = self.remote.as_ref()?; Some(serde_json::json!({ - "address": r.session.address, + "address": horizon_client::net::shown_address(&r.session.address), "name": r.session.name, "joined": r.joined, "status": r.status, @@ -2695,6 +2693,13 @@ impl Game<'_> { m }), "players": r.players.values().collect::>(), + // Where the other players' entities are (harnesses check movement). + "player_positions": r + .entities + .values() + .filter(|t| t.kind == "minecraft:player") + .map(|t| t.position) + .collect::>(), "health": r.health.0, "food": r.health.1, "decode_errors": r.decode_errors, diff --git a/crates/horizon-client/src/multiplayer.rs b/crates/horizon-client/src/multiplayer.rs index be1ddf2b2..0c4019568 100644 --- a/crates/horizon-client/src/multiplayer.rs +++ b/crates/horizon-client/src/multiplayer.rs @@ -45,6 +45,11 @@ pub enum Screen { Direct { address: String, }, + /// Join a friend's world with its invite code (Horizon's own, reached + /// from Horizon's multiplayer page). + Friend { + code: String, + }, Disconnected { reason: String, /// Auto-reconnect's next attempt, until it is cancelled. @@ -207,6 +212,24 @@ impl Screen { 53, ), ], + Self::Friend { code } => vec![ + b( + w / 2.0 - 100.0, + h / 4.0 + 96.0 + 12.0, + 200.0, + "Join", + horizon_friends::Code::parse(code).is_some(), + 56, + ), + b( + w / 2.0 - 100.0, + h / 4.0 + 120.0 + 12.0, + 200.0, + "Cancel", + true, + 57, + ), + ], Self::Disconnected { retry, .. } => { let mut v = vec![b( w / 2.0 - 100.0, @@ -442,6 +465,10 @@ impl Screen { blink, ); } + Self::Friend { code } => { + centered(batch, "Join a Friend", 20.0, u32::MAX); + Self::field(atlas, batch, "Invite Code", code, 100.0 - 11.0, true, blink); + } Self::Disconnected { reason, retry } => { centered( batch, @@ -487,6 +514,11 @@ impl Screen { address: String::new(), } } + (Self::List { .. }, Some(47)) => { + *self = Self::Friend { + code: String::new(), + } + } (Self::List { .. }, Some(42)) => { *self = Self::Edit { index: None, @@ -568,13 +600,21 @@ impl Screen { *self = Self::list(saves); } ( - Self::Edit { .. } | Self::Direct { .. } | Self::Disconnected { .. }, - Some(51 | 53 | 54), + Self::Edit { .. } + | Self::Direct { .. } + | Self::Friend { .. } + | Self::Disconnected { .. }, + Some(51 | 53 | 54 | 57), ) => *self = Self::list(saves), (Self::Disconnected { retry, .. }, Some(55)) => *retry = None, (Self::Direct { address }, Some(52)) => { return Outcome::Connect(address.trim().to_owned()); } + (Self::Friend { code }, Some(56)) => { + if let Some(code) = horizon_friends::Code::parse(code) { + return Outcome::Connect(format!("{}{code}", crate::net::FRIEND)); + } + } (Self::Edit { focus, .. }, None) => { for (i, fy) in [(0u8, 53.0 + 11.0), (1, 94.0 + 11.0)] { if y >= fy && y < fy + 20.0 && (x - w / 2.0).abs() < 100.0 { @@ -595,6 +635,7 @@ impl Screen { .. } => Some(if *focus == 0 { name } else { address }), Self::Direct { address } => Some(address), + Self::Friend { code } => Some(code), _ => None, } } @@ -614,6 +655,7 @@ impl Screen { Self::Edit { focus: 0, .. } => ("server.name", 0), Self::Edit { .. } => ("server.address", 0), Self::Direct { .. } => ("server.direct", 0), + Self::Friend { .. } => ("friend.code", 0), _ => return None, }; self.focused_field().map(|f| (id, f, 128)) diff --git a/crates/horizon-client/src/net.rs b/crates/horizon-client/src/net.rs index ef1938ead..8af10f66a 100644 --- a/crates/horizon-client/src/net.rs +++ b/crates/horizon-client/src/net.rs @@ -145,6 +145,54 @@ impl Drop for Session { } } +/// An address of the form `friend:K7QM-3XPD` joins a friend's world through +/// its invite code (horizon-friends): the session goes through a tunnel the +/// client reaches on a loopback port, so everything after is a plain join. +pub const FRIEND: &str = horizon_friends::ADDRESS_PREFIX; + +/// An address as players and logs see it: a friend's invite code without +/// its secret half. +pub fn shown_address(address: &str) -> String { + match address.strip_prefix(FRIEND) { + Some(code) => match horizon_friends::Code::parse(code) { + Some(code) => format!("Friend's world ({}-****)", code.nameplate), + None => "Friend's world".to_owned(), + }, + None => address.to_owned(), + } +} + +/// Find the friend's world behind the code and open the tunnel: the loopback +/// address to connect to. +fn join_friend(code: &str, send: &Sender) -> Result<(String, u16), String> { + use horizon_friends::{ + Code, JoinError, PathMode, + guest::{self, GuestConfig}, + }; + let code = Code::parse(code) + .ok_or("That isn't an invite code: codes are eight letters and digits, like K7QM-3XPD.")?; + let relay = horizon_friends::relay_url().ok_or_else(|| JoinError::NotAvailable.to_string())?; + status(send, "Finding your friend's world..."); + let tunnel = guest::join(&GuestConfig { + relay, + code, + protocol: PROTOCOL_VERSION, + game: horizon_protocol::GAME_VERSION.to_owned(), + path: PathMode::from_env(), + }) + .map_err(|e| e.to_string())?; + status( + send, + if tunnel.direct { + "Connected straight to your friend..." + } else { + "Connected to your friend through the relay..." + }, + ); + let (port, _) = tunnel.serve_loopback().map_err(|e| e.to_string())?; + Ok(("127.0.0.1".to_owned(), port)) +} + fn status(send: &Sender, text: &str) { let _ = send.send(Event::Status(text.to_owned())); } @@ -169,10 +217,16 @@ fn run( shared_writer: &Mutex>, shared_counters: &Mutex>>, ) -> Result { - let Some((host, port)) = parse_address(address) else { - return Ok(format!("Invalid server address: {address}")); + let (host, port) = match address.strip_prefix(FRIEND) { + Some(code) => join_friend(code, send)?, + None => { + let Some(target) = parse_address(address) else { + return Ok(format!("Invalid server address: {address}")); + }; + status(send, "Connecting to the server..."); + target + } }; - status(send, "Connecting to the server..."); let mut c = Connection::connect(&host, port, Duration::from_secs(10)).map_err(|e| e.to_string())?; *shared_counters.lock().unwrap() = Some(c.reader.counters.clone()); diff --git a/crates/horizon-friends/Cargo.toml b/crates/horizon-friends/Cargo.toml index afe5dbe62..d53b9435f 100644 --- a/crates/horizon-friends/Cargo.toml +++ b/crates/horizon-friends/Cargo.toml @@ -1,9 +1,8 @@ [package] name = "horizon-friends" version = "0.1.0" -edition.workspace = true -license.workspace = true -rust-version.workspace = true +edition = "2024" +license = "MIT" description = "Play with friends: invite codes, the relay protocol, the end-to-end encrypted tunnel between a host's integrated server and its guests" [dependencies] diff --git a/crates/horizon-friends/src/lib.rs b/crates/horizon-friends/src/lib.rs index ac0e037ab..0a0c2d10c 100644 --- a/crates/horizon-friends/src/lib.rs +++ b/crates/horizon-friends/src/lib.rs @@ -32,6 +32,11 @@ use std::{ time::Duration, }; +/// The game's server address for a friend's world: `friend:K7QM-3XPD` +/// (`horizon-client --server friend:…`, what the launcher's Join a friend +/// starts). +pub const ADDRESS_PREFIX: &str = "friend:"; + /// Fill `buf` from the OS random generator. pub(crate) fn fill_random(buf: &mut [u8]) -> io::Result<()> { getrandom::fill(buf).map_err(|e| io::Error::other(e.to_string())) diff --git a/launcher/Cargo.lock b/launcher/Cargo.lock index 893272f99..262ee3628 100644 --- a/launcher/Cargo.lock +++ b/launcher/Cargo.lock @@ -8,6 +8,16 @@ version = "2.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" +[[package]] +name = "aead" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0" +dependencies = [ + "crypto-common 0.1.7", + "generic-array", +] + [[package]] name = "aes" version = "0.8.4" @@ -859,6 +869,17 @@ dependencies = [ "libc", ] +[[package]] +name = "chacha20" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3613f74bd2eac03dad61bd53dbe620703d4371614fe0bc3b9f04dd36fe4e818" +dependencies = [ + "cfg-if", + "cipher", + "cpufeatures 0.2.17", +] + [[package]] name = "chacha20" version = "0.10.2" @@ -870,6 +891,19 @@ dependencies = [ "rand_core 0.10.1", ] +[[package]] +name = "chacha20poly1305" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10cd79432192d1c0f4e1a0fef9527696cc039165d729fb41b3f4f4f354c2dc35" +dependencies = [ + "aead", + "chacha20 0.9.1", + "cipher", + "poly1305", + "zeroize", +] + [[package]] name = "cipher" version = "0.4.4" @@ -1351,6 +1385,32 @@ version = "0.0.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e2931af7e13dc045d8e9d26afccc6fa115d64e115c9c84b1166288b46f6782c2" +[[package]] +name = "curve25519-dalek" +version = "4.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "97fb8b7c4503de7d6ae7b42ab72a5a59857b4c937ec27a3d4539dba95b5ab2be" +dependencies = [ + "cfg-if", + "cpufeatures 0.2.17", + "curve25519-dalek-derive", + "fiat-crypto", + "rand_core 0.6.4", + "rustc_version", + "subtle", +] + +[[package]] +name = "curve25519-dalek-derive" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f46882e17999c6cc590af592290432be3bce0428cb0d5f8b6715e4dc7b383eb3" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "data-url" version = "0.3.2" @@ -1731,6 +1791,12 @@ dependencies = [ "simd-adler32", ] +[[package]] +name = "fiat-crypto" +version = "0.2.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d" + [[package]] name = "filedescriptor" version = "0.8.3" @@ -2563,6 +2629,20 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "horizon-friends" +version = "0.1.0" +dependencies = [ + "chacha20poly1305", + "getrandom 0.3.4", + "hkdf", + "serde", + "serde_json", + "sha2 0.10.9", + "socket2 0.5.10", + "spake2", +] + [[package]] name = "horizon-launcher" version = "0.1.5" @@ -2573,6 +2653,7 @@ dependencies = [ "futures-lite 2.6.1", "getrandom 0.3.4", "gpui", + "horizon-friends", "horizon-prepare", "horizon-theme", "keyring", @@ -2701,7 +2782,7 @@ dependencies = [ "hyper", "libc", "pin-project-lite", - "socket2", + "socket2 0.6.5", "tokio", "tower-service", "tracing", @@ -3766,6 +3847,12 @@ dependencies = [ "zvariant", ] +[[package]] +name = "opaque-debug" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381" + [[package]] name = "open" version = "5.4.4" @@ -3975,6 +4062,17 @@ version = "0.2.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5da3b0203fd7ee5720aa0b5e790b591aa5d3f41c3ed2c34a3a393382198af2f7" +[[package]] +name = "poly1305" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8159bd90725d2df49889a078b54f4f79e87f1f8a8444194cdca81d38f5393abf" +dependencies = [ + "cpufeatures 0.2.17", + "opaque-debug", + "universal-hash", +] + [[package]] name = "postage" version = "0.5.0" @@ -4166,7 +4264,7 @@ dependencies = [ "quinn-udp", "rustc-hash 2.1.3", "rustls", - "socket2", + "socket2 0.6.5", "thiserror 2.0.21", "tokio", "tracing", @@ -4204,7 +4302,7 @@ dependencies = [ "cfg_aliases", "libc", "once_cell", - "socket2", + "socket2 0.6.5", "tracing", "windows-sys 0.61.2", ] @@ -4257,7 +4355,7 @@ version = "0.10.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "65c9fb96cbc91e3478eaae79a69fcd3f1ae4ad052e471fe6732fff548984b4af" dependencies = [ - "chacha20", + "chacha20 0.10.2", "getrandom 0.4.3", "rand_core 0.10.1", ] @@ -5157,6 +5255,16 @@ version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "dd538fb6910ac1099850255cf94a94df6551fbdd602454387d0adb2d1ca6dead" +[[package]] +name = "socket2" +version = "0.5.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e22376abed350d73dd1cd119b57ffccad95b4e585a7cda43e286245ce23c0678" +dependencies = [ + "libc", + "windows-sys 0.52.0", +] + [[package]] name = "socket2" version = "0.6.5" @@ -5167,6 +5275,18 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "spake2" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c5482afe85a0b6ce956c945401598dbc527593c77ba51d0a87a586938b1b893a" +dependencies = [ + "curve25519-dalek", + "hkdf", + "rand_core 0.6.4", + "sha2 0.10.9", +] + [[package]] name = "spin" version = "0.9.9" @@ -5686,7 +5806,7 @@ dependencies = [ "libc", "mio", "pin-project-lite", - "socket2", + "socket2 0.6.5", "windows-sys 0.61.2", ] @@ -6004,6 +6124,16 @@ version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254" +[[package]] +name = "universal-hash" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea" +dependencies = [ + "crypto-common 0.1.7", + "subtle", +] + [[package]] name = "untrusted" version = "0.9.0" diff --git a/launcher/Cargo.toml b/launcher/Cargo.toml index 267b6707e..f2c24f429 100644 --- a/launcher/Cargo.toml +++ b/launcher/Cargo.toml @@ -21,6 +21,8 @@ self-replace = "1" clap = { version = "4", features = ["derive"] } horizon-theme = { path = "../crates/horizon-theme" } horizon-prepare = { path = "../crates/horizon-prepare" } +# Join a friend: invite codes (the game does the joining). +horizon-friends = { path = "../crates/horizon-friends" } # The session file's random name. getrandom = "0.3" diff --git a/launcher/src/backend.rs b/launcher/src/backend.rs index b695b4ae2..08c679a88 100644 --- a/launcher/src/backend.rs +++ b/launcher/src/backend.rs @@ -1055,6 +1055,15 @@ pub fn client(tag: &str) -> Result { Ok(cmd) } +/// Start the game straight into a friend's world: `--server friend:CODE`. +pub fn join_friend(cmd: &mut Command, code: &str) -> Result<(), String> { + let code = horizon_friends::Code::parse(code) + .ok_or("That isn't an invite code: codes are eight letters and digits, like K7QM-3XPD.")?; + cmd.arg("--server") + .arg(format!("{}{code}", horizon_friends::ADDRESS_PREFIX)); + Ok(()) +} + /// The dedicated server's command in `folder`, once prepared and the EULA is agreed to. pub fn server(tag: &str, folder: &Path, accept_eula: bool) -> Result { need_prepared(tag)?; diff --git a/launcher/src/cli.rs b/launcher/src/cli.rs index 095d25c4a..600b6eaf8 100644 --- a/launcher/src/cli.rs +++ b/launcher/src/cli.rs @@ -63,6 +63,9 @@ enum Cmd { Play { #[arg(long)] version: Option, + /// Join a friend's world with its invite code + #[arg(long)] + join: Option, }, /// Run a dedicated server here; type commands into its console Server { @@ -255,9 +258,13 @@ fn execute(command: Cmd, as_json: bool) -> Result<(), String> { } println!("{tag} is prepared."); } - Cmd::Play { version } => attached(backend::client(&backend::resolve_version( - version.as_deref(), - )?)?)?, + Cmd::Play { version, join } => { + let mut cmd = backend::client(&backend::resolve_version(version.as_deref())?)?; + if let Some(code) = join { + backend::join_friend(&mut cmd, &code)?; + } + attached(cmd)? + } Cmd::Server { dir, version, diff --git a/launcher/src/main.rs b/launcher/src/main.rs index dc7ffd7a0..6ee37b95c 100644 --- a/launcher/src/main.rs +++ b/launcher/src/main.rs @@ -138,6 +138,12 @@ struct Launcher { input: String, input_focused: bool, focus: FocusHandle, + /// Join a friend: the code typed on the Play page, and the one the game + /// starting now joins. + friend_code: String, + friend_focused: bool, + friend_focus: FocusHandle, + joining: Option, console_scroll: ScrollHandle, tx: Sender, rx: Receiver, @@ -233,6 +239,10 @@ impl Launcher { input: String::new(), input_focused: false, focus: cx.focus_handle(), + friend_code: String::new(), + friend_focused: false, + friend_focus: cx.focus_handle(), + joining: None, console_scroll: ScrollHandle::new(), tx, rx, @@ -358,6 +368,11 @@ impl Launcher { Err(e) => self.client_error = Some(format!("Playing offline: {e}")), } self.accounts = Accounts::load(); + if let Some(code) = self.joining.take() { + if let Err(e) = backend::join_friend(&mut cmd, &code) { + self.client_error = Some(e); + } + } match backend::spawn(Job::Client, cmd, self.tx.clone()) { Ok(r) => self.client = Some(r), Err(e) => self.client_error = Some(e), @@ -1404,8 +1419,9 @@ impl Launcher { Some(a) => format!("{} (Microsoft account)", a.name), None => "Offline: online servers need a Microsoft account.".to_string(), }; + rows = rows.child(self.join_friend_row(prepared && !running, cx)); rows = rows.child(index_row( - 3, + 4, "Playing as", Some(div().child(who).into_any_element()), Some( @@ -2120,6 +2136,108 @@ impl Launcher { (rows, n) } + /// Join a friend: a code field and Join, which starts the game straight + /// into the friend's world (errors show in the game). + fn join_friend_row(&self, can_play: bool, cx: &mut Context) -> Div { + let t = self.theme; + let focused = self.friend_focused; + let field = div() + .id("friend-code") + .track_focus(&self.friend_focus) + .flex() + .items_center() + .w(px(260.)) + .h(px(30.)) + .px(px(12.)) + .overflow_hidden() + .rounded(px(6.)) + .border_1() + .border_color(if focused { t.accent } else { t.rule }) + .bg(t.surface) + .font_family(theme::MONO) + .text_size(px(12.)) + .cursor_text() + .child(if self.friend_code.is_empty() && !focused { + div().text_color(t.muted).child("Paste an invite code") + } else { + // The end of a long code stays in view while typing. + let shown: String = { + let chars: Vec = self.friend_code.chars().collect(); + chars[chars.len().saturating_sub(30)..].iter().collect() + }; + div().text_color(t.ink).child(shown) + }) + .when(focused, |d| d.child(div().w(px(1.)).h(px(14.)).bg(t.ink))) + .on_click(cx.listener(|this, _: &ClickEvent, window, cx| { + window.focus(&this.friend_focus); + cx.notify(); + })) + .on_key_down(cx.listener(|this, ev: &KeyDownEvent, _, cx| { + let k = &ev.keystroke; + let paste = k.key == "v" && (k.modifiers.control || k.modifiers.platform); + match k.key.as_str() { + "enter" => this.join_friend(), + "backspace" => { + this.friend_code.pop(); + } + _ if paste => { + if let Some(text) = cx.read_from_clipboard().and_then(|c| c.text()) { + this.friend_code.push_str(text.trim()); + } + } + _ if !k.modifiers.control && !k.modifiers.platform => { + if let Some(ch) = &k.key_char { + this.friend_code.push_str(ch); + } + } + _ => return, + } + this.friend_code.truncate(256); + cx.stop_propagation(); + cx.notify(); + })); + let valid = horizon_friends::invite::parse(&self.friend_code).is_some(); + let mut join = button("join-friend", "Join", Kind::Secondary, &t); + if can_play && valid { + join = join.on_click(cx.listener(|this, _: &ClickEvent, _, cx| { + this.join_friend(); + cx.notify(); + })); + } else { + join = disabled(join); + } + index_row( + 3, + "Join a friend", + Some( + div() + .child("Paste the code a friend shows when they invite you.") + .into_any_element(), + ), + Some( + div() + .flex() + .items_center() + .gap(px(8.)) + .child(field) + .child(join) + .into_any_element(), + ), + &t, + ) + } + + fn join_friend(&mut self) { + if self.mode != Mode::Client || horizon_friends::invite::parse(&self.friend_code).is_none() { + return; + } + self.joining = Some(self.friend_code.clone()); + self.play(); + if self.starting_client.is_none() { + self.joining = None; + } + } + fn console(&self, cx: &mut Context) -> Div { let t = self.theme; let running = self.server.is_some(); @@ -2585,6 +2703,7 @@ impl Render for Launcher { fn render(&mut self, window: &mut Window, cx: &mut Context) -> impl IntoElement { let t = self.theme; self.input_focused = self.focus.is_focused(window); + self.friend_focused = self.friend_focus.is_focused(window); let content = match self.page { Page::Play => self.play_page(cx), Page::Versions => self.versions_page(cx), diff --git a/tools/test_friends.py b/tools/test_friends.py new file mode 100644 index 000000000..482aea2de --- /dev/null +++ b/tools/test_friends.py @@ -0,0 +1,327 @@ +#!/usr/bin/env python3 +"""Play with friends end to end, without the internet. + +A relay (`horizon-relay`) on a free local port; a host Horizon that opens a +world and shares it behind an invite code (`friends host`); a guest Horizon +that joins with the code (`connect friend:CODE`). The guest joins twice: +first on the direct path, then started with HORIZON_FRIENDS_PATH=relay so +the session goes through the relay. Each time both sides must see the +other's chat line, the other moving, a block the host places and the block +the guest breaks; the host's counts say which path each session took, and +the relay's relayed bytes must stay small for the direct session and grow +with the relayed one. Last, the host stops sharing and a guest using the +old code is told the invite has ended. + + python3 tools/test_friends.py --client target/fast/horizon-client --relay target/fast/horizon-relay + +`--relay-url HOST:PORT` uses a relay already running elsewhere (two +machines); `--role host|guest` then runs one side only and prints or takes +the code (`--code`). Needs a display on Linux (xvfb-run -a). +""" +import argparse +import json +import math +import os +from pathlib import Path +import socket +import subprocess +import tempfile +import time +import urllib.request + +ROOT = Path(__file__).resolve().parents[1] + + +def command(endpoint, line, check=True): + with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection: + connection.settimeout(60) + connection.connect(str(endpoint)) + connection.sendall((line + '\n').encode()) + with connection.makefile('r') as reply: + result = json.loads(reply.readline()) + if check: + assert 'error' not in result, (line, result) + return result + + +def wait_for(endpoint, line, predicate, timeout=60, what=None): + deadline = time.monotonic() + timeout + last = None + while time.monotonic() < deadline: + try: + last = command(endpoint, line, check=False) + except (FileNotFoundError, ConnectionRefusedError): + time.sleep(0.1) + continue + try: + if predicate(last): + return last + except (KeyError, TypeError, IndexError): + pass + time.sleep(0.1) + raise AssertionError(f'timed out waiting for {what or line}: {last}') + + +def free_port(): + with socket.socket() as s: + s.bind(('127.0.0.1', 0)) + return s.getsockname()[1] + + +def health(relay_url): + with urllib.request.urlopen(f'http://{relay_url}/health', timeout=5) as r: + return json.loads(r.read()) + + +class Game: + """A Horizon client with a control socket in its own home.""" + + def __init__(self, client, resources, work, name, env): + self.home = work / name + self.home.mkdir() + self.endpoint = self.home / 'c.sock' + self.log = (self.home / 'client.log').open('w+') + self.process = subprocess.Popen([ + str(client), '--resources', str(resources), '--render-distance', '2', '--test-terrain', + '--control-socket', str(self.endpoint), '--timeout-seconds', '600', + ], cwd=self.home, env=dict(os.environ, HORIZON_HOME=str(self.home), HORIZON_NO_AUDIO='1', **env), + stdout=self.log, stderr=subprocess.STDOUT) + wait_for(self.endpoint, 'screen', lambda v: v['screen'] == 'title', 120, f'{name} title') + + def __call__(self, line, check=True): + return command(self.endpoint, line, check) + + def wait(self, line, predicate, timeout=60, what=None): + return wait_for(self.endpoint, line, predicate, timeout, what) + + def stop(self): + if self.process.poll() is None: + try: + self('quit', check=False) + self.process.wait(timeout=20) + except Exception: + self.process.terminate() + try: + self.process.wait(timeout=10) + except subprocess.TimeoutExpired: + self.process.kill() + self.log.seek(0) + return self.log.read() + + +def host_world(host): + host('open Friends 0 creative') + host.wait('status', lambda v: v['player'] is not None and v['pending_chunks'] == 0, 120, 'host world') + assert host('friends status')['available'], 'HORIZON_RELAY_URL did not reach the host' + host('friends host') + return host.wait('friends status', lambda v: v['code'], 30, 'invite code')['code'] + + +def guest_pos(host, name): + guests = host('lan status')['guests'] + return next(g['position'] for g in guests if g['name'] == name) + + +def play_together(host, guest, name, round_index): + """Chat, movement and blocks seen from both sides.""" + host.wait('lan status', lambda v: any(g['name'] == name and g['placed'] for g in v['guests']), 60, + 'the guest in the host world') + guest.wait('status', lambda v: v['server']['joined'] and v['player'] is not None, 60, 'guest joined') + # Chat both ways. + guest(f'chat hello from {name} {round_index}') + host.wait('chat-log 20', lambda v: any(f'hello from {name} {round_index}' in l for l in v['chat']), 30, + 'guest chat on the host') + host(f'chat hello from the host {round_index}') + guest.wait('status', lambda v: any(f'hello from the host {round_index}' in l for l in v['server']['chat']), 30, + 'host chat on the guest') + # The guest walks; the host sees it move. + before = guest_pos(host, name) + guest('look 0 0') + guest('key w down') + time.sleep(1.5) + guest('key w up') + host.wait('lan status', lambda v: math.dist(before, next(g['position'] for g in v['guests'] if g['name'] == name)) > 1.0, + 20, 'guest movement on the host') + # The host moves; the guest sees the host's player there. + hp = host('status')['player']['position'] + target = [hp[0] + 3.0, hp[1], hp[2] + 1.0] + host(f'tp {target[0]} {target[1]} {target[2]}') + guest.wait('status', lambda v: any(math.dist(p, target) < 0.6 for p in v['server']['player_positions']), 20, + 'host movement on the guest') + # A block the host places, which the guest sees and then breaks. + gp = guest('status')['player']['position'] + feet = [math.floor(gp[0]), math.floor(gp[1]), math.floor(gp[2])] + block = [feet[0] + 2, feet[1] + 1, feet[2]] + # Clear the line of sight (the test terrain has hills), then the block at eye level. + host(f'fill {feet[0] + 1} {feet[1]} {feet[2]} {feet[0] + 1} {feet[1] + 2} {feet[2]} minecraft:air') + host(f'setblock {block[0]} {block[1]} {block[2]} minecraft:gold_block') + guest.wait(f'getblock {block[0]} {block[1]} {block[2]}', lambda v: v['block'] == 'minecraft:gold_block', 20, + 'the host block on the guest') + eye = [gp[0], gp[1] + 1.62, gp[2]] + dx, dy, dz = block[0] + 0.5 - eye[0], block[1] + 0.5 - eye[1], block[2] + 0.5 - eye[2] + yaw = math.degrees(math.atan2(-dx, dz)) + pitch = -math.degrees(math.atan2(dy, math.hypot(dx, dz))) + guest(f'look {yaw:.3f} {pitch:.3f}') + guest.wait('status', lambda v: v['target']['pos'] == block, 10, 'the guest aiming at the block') + # Held for a few ticks, as a player clicks (creative breaks at once). + guest('mouse left down') + time.sleep(0.25) + guest('mouse left up') + host.wait(f'getblock {block[0]} {block[1]} {block[2]}', lambda v: v['block'] == 'minecraft:air', 20, + 'the guest breaking the block, on the host') + guest.wait(f'getblock {block[0]} {block[1]} {block[2]}', lambda v: v['block'] == 'minecraft:air', 20, + 'the broken block on the guest') + + +def join(guest, code, name): + guest(f'connect friend:{code} {name}') + + +def leave(host, guest, name): + guest('disconnect') + host.wait('lan status', lambda v: all(g['name'] != name for g in v['guests']), 30, 'the guest leaving') + + +def full(args, work, relay_url): + env = {'HORIZON_RELAY_URL': relay_url} + host = Game(args.client, args.resources, work, 'host', env) + games = [host] + try: + code = host_world(host) + print(f'host shares the world: {code[:4]}-****') + if args.baseline: + # The same checks over plain LAN, without the tunnel: the behaviour + # the tunnel must reproduce. + guest = Game(args.client, args.resources, work, 'guest-lan', env) + games.append(guest) + guest(f'connect 127.0.0.1:{host("lan status")["port"]} Plain') + play_together(host, guest, 'Plain', 0) + print('plain LAN: chat, movement and blocks both ways') + leave(host, guest, 'Plain') + guest.stop() + # Direct path. + guest = Game(args.client, args.resources, work, 'guest-direct', env) + games.append(guest) + before = health(relay_url)['relayed_bytes'] + join(guest, code, 'Guest') + play_together(host, guest, 'Guest', 1) + direct_bytes = health(relay_url)['relayed_bytes'] - before + assert host('friends status')['direct'] == 1, host('friends status') + assert direct_bytes < 64 * 1024, f'the direct session went through the relay ({direct_bytes} bytes)' + print(f'direct path: chat, movement and blocks both ways; relay carried {direct_bytes} bytes') + leave(host, guest, 'Guest') + guest.stop() + # Forced relay path. + guest = Game(args.client, args.resources, work, 'guest-relay', + dict(env, HORIZON_FRIENDS_PATH='relay')) + games.append(guest) + before = health(relay_url)['relayed_bytes'] + join(guest, code, 'Relayed') + play_together(host, guest, 'Relayed', 2) + relayed_bytes = health(relay_url)['relayed_bytes'] - before + status = host('friends status') + assert status['relayed'] == 1, status + # Render distance 2: the join is some tens of kB of compressed chunks. + assert relayed_bytes > max(32 * 1024, 4 * direct_bytes), \ + f'the relayed session carried only {relayed_bytes} bytes (direct: {direct_bytes})' + print(f'relay path: chat, movement and blocks both ways; relay carried {relayed_bytes} bytes') + leave(host, guest, 'Relayed') + # The code ends with sharing. + host('friends stop') + assert host('friends status')['code'] is None + join(guest, code, 'Late') + reason = guest.wait('screen', lambda v: v['menu']['disconnected'], 30, 'the ended invite')['menu']['disconnected'] + assert 'invite has ended' in reason, reason + print(f'after stopping: "{reason}"') + assert host('lan status') == {'open': False}, 'sharing opened LAN, so stopping closes it' + return code + except Exception: + for g in games: + print(f'--- {g.home.name} log tail ---') + print('\n'.join(g.stop().splitlines()[-25:])) + raise + finally: + for g in games: + g.stop() + + +def one_side(args, work): + env = {'HORIZON_RELAY_URL': args.relay_url} + if args.path: + env['HORIZON_FRIENDS_PATH'] = args.path + game = Game(args.client, args.resources, work, args.role, env) + try: + if args.role == 'host': + code = host_world(game) + print(f'CODE {code}', flush=True) + game.wait('lan status', lambda v: v['guests'], args.wait, 'a guest') + game.wait('lan status', lambda v: not v['guests'], args.wait, 'the guest leaving') + print(f'host: {game("friends status")}') + else: + join(game, args.code, 'Remote') + v = game.wait('status', lambda v: v['server']['joined'] and v['player'] is not None, 60, 'joined') + game('chat hello across machines') + game.wait('status', lambda v: v['server']['chunks'] > 0, 30, 'chunks') + print(f'guest joined: {v["server"]["address"]}, {v["server"]["chunks"]} chunks') + game('key w down') + time.sleep(1.0) + game('key w up') + game('disconnect') + finally: + game.stop() + + +def main(): + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument('--client', type=Path, required=True) + parser.add_argument('--relay', type=Path, help='horizon-relay binary (started on a free local port)') + parser.add_argument('--relay-url', help='an already running relay, HOST:PORT') + parser.add_argument('--resources', type=Path, default=ROOT / '.local/horizon-client/26.3') + parser.add_argument('--role', choices=['host', 'guest']) + parser.add_argument('--code') + parser.add_argument('--path', choices=['relay', 'direct']) + parser.add_argument('--wait', type=float, default=600) + parser.add_argument('--baseline', action='store_true', help='first run the same checks over plain LAN') + args = parser.parse_args() + args.client, args.resources = args.client.resolve(), args.resources.resolve() + # Short: Unix socket paths are limited to about 100 bytes. + with tempfile.TemporaryDirectory(prefix='hzf-', dir='/tmp') as directory: + work = Path(directory) + if args.role: + assert args.relay_url, '--role needs --relay-url' + return one_side(args, work) + relay = None + relay_url = args.relay_url + if not relay_url: + assert args.relay, 'give --relay or --relay-url' + port = free_port() + relay_url = f'127.0.0.1:{port}' + relay_log = (work / 'relay.log').open('w+') + relay = subprocess.Popen([str(args.relay.resolve())], env=dict(os.environ, PORT=str(port)), + stdout=relay_log, stderr=subprocess.STDOUT) + deadline = time.monotonic() + 10 + while True: + try: + health(relay_url) + break + except OSError: + assert time.monotonic() < deadline, 'the relay did not start' + time.sleep(0.1) + try: + code = full(args, work, relay_url) + finally: + if relay: + relay.terminate() + relay.wait(timeout=10) + relay_log.seek(0) + text = relay_log.read() + print(f'relay log: {text.splitlines()}') + if relay: + # Counts only: no code, no address, no name. + for secret in [code[:4], '127.0.0.1', 'Guest', 'Relayed']: + assert secret not in text, f'the relay logged {secret!r}' + print('Play with friends passed: direct and relayed sessions, chat, movement and blocks both ways') + + +if __name__ == '__main__': + main() From 7784350bad422fff2741959e5e1698255d3d8251 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:27:15 +0200 Subject: [PATCH 27/97] Play with friends: Invite friends in the pause menu The Horizon pause menu gains "Invite friends" beside Open to LAN. It opens the world to LAN if it isn't (Open to LAN's defaults) and shares that port behind an invite code through the relay; the menu shows the code with Copy and Stop sharing, who is here and why the code changed. Closing the LAN server ends the code; stopping sharing closes LAN again if sharing opened it. `horizon-ctl friends host|stop|status` drives it in harnesses. Without HORIZON_RELAY_URL (the default until a relay is deployed) the button is disabled and says the feature isn't available yet. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 1 + crates/horizon-client/Cargo.toml | 1 + crates/horizon-client/src/front.rs | 114 +++++++++++- crates/horizon-client/src/game.rs | 5 + crates/horizon-client/src/game/control.rs | 4 + crates/horizon-client/src/game/friends.rs | 215 ++++++++++++++++++++++ crates/horizon-client/src/game/lan.rs | 1 + crates/horizon-client/src/game/screens.rs | 12 +- 8 files changed, 350 insertions(+), 3 deletions(-) create mode 100644 crates/horizon-client/src/game/friends.rs diff --git a/Cargo.lock b/Cargo.lock index 18f4db44a..d278339d4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1007,6 +1007,7 @@ dependencies = [ "glam", "horizon-assets", "horizon-core", + "horizon-friends", "horizon-protocol", "horizon-telemetry", "horizon-theme", diff --git a/crates/horizon-client/Cargo.toml b/crates/horizon-client/Cargo.toml index 838e56ace..0b9df5a04 100644 --- a/crates/horizon-client/Cargo.toml +++ b/crates/horizon-client/Cargo.toml @@ -12,6 +12,7 @@ horizon-assets = { path = "../horizon-assets" } horizon-core = { path = "../horizon-core" } horizon-world = { path = "../horizon-world" } horizon-protocol = { path = "../horizon-protocol" } +horizon-friends = { path = "../horizon-friends" } wgpu = { version = "30.0.1", default-features = false, features = ["std", "parking_lot", "vulkan", "metal", "wgsl"] } winit = "0.30.13" pollster = "0.4" diff --git a/crates/horizon-client/src/front.rs b/crates/horizon-client/src/front.rs index 64a27d5ac..4eddbdcdd 100644 --- a/crates/horizon-client/src/front.rs +++ b/crates/horizon-client/src/front.rs @@ -1018,12 +1018,36 @@ pub fn wrap(ui: &Ui, text: &str, width: f32) -> Vec { /// blurred world, with the game's actions as a page. Ids match /// `game/screens.rs`'s PauseScreen actions: 0 back to game, 1 options, /// 2 save and quit, 3 statistics, 4 advancements, 9 world options. +/// Play with friends as the pause menu shows it (game/friends.rs fills it). +#[derive(Clone, Debug, Default)] +pub struct FriendsView { + /// A singleplayer world (not a server): the button is offered. + pub shown: bool, + /// A relay is configured in this build. + pub available: bool, + pub sharing: bool, + pub code: Option, + /// While there is no code: getting one, or why not. + pub status: String, + /// The players in the world besides the host. + pub guests: Vec, + pub notice: Option, + /// The code was just copied. + pub copied: bool, +} + pub mod pause { use super::*; fn act(a: u8) -> u64 { id("pause", u64::from(a)) } - pub fn draw(ui: &mut Ui, world: &str, quit_label: &str, opened: Instant) { + pub fn draw( + ui: &mut Ui, + world: &str, + quit_label: &str, + opened: Instant, + friends: &FriendsView, + ) { let (w, h) = (ui.w, ui.h); let p = t::ease_out_quint(opened.elapsed().as_secs_f32() / t::move_()); ui.opacity = p; @@ -1065,8 +1089,31 @@ pub mod pause { Kind::Secondary, true, ); + if friends.shown { + let iw = ui.button_width("Invite friends", true); + ui.button( + act(10), + [x + bw + lw + 16.0, y, iw, CONTROL_LARGE], + "Invite friends", + Kind::Secondary, + friends.available && !friends.sharing, + ); + } y += CONTROL_LARGE + 32.0; ui.row_index = 0; + if friends.shown && !friends.available { + ui.text( + Face::Regular, + SMALL, + x, + y - 18.0, + color::FAINT, + "Inviting friends isn't available yet in this build.", + ); + } + if friends.sharing { + y = invite(ui, x, y, cw, friends); + } ui.divider(x, y, cw); let rh = ui.row( x, @@ -1088,6 +1135,65 @@ pub mod pause { ui.opacity = 1.0; ui.offset = (0.0, 0.0); } + /// The invite section while sharing: the code with Copy and Stop + /// sharing, who is here, and what changed. Returns the y below it. + fn invite(ui: &mut Ui, x: f32, mut y: f32, cw: f32, f: &FriendsView) -> f32 { + ui.divider(x, y, cw); + let top = y + 12.0; + ui.text( + Face::Regular, + BODY, + x, + top + 6.0, + color::MUTED, + "Invite code", + ); + let vx = x + t::ROW_LABEL + 16.0; + match &f.code { + Some(code) => { + ui.text_line(Face::Display, 22.0, CONTROL, vx, top, color::TEXT, code); + } + None => { + let status = ui.fit(Face::Regular, BODY, &f.status, cw - t::ROW_LABEL - 220.0); + ui.text_line(Face::Regular, BODY, CONTROL, vx, top, color::MUTED, &status); + } + } + let stop = "Stop sharing"; + let sw = ui.button_width(stop, false); + ui.button( + act(12), + [x + cw - sw, top, sw, CONTROL], + stop, + Kind::Danger, + true, + ); + let copy = if f.copied { "Copied" } else { "Copy" }; + let copy_w = ui.button_width("Copied", false); + ui.button( + act(11), + [x + cw - sw - 8.0 - copy_w, top, copy_w, CONTROL], + copy, + Kind::Secondary, + f.code.is_some(), + ); + y = top + CONTROL + 10.0; + let here = if f.guests.is_empty() { + "No friends here yet.".to_owned() + } else { + format!("Here now: {}", f.guests.join(", ")) + }; + let lines = [ + Some("Friends paste the code in Multiplayer, Join a friend, or on the launcher's Play page.".to_owned()), + Some(here), + f.notice.clone(), + ]; + for line in lines.into_iter().flatten() { + let line = ui.fit(Face::Regular, SMALL, &line, cw); + ui.text(Face::Regular, SMALL, x, y, color::FAINT, &line); + y += (SMALL * 1.45).round(); + } + y + 12.0 + } /// The PauseScreen action under a click, if any. pub fn click( atlas: &HudAtlas, @@ -1096,6 +1202,7 @@ pub mod pause { y: f32, world: &str, quit_label: &str, + friends: &FriendsView, ) -> Option { let mut ui = Ui::dry(atlas, batch, (x, y)); draw( @@ -1103,6 +1210,7 @@ pub mod pause { world, quit_label, Instant::now() - std::time::Duration::from_secs(5), + friends, ); let hit = ui.hit((x, y))?; let nav = id("pause.nav", 0); @@ -1111,7 +1219,9 @@ pub mod pause { h if h == nav + 1 => Some(4), h if h == nav + 2 => Some(3), h if h == nav + 3 => Some(1), - h => [0u8, 1, 2, 3, 4, 9].into_iter().find(|&a| act(a) == h), + h => [0u8, 1, 2, 3, 4, 9, 10, 11, 12] + .into_iter() + .find(|&a| act(a) == h), } } } diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index 5e2156f10..3f93b5f4b 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -40,6 +40,7 @@ mod fireworks; mod fishing; mod fov; mod frames; +mod friends; mod functions; mod game_mode; mod ghasts; @@ -927,6 +928,8 @@ struct Game<'a> { remote: Option, /// This world is open to the network (game/lan.rs). lan: Option, + /// The open world is shared behind an invite code (game/friends.rs). + friends: Option, world_options: Option, /// KeyboardHandler's debug key state (game/debug_keys.rs), the physical /// keys held, and the debug renderers F3+B and F3+G switch on. @@ -3161,6 +3164,7 @@ impl Game<'_> { }); } horizon_client::spans::time("tick_lan", || self.tick_lan()); + self.tick_friends(); horizon_client::spans::time("tick_hand", || self.tick_hand()); horizon_client::spans::time("tick_sleep", || self.tick_sleep()); horizon_client::spans::time("tick_portal", || self.tick_nether_portal())?; @@ -9446,6 +9450,7 @@ pub fn run() -> Result<()> { remote: None, lan: None, world_options: None, + friends: None, debug_keys: Default::default(), show_hitboxes: false, show_chunk_borders: false, diff --git a/crates/horizon-client/src/game/control.rs b/crates/horizon-client/src/game/control.rs index 61c0cce0a..328e13b27 100644 --- a/crates/horizon-client/src/game/control.rs +++ b/crates/horizon-client/src/game/control.rs @@ -120,6 +120,9 @@ impl Game<'_> { if let Some(value) = self.lan_control(&words)? { return Ok(Some(value)); } + if let Some(value) = self.friends_control(&words)? { + return Ok(Some(value)); + } match self.agent_command(&words, line, reply, event_loop)? { super::agent::Handled::Reply(value) => return Ok(Some(value)), super::agent::Handled::Deferred => return Ok(None), @@ -131,6 +134,7 @@ impl Game<'_> { .chain(super::station_control::HELP) .chain(super::blockctl::HELP) .chain(super::lan::HELP) + .chain(super::friends::HELP) .chain(super::render_control::HELP) .chain(super::sculk::HELP) .chain(super::agent::HELP) diff --git a/crates/horizon-client/src/game/friends.rs b/crates/horizon-client/src/game/friends.rs new file mode 100644 index 000000000..0ccdcfdff --- /dev/null +++ b/crates/horizon-client/src/game/friends.rs @@ -0,0 +1,215 @@ +//! Play with friends, host side: "Invite friends" opens the world to LAN if +//! it isn't (with Open to LAN's defaults) and shares that port behind an +//! invite code through the relay (horizon-friends). The integrated server is +//! the LAN one, unchanged: tunnelled guests are LAN guests that connect from +//! the loopback address. +use super::{Game, lan::LanSettings}; +use horizon_client::{Result, front::FriendsView, text::Text}; +use horizon_friends::{Code, Host, HostConfig, HostEvent, HostState, PathMode}; +use horizon_protocol::{GAME_VERSION, PROTOCOL_VERSION}; +use std::time::{Duration, Instant}; + +pub(super) struct Sharing { + host: Host, + /// Sharing opened the world to LAN, so stopping closes it again. + opened_lan: bool, + code: Option, + /// Wrong codes tried against the current code. + wrong: u32, + notice: Option, + copied: Option, +} + +pub const HELP: &[&str] = &[ + "friends host share the open world behind an invite code (needs HORIZON_RELAY_URL)", + "friends stop stop sharing", + "friends status the code, the relay state and the guests", +]; + +impl Game<'_> { + /// Start sharing the open world. + pub(super) fn friends_start(&mut self) -> Result<()> { + if self.friends.is_some() { + return Ok(()); + } + if self.remote.is_some() || self.title.is_some() { + return Err("open a singleplayer world first".into()); + } + let relay = horizon_friends::relay_url() + .ok_or("inviting friends is not available yet in this build")?; + let opened_lan = self.lan.is_none(); + if opened_lan { + // ShareToLanScreen's defaults, as the world options screen offers them. + self.lan_open(LanSettings { + port: horizon_client::lan::available_port(), + guest_commands: false, + force_game_mode: true, + })?; + } + let port = self.lan_port().ok_or("the world isn't open to LAN")?; + let host = match Host::start(HostConfig { + relay, + lan: std::net::SocketAddr::from(([127, 0, 0, 1], port)), + protocol: PROTOCOL_VERSION, + game: GAME_VERSION.to_owned(), + path: PathMode::from_env(), + }) { + Ok(h) => h, + Err(e) => { + if opened_lan { + self.lan_close(true); + } + return Err(e.into()); + } + }; + self.friends = Some(Sharing { + host, + opened_lan, + code: None, + wrong: 0, + notice: None, + copied: None, + }); + Ok(()) + } + + /// Stop sharing: the code ends; the world closes to LAN again if sharing + /// opened it. + pub(super) fn friends_stop(&mut self) { + let Some(mut sharing) = self.friends.take() else { + return; + }; + sharing.host.stop(); + if sharing.opened_lan { + self.lan_close(true); + } else { + self.system_message(Text::literal("Stopped sharing the invite code.")); + } + } + + /// The LAN server is closing: the code goes with it. + pub(super) fn friends_lan_closed(&mut self) { + if let Some(mut sharing) = self.friends.take() { + sharing.host.stop(); + } + } + + /// New codes and the relay's state, once a tick and while the pause menu + /// is drawn. + pub(super) fn tick_friends(&mut self) { + let Some(sharing) = self.friends.as_mut() else { + return; + }; + let mut announce = None; + for event in sharing.host.poll() { + match event { + HostEvent::Code(code) => { + if sharing.code.is_some() { + sharing.notice = + Some(if sharing.wrong >= horizon_friends::host::MAX_WRONG { + "Someone kept trying a wrong code, so the code changed.".to_owned() + } else { + "The invite service restarted, so the code changed.".to_owned() + }); + } + sharing.wrong = 0; + announce = Some(code.to_string()); + sharing.code = Some(code); + } + HostEvent::WrongCode { count } => { + sharing.wrong = count; + sharing.notice = Some(format!("Someone tried a wrong code ({count} of 5).")); + } + HostEvent::Connected { .. } | HostEvent::Disconnected { .. } => {} + } + } + if let HostState::Retrying(_) = sharing.host.state() { + sharing.code = None; + } + if let Some(code) = announce { + self.system_message(Text::literal(format!( + "Friends can join with the code {code}" + ))); + } + } + + pub(super) fn friends_copy(&mut self) { + let Some(code) = self.friends.as_ref().and_then(|s| s.code.clone()) else { + return; + }; + use horizon_client::clipboard::Clipboard; + self.clipboard.set(&code.to_string()); + if let Some(s) = self.friends.as_mut() { + s.copied = Some(Instant::now()); + } + } + + /// What the pause menu shows. + pub(super) fn friends_view(&self) -> FriendsView { + let guests = self + .lan + .as_ref() + .map(|h| h.hub.guests.iter().map(|g| g.name.clone()).collect()) + .unwrap_or_default(); + let Some(s) = &self.friends else { + return FriendsView { + shown: self.remote.is_none(), + available: horizon_friends::relay_url().is_some(), + ..FriendsView::default() + }; + }; + let status = match s.host.state() { + HostState::Registering => "Getting a code…".to_owned(), + HostState::Retrying(e) => format!("Couldn't reach the invite service; retrying ({e})"), + HostState::Sharing(_) | HostState::Stopped => String::new(), + }; + FriendsView { + shown: true, + available: true, + sharing: true, + code: s.code.as_ref().map(Code::to_string), + status, + guests, + notice: s.notice.clone(), + copied: s + .copied + .is_some_and(|t| t.elapsed() < Duration::from_secs(2)), + } + } + + /// `horizon-ctl friends ...`. + pub(super) fn friends_control(&mut self, words: &[&str]) -> Result> { + use serde_json::json; + if words[0] != "friends" { + return Ok(None); + } + match words.get(1).copied() { + Some("host") => { + self.friends_start()?; + Ok(Some(json!({ "ok": true, "lan_port": self.lan_port() }))) + } + Some("stop") => { + self.friends_stop(); + Ok(Some(json!({ "ok": true }))) + } + Some("status") => { + self.tick_friends(); + let view = self.friends_view(); + let state = self + .friends + .as_ref() + .map(|s| format!("{:?}", s.host.state())); + Ok(Some(json!({ + "available": view.available, + "sharing": view.sharing, + "code": view.code, + "state": state, + "sessions": self.friends.as_ref().map_or(0, |s| s.host.sessions()), + "guests": view.guests, + "lan_port": self.lan_port(), + }))) + } + _ => Err("friends host|stop|status".into()), + } + } +} diff --git a/crates/horizon-client/src/game/lan.rs b/crates/horizon-client/src/game/lan.rs index ed29d0305..1bce62bb8 100644 --- a/crates/horizon-client/src/game/lan.rs +++ b/crates/horizon-client/src/game/lan.rs @@ -450,6 +450,7 @@ impl Game<'_> { /// IntegratedServer.unpublishServer: the guests are sent away. pub(super) fn lan_close(&mut self, announce: bool) { + self.friends_lan_closed(); let Some(mut host) = self.lan.take() else { return; }; diff --git a/crates/horizon-client/src/game/screens.rs b/crates/horizon-client/src/game/screens.rs index 7858cdfe2..91fba4365 100644 --- a/crates/horizon-client/src/game/screens.rs +++ b/crates/horizon-client/src/game/screens.rs @@ -76,8 +76,10 @@ impl Game<'_> { if horizon_client::ui_theme::horizon() { let opened = *self.pause_since.get_or_insert_with(std::time::Instant::now); let (world, quit) = self.pause_labels(); + self.tick_friends(); + let friends = self.friends_view(); let mut ui = horizon_client::ui_theme::Ui::new(&self.res.atlas, batch, self.cursor); - horizon_client::front::pause::draw(&mut ui, &world, quit, opened); + horizon_client::front::pause::draw(&mut ui, &world, quit, opened, &friends); ui.finish(); return; } @@ -144,6 +146,7 @@ impl Game<'_> { self.cursor.1, &world, quit, + &self.friends_view(), ) } else { pause_buttons(w, h) @@ -163,6 +166,13 @@ impl Game<'_> { Some(3) => self.open_stats(), Some(4) => self.open_advancements(true), Some(9) => self.open_world_options(), + Some(10) => { + if let Err(e) = self.friends_start() { + self.system_message(Text::literal(format!("Couldn't share the world: {e}"))); + } + } + Some(11) => self.friends_copy(), + Some(12) => self.friends_stop(), Some(2) => self.close_world()?, _ => {} } From c7f30d2105394215cfb9b12630e8a6580d863b5f Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:47:56 +0200 Subject: [PATCH 28/97] Relay: RELAY_BIND listens on one address (tailnet-only test relays) Co-Authored-By: Claude Opus 5.5 --- crates/horizon-relay/src/main.rs | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/crates/horizon-relay/src/main.rs b/crates/horizon-relay/src/main.rs index 600abade5..a5f2dfe83 100644 --- a/crates/horizon-relay/src/main.rs +++ b/crates/horizon-relay/src/main.rs @@ -1,6 +1,6 @@ -//! `horizon-relay`: listens on `$PORT` (7000 when unset), limits from the -//! `RELAY_*` variables (docs/play-with-friends.md). Prints counts every five -//! minutes, nothing else. +//! `horizon-relay`: listens on `$PORT` (7000 when unset; `RELAY_BIND` for one +//! address), limits from the `RELAY_*` variables (docs/play-with-friends.md). +//! Prints counts every five minutes, nothing else. use horizon_relay::{Config, Relay}; use std::{net::TcpListener, time::Duration}; @@ -9,13 +9,19 @@ fn main() { .ok() .and_then(|p| p.trim().parse().ok()) .unwrap_or(7000); - // Dual-stack where the system allows it, else IPv4. - let listener = TcpListener::bind(("::", port)) - .or_else(|_| TcpListener::bind(("0.0.0.0", port))) - .unwrap_or_else(|e| { - eprintln!("horizon-relay: can't listen on port {port}: {e}"); - std::process::exit(1); - }); + // RELAY_BIND picks one address (e.g. only a tailnet); else dual-stack + // where the system allows it, else IPv4. + let bind = std::env::var("RELAY_BIND") + .ok() + .filter(|b| !b.trim().is_empty()); + let listener = match bind { + Some(address) => TcpListener::bind((address.trim(), port)), + None => TcpListener::bind(("::", port)).or_else(|_| TcpListener::bind(("0.0.0.0", port))), + } + .unwrap_or_else(|e| { + eprintln!("horizon-relay: can't listen on port {port}: {e}"); + std::process::exit(1); + }); let config = Config::from_env(); println!( "horizon-relay {} listening on port {port} (hosts {}, bridges {}, {} KiB/s per stream, per-address limits {})", From 21a70c8e97b606bf791a6e79b244b23e37d3883f Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:45:53 +0200 Subject: [PATCH 29/97] LAN: a guest's entity id no longer takes the host's Hub::admit read the entity counter before incrementing it, while the game increments first (the current value is the last id in use). The first guest after Open to LAN got the host's own entity id, so its client took the host's AddEntity for itself and never showed the host. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/lan/hub.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/crates/horizon-client/src/lan/hub.rs b/crates/horizon-client/src/lan/hub.rs index 6811eb129..2486fd1a5 100644 --- a/crates/horizon-client/src/lan/hub.rs +++ b/crates/horizon-client/src/lan/hub.rs @@ -420,8 +420,10 @@ impl Hub { } fn admit(&mut self, j: super::Joined, ctx: &mut TickCtx) -> u32 { - let entity_id = *ctx.next_entity as i32; + // The game's ids are taken by incrementing first: the current value + // is the last id in use (the host's own, right after opening to LAN). *ctx.next_entity += 1; + let entity_id = *ctx.next_entity as i32; let conn = j.conn; let mut guest = Guest::new(j, entity_id, ctx.spawn, self.config.view_distance); guest.last_action_tick = self.ticks; From 341aa98a968c7067e6e778683b67f71e4be30b76 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:03:06 +0200 Subject: [PATCH 30/97] test_friends: --hold for the guest role, report chunks once they arrive Co-Authored-By: Claude Opus 5.5 --- tools/test_friends.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tools/test_friends.py b/tools/test_friends.py index 482aea2de..97ef7a41c 100644 --- a/tools/test_friends.py +++ b/tools/test_friends.py @@ -259,13 +259,14 @@ def one_side(args, work): print(f'host: {game("friends status")}') else: join(game, args.code, 'Remote') - v = game.wait('status', lambda v: v['server']['joined'] and v['player'] is not None, 60, 'joined') + game.wait('status', lambda v: v['server']['joined'] and v['player'] is not None, 60, 'joined') game('chat hello across machines') - game.wait('status', lambda v: v['server']['chunks'] > 0, 30, 'chunks') + v = game.wait('status', lambda v: v['server']['chunks'] > 0, 30, 'chunks') print(f'guest joined: {v["server"]["address"]}, {v["server"]["chunks"]} chunks') game('key w down') time.sleep(1.0) game('key w up') + time.sleep(args.hold) game('disconnect') finally: game.stop() @@ -281,6 +282,7 @@ def main(): parser.add_argument('--code') parser.add_argument('--path', choices=['relay', 'direct']) parser.add_argument('--wait', type=float, default=600) + parser.add_argument('--hold', type=float, default=0, help='guest: stay this many seconds before leaving') parser.add_argument('--baseline', action='store_true', help='first run the same checks over plain LAN') args = parser.parse_args() args.client, args.resources = args.client.resolve(), args.resources.resolve() From 241dee2649b601ebb43326345cd0ea85b845f55a Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:45:53 +0200 Subject: [PATCH 31/97] Invite friends: count direct and relayed sessions in friends status Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/game/friends.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/crates/horizon-client/src/game/friends.rs b/crates/horizon-client/src/game/friends.rs index 0ccdcfdff..57a2c09de 100644 --- a/crates/horizon-client/src/game/friends.rs +++ b/crates/horizon-client/src/game/friends.rs @@ -16,6 +16,8 @@ pub(super) struct Sharing { code: Option, /// Wrong codes tried against the current code. wrong: u32, + /// Sessions carried directly and through the relay so far. + paths: (u32, u32), notice: Option, copied: Option, } @@ -67,6 +69,7 @@ impl Game<'_> { opened_lan, code: None, wrong: 0, + paths: (0, 0), notice: None, copied: None, }); @@ -120,7 +123,9 @@ impl Game<'_> { sharing.wrong = count; sharing.notice = Some(format!("Someone tried a wrong code ({count} of 5).")); } - HostEvent::Connected { .. } | HostEvent::Disconnected { .. } => {} + HostEvent::Connected { direct: true, .. } => sharing.paths.0 += 1, + HostEvent::Connected { direct: false, .. } => sharing.paths.1 += 1, + HostEvent::Disconnected { .. } => {} } } if let HostState::Retrying(_) = sharing.host.state() { @@ -205,6 +210,8 @@ impl Game<'_> { "code": view.code, "state": state, "sessions": self.friends.as_ref().map_or(0, |s| s.host.sessions()), + "direct": self.friends.as_ref().map_or(0, |s| s.paths.0), + "relayed": self.friends.as_ref().map_or(0, |s| s.paths.1), "guests": view.guests, "lan_port": self.lan_port(), }))) From a3913be6410bff7fa71ca8012d35e4c3c6103e13 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:41:54 +0200 Subject: [PATCH 32/97] Join a friend with the full code (no server) or a relay's short code The game joins `friend:CODE` with either code: a full invite is dialled directly, then through the relay it names; a short code goes through the relay the player set. Join a friend gains a Relay (optional) field, saved to horizon.txt (friendsRelay) and used for hosting too; the code field shows the end of long codes and says what is wrong with one (typo, other version, short code without a relay). The launcher validates both kinds. tools/test_friends.py now runs (a) the code alone with no relay anywhere and (b) a relay run locally with the short code; routers and STUN stay out of tests. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/front.rs | 82 ++++++++--- crates/horizon-client/src/game/friends.rs | 11 +- crates/horizon-client/src/multiplayer.rs | 69 +++++++--- crates/horizon-client/src/net.rs | 40 ++++-- launcher/src/backend.rs | 4 +- launcher/src/main.rs | 3 +- tools/test_friends.py | 158 ++++++++++++---------- 7 files changed, 231 insertions(+), 136 deletions(-) diff --git a/crates/horizon-client/src/front.rs b/crates/horizon-client/src/front.rs index 75e6547e1..1fa91f6cf 100644 --- a/crates/horizon-client/src/front.rs +++ b/crates/horizon-client/src/front.rs @@ -455,7 +455,7 @@ impl Title { _ => 50, }), FIELD_A | FIELD_B => { - if let Screen::Edit { focus, .. } = screen { + if let Screen::Edit { focus, .. } | Screen::Friend { focus, .. } = screen { *focus = u8::from(hit == FIELD_B); } None @@ -488,6 +488,25 @@ impl Title { } } +/// The end of `text` that fits `width`, led by an ellipsis when cut. +fn tail_fit(ui: &Ui, text: &str, width: f32) -> String { + if ui.measure(Face::Regular, BODY, text) <= width { + return text.to_owned(); + } + let chars: Vec = text.chars().collect(); + let mut start = 0; + while start < chars.len() { + let tail: String = std::iter::once('…') + .chain(chars[start..].iter().copied()) + .collect(); + if ui.measure(Face::Regular, BODY, &tail) <= width { + return tail; + } + start += 1; + } + String::new() +} + /// The page header plus a row of actions under it; returns the y below. fn header(ui: &mut Ui, x: f32, title: &str, description: &str) -> f32 { let y = 36.0; @@ -960,15 +979,15 @@ fn multiplayer_page(ui: &mut Ui, x: f32, w: f32, screen: &Screen, caret: bool) { ); ui.divider(x, y + rh, w); } - Screen::Friend { code } => { + Screen::Friend { code, relay, focus } => { let y = header( ui, x, "Join a friend", "Paste the invite code your friend sees in their pause menu.", ); - let available = horizon_friends::relay_url().is_some(); - let ok = available && horizon_friends::Code::parse(code).is_some(); + let parsed = horizon_friends::invite::parse_detailed(code); + let ok = parsed.is_ok(); actions_right( ui, x + w, @@ -980,26 +999,45 @@ fn multiplayer_page(ui: &mut Ui, x: f32, w: f32, screen: &Screen, caret: bool) { ); ui.divider(x, y, w); let rh = 12.0 + CONTROL + 12.0; - ui.text_line(Face::Regular, BODY, rh, x, y, color::MUTED, "Invite code"); let fx = x + t::ROW_LABEL + 16.0; - ui.field( - FIELD_A, - [fx, y + 12.0, (w - t::ROW_LABEL - 16.0).min(240.0), CONTROL], - code, - "K7QM-3XPD", - true, - caret, - ); - ui.divider(x, y + rh, w); - if !available { - ui.text( - Face::Regular, - SMALL, - x, - y + rh + 12.0, - color::FAINT, - "Joining friends isn't available yet in this build.", + let fw = w - t::ROW_LABEL - 16.0; + let rows = [ + (FIELD_A, "Invite code", code, "Paste the code here", fw), + ( + FIELD_B, + "Relay (optional)", + relay, + "host:port, for short codes", + fw.min(360.0), + ), + ]; + let mut ry = y; + for (i, (fid, label, value, hint, width)) in rows.into_iter().enumerate() { + ui.text_line(Face::Regular, BODY, rh, x, ry, color::MUTED, label); + // A long code shows its end, where the typing is. + let shown = tail_fit(ui, value, width - 28.0); + ui.field( + fid, + [fx, ry + 12.0, width, CONTROL], + &shown, + hint, + usize::from(*focus) == i, + caret, ); + ry += rh; + ui.divider(x, ry, w); + } + let note = match parsed { + _ if code.trim().is_empty() => None, + Err(e) => Some(e.to_string()), + Ok(horizon_friends::invite::Parsed::Short(_)) if relay.trim().is_empty() => Some( + "This is a relay's short code: fill in your friend's relay above, or ask for the full code." + .to_owned(), + ), + Ok(_) => None, + }; + if let Some(note) = note { + ui.text(Face::Regular, SMALL, x, ry + 12.0, color::MUTED, ¬e); } } Screen::Disconnected { reason, retry } => { diff --git a/crates/horizon-client/src/game/friends.rs b/crates/horizon-client/src/game/friends.rs index 90e5b82a2..51dfe3fbf 100644 --- a/crates/horizon-client/src/game/friends.rs +++ b/crates/horizon-client/src/game/friends.rs @@ -30,15 +30,6 @@ pub const HELP: &[&str] = &[ "friends status the code, how friends reach this host, the guests", ]; -/// The relay the player set (Join a friend's Relay field, `friendsRelay` -/// in horizon.txt), else `HORIZON_RELAY_URL`. None by default. -pub(super) fn relay_setting() -> Option { - let dir = std::env::current_dir().ok()?; - horizon_client::ui_theme::preference(&dir, "friendsRelay") - .filter(|r| !r.is_empty()) - .or_else(horizon_friends::relay_url) -} - /// `HORIZON_STUN_SERVERS`, else `friendsStun` in horizon.txt, else the defaults. fn stun_servers() -> Vec { if std::env::var_os("HORIZON_STUN_SERVERS").is_some() { @@ -78,7 +69,7 @@ impl Game<'_> { lan: std::net::SocketAddr::from(([127, 0, 0, 1], port)), protocol: PROTOCOL_VERSION, game: GAME_VERSION.to_owned(), - relay: relay_setting(), + relay: horizon_client::net::friends_relay_setting(), path: PathMode::from_env(), port: std::env::var("HORIZON_FRIENDS_PORT") .ok() diff --git a/crates/horizon-client/src/multiplayer.rs b/crates/horizon-client/src/multiplayer.rs index 0c4019568..a94972146 100644 --- a/crates/horizon-client/src/multiplayer.rs +++ b/crates/horizon-client/src/multiplayer.rs @@ -49,6 +49,9 @@ pub enum Screen { /// from Horizon's multiplayer page). Friend { code: String, + /// The relay for short codes (optional; saved on Join). + relay: String, + focus: u8, }, Disconnected { reason: String, @@ -212,18 +215,18 @@ impl Screen { 53, ), ], - Self::Friend { code } => vec![ + Self::Friend { code, .. } => vec![ b( w / 2.0 - 100.0, - h / 4.0 + 96.0 + 12.0, + h / 4.0 + 96.0 + 18.0, 200.0, "Join", - horizon_friends::Code::parse(code).is_some(), + horizon_friends::invite::parse(code).is_some(), 56, ), b( w / 2.0 - 100.0, - h / 4.0 + 120.0 + 12.0, + h / 4.0 + 120.0 + 18.0, 200.0, "Cancel", true, @@ -465,9 +468,18 @@ impl Screen { blink, ); } - Self::Friend { code } => { + Self::Friend { code, relay, focus } => { centered(batch, "Join a Friend", 20.0, u32::MAX); - Self::field(atlas, batch, "Invite Code", code, 100.0 - 11.0, true, blink); + Self::field(atlas, batch, "Invite Code", code, 53.0, *focus == 0, blink); + Self::field( + atlas, + batch, + "Relay (optional)", + relay, + 94.0, + *focus == 1, + blink, + ); } Self::Disconnected { reason, retry } => { centered( @@ -514,11 +526,7 @@ impl Screen { address: String::new(), } } - (Self::List { .. }, Some(47)) => { - *self = Self::Friend { - code: String::new(), - } - } + (Self::List { .. }, Some(47)) => *self = Self::friend(), (Self::List { .. }, Some(42)) => { *self = Self::Edit { index: None, @@ -610,12 +618,14 @@ impl Screen { (Self::Direct { address }, Some(52)) => { return Outcome::Connect(address.trim().to_owned()); } - (Self::Friend { code }, Some(56)) => { - if let Some(code) = horizon_friends::Code::parse(code) { + (Self::Friend { code, relay, .. }, Some(56)) => { + if horizon_friends::invite::parse(code).is_some() { + crate::net::save_friends_relay(relay.trim()); + let code: String = code.chars().filter(|c| !c.is_whitespace()).collect(); return Outcome::Connect(format!("{}{code}", crate::net::FRIEND)); } } - (Self::Edit { focus, .. }, None) => { + (Self::Edit { focus, .. } | Self::Friend { focus, .. }, None) => { for (i, fy) in [(0u8, 53.0 + 11.0), (1, 94.0 + 11.0)] { if y >= fy && y < fy + 20.0 && (x - w / 2.0).abs() < 100.0 { *focus = i; @@ -635,10 +645,20 @@ impl Screen { .. } => Some(if *focus == 0 { name } else { address }), Self::Direct { address } => Some(address), - Self::Friend { code } => Some(code), + Self::Friend { + code, relay, focus, .. + } => Some(if *focus == 0 { code } else { relay }), _ => None, } } + /// Join a friend, with the relay the player set before. + pub fn friend() -> Self { + Self::Friend { + code: String::new(), + relay: crate::net::friends_relay_setting().unwrap_or_default(), + focus: 0, + } + } /// Auto-reconnect's attempt, once its countdown is over. pub fn due_retry(&mut self) -> Option { let Self::Disconnected { retry, .. } = self else { @@ -655,15 +675,26 @@ impl Screen { Self::Edit { focus: 0, .. } => ("server.name", 0), Self::Edit { .. } => ("server.address", 0), Self::Direct { .. } => ("server.direct", 0), - Self::Friend { .. } => ("friend.code", 0), + Self::Friend { focus: 0, .. } => ("friend.code", 0), + Self::Friend { .. } => ("friend.relay", 0), _ => return None, }; - self.focused_field().map(|f| (id, f, 128)) + let max = self.max_length(); + self.focused_field().map(|f| (id, f, max)) + } + /// Invite codes with IPv6 and a relay run past a server address's 128. + fn max_length(&self) -> usize { + if matches!(self, Self::Friend { .. }) { + 256 + } else { + 128 + } } pub fn type_text(&mut self, text: &str) { + let max = self.max_length(); if let Some(field) = self.focused_field() { for c in text.chars().filter(|c| !c.is_control()) { - if field.chars().count() < 128 { + if field.chars().count() < max { field.push(c); } } @@ -675,7 +706,7 @@ impl Screen { } } pub fn tab(&mut self) { - if let Self::Edit { focus, .. } = self { + if let Self::Edit { focus, .. } | Self::Friend { focus, .. } = self { *focus = (*focus + 1) % 2; } } diff --git a/crates/horizon-client/src/net.rs b/crates/horizon-client/src/net.rs index 8af10f66a..047698e14 100644 --- a/crates/horizon-client/src/net.rs +++ b/crates/horizon-client/src/net.rs @@ -150,32 +150,46 @@ impl Drop for Session { /// client reaches on a loopback port, so everything after is a plain join. pub const FRIEND: &str = horizon_friends::ADDRESS_PREFIX; -/// An address as players and logs see it: a friend's invite code without -/// its secret half. +/// An address as players and logs see it: a friend's invite code stays +/// out of it (its secret is in there). pub fn shown_address(address: &str) -> String { match address.strip_prefix(FRIEND) { - Some(code) => match horizon_friends::Code::parse(code) { - Some(code) => format!("Friend's world ({}-****)", code.nameplate), - None => "Friend's world".to_owned(), + Some(code) => match horizon_friends::invite::parse(code) { + Some(horizon_friends::invite::Parsed::Short(c)) => { + format!("Friend's world ({}-****)", c.nameplate) + } + _ => "Friend's world".to_owned(), }, None => address.to_owned(), } } -/// Find the friend's world behind the code and open the tunnel: the loopback -/// address to connect to. +/// The relay the player set (`friendsRelay` in horizon.txt, beside +/// options.txt), else `HORIZON_RELAY_URL`. None by default. +pub fn friends_relay_setting() -> Option { + let dir = std::env::current_dir().ok()?; + crate::ui_theme::preference(&dir, "friendsRelay") + .filter(|r| !r.is_empty()) + .or_else(horizon_friends::relay_url) +} +/// Remember the relay typed on Join a friend (empty forgets it). +pub fn save_friends_relay(relay: &str) { + if let Ok(dir) = std::env::current_dir() { + crate::ui_theme::set_preference(&dir, "friendsRelay", (!relay.is_empty()).then_some(relay)); + } +} + +/// Reach the friend's world from the code (directly, or through a relay) +/// and open the tunnel: the loopback address to connect to. fn join_friend(code: &str, send: &Sender) -> Result<(String, u16), String> { use horizon_friends::{ - Code, JoinError, PathMode, + PathMode, guest::{self, GuestConfig}, }; - let code = Code::parse(code) - .ok_or("That isn't an invite code: codes are eight letters and digits, like K7QM-3XPD.")?; - let relay = horizon_friends::relay_url().ok_or_else(|| JoinError::NotAvailable.to_string())?; status(send, "Finding your friend's world..."); let tunnel = guest::join(&GuestConfig { - relay, - code, + code: code.to_owned(), + relay: friends_relay_setting(), protocol: PROTOCOL_VERSION, game: horizon_protocol::GAME_VERSION.to_owned(), path: PathMode::from_env(), diff --git a/launcher/src/backend.rs b/launcher/src/backend.rs index 08c679a88..00c0db163 100644 --- a/launcher/src/backend.rs +++ b/launcher/src/backend.rs @@ -1057,8 +1057,8 @@ pub fn client(tag: &str) -> Result { /// Start the game straight into a friend's world: `--server friend:CODE`. pub fn join_friend(cmd: &mut Command, code: &str) -> Result<(), String> { - let code = horizon_friends::Code::parse(code) - .ok_or("That isn't an invite code: codes are eight letters and digits, like K7QM-3XPD.")?; + horizon_friends::invite::parse_detailed(code).map_err(|e| e.to_string())?; + let code: String = code.chars().filter(|c| !c.is_whitespace()).collect(); cmd.arg("--server") .arg(format!("{}{code}", horizon_friends::ADDRESS_PREFIX)); Ok(()) diff --git a/launcher/src/main.rs b/launcher/src/main.rs index 6ee37b95c..0a6d5b453 100644 --- a/launcher/src/main.rs +++ b/launcher/src/main.rs @@ -2228,7 +2228,8 @@ impl Launcher { } fn join_friend(&mut self) { - if self.mode != Mode::Client || horizon_friends::invite::parse(&self.friend_code).is_none() { + if self.mode != Mode::Client || horizon_friends::invite::parse(&self.friend_code).is_none() + { return; } self.joining = Some(self.friend_code.clone()); diff --git a/tools/test_friends.py b/tools/test_friends.py index 97ef7a41c..086516a72 100644 --- a/tools/test_friends.py +++ b/tools/test_friends.py @@ -1,22 +1,24 @@ #!/usr/bin/env python3 """Play with friends end to end, without the internet. -A relay (`horizon-relay`) on a free local port; a host Horizon that opens a -world and shares it behind an invite code (`friends host`); a guest Horizon -that joins with the code (`connect friend:CODE`). The guest joins twice: -first on the direct path, then started with HORIZON_FRIENDS_PATH=relay so -the session goes through the relay. Each time both sides must see the -other's chat line, the other moving, a block the host places and the block -the guest breaks; the host's counts say which path each session took, and -the relay's relayed bytes must stay small for the direct session and grow -with the relayed one. Last, the host stops sharing and a guest using the -old code is told the invite has ended. +(a) The code alone: a host Horizon opens a world and shares it (`friends +host`) with no relay anywhere; a guest Horizon joins with the full invite +code (`connect friend:CODE`) by dialling the endpoints in it. (b) A +self-hosted relay run locally (`horizon-relay`): the host also gets a short +code from it, and a guest started with HORIZON_FRIENDS_PATH=relay joins with +the short code through it. Each time both sides must see the other's chat +line, the other moving, a block the host places and the block the guest +breaks; then the host stops sharing and a guest with the old code is told +why it can't join. `--baseline` first runs the same checks over plain LAN. +The router is never asked to open a port (HORIZON_FRIENDS_UPNP=0) and STUN +is off: nothing leaves the machine. python3 tools/test_friends.py --client target/fast/horizon-client --relay target/fast/horizon-relay -`--relay-url HOST:PORT` uses a relay already running elsewhere (two -machines); `--role host|guest` then runs one side only and prints or takes -the code (`--code`). Needs a display on Linux (xvfb-run -a). +`--role host|guest` runs one side only (two machines, e.g. over a tailnet): +the host prints the code, the guest takes it with `--code` (`--relay-url` +for a relay elsewhere, `--path relay` to force it). Needs a display on Linux +(xvfb-run -a). """ import argparse import json @@ -112,7 +114,6 @@ class Game: def host_world(host): host('open Friends 0 creative') host.wait('status', lambda v: v['player'] is not None and v['pending_chunks'] == 0, 120, 'host world') - assert host('friends status')['available'], 'HORIZON_RELAY_URL did not reach the host' host('friends host') return host.wait('friends status', lambda v: v['code'], 30, 'invite code')['code'] @@ -182,13 +183,45 @@ def leave(host, guest, name): host.wait('lan status', lambda v: all(g['name'] != name for g in v['guests']), 30, 'the guest leaving') -def full(args, work, relay_url): - env = {'HORIZON_RELAY_URL': relay_url} +def start_relay(args, work): + """A relay on a free local port, as anyone would run their own.""" + port = free_port() + url = f'127.0.0.1:{port}' + log = (work / 'relay.log').open('w+') + process = subprocess.Popen([str(args.relay.resolve())], env=dict(os.environ, PORT=str(port)), + stdout=log, stderr=subprocess.STDOUT) + deadline = time.monotonic() + 10 + while True: + try: + health(url) + return process, log, url + except OSError: + assert time.monotonic() < deadline, 'the relay did not start' + time.sleep(0.1) + + +def set_relay(game, url): + """What typing the relay on Join a friend saves (horizon.txt).""" + path = game.home / 'horizon.txt' + lines = [l for l in (path.read_text().splitlines() if path.exists() else []) if not l.startswith('friendsRelay:')] + path.write_text('\n'.join(lines + [f'friendsRelay:{url}']) + '\n') + + +def full(args, work): + # Tests never touch the real router or ask the internet. Both games run on + # this machine, so the code also holds 127.0.0.1 (a firewall such as + # macOS's may hold back connections to the LAN address from an unsigned + # binary started over SSH, which can't show its prompt). + env = {'HORIZON_FRIENDS_UPNP': '0', 'HORIZON_STUN_SERVERS': 'none', 'HORIZON_FRIENDS_LOOPBACK': '1'} host = Game(args.client, args.resources, work, 'host', env) games = [host] + relay = None try: + # (a) The code alone: no relay anywhere. code = host_world(host) - print(f'host shares the world: {code[:4]}-****') + status = host('friends status') + assert status['short'] is None and len(code) > 30, status + print(f'host shares the world: a {len(code.replace("-", ""))}-symbol code, no relay; {status["summary"]}') if args.baseline: # The same checks over plain LAN, without the tunnel: the behaviour # the tunnel must reproduce. @@ -199,42 +232,47 @@ def full(args, work, relay_url): print('plain LAN: chat, movement and blocks both ways') leave(host, guest, 'Plain') guest.stop() - # Direct path. - guest = Game(args.client, args.resources, work, 'guest-direct', env) + guest = Game(args.client, args.resources, work, 'guest-code', env) games.append(guest) - before = health(relay_url)['relayed_bytes'] join(guest, code, 'Guest') play_together(host, guest, 'Guest', 1) - direct_bytes = health(relay_url)['relayed_bytes'] - before assert host('friends status')['direct'] == 1, host('friends status') - assert direct_bytes < 64 * 1024, f'the direct session went through the relay ({direct_bytes} bytes)' - print(f'direct path: chat, movement and blocks both ways; relay carried {direct_bytes} bytes') + print('code alone: chat, movement and blocks both ways, no server involved') leave(host, guest, 'Guest') + host('friends stop') + assert host('friends status')['code'] is None + assert host('lan status') == {'open': False}, 'sharing opened LAN, so stopping closes it' + join(guest, code, 'Late') + reason = guest.wait('screen', lambda v: v['menu']['disconnected'], 30, 'the ended code')['menu']['disconnected'] + assert "Couldn't reach your friend's game" in reason, reason + print(f'after stopping: "{reason}"') guest.stop() - # Forced relay path. - guest = Game(args.client, args.resources, work, 'guest-relay', - dict(env, HORIZON_FRIENDS_PATH='relay')) + # (b) A self-hosted relay, run locally: the short code, relayed. + relay, relay_log, relay_url = start_relay(args, work) + set_relay(host, relay_url) + host('friends host') + status = host.wait('friends status', lambda v: v['short'], 30, 'the short code') + short = status['short'] + guest = Game(args.client, args.resources, work, 'guest-relay', dict(env, HORIZON_FRIENDS_PATH='relay')) games.append(guest) + set_relay(guest, relay_url) before = health(relay_url)['relayed_bytes'] - join(guest, code, 'Relayed') + join(guest, short, 'Relayed') play_together(host, guest, 'Relayed', 2) relayed_bytes = health(relay_url)['relayed_bytes'] - before status = host('friends status') assert status['relayed'] == 1, status # Render distance 2: the join is some tens of kB of compressed chunks. - assert relayed_bytes > max(32 * 1024, 4 * direct_bytes), \ - f'the relayed session carried only {relayed_bytes} bytes (direct: {direct_bytes})' - print(f'relay path: chat, movement and blocks both ways; relay carried {relayed_bytes} bytes') + assert relayed_bytes > 32 * 1024, f'the relayed session carried only {relayed_bytes} bytes' + print(f'self-hosted relay, short code {short[:4]}-****: chat, movement and blocks both ways; ' + f'relay carried {relayed_bytes} bytes') leave(host, guest, 'Relayed') - # The code ends with sharing. host('friends stop') - assert host('friends status')['code'] is None - join(guest, code, 'Late') + join(guest, short, 'Late') reason = guest.wait('screen', lambda v: v['menu']['disconnected'], 30, 'the ended invite')['menu']['disconnected'] assert 'invite has ended' in reason, reason print(f'after stopping: "{reason}"') - assert host('lan status') == {'open': False}, 'sharing opened LAN, so stopping closes it' - return code + return code + short except Exception: for g in games: print(f'--- {g.home.name} log tail ---') @@ -243,10 +281,21 @@ def full(args, work, relay_url): finally: for g in games: g.stop() + if relay: + relay.terminate() + relay.wait(timeout=10) + relay_log.seek(0) + text = relay_log.read() + print(f'relay log: {text.splitlines()}') + # Counts only: no code, no address, no name. + for secret in ['127.0.0.1', 'Guest', 'Relayed', 'Late']: + assert secret not in text, f'the relay logged {secret!r}' def one_side(args, work): - env = {'HORIZON_RELAY_URL': args.relay_url} + env = {'HORIZON_FRIENDS_UPNP': '0', 'HORIZON_STUN_SERVERS': 'none'} + if args.relay_url: + env['HORIZON_RELAY_URL'] = args.relay_url if args.path: env['HORIZON_FRIENDS_PATH'] = args.path game = Game(args.client, args.resources, work, args.role, env) @@ -276,7 +325,7 @@ def main(): parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) parser.add_argument('--client', type=Path, required=True) parser.add_argument('--relay', type=Path, help='horizon-relay binary (started on a free local port)') - parser.add_argument('--relay-url', help='an already running relay, HOST:PORT') + parser.add_argument('--relay-url', help='--role: a relay already running elsewhere, HOST:PORT') parser.add_argument('--resources', type=Path, default=ROOT / '.local/horizon-client/26.3') parser.add_argument('--role', choices=['host', 'guest']) parser.add_argument('--code') @@ -290,39 +339,10 @@ def main(): with tempfile.TemporaryDirectory(prefix='hzf-', dir='/tmp') as directory: work = Path(directory) if args.role: - assert args.relay_url, '--role needs --relay-url' return one_side(args, work) - relay = None - relay_url = args.relay_url - if not relay_url: - assert args.relay, 'give --relay or --relay-url' - port = free_port() - relay_url = f'127.0.0.1:{port}' - relay_log = (work / 'relay.log').open('w+') - relay = subprocess.Popen([str(args.relay.resolve())], env=dict(os.environ, PORT=str(port)), - stdout=relay_log, stderr=subprocess.STDOUT) - deadline = time.monotonic() + 10 - while True: - try: - health(relay_url) - break - except OSError: - assert time.monotonic() < deadline, 'the relay did not start' - time.sleep(0.1) - try: - code = full(args, work, relay_url) - finally: - if relay: - relay.terminate() - relay.wait(timeout=10) - relay_log.seek(0) - text = relay_log.read() - print(f'relay log: {text.splitlines()}') - if relay: - # Counts only: no code, no address, no name. - for secret in [code[:4], '127.0.0.1', 'Guest', 'Relayed']: - assert secret not in text, f'the relay logged {secret!r}' - print('Play with friends passed: direct and relayed sessions, chat, movement and blocks both ways') + assert args.relay, 'give --relay (the relay binary, run locally for the relay half)' + full(args, work) + print('Play with friends passed: the code alone and a self-hosted relay; chat, movement and blocks both ways') if __name__ == '__main__': From 872e77e19bdf6af8c58a3b1c269ba0e8344fc206 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:03:18 +0200 Subject: [PATCH 33/97] Invite friends: who is here and notices read in the muted colour, the hint stays faint Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/front.rs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/crates/horizon-client/src/front.rs b/crates/horizon-client/src/front.rs index 4eddbdcdd..ffe0b1ace 100644 --- a/crates/horizon-client/src/front.rs +++ b/crates/horizon-client/src/front.rs @@ -1182,14 +1182,16 @@ pub mod pause { } else { format!("Here now: {}", f.guests.join(", ")) }; + let hint = + "Friends paste the code in Multiplayer, Join a friend, or on the launcher's Play page."; let lines = [ - Some("Friends paste the code in Multiplayer, Join a friend, or on the launcher's Play page.".to_owned()), - Some(here), - f.notice.clone(), + Some((here, color::MUTED)), + f.notice.clone().map(|n| (n, color::MUTED)), + Some((hint.to_owned(), color::FAINT)), ]; - for line in lines.into_iter().flatten() { + for (line, tint) in lines.into_iter().flatten() { let line = ui.fit(Face::Regular, SMALL, &line, cw); - ui.text(Face::Regular, SMALL, x, y, color::FAINT, &line); + ui.text(Face::Regular, SMALL, x, y, tint, &line); y += (SMALL * 1.45).round(); } y + 12.0 From 9e6d248fbea88d87cb5f1db9f06a7bbff02daaad Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 01:03:40 +0200 Subject: [PATCH 34/97] test_friends: --xvfb and --offscreen for headless Linux machines Co-Authored-By: Claude Opus 5.5 --- tools/test_friends.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/tools/test_friends.py b/tools/test_friends.py index 086516a72..04399fe0f 100644 --- a/tools/test_friends.py +++ b/tools/test_friends.py @@ -78,15 +78,19 @@ def health(relay_url): class Game: """A Horizon client with a control socket in its own home.""" + # Extra words before and after the client (`--xvfb`, `--offscreen`). + prefix = [] + extra = [] + def __init__(self, client, resources, work, name, env): self.home = work / name self.home.mkdir() self.endpoint = self.home / 'c.sock' self.log = (self.home / 'client.log').open('w+') - self.process = subprocess.Popen([ + self.process = subprocess.Popen(Game.prefix + [ str(client), '--resources', str(resources), '--render-distance', '2', '--test-terrain', '--control-socket', str(self.endpoint), '--timeout-seconds', '600', - ], cwd=self.home, env=dict(os.environ, HORIZON_HOME=str(self.home), HORIZON_NO_AUDIO='1', **env), + ] + Game.extra, cwd=self.home, env=dict(os.environ, HORIZON_HOME=str(self.home), HORIZON_NO_AUDIO='1', **env), stdout=self.log, stderr=subprocess.STDOUT) wait_for(self.endpoint, 'screen', lambda v: v['screen'] == 'title', 120, f'{name} title') @@ -333,7 +337,11 @@ def main(): parser.add_argument('--wait', type=float, default=600) parser.add_argument('--hold', type=float, default=0, help='guest: stay this many seconds before leaving') parser.add_argument('--baseline', action='store_true', help='first run the same checks over plain LAN') + parser.add_argument('--offscreen', action='store_true', help='run the games without a window') + parser.add_argument('--xvfb', action='store_true', help='run the games under xvfb-run (headless Linux)') args = parser.parse_args() + Game.prefix = ['xvfb-run', '-a'] if args.xvfb else [] + Game.extra = ['--offscreen'] if args.offscreen else [] args.client, args.resources = args.client.resolve(), args.resources.resolve() # Short: Unix socket paths are limited to about 100 bytes. with tempfile.TemporaryDirectory(prefix='hzf-', dir='/tmp') as directory: From fe7df463fa1de5b7d352c7d5034faaa7918f5b86 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 03:08:07 +0200 Subject: [PATCH 35/97] Play with friends: bound handshakes and the relay's first line in time, cap relay connections A read timeout restarts with every byte, so a peer trickling one byte at a time could hold the host's 8 handshake slots (or relay threads) for hours. The host's openings and the relay's first line now end after 10 s in all; the relay closes connections past RELAY_MAX_CONNECTIONS (4096). The docs say what happens to a router mapping when the game crashes. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-friends/src/host.rs | 17 ++++++-- crates/horizon-friends/src/lib.rs | 58 +++++++++++++++++++++++++++- crates/horizon-relay/src/lib.rs | 24 +++++++++++- crates/horizon-relay/tests/tunnel.rs | 27 +++++++++++++ docs/play-with-friends.md | 9 +++-- 5 files changed, 127 insertions(+), 8 deletions(-) diff --git a/crates/horizon-friends/src/host.rs b/crates/horizon-friends/src/host.rs index d7f4ae6c2..8268ba7b2 100644 --- a/crates/horizon-friends/src/host.rs +++ b/crates/horizon-friends/src/host.rs @@ -37,6 +37,9 @@ pub const MAX_SESSIONS: usize = 8; pub const DEFAULT_PORT: u16 = 25580; /// Code handshakes in progress at once (scanners can't pile them up). const MAX_HANDSHAKES: usize = 8; +/// The most an inbound stream's opening (hello, key exchange, confirmation) +/// may take, however slowly its bytes come. +const HANDSHAKE: Duration = Duration::from_secs(10); #[derive(Clone)] pub struct HostConfig { @@ -296,6 +299,10 @@ fn route_inbound(listeners: Vec, shared: Arc) { .name("horizon-friends-inbound".into()) .spawn(move || { let _ = s.set_nonblocking(false); + let Ok(deadline) = crate::deadline(&s, HANDSHAKE) else { + shared.handshakes.fetch_sub(1, Ordering::Relaxed); + return; + }; match direct::read_hello(&mut s) { Ok(direct::Hello::Relayed(session)) => { shared.handshakes.fetch_sub(1, Ordering::Relaxed); @@ -310,7 +317,9 @@ fn route_inbound(listeners: Vec, shared: Arc) { let _ = tx.send(s); } } - Ok(direct::Hello::Code(session)) => serve_code(&shared, s, session), + Ok(direct::Hello::Code(session)) => { + serve_code(&shared, s, session, deadline) + } Err(_) => { shared.handshakes.fetch_sub(1, Ordering::Relaxed); } @@ -324,8 +333,9 @@ fn route_inbound(listeners: Vec, shared: Arc) { } /// 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, mut s: TcpStream, session: u64) { +/// the code's secret, then carry the session (`deadline` bounds the +/// handshake, not the game). +fn serve_code(shared: &Arc, mut s: TcpStream, session: u64, deadline: crate::Deadline) { let secret = shared .invite .lock() @@ -338,6 +348,7 @@ fn serve_code(shared: &Arc, mut s: TcpStream, session: u64) { let key = crypto::exchange(&mut s, &secret, "direct", session)?; session::secure(s, &key, Role::Host) })(); + drop(deadline); shared.handshakes.fetch_sub(1, Ordering::Relaxed); match secured { Ok(secure) => carry(shared, session, secure, true), diff --git a/crates/horizon-friends/src/lib.rs b/crates/horizon-friends/src/lib.rs index ffc61721d..ac0e037ab 100644 --- a/crates/horizon-friends/src/lib.rs +++ b/crates/horizon-friends/src/lib.rs @@ -26,8 +26,10 @@ pub use host::{Host, HostConfig, HostEvent, HostState}; use std::{ io, - net::{SocketAddr, TcpStream, ToSocketAddrs}, + net::{Shutdown, SocketAddr, TcpStream, ToSocketAddrs}, + sync::mpsc::{RecvTimeoutError, Sender, channel}, thread::JoinHandle, + time::Duration, }; /// Fill `buf` from the OS random generator. @@ -35,6 +37,29 @@ pub(crate) fn fill_random(buf: &mut [u8]) -> io::Result<()> { getrandom::fill(buf).map_err(|e| io::Error::other(e.to_string())) } +/// Ends a stream's opening once its time is up; dropping it first lets the +/// stream go on. A read timeout alone restarts with every byte, so a peer +/// sending one byte at a time could hold a handshake (and its slot) for +/// hours. +pub struct Deadline { + _cancel: Sender<()>, +} + +/// Shut `stream` down after `limit` unless the returned [`Deadline`] is +/// dropped before. +pub fn deadline(stream: &TcpStream, limit: Duration) -> io::Result { + let stream = stream.try_clone()?; + let (tx, rx) = channel::<()>(); + std::thread::Builder::new() + .name("horizon-friends-deadline".into()) + .spawn(move || { + if rx.recv_timeout(limit) == Err(RecvTimeoutError::Timeout) { + let _ = stream.shutdown(Shutdown::Both); + } + })?; + Ok(Deadline { _cancel: tx }) +} + /// Which paths a session may take (`HORIZON_FRIENDS_PATH`). #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum PathMode { @@ -127,3 +152,34 @@ pub fn pump( let _ = outbound.join(); }) } + +#[cfg(test)] +mod tests { + use super::*; + use std::{ + io::Read, + net::TcpListener, + time::{Duration, Instant}, + }; + + #[test] + fn a_deadline_ends_the_stream_unless_dropped() { + let l = TcpListener::bind("127.0.0.1:0").unwrap(); + let _kept = TcpStream::connect(l.local_addr().unwrap()).unwrap(); + let (mut kept, _) = l.accept().unwrap(); + let _ended = TcpStream::connect(l.local_addr().unwrap()).unwrap(); + let (mut ended, _) = l.accept().unwrap(); + drop(deadline(&kept, Duration::from_millis(100)).unwrap()); + let _running = deadline(&ended, Duration::from_millis(100)).unwrap(); + let started = Instant::now(); + assert_eq!(ended.read(&mut [0u8; 1]).unwrap(), 0); + assert!(started.elapsed() < Duration::from_secs(2)); + kept.set_read_timeout(Some(Duration::from_millis(300))) + .unwrap(); + let e = kept.read(&mut [0u8; 1]).unwrap_err(); + assert!(matches!( + e.kind(), + io::ErrorKind::WouldBlock | io::ErrorKind::TimedOut + )); + } +} diff --git a/crates/horizon-relay/src/lib.rs b/crates/horizon-relay/src/lib.rs index 958e8cd59..f30169107 100644 --- a/crates/horizon-relay/src/lib.rs +++ b/crates/horizon-relay/src/lib.rs @@ -29,6 +29,8 @@ pub struct Config { pub max_hosts: usize, pub max_bridges: usize, pub max_pending_per_host: usize, + /// Connections open at once, of every kind (each is a thread). + pub max_connections: usize, /// Bytes a second each way per relayed stream. pub session_rate: f64, /// Bytes a second for everything relayed. @@ -55,6 +57,7 @@ impl Default for Config { max_hosts: 1000, max_bridges: 200, max_pending_per_host: 8, + max_connections: 4096, session_rate: 1024.0 * 1024.0, total_rate: 100.0 * 1_000_000.0 / 8.0, rates: Rates::default(), @@ -87,6 +90,9 @@ impl Config { if let Some(v) = var("RELAY_MAX_PENDING_PER_HOST") { c.max_pending_per_host = v; } + if let Some(v) = var("RELAY_MAX_CONNECTIONS") { + c.max_connections = v; + } if let Some(v) = var::("RELAY_SESSION_KBPS") { c.session_rate = v * 1024.0; } @@ -163,6 +169,7 @@ struct State { global_unknown: Mutex, total: Mutex, bridges: AtomicUsize, + connections: AtomicUsize, registrations: AtomicU64, joins: AtomicU64, unknown: AtomicU64, @@ -202,6 +209,7 @@ impl Relay { config, inner: Mutex::new(Inner::default()), bridges: AtomicUsize::new(0), + connections: AtomicUsize::new(0), registrations: AtomicU64::new(0), joins: AtomicU64::new(0), unknown: AtomicU64::new(0), @@ -232,14 +240,25 @@ impl Relay { while !self.state.stop.load(Ordering::Relaxed) { match listener.accept() { Ok((stream, peer)) => { + // Beyond the cap the connection is closed unanswered. + if self.state.connections.fetch_add(1, Ordering::Relaxed) + >= self.state.config.max_connections + { + self.state.connections.fetch_sub(1, Ordering::Relaxed); + continue; + } let state = self.state.clone(); - let _ = + let spawned = std::thread::Builder::new() .name("relay-conn".into()) .spawn(move || { let _ = stream.set_nonblocking(false); let _ = handle(&state, stream, peer); + state.connections.fetch_sub(1, Ordering::Relaxed); }); + if spawned.is_err() { + self.state.connections.fetch_sub(1, Ordering::Relaxed); + } } Err(e) if e.kind() == io::ErrorKind::WouldBlock => { std::thread::sleep(Duration::from_millis(10)); @@ -295,6 +314,8 @@ fn handle(state: &Arc, mut stream: TcpStream, peer: SocketAddr) -> io::Re return Ok(()); } let mut peer = unmap(peer); + // The first line (and an HTTP request) within `first_line` in all. + let first_line = horizon_friends::deadline(&stream, state.config.first_line)?; stream.set_read_timeout(Some(state.config.first_line))?; let _ = stream.set_nodelay(true); let mut line = wire::read_line(&mut stream)?.ok_or(io::ErrorKind::UnexpectedEof)?; @@ -307,6 +328,7 @@ fn handle(state: &Arc, mut stream: TcpStream, peer: SocketAddr) -> io::Re if line.starts_with(b"GET ") { return http(state, &mut stream, &line, peer); } + drop(first_line); let Ok(hello) = serde_json::from_slice::(&line) else { return refuse(&mut stream, ErrorCode::BadRequest); }; diff --git a/crates/horizon-relay/tests/tunnel.rs b/crates/horizon-relay/tests/tunnel.rs index 99c3eb663..e59f48d52 100644 --- a/crates/horizon-relay/tests/tunnel.rs +++ b/crates/horizon-relay/tests/tunnel.rs @@ -432,3 +432,30 @@ fn health_and_whoami_answer_http() { assert!(get("/whoami").contains("\"address\":\"127.0.0.1:")); assert!(get("/").starts_with("HTTP/1.1 404")); } + +/// A first line trickled a byte at a time still has to arrive within +/// `first_line` in all; past `max_connections`, connections close unanswered. +#[test] +fn slow_first_lines_and_too_many_connections_are_closed() { + let (_relay, address) = relay(Config { + first_line: Duration::from_secs(1), + max_connections: 2, + ..Config::default() + }); + let started = Instant::now(); + let mut slow = TcpStream::connect(&address).unwrap(); + let held = TcpStream::connect(&address).unwrap(); + std::thread::sleep(Duration::from_millis(200)); + let mut over = TcpStream::connect(&address).unwrap(); + over.set_read_timeout(Some(Duration::from_secs(5))).unwrap(); + assert_eq!(over.read(&mut [0u8; 1]).unwrap_or(0), 0); + while slow.write_all(b"{").is_ok() && started.elapsed() < Duration::from_secs(5) { + std::thread::sleep(Duration::from_millis(200)); + } + let closed = started.elapsed(); + assert!( + closed < Duration::from_secs(3), + "the slow first line held on for {closed:?}" + ); + drop(held); +} diff --git a/docs/play-with-friends.md b/docs/play-with-friends.md index eae5082da..38f4221e4 100644 --- a/docs/play-with-friends.md +++ b/docs/play-with-friends.md @@ -32,7 +32,8 @@ LAN's defaults), then the host's game, on its own: 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; + one, deleted on stop the same way (if the game crashes instead, a timed mapping expires within the + hour; a permanent one stays until it is removed in the router's settings); 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` @@ -79,7 +80,8 @@ The code's secret never leaves the code. Every session runs a password-authentic 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. +guesses against offline. Online guesses on the direct port face the 80-bit secret; at most 8 openings +run at once there, and each must finish within 10 seconds however slowly its bytes come. ## Privacy: who sees what @@ -155,6 +157,7 @@ Settings, all optional: | `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_MAX_CONNECTIONS` | 4096 | connections open at once, of every kind (more are closed unanswered) | | `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 | @@ -163,7 +166,7 @@ Settings, all optional: 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; +for 120 s is closed (the game's keep-alive sends every 15 s); the first line must be complete 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. ### The relay protocol From 7a475a948cd934373cdfc4326155efac2b69dba8 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:34:10 +0200 Subject: [PATCH 36/97] Invite friends works with no relay: the code, and what friends can expect Sharing no longer needs a relay. The panel shows the full invite code in groups (monospace, wrapped) with Copy and Stop sharing, then who can join: friends anywhere when the router opened the port or this computer has a public address; otherwise what to do (UPnP, the port to forward and the LAN address, a relay, a VPN; CGNAT called out) with a link to the troubleshooting docs. A relay set in horizon.txt (friendsRelay) or HORIZON_RELAY_URL adds its short code. horizon.txt keeps other lines when the menu style is saved. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/front.rs | 87 +++++++++---- crates/horizon-client/src/game/friends.rs | 141 ++++++++++++++-------- crates/horizon-client/src/ui_theme.rs | 25 +++- 3 files changed, 176 insertions(+), 77 deletions(-) diff --git a/crates/horizon-client/src/front.rs b/crates/horizon-client/src/front.rs index ffe0b1ace..cc6237ead 100644 --- a/crates/horizon-client/src/front.rs +++ b/crates/horizon-client/src/front.rs @@ -1023,12 +1023,15 @@ pub fn wrap(ui: &Ui, text: &str, width: f32) -> Vec { pub struct FriendsView { /// A singleplayer world (not a server): the button is offered. pub shown: bool, - /// A relay is configured in this build. - pub available: bool, pub sharing: bool, pub code: Option, - /// While there is no code: getting one, or why not. + /// Who can join and what to do when friends on the internet can't (or, + /// before the code, what the game is doing). pub status: String, + /// Friends on the internet can reach the host. + pub reachable: bool, + /// Where the troubleshooting is, when they can't. + pub help: Option, /// The players in the world besides the host. pub guests: Vec, pub notice: Option, @@ -1096,21 +1099,11 @@ pub mod pause { [x + bw + lw + 16.0, y, iw, CONTROL_LARGE], "Invite friends", Kind::Secondary, - friends.available && !friends.sharing, + !friends.sharing, ); } y += CONTROL_LARGE + 32.0; ui.row_index = 0; - if friends.shown && !friends.available { - ui.text( - Face::Regular, - SMALL, - x, - y - 18.0, - color::FAINT, - "Inviting friends isn't available yet in this build.", - ); - } if friends.sharing { y = invite(ui, x, y, cw, friends); } @@ -1137,6 +1130,20 @@ pub mod pause { } /// The invite section while sharing: the code with Copy and Stop /// sharing, who is here, and what changed. Returns the y below it. + /// The code's groups packed into lines of at most `width`. + fn code_lines(ui: &Ui, code: &str, width: f32) -> Vec { + let mut lines: Vec = Vec::new(); + for group in code.split('-') { + match lines.last_mut() { + Some(l) if ui.measure(Face::Mono, BODY, &format!("{l}-{group}")) <= width => { + l.push('-'); + l.push_str(group); + } + _ => lines.push(group.to_owned()), + } + } + lines + } fn invite(ui: &mut Ui, x: f32, mut y: f32, cw: f32, f: &FriendsView) -> f32 { ui.divider(x, y, cw); let top = y + 12.0; @@ -1149,15 +1156,6 @@ pub mod pause { "Invite code", ); let vx = x + t::ROW_LABEL + 16.0; - match &f.code { - Some(code) => { - ui.text_line(Face::Display, 22.0, CONTROL, vx, top, color::TEXT, code); - } - None => { - let status = ui.fit(Face::Regular, BODY, &f.status, cw - t::ROW_LABEL - 220.0); - ui.text_line(Face::Regular, BODY, CONTROL, vx, top, color::MUTED, &status); - } - } let stop = "Stop sharing"; let sw = ui.button_width(stop, false); ui.button( @@ -1169,14 +1167,51 @@ pub mod pause { ); let copy = if f.copied { "Copied" } else { "Copy" }; let copy_w = ui.button_width("Copied", false); + let buttons = sw + 8.0 + copy_w; ui.button( act(11), - [x + cw - sw - 8.0 - copy_w, top, copy_w, CONTROL], + [x + cw - buttons, top, copy_w, CONTROL], copy, Kind::Secondary, f.code.is_some(), ); - y = top + CONTROL + 10.0; + let line = (BODY * 1.45).round(); + let value_w = (cw - t::ROW_LABEL - 16.0 - buttons - 16.0).max(120.0); + y = top + 6.0; + match &f.code { + Some(code) => { + for l in code_lines(ui, code, value_w) { + ui.text(Face::Mono, BODY, vx, y, color::TEXT, &l); + y += line; + } + } + None => { + for l in wrap(ui, &f.status, value_w) { + ui.text(Face::Regular, BODY, vx, y, color::MUTED, &l); + y += line; + } + } + } + y = y.max(top + CONTROL) + 10.0; + let small = (SMALL * 1.45).round(); + if f.code.is_some() { + // Who can join: plain when friends anywhere can, in the text + // colour (it asks for something) when only the LAN and VPNs can. + let tint = if f.reachable { + color::MUTED + } else { + color::TEXT + }; + for l in wrap(ui, &f.status, cw) { + ui.text(Face::Regular, SMALL, x, y, tint, &l); + y += small; + } + if let Some(help) = &f.help { + let l = ui.fit(Face::Regular, SMALL, &format!("Help: {help}"), cw); + ui.text(Face::Regular, SMALL, x, y, color::FAINT, &l); + y += small; + } + } let here = if f.guests.is_empty() { "No friends here yet.".to_owned() } else { @@ -1192,7 +1227,7 @@ pub mod pause { for (line, tint) in lines.into_iter().flatten() { let line = ui.fit(Face::Regular, SMALL, &line, cw); ui.text(Face::Regular, SMALL, x, y, tint, &line); - y += (SMALL * 1.45).round(); + y += small; } y + 12.0 } diff --git a/crates/horizon-client/src/game/friends.rs b/crates/horizon-client/src/game/friends.rs index 57a2c09de..90e5b82a2 100644 --- a/crates/horizon-client/src/game/friends.rs +++ b/crates/horizon-client/src/game/friends.rs @@ -1,11 +1,13 @@ //! Play with friends, host side: "Invite friends" opens the world to LAN if //! it isn't (with Open to LAN's defaults) and shares that port behind an -//! invite code through the relay (horizon-friends). The integrated server is -//! the LAN one, unchanged: tunnelled guests are LAN guests that connect from -//! the loopback address. +//! invite code (horizon-friends). The code holds this computer's addresses +//! and the key, so friends join with no server of ours; a relay the player +//! configured adds a short code and a fallback. The integrated server is the +//! LAN one, unchanged: tunnelled guests are LAN guests that connect from the +//! loopback address. use super::{Game, lan::LanSettings}; use horizon_client::{Result, front::FriendsView, text::Text}; -use horizon_friends::{Code, Host, HostConfig, HostEvent, HostState, PathMode}; +use horizon_friends::{Host, HostConfig, HostEvent, PathMode, host::DEFAULT_PORT, reach, stun}; use horizon_protocol::{GAME_VERSION, PROTOCOL_VERSION}; use std::time::{Duration, Instant}; @@ -13,21 +15,46 @@ pub(super) struct Sharing { host: Host, /// Sharing opened the world to LAN, so stopping closes it again. opened_lan: bool, - code: Option, - /// Wrong codes tried against the current code. + code: Option, + /// Wrong codes tried so far. wrong: u32, - /// Sessions carried directly and through the relay so far. - paths: (u32, u32), notice: Option, copied: Option, + /// Sessions carried directly and through the relay so far. + paths: (u32, u32), } pub const HELP: &[&str] = &[ - "friends host share the open world behind an invite code (needs HORIZON_RELAY_URL)", + "friends host share the open world behind an invite code", "friends stop stop sharing", - "friends status the code, the relay state and the guests", + "friends status the code, how friends reach this host, the guests", ]; +/// The relay the player set (Join a friend's Relay field, `friendsRelay` +/// in horizon.txt), else `HORIZON_RELAY_URL`. None by default. +pub(super) fn relay_setting() -> Option { + let dir = std::env::current_dir().ok()?; + horizon_client::ui_theme::preference(&dir, "friendsRelay") + .filter(|r| !r.is_empty()) + .or_else(horizon_friends::relay_url) +} + +/// `HORIZON_STUN_SERVERS`, else `friendsStun` in horizon.txt, else the defaults. +fn stun_servers() -> Vec { + if std::env::var_os("HORIZON_STUN_SERVERS").is_some() { + return stun::servers_from_env(); + } + let dir = std::env::current_dir().unwrap_or_default(); + match horizon_client::ui_theme::preference(&dir, "friendsStun") { + Some(list) => stun::parse_servers(&list), + None => stun::servers_from_env(), + } +} + +fn env_flag(name: &str, default: bool) -> bool { + std::env::var(name).map_or(default, |v| v != "0") +} + impl Game<'_> { /// Start sharing the open world. pub(super) fn friends_start(&mut self) -> Result<()> { @@ -37,8 +64,6 @@ impl Game<'_> { if self.remote.is_some() || self.title.is_some() { return Err("open a singleplayer world first".into()); } - let relay = horizon_friends::relay_url() - .ok_or("inviting friends is not available yet in this build")?; let opened_lan = self.lan.is_none(); if opened_lan { // ShareToLanScreen's defaults, as the world options screen offers them. @@ -50,11 +75,22 @@ impl Game<'_> { } let port = self.lan_port().ok_or("the world isn't open to LAN")?; let host = match Host::start(HostConfig { - relay, lan: std::net::SocketAddr::from(([127, 0, 0, 1], port)), protocol: PROTOCOL_VERSION, game: GAME_VERSION.to_owned(), + relay: relay_setting(), path: PathMode::from_env(), + port: std::env::var("HORIZON_FRIENDS_PORT") + .ok() + .and_then(|p| p.parse().ok()) + .unwrap_or(DEFAULT_PORT), + reach: reach::Options { + // HORIZON_FRIENDS_UPNP=0 leaves the router alone. + map_port: env_flag("HORIZON_FRIENDS_UPNP", true), + stun: stun_servers(), + // Both ends on one machine (tests). + loopback: env_flag("HORIZON_FRIENDS_LOOPBACK", false), + }, }) { Ok(h) => h, Err(e) => { @@ -69,15 +105,15 @@ impl Game<'_> { opened_lan, code: None, wrong: 0, - paths: (0, 0), notice: None, copied: None, + paths: (0, 0), }); Ok(()) } - /// Stop sharing: the code ends; the world closes to LAN again if sharing - /// opened it. + /// Stop sharing: the code ends (direct port closed, router mapping + /// deleted); the world closes to LAN again if sharing opened it. pub(super) fn friends_stop(&mut self) { let Some(mut sharing) = self.friends.take() else { return; @@ -97,44 +133,37 @@ impl Game<'_> { } } - /// New codes and the relay's state, once a tick and while the pause menu - /// is drawn. + /// New codes and sessions, once a tick and while the pause menu is drawn. pub(super) fn tick_friends(&mut self) { let Some(sharing) = self.friends.as_mut() else { return; }; - let mut announce = None; + let mut announce = false; for event in sharing.host.poll() { match event { HostEvent::Code(code) => { - if sharing.code.is_some() { - sharing.notice = - Some(if sharing.wrong >= horizon_friends::host::MAX_WRONG { - "Someone kept trying a wrong code, so the code changed.".to_owned() - } else { - "The invite service restarted, so the code changed.".to_owned() - }); + if sharing.code.is_some() && sharing.wrong >= horizon_friends::host::MAX_WRONG { + sharing.notice = Some( + "Someone kept trying a wrong short code, so it changed.".to_owned(), + ); + sharing.wrong = 0; } - sharing.wrong = 0; - announce = Some(code.to_string()); + announce = sharing.code.is_none(); sharing.code = Some(code); } HostEvent::WrongCode { count } => { sharing.wrong = count; - sharing.notice = Some(format!("Someone tried a wrong code ({count} of 5).")); + sharing.notice = Some("Someone tried a wrong code.".to_owned()); } HostEvent::Connected { direct: true, .. } => sharing.paths.0 += 1, HostEvent::Connected { direct: false, .. } => sharing.paths.1 += 1, HostEvent::Disconnected { .. } => {} } } - if let HostState::Retrying(_) = sharing.host.state() { - sharing.code = None; - } - if let Some(code) = announce { - self.system_message(Text::literal(format!( - "Friends can join with the code {code}" - ))); + if announce { + self.system_message(Text::literal( + "Your invite code is ready in the pause menu: copy it and send it to your friends.", + )); } } @@ -143,7 +172,7 @@ impl Game<'_> { return; }; use horizon_client::clipboard::Clipboard; - self.clipboard.set(&code.to_string()); + self.clipboard.set(&code); if let Some(s) = self.friends.as_mut() { s.copied = Some(Instant::now()); } @@ -159,21 +188,33 @@ impl Game<'_> { let Some(s) = &self.friends else { return FriendsView { shown: self.remote.is_none(), - available: horizon_friends::relay_url().is_some(), ..FriendsView::default() }; }; - let status = match s.host.state() { - HostState::Registering => "Getting a code…".to_owned(), - HostState::Retrying(e) => format!("Couldn't reach the invite service; retrying ({e})"), - HostState::Sharing(_) | HostState::Stopped => String::new(), + let state = s.host.state(); + let mut status = if s.code.is_none() { + "Finding how friends can reach you…".to_owned() + } else { + state.summary.clone() }; + if let Some(short) = &state.short { + status.push_str(&format!(" Short code for the relay: {short}.")); + } + if let Some(problem) = &state.relay_problem { + status.push(' '); + status.push_str(problem); + } + let reachable = matches!( + state.verdict, + Some(reach::Verdict::Mapped(_) | reach::Verdict::Public) + ) || state.short.is_some(); FriendsView { shown: true, - available: true, sharing: true, - code: s.code.as_ref().map(Code::to_string), + code: s.code.clone(), status, + reachable, + help: (!reachable && s.code.is_some()).then(|| reach::HELP_URL.to_owned()), guests, notice: s.notice.clone(), copied: s @@ -200,15 +241,15 @@ impl Game<'_> { Some("status") => { self.tick_friends(); let view = self.friends_view(); - let state = self - .friends - .as_ref() - .map(|s| format!("{:?}", s.host.state())); + let state = self.friends.as_ref().map(|s| s.host.state()); Ok(Some(json!({ - "available": view.available, "sharing": view.sharing, "code": view.code, - "state": state, + "short": state.as_ref().and_then(|s| s.short.as_ref().map(ToString::to_string)), + "summary": view.status, + "reachable": view.reachable, + "verdict": state.as_ref().and_then(|s| s.verdict.as_ref().map(|v| format!("{v:?}"))), + "direct_port": state.as_ref().map(|s| s.port), "sessions": self.friends.as_ref().map_or(0, |s| s.host.sessions()), "direct": self.friends.as_ref().map_or(0, |s| s.paths.0), "relayed": self.friends.as_ref().map_or(0, |s| s.paths.1), diff --git a/crates/horizon-client/src/ui_theme.rs b/crates/horizon-client/src/ui_theme.rs index 8b8a74f65..c554f44f9 100644 --- a/crates/horizon-client/src/ui_theme.rs +++ b/crates/horizon-client/src/ui_theme.rs @@ -71,7 +71,30 @@ pub fn save_preferences(dir: &Path) { MenuStyle::Horizon => "horizon", MenuStyle::Classic => "classic", }; - let _ = std::fs::write(dir.join("horizon.txt"), format!("menuStyle:{value}\n")); + set_preference(dir, "menuStyle", Some(value)); +} +/// A Horizon-only preference from `horizon.txt` (`key:value` lines). +pub fn preference(dir: &Path, key: &str) -> Option { + let text = std::fs::read_to_string(dir.join("horizon.txt")).ok()?; + text.lines().find_map(|l| { + let (k, v) = l.split_once(':')?; + (k.trim() == key).then(|| v.trim().to_owned()) + }) +} +/// Set (or with None remove) one preference, keeping the others. +pub fn set_preference(dir: &Path, key: &str, value: Option<&str>) { + let text = std::fs::read_to_string(dir.join("horizon.txt")).unwrap_or_default(); + let mut lines: Vec = text + .lines() + .filter(|l| l.split_once(':').is_none_or(|(k, _)| k.trim() != key)) + .map(str::to_owned) + .collect(); + if let Some(v) = value { + lines.push(format!("{key}:{v}")); + } + let mut out = lines.join("\n"); + out.push('\n'); + let _ = std::fs::write(dir.join("horizon.txt"), out); } /// The dark palette (`horizon_theme::DARK`) in the HUD's colour encoding, plus the From c9b3a06cf7b4335878e54ab85450d4b2e93d37a5 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 01:06:54 +0200 Subject: [PATCH 37/97] Launcher lockfile: horizon-friends' if-addrs Co-Authored-By: Claude Opus 5.5 --- launcher/Cargo.lock | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/launcher/Cargo.lock b/launcher/Cargo.lock index 262ee3628..427662703 100644 --- a/launcher/Cargo.lock +++ b/launcher/Cargo.lock @@ -2636,6 +2636,7 @@ dependencies = [ "chacha20poly1305", "getrandom 0.3.4", "hkdf", + "if-addrs", "serde", "serde_json", "sha2 0.10.9", @@ -2892,6 +2893,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 = "image" version = "0.25.10" From 9927d06049c27fcf0c4da50fca901be80f4daf7e Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:41:42 +0200 Subject: [PATCH 38/97] Controllers: focus navigation in menus, on-screen keyboard, menu navigation option Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/game/books.rs | 9 +- crates/horizon-client/src/game/lan_screen.rs | 27 +- crates/horizon-client/src/game/pad.rs | 15 +- crates/horizon-client/src/game/pad_menu.rs | 714 +++++++++++++++++-- crates/horizon-client/src/game/remote.rs | 33 +- crates/horizon-client/src/game/sign_edit.rs | 21 +- crates/horizon-client/src/gamepad.rs | 300 +++++++- crates/horizon-client/src/lib.rs | 1 + crates/horizon-client/src/multiplayer.rs | 8 + crates/horizon-client/src/options_horizon.rs | 2 + crates/horizon-client/src/options_ui.rs | 30 + crates/horizon-client/src/osk.rs | 412 +++++++++++ crates/horizon-client/src/screen_draw.rs | 9 + crates/horizon-client/src/title.rs | 8 + crates/horizon-client/src/ui.rs | 12 +- crates/horizon-client/src/ui_theme.rs | 40 +- crates/horizon-client/src/widgets.rs | 85 ++- 17 files changed, 1596 insertions(+), 130 deletions(-) create mode 100644 crates/horizon-client/src/osk.rs diff --git a/crates/horizon-client/src/game/books.rs b/crates/horizon-client/src/game/books.rs index dc5c7cdf1..7bf687899 100644 --- a/crates/horizon-client/src/game/books.rs +++ b/crates/horizon-client/src/game/books.rs @@ -139,6 +139,11 @@ impl Game<'_> { PhysicalKey::Code(k) => Some(k), _ => None, }; + self.book_input(key, event.text.as_deref()); + } + /// A key and the text it typed in the open book (the keyboard, or a + /// controller's on-screen keyboard). + pub(super) fn book_input(&mut self, key: Option, text: Option<&str>) { match self.book.as_mut() { Some(BookScreen::View { .. }) => match key { Some(KeyCode::Escape) => self.close_book(), @@ -167,7 +172,7 @@ impl Game<'_> { } } _ => { - if let Some(typed) = event.text.as_ref() { + if let Some(typed) = text { self.text_selection.take(BOOK_TITLE, title); for c in typed.chars().filter(|c| !c.is_control()) { if title.chars().count() < 15 { @@ -193,7 +198,7 @@ impl Game<'_> { self.type_into_page("\n") } _ => { - if let Some(typed) = event.text.as_ref().map(|t| t.to_string()) { + if let Some(typed) = text { let typed: String = typed.chars().filter(|c| !c.is_control()).collect(); if !typed.is_empty() { self.take_page_selection(); diff --git a/crates/horizon-client/src/game/lan_screen.rs b/crates/horizon-client/src/game/lan_screen.rs index c36ce5d84..f0eb57b3e 100644 --- a/crates/horizon-client/src/game/lan_screen.rs +++ b/crates/horizon-client/src/game/lan_screen.rs @@ -333,13 +333,26 @@ impl Game<'_> { o.port.shortcut(shortcut, &mut self.clipboard); return; } - if !o.port.key(key, ctrl, false) - && !ctrl - && let Some(text) = &event.text - { - let digits: String = text.chars().filter(char::is_ascii_digit).collect(); - if !digits.is_empty() { - o.port.insert_text(&digits); + if !o.port.key(key, ctrl, false) && !ctrl { + self.world_options_text(event.text.as_deref()); + } + } + /// Digits typed into the port field (the keyboard, or a controller's + /// on-screen keyboard), and its backspace. + pub(super) fn world_options_text(&mut self, text: Option<&str>) { + let Some(o) = self.world_options.as_mut().filter(|o| o.port.focused) else { + return; + }; + match text { + Some(text) => { + let digits: String = text.chars().filter(char::is_ascii_digit).collect(); + if !digits.is_empty() { + o.port.insert_text(&digits); + } + } + None => { + o.port + .key(winit::keyboard::KeyCode::Backspace, false, false); } } } diff --git a/crates/horizon-client/src/game/pad.rs b/crates/horizon-client/src/game/pad.rs index 2f050fdec..111567117 100644 --- a/crates/horizon-client/src/game/pad.rs +++ b/crates/horizon-client/src/game/pad.rs @@ -255,7 +255,7 @@ impl Game<'_> { if down && !self.pad_focused() { return Ok(()); } - let playing = self.title.is_none() && self.screen == Screen::Playing; + let playing = !self.pad_in_menu(); if down && playing && !self.captured && self.focused { // Like a click into the window: take the pointer. self.capture(true); @@ -340,11 +340,7 @@ impl Game<'_> { /// The left stick as the move vector, while playing. pub(super) fn pad_move(&self) -> Option<[f32; 2]> { let settings = &self.settings.controller; - if !settings.enabled - || self.title.is_some() - || self.screen != Screen::Playing - || !self.pad_focused() - { + if !settings.enabled || self.pad_in_menu() || !self.pad_focused() { return None; } gamepad::move_vector(self.pad.state.left, settings.move_deadzone) @@ -353,12 +349,7 @@ impl Game<'_> { /// The right stick turns the view, once per frame (`Entity.turn`). pub(super) fn pad_look(&mut self, seconds: f32) { let settings = &self.settings.controller; - if !settings.enabled - || self.title.is_some() - || self.screen != Screen::Playing - || self.player.is_none() - || !self.pad_focused() - { + if !settings.enabled || self.pad_in_menu() || self.player.is_none() || !self.pad_focused() { return; } // A long frame (a hitch) must not spin the view. diff --git a/crates/horizon-client/src/game/pad_menu.rs b/crates/horizon-client/src/game/pad_menu.rs index 8047e889a..a321697ef 100644 --- a/crates/horizon-client/src/game/pad_menu.rs +++ b/crates/horizon-client/src/game/pad_menu.rs @@ -1,17 +1,29 @@ //! A controller in menus, screens and inventories (Horizon's own; -//! docs/controllers.md): a virtual cursor the left stick moves and the -//! D-pad steps between slots and buttons, with A, X and the stick feeding -//! the screens the same pointer events a mouse sends. Every screen keeps -//! its mouse behaviour (drags, sliders, scrollbars) with no pad code of its -//! own. +//! docs/controllers.md). Two ways to drive them, picked in the controller +//! options: +//! +//! - **Focus** (console-style): a highlight steps between the widgets, list +//! rows, fields and slots each screen registers (`widgets::target_as`) +//! with vanilla's arrow-key navigation; A presses the focused one, the +//! bumpers switch tabs, left/right move a focused slider, A on a text field +//! opens the on-screen keyboard (`osk`). +//! - **Pointer**: a virtual cursor the left stick moves and the D-pad steps +//! between slots and buttons. +//! +//! Both feed the screens the same pointer events a mouse sends (the pointer +//! sits on the focused widget, hidden), so every screen keeps its mouse +//! behaviour (drags, sliders, scrollbars, hover highlights) with no pad code +//! of its own. A screen with nothing registered falls back to the pointer, +//! and a right stick click swaps modes for the open screen. use super::{Game, Screen}; use horizon_client::{ Result, creative::Creative, - gamepad::{self, Button}, + gamepad::{self, Button, MenuNav, Rect}, hud::{HudBatch, rgba}, options_ui::{Event, Page}, - widgets, + osk::{self, Keyboard}, + widgets::{self, Kind, Target}, }; use std::time::Instant; use winit::{ @@ -19,7 +31,7 @@ use winit::{ dpi::PhysicalPosition, event::{DeviceId, ElementState, MouseButton, MouseScrollDelta, TouchPhase, WindowEvent}, event_loop::ActiveEventLoop, - keyboard::KeyCode, + keyboard::{KeyCode, NamedKey}, }; /// D-pad auto-repeat: the first step at once, the next after a pause. @@ -27,6 +39,20 @@ const REPEAT_DELAY: f32 = 0.35; const REPEAT_EVERY: f32 = 0.09; /// Lines per second the right stick scrolls at full tilt. const SCROLL_SPEED: f32 = 12.0; +/// How far the stick must lean to step focus. +const STICK_STEP: f32 = 0.55; +/// Scrolls a step may try to reveal the next row of a list. +const SCROLL_TRIES: u8 = 4; + +/// A focus step that ran off the visible part of a list: the list was +/// scrolled and the step runs again once a new frame is drawn. +#[derive(Clone, Copy)] +struct Pending { + button: Button, + from: Rect, + generation: u64, + tries: u8, +} #[derive(Default)] pub(super) struct MenuCursor { @@ -45,12 +71,31 @@ pub(super) struct MenuCursor { os_hidden: bool, /// Polls since a menu opened (its widgets are drawn after one frame). open_polls: u32, + /// Focus mode: the focused target as last drawn. + focus: Option, + /// The left stick's step direction last poll. + stick: Option