From 8d55af7caeb3dec092610b27f730c8a51e5566a3 Mon Sep 17 00:00:00 2001 From: yvonne Date: Mon, 19 Oct 2026 19:15:08 +0200 Subject: [PATCH] Mods: capability storage, a quota'd per-mod key/value folder A mod with capability storage gets get(key)/set(key, value)/delete(key), backed by real files beside horizon-mods/ (.horizon-mod-data//, 4 MiB quota per mod). Keys are a single path segment so they can't leave the mod's own directory. Unlike in-memory mod state, this survives a cargo-horizon-mod dev reload, since it's keyed by the mod's path and id rather than its Store. --- crates/horizon-mod-sdk/src/lib.rs | 4 +- crates/horizon-mod-sdk/wit/horizon.wit | 12 ++++ crates/horizon-mods/src/manifest.rs | 15 +++- crates/horizon-mods/src/runtime.rs | 82 +++++++++++++++++++--- crates/horizon-mods/tests/guest/src/lib.rs | 19 +++-- crates/horizon-mods/tests/sandbox.rs | 53 +++++++++++++- docs/mods.md | 13 ++-- 7 files changed, 173 insertions(+), 25 deletions(-) diff --git a/crates/horizon-mod-sdk/src/lib.rs b/crates/horizon-mod-sdk/src/lib.rs index 428638c6d..ccfdb7947 100644 --- a/crates/horizon-mod-sdk/src/lib.rs +++ b/crates/horizon-mod-sdk/src/lib.rs @@ -21,7 +21,7 @@ //! ``` //! //! Every interface but `log` is a capability: list the ones the mod uses in -//! `horizon-mod.toml` (`game-read`, `chat`, `hud`). +//! `horizon-mod.toml` (`game-read`, `chat`, `hud`, `storage`). wit_bindgen::generate!({ path: "wit", @@ -32,7 +32,7 @@ wit_bindgen::generate!({ }); pub use exports::horizon::mods::events::{Guest as __Guest, Registration}; -pub use horizon::mods::{chat, game, hud, log}; +pub use horizon::mods::{chat, game, hud, log, storage}; /// The game's calls into a mod. Only the hooks [`Registration`] asks for /// are called; the others may stay as their defaults. diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit index 749183bbd..972389a82 100644 --- a/crates/horizon-mod-sdk/wit/horizon.wit +++ b/crates/horizon-mod-sdk/wit/horizon.wit @@ -66,6 +66,17 @@ interface hud { clear: func(); } +/// Capability `storage`: a per-mod folder of small key/value files, quota'd +/// (docs/mods.md). Keys are `[a-z0-9_.-]{1,64}`, one path segment. +interface storage { + /// None if `key` has never been `set`, or the key is not well-formed. + get: func(key: string) -> option>; + /// Errs on a malformed key or over quota (bytes for the whole mod). + set: func(key: string, value: list) -> result<_, string>; + /// No error if `key` was already absent. + delete: func(key: string); +} + /// What the game calls. Only the hooks `init` asks for are ever called. interface events { record registration { @@ -93,5 +104,6 @@ world horizon-mod { import game; import chat; import hud; + import storage; export events; } diff --git a/crates/horizon-mods/src/manifest.rs b/crates/horizon-mods/src/manifest.rs index e44673a41..44cdbd418 100644 --- a/crates/horizon-mods/src/manifest.rs +++ b/crates/horizon-mods/src/manifest.rs @@ -64,15 +64,17 @@ pub enum Capability { GameRead, Chat, Hud, + Storage, /// New blocks and items from the mod's `data/` (API 0.2): no WIT /// interface, the game reads them before the world loads. Registries, } impl Capability { - pub const ALL: [Capability; 4] = [ + pub const ALL: [Capability; 5] = [ Capability::GameRead, Capability::Chat, Capability::Hud, + Capability::Storage, Capability::Registries, ]; /// The WIT interface it grants, in `horizon:mods`. @@ -81,6 +83,7 @@ impl Capability { Capability::GameRead => "game", Capability::Chat => "chat", Capability::Hud => "hud", + Capability::Storage => "storage", Capability::Registries => "registries", } } @@ -90,6 +93,7 @@ impl Capability { Capability::GameRead => "see your position, health and the time", Capability::Chat => "show you chat messages", Capability::Hud => "draw text on your screen", + Capability::Storage => "save its own settings to disk", Capability::Registries => "add blocks and items to your worlds", } } @@ -119,6 +123,7 @@ impl fmt::Display for Capability { Capability::GameRead => "game-read", Capability::Chat => "chat", Capability::Hud => "hud", + Capability::Storage => "storage", Capability::Registries => "registries", }; f.write_str(name) @@ -338,6 +343,14 @@ capabilities = ["game-read", "hud"] ); assert!(m.check_imports(["wasi:filesystem/types@0.2.0"]).is_err()); assert!(m.check_imports(["horizon:mods/game@0.2.0"]).is_err()); + let storage = m.check_imports(["horizon:mods/storage@0.1.0"]); + assert_eq!( + storage, + Err("uses capability storage, missing from horizon-mod.toml".into()) + ); + let with_storage = EXAMPLE.replace("\"hud\"", "\"hud\", \"storage\""); + let m = Manifest::parse(&with_storage).unwrap(); + assert_eq!(m.check_imports(["horizon:mods/storage@0.1.0"]), Ok(())); } #[test] diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs index f8a6e5865..e50d7ddcc 100644 --- a/crates/horizon-mods/src/runtime.rs +++ b/crates/horizon-mods/src/runtime.rs @@ -23,7 +23,7 @@ pub use bindings::horizon::mods::{ use bindings::{ HorizonMod, exports::horizon::mods::events::Registration, - horizon::mods::{chat, game, hud, log as mod_log}, + horizon::mods::{chat, game, hud, log as mod_log, storage}, }; /// A mod's linear memory cap. @@ -38,6 +38,11 @@ const FUEL_EVENT: u64 = 100_000_000; const CHAT_PER_CALL: usize = 8; const HUD_LINES: usize = 16; const LINE_CHARS: usize = 256; +/// Total bytes a mod's `storage` may hold on disk, across all its keys. +const STORAGE_QUOTA: u64 = 4 << 20; +/// A mod's data, beside its `horizon-mods` folder (`find`'s `path.parent()` +/// never has a manifest there, so `find` never mistakes it for a mod). +const STORAGE_DIR: &str = ".horizon-mod-data"; /// What mods may read of the game, copied once per tick by the game. #[derive(Clone, Debug, Default)] @@ -97,6 +102,8 @@ struct State { snapshot: Arc, out: Vec, panel: Option, + /// Capability `storage`'s folder; made on first `set`. + data_dir: PathBuf, limits: StoreLimits, } @@ -156,13 +163,14 @@ impl Mods { // Content is read before the world loads; a mod whose // content is refused stays off, with the reason. let content = crate::Content::read(path, &package.manifest); - entry.status = match content.and_then(|_| mods.start(&package, &reserved)) { - Ok(run) => { - entry.run = run; - Status::Running - } - Err(e) => Status::Failed(e), - }; + entry.status = + match content.and_then(|_| mods.start(path, &package, &reserved)) { + Ok(run) => { + entry.run = run; + Status::Running + } + Err(e) => Status::Failed(e), + }; } } } @@ -189,8 +197,11 @@ impl Mods { /// Starts a mod's code; `Ok(None)` for a content-only mod, which has /// nothing to run (the game reads its content before the world loads). + /// `path` is the mod's own `.hmod` or folder, for capability `storage`'s + /// per-mod directory. fn start( &mut self, + path: &Path, package: &Package, reserved: &dyn Fn(&str) -> bool, ) -> Result, String> { @@ -217,12 +228,18 @@ impl Mods { .map(|(name, _)| name.to_string()) .collect(); m.check_imports(imports.iter().map(String::as_str))?; + let data_dir = path + .parent() + .unwrap_or(Path::new(".")) + .join(STORAGE_DIR) + .join(&m.id); let state = State { name: m.name.clone(), id: m.id.clone(), snapshot, out: Vec::new(), panel: None, + data_dir, limits: StoreLimitsBuilder::new() .memory_size(MEMORY) .instances(16) @@ -402,9 +419,10 @@ impl Mods { any = true; self.entries[i].modified = now; self.entries[i].run = None; - let started = Package::read(&self.entries[i].path).and_then(|p| { + let path = self.entries[i].path.clone(); + let started = Package::read(&path).and_then(|p| { self.entries[i].manifest = Some(p.manifest.clone()); - self.start(&p, &reserved) + self.start(&path, &p, &reserved) }); let entry = &mut self.entries[i]; let id = entry.manifest.as_ref().map_or("?", |m| m.id.as_str()); @@ -504,3 +522,47 @@ impl hud::Host for State { self.panel = None; } } +impl storage::Host for State { + fn get(&mut self, key: String) -> Option> { + storage_key_ok(&key) + .then(|| std::fs::read(self.data_dir.join(&key)).ok()) + .flatten() + } + fn set(&mut self, key: String, value: Vec) -> Result<(), String> { + if !storage_key_ok(&key) { + return Err(format!("{key:?} is not [a-z0-9_.-]{{1,64}}")); + } + // Everything already on disk but the file this call replaces. + let used: u64 = std::fs::read_dir(&self.data_dir) + .into_iter() + .flatten() + .flatten() + .filter(|e| e.file_name().to_string_lossy() != key) + .filter_map(|e| e.metadata().ok()) + .map(|m| m.len()) + .sum(); + if used + value.len() as u64 > STORAGE_QUOTA { + return Err(format!( + "would use over {} MiB of storage", + STORAGE_QUOTA >> 20 + )); + } + std::fs::create_dir_all(&self.data_dir).map_err(|e| e.to_string())?; + std::fs::write(self.data_dir.join(&key), value).map_err(|e| e.to_string()) + } + fn delete(&mut self, key: String) { + if storage_key_ok(&key) { + let _ = std::fs::remove_file(self.data_dir.join(&key)); + } + } +} + +/// A storage key: one path segment of `[a-z0-9_.-]{1,64}`, not `.` or `..`. +/// No `/`, so a key can never leave the mod's own directory. +fn storage_key_ok(key: &str) -> bool { + let chars_ok = (1..=64).contains(&key.len()) + && key + .bytes() + .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"_.-".contains(&b)); + chars_ok && key != "." && key != ".." +} diff --git a/crates/horizon-mods/tests/guest/src/lib.rs b/crates/horizon-mods/tests/guest/src/lib.rs index 86caf17bf..1a21f5bdf 100644 --- a/crates/horizon-mods/tests/guest/src/lib.rs +++ b/crates/horizon-mods/tests/guest/src/lib.rs @@ -1,7 +1,8 @@ //! A mod for the runtime's tests: `/spin` loops forever, `/panic` panics, -//! `/grow` asks for a gigabyte, `/hello` chats; `tick` and `frame` do -//! nothing, to measure the cost of a call. -use horizon_mod_sdk::{Mod, Registration, chat}; +//! `/grow` asks for a gigabyte, `/hello` chats, `/save` and `/load` exercise +//! capability `storage`; `tick` and `frame` do nothing, to measure the cost +//! of a call. +use horizon_mod_sdk::{Mod, Registration, chat, storage}; struct Guest { ticks: u64, @@ -9,7 +10,7 @@ struct Guest { impl Mod for Guest { fn init() -> Result<(Self, Registration), String> { - let hooks = ["spin", "panic", "grow", "hello"] + let hooks = ["spin", "panic", "grow", "hello", "save", "load"] .into_iter() .fold(Registration::new(), Registration::command) .on_tick() @@ -33,6 +34,16 @@ impl Mod for Guest { let big = std::hint::black_box(vec![1u8; 1 << 30]); Ok(Some(format!("{}", big.len()))) } + "save" => { + storage::set("note", args.as_bytes())?; + Ok(Some("saved".into())) + } + "load" => { + let text = + storage::get("note").map(|bytes| String::from_utf8_lossy(&bytes).into_owned()); + chat::show(text.as_deref().unwrap_or("(empty)")); + Ok(None) + } _ => { chat::show(&format!("hello {args} after {} ticks", self.ticks)); Ok(None) diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs index 6aa45e5cc..d76db2a60 100644 --- a/crates/horizon-mods/tests/sandbox.rs +++ b/crates/horizon-mods/tests/sandbox.rs @@ -15,7 +15,7 @@ id = "test_guest" name = "Test Guest" version = "0.1.0" api = "0.1" -capabilities = ["chat"] +capabilities = ["chat", "storage"] "#; /// Builds both mods once and writes their `.hmod` files; returns the folder. @@ -133,7 +133,7 @@ fn undeclared_capabilities_are_refused() { .unwrap() .wasm .expect("the guest has code"); - let manifest = GUEST_MANIFEST.replace("[\"chat\"]", "[]"); + let manifest = GUEST_MANIFEST.replace("\"chat\", ", ""); std::fs::write(dir.join("horizon-mod.toml"), manifest).unwrap(); std::fs::write(dir.join("mod.wasm"), wasm).unwrap(); let mods = Mods::load(&[dir], |_| true, |_| false); @@ -207,6 +207,55 @@ fn hot_reload_restarts_a_changed_mod() { assert_eq!(mods.drain(), [chat]); } +#[test] +fn storage_persists_across_reload() { + let dir = mods_dir().join("storage_reload"); + std::fs::create_dir_all(&dir).unwrap(); + let path = dir.join("guest.hmod"); + std::fs::copy(mods_dir().join("horizon_mods_test_guest.hmod"), &path).unwrap(); + let mut mods = Mods::load(std::slice::from_ref(&path), |_| true, |_| false); + assert!(mods.command("save remembered")); + let saved = Output::Feedback { + text: "saved".into(), + error: false, + }; + assert_eq!(mods.drain(), [saved]); + + // A rebuild (hot_reload_restarts_a_changed_mod's pattern): a fresh Store, + // but the same on-disk data directory. + let later = std::time::SystemTime::now() + std::time::Duration::from_secs(5); + std::fs::File::options() + .write(true) + .open(&path) + .unwrap() + .set_modified(later) + .unwrap(); + assert!(mods.reload_changed(|_| false)); + + assert!(mods.command("load")); + let chat = Output::Chat { + name: "Test Guest".into(), + text: "remembered".into(), + }; + assert_eq!(mods.drain(), [chat]); +} + +#[test] +fn storage_quota_is_enforced() { + let dir = mods_dir().join("storage_quota"); + std::fs::create_dir_all(&dir).unwrap(); + let path = dir.join("guest.hmod"); + std::fs::copy(mods_dir().join("horizon_mods_test_guest.hmod"), &path).unwrap(); + let mut mods = Mods::load(std::slice::from_ref(&path), |_| true, |_| false); + let over_quota = "a".repeat((4 << 20) + 1024); + assert!(mods.command(&format!("save {over_quota}"))); + let refused = Output::Feedback { + text: "would use over 4 MiB of storage".into(), + error: true, + }; + assert_eq!(mods.drain(), [refused]); +} + /// `cargo test -p horizon-mods --release -- --ignored --nocapture`: the /// cost of the per-tick and per-frame hooks (docs/mods.md, Performance). #[test] diff --git a/docs/mods.md b/docs/mods.md index 758ac7af4..2b0b7076c 100644 --- a/docs/mods.md +++ b/docs/mods.md @@ -11,7 +11,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3. | Part | Where | State | |---|---|---| -| The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud; tick, frame, chat and command hooks | +| The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage; tick, frame, chat and command hooks | | SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 | | Example mod | `crates/horizon-mod-sdk/examples/coords-hud` | coordinates, facing and time HUD, `/where`, `/coords` | | Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model | @@ -82,6 +82,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3. | `game` | `game-read` | `get-player()`: x y z, yaw, pitch, health, food, dimension; `get-clock()`: game time, day time | | `chat` | `chat` | `show(text)`: a line only the local player sees, after the mod's name (8 per call) | | `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters | +| `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of files, 4 MiB total | | Hook (export) | When | |---|---| @@ -111,7 +112,6 @@ loading. Ordered by what the first native ports need ([research](research/java-m | `ui` | widgets: text, item icons, lists, a screen the mod owns, a settings page in Options > Mods | built on `ui_theme` so it matches the menus | | `world-read` | blocks and biomes around the player, within the render distance | minimaps, schematics | | `render` | world-space lines, boxes and ghost blocks in a per-frame budget | Litematica-style placement, waypoints | -| `storage` | a per-mod folder of key/value files, quota'd | settings, waypoints | | `registries` | new blocks, items, entities and recipes, mostly data: JSON models, textures, loot and recipes in the `.hmod`'s `assets/` and `data/` | server side; see [Multiplayer](#multiplayer) | | `server` | world events (block break/place, entity spawn/death, player join), game rules, server commands | runs where the world is simulated | | `net` | a mod's own client↔server channel (custom payloads) | only between the two halves of the same mod | @@ -208,8 +208,8 @@ cargo horizon-mod build # again after an edit: the running game relo `run` starts `horizon-client` (on `PATH`, or `--game PATH`, or `HORIZON_CLIENT`) with `--dev-mod target/horizon-mod/.hmod`. A dev mod is always on, and the game checks its file once a second: rebuild and it restarts -with "Mods reloaded" in chat. Its state starts over (persisted state comes with -`storage`). +with "Mods reloaded" in chat. Its in-memory state starts over; whatever it +saved with capability `storage` survives the reload. ### Template layout @@ -398,8 +398,9 @@ none. 1. Design (this page) and the Java research. 2. SDK, example mod, runtime, `cargo horizon-mod`, the game's Mods page: API 0.1. -3. `keys`, `target`, `inventory-read`, `storage`, `ui`: enough for the first - native ports (zoom presets, AppleSkin-style food HUD, Jade-style tooltips). +3. `storage` (done), `keys`, `target`, `inventory-read`, `ui`: enough for the + first native ports (zoom presets, AppleSkin-style food HUD, Jade-style + tooltips). 4. Launcher Mods tab, the index, signatures; the Mods page shows cost and update state. 5. `recipes`, `world-read`, `render`: recipe viewer and schematics ports.