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:
@@ -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.
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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]
|
||||
|
||||
@@ -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 != ".."
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user