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/<id>/, 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.
This commit is contained in:
yvonne
2026-10-19 19:15:08 +02:00
parent defaa7cd2a
commit 8d55af7cae
7 changed files with 173 additions and 25 deletions
+2 -2
View File
@@ -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.
+12
View File
@@ -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<list<u8>>;
/// Errs on a malformed key or over quota (bytes for the whole mod).
set: func(key: string, value: list<u8>) -> 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;
}
+14 -1
View File
@@ -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]
+72 -10
View File
@@ -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<Snapshot>,
out: Vec<Output>,
panel: Option<Panel>,
/// 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<Option<Running>, 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<Vec<u8>> {
storage_key_ok(&key)
.then(|| std::fs::read(self.data_dir.join(&key)).ok())
.flatten()
}
fn set(&mut self, key: String, value: Vec<u8>) -> 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 != ".."
}
+15 -4
View File
@@ -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)
+51 -2
View File
@@ -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]
+7 -6
View File
@@ -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/<id>.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.