@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-module-macros/src/lib.rs

@@ -0,0 +1,148 @@
+//! Proc-macros for KROMA modules. [`embedded_module!`] finds a module's
+//! `module.json` and `icon.<ext>` by convention - the module root is the parent
+//! of the server crate - and expands to the right `EmbeddedModule` constructor.
+
+use proc_macro::TokenStream;
+use std::path::{Path, PathBuf};
+
+/// Builds the `MODULE` const for a module server crate. Takes no arguments.
+#[proc_macro]
+pub fn embedded_module(_input: TokenStream) -> TokenStream {
+    // The proc-macro runs inside the caller's rustc, so CARGO_MANIFEST_DIR is the
+    // CALLER's crate dir: `<module>/server`, whose parent is the module root.
+    expansion(std::env::var("CARGO_MANIFEST_DIR").ok())
+        .parse()
+        .expect("embedded_module!(): generated a valid const expression")
+}
+
+fn expansion(manifest_dir: Option<String>) -> String {
+    let Some(manifest_dir) = manifest_dir else {
+        return compile_error("embedded_module!(): CARGO_MANIFEST_DIR is not set");
+    };
+    let Some(module_root) = Path::new(&manifest_dir).parent().map(Path::to_path_buf) else {
+        return compile_error("embedded_module!(): the server crate has no parent dir");
+    };
+
+    let manifest_json = module_root.join("module.json");
+    if !manifest_json.exists() {
+        return compile_error(&format!(
+            "embedded_module!(): no module.json at {}",
+            manifest_json.display()
+        ));
+    }
+    let json_path = manifest_json.to_string_lossy();
+
+    // `EmbeddedModule` is emitted unqualified so it resolves against whatever the
+    // caller has in scope; the parsed tokens carry call-site hygiene, so the macro
+    // never has to hardcode a crate path.
+    match find_icon(&module_root) {
+        Some((icon_path, mime)) => {
+            let icon_path = icon_path.to_string_lossy();
+            format!(
+                "EmbeddedModule::with_icon(include_str!({json:?}), include_bytes!({icon:?}), {mime:?})"
+            , json = json_path, icon = icon_path, mime = mime)
+        }
+        None => format!(
+            "EmbeddedModule::iconless(include_str!({json:?}))",
+            json = json_path
+        ),
+    }
+}
+
+fn find_icon(dir: &Path) -> Option<(PathBuf, &'static str)> {
+    const CANDIDATES: &[(&str, &str)] = &[
+        ("svg", "image/svg+xml"),
+        ("png", "image/png"),
+        ("webp", "image/webp"),
+        ("jpg", "image/jpeg"),
+        ("jpeg", "image/jpeg"),
+        ("gif", "image/gif"),
+        ("avif", "image/avif"),
+        ("ico", "image/x-icon"),
+    ];
+    for (ext, mime) in CANDIDATES {
+        let path = dir.join(format!("icon.{ext}"));
+        if path.exists() {
+            return Some((path, mime));
+        }
+    }
+    None
+}
+
+fn compile_error(message: &str) -> String {
+    format!("compile_error!({message:?})")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    struct Scratch(kroma_testing::TempDir);
+
+    impl Scratch {
+        fn new(tag: &str) -> Self {
+            let scratch = Self(kroma_testing::temp_dir(tag));
+            std::fs::create_dir_all(scratch.0.path().join("server")).expect("scratch dir");
+            scratch
+        }
+
+        fn write(&self, name: &str, bytes: &[u8]) {
+            std::fs::write(self.0.path().join(name), bytes).expect("write");
+        }
+
+        fn expand(&self) -> String {
+            expansion(Some(
+                self.0.path().join("server").to_string_lossy().to_string(),
+            ))
+        }
+    }
+
+    #[test]
+    fn a_module_root_with_no_icon_file_is_not_an_error() {
+        assert!(find_icon(Path::new(env!("CARGO_MANIFEST_DIR"))).is_none());
+    }
+
+    #[test]
+    fn a_build_that_names_no_crate_directory_fails_the_compile_by_name() {
+        let out = expansion(None);
+        assert!(out.starts_with("compile_error!"), "{out}");
+        assert!(out.contains("CARGO_MANIFEST_DIR"), "{out}");
+    }
+
+    #[test]
+    fn a_crate_directory_with_nothing_above_it_cannot_hold_a_module() {
+        let out = expansion(Some(String::new()));
+        assert!(out.contains("no parent dir"), "{out}");
+    }
+
+    #[test]
+    fn a_server_crate_with_no_module_beside_it_says_where_it_looked() {
+        let scratch = Scratch::new("no-manifest");
+        let out = scratch.expand();
+        assert!(out.starts_with("compile_error!"), "{out}");
+        assert!(out.contains("module.json"), "{out}");
+    }
+
+    #[test]
+    fn a_module_without_an_icon_still_embeds_its_manifest() {
+        let scratch = Scratch::new("iconless");
+        scratch.write("module.json", br#"{"id":"com.example.demo"}"#);
+
+        let out = scratch.expand();
+        assert!(out.starts_with("EmbeddedModule::iconless("), "{out}");
+        assert!(out.contains("module.json"), "{out}");
+    }
+
+    #[test]
+    fn the_first_icon_extension_that_exists_is_the_one_embedded() {
+        let scratch = Scratch::new("icon");
+        scratch.write("module.json", br#"{"id":"com.example.demo"}"#);
+        scratch.write("icon.png", b"\x89PNG");
+        scratch.write("icon.svg", b"<svg/>");
+
+        let out = scratch.expand();
+        assert!(out.starts_with("EmbeddedModule::with_icon("), "{out}");
+        assert!(out.contains("icon.svg"), "svg outranks png: {out}");
+        assert!(out.contains("\"image/svg+xml\""), "{out}");
+    }
+}

package/rust/kroma-module-manifest/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "kroma-module-manifest"
+version = "0.1.40-canary.0"
+edition = "2021"
+rust-version = "1.88"
+description = "Low-level module manifest/registry/embedded types (below kroma-engine). Modules use the kroma-module-sdk facade; this is the shared manifest layer engine/kernel/wasm build on."
+license = "MIT"
+
+[dependencies]
+# The embedded_module!() proc-macro, re-exported for the below-facade modules.
+kroma-module-macros = { path = "../kroma-module-macros" }
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1" }
+# Semver range checks for versioned module dependencies (dependsOn version reqs).
+semver = "1"

package/rust/kroma-module-manifest/src/compat.rs

@@ -0,0 +1,157 @@
+//! Module <-> server compatibility checks, shared by the supervisor (install /
+//! spawn gate) and the store endpoints (catalog "compatible" flag).
+//!
+//! The RANGE helpers are permissive, mirroring the dependency-range policy in
+//! [`crate::Registry`]: an unparseable declaration or version is treated as
+//! "no constraint" rather than a mismatch, so a typo'd range degrades to
+//! installable instead of bricking the module everywhere. [`engines_satisfied`]
+//! is the exception, and deliberately: a requirement this build cannot even
+//! name is refused rather than ignored.
+
+use std::collections::BTreeMap;
+
+/// The engines this build knows how to check. A module may only require what a
+/// server can verify: ignoring an unknown requirement is how a module gets
+/// installed onto a host that cannot run it, and then fails somewhere else.
+pub const KNOWN_ENGINES: &[&str] = &["server"];
+
+/// A module's `engines` map against what this build provides.
+///
+/// `Err` carries the reason, phrased for an operator. An empty map is no
+/// constraint; a range that will not parse is (like every other range here)
+/// treated as no constraint rather than a refusal.
+pub fn engines_satisfied(
+    engines: &BTreeMap<String, String>,
+    server_version: &str,
+) -> Result<(), String> {
+    for (engine, range) in engines {
+        if !KNOWN_ENGINES.contains(&engine.as_str()) {
+            return Err(format!(
+                "requires an engine this server cannot check: {engine:?} (known: {})",
+                KNOWN_ENGINES.join(", "),
+            ));
+        }
+        if !version_satisfies(Some(range), server_version) {
+            return Err(format!(
+                "requires {engine} {range} (this server is {server_version})",
+            ));
+        }
+    }
+    Ok(())
+}
+
+/// Whether `version` satisfies a declaration that accepts a bare version
+/// (`"0.2.0"`, meaning "at least 0.2.0") or a full dtolnay semver range
+/// (`">=0.2, <0.4"`). `None`, blank and `"*"` all mean "anything".
+pub fn version_satisfies(decl: Option<&str>, version: &str) -> bool {
+    let Some(decl) = decl.map(str::trim).filter(|s| !s.is_empty() && *s != "*") else {
+        return true;
+    };
+    let Ok(server) = semver::Version::parse(version) else {
+        return true;
+    };
+    if let Ok(min) = semver::Version::parse(decl) {
+        return server >= min;
+    }
+    if let Ok(req) = semver::VersionReq::parse(decl) {
+        return req.matches(&server);
+    }
+    true
+}
+
+/// Whether `version` satisfies a dependency `range` (dtolnay semver syntax).
+/// Blank / `"*"` ranges match anything; unparseable inputs never block.
+pub fn range_matches(range: &str, version: &str) -> bool {
+    let range = range.trim();
+    if range.is_empty() || range == "*" {
+        return true;
+    }
+    match (
+        semver::VersionReq::parse(range),
+        semver::Version::parse(version),
+    ) {
+        (Ok(req), Ok(v)) => req.matches(&v),
+        _ => true,
+    }
+}
+
+/// Whether `candidate` is a strictly newer version than `current` (the store's
+/// "update available" test). Falls back to plain inequality when either side
+/// is not semver, so a registry with odd versions still surfaces changes.
+pub fn is_newer(candidate: &str, current: &str) -> bool {
+    match (
+        semver::Version::parse(candidate.trim()),
+        semver::Version::parse(current.trim()),
+    ) {
+        (Ok(c), Ok(i)) => c > i,
+        _ => candidate.trim() != current.trim(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn engines(pairs: &[(&str, &str)]) -> BTreeMap<String, String> {
+        pairs
+            .iter()
+            .map(|(k, v)| ((*k).to_string(), (*v).to_string()))
+            .collect()
+    }
+
+    #[test]
+    fn an_engine_range_is_checked_against_this_server() {
+        assert!(engines_satisfied(&engines(&[("server", ">=0.1.4")]), "0.2.0").is_ok());
+        assert!(engines_satisfied(&engines(&[]), "0.1.0").is_ok());
+
+        let err = engines_satisfied(&engines(&[("server", ">=0.9")]), "0.2.0").unwrap_err();
+        assert!(err.contains("requires server >=0.9"), "{err}");
+        assert!(err.contains("this server is 0.2.0"), "{err}");
+    }
+
+    #[test]
+    fn an_engine_this_build_cannot_check_is_refused_rather_than_ignored() {
+        let err = engines_satisfied(&engines(&[("ffmpeg", ">=6")]), "0.2.0").unwrap_err();
+        assert!(err.contains("cannot check"), "{err}");
+        assert!(err.contains("ffmpeg"), "{err}");
+        assert!(err.contains("known: server"), "{err}");
+    }
+
+    #[test]
+    fn is_newer_compares_semver_then_falls_back() {
+        assert!(is_newer("0.2.0", "0.1.9"));
+        assert!(!is_newer("0.1.9", "0.2.0"));
+        assert!(!is_newer("0.2.0", "0.2.0"));
+        assert!(is_newer("nightly-2", "nightly-1"));
+    }
+
+    #[test]
+    fn bare_min_server_means_at_least() {
+        assert!(version_satisfies(Some("0.1.4"), "0.1.4"));
+        assert!(version_satisfies(Some("0.1.4"), "0.2.0"));
+        assert!(!version_satisfies(Some("0.2.0"), "0.1.4"));
+    }
+
+    #[test]
+    fn ranges_and_wildcards_work() {
+        assert!(version_satisfies(Some(">=0.1, <0.3"), "0.2.9"));
+        assert!(!version_satisfies(Some(">=0.3"), "0.2.9"));
+        assert!(version_satisfies(Some("*"), "0.0.1"));
+        assert!(version_satisfies(Some("  "), "0.0.1"));
+        assert!(version_satisfies(None, "0.0.1"));
+    }
+
+    #[test]
+    fn unparseable_declarations_never_block() {
+        assert!(version_satisfies(Some("not-a-version"), "0.1.4"));
+        assert!(version_satisfies(Some("1.0.0"), "not-a-version"));
+        assert!(range_matches("garbage", "0.1.0"));
+    }
+
+    #[test]
+    fn dependency_ranges() {
+        assert!(range_matches("^0.1.0", "0.1.9"));
+        assert!(!range_matches("^0.1.0", "0.2.0"));
+        assert!(range_matches("*", "9.9.9"));
+    }
+}

package/rust/kroma-module-manifest/src/embedded.rs

@@ -0,0 +1,160 @@
+//! A ready-made [`Module`] backed by a module's embedded `module.json` + icon.
+//!
+//! `include_str!`/`include_bytes!` stay at the module crate so their paths
+//! resolve there — a cross-crate `macro_rules!` would resolve them against
+//! this crate instead.
+
+use crate::{Module, ModuleIcon, ModuleManifest};
+
+#[derive(Clone, Copy)]
+struct EmbeddedIcon {
+    content_type: &'static str,
+    bytes: &'static [u8],
+}
+
+/// A module whose manifest and icon are embedded at compile time.
+#[derive(Clone, Copy)]
+pub struct EmbeddedModule {
+    manifest_json: &'static str,
+    icon: Option<EmbeddedIcon>,
+}
+
+impl EmbeddedModule {
+    /// A module with an embedded SVG icon (the common case).
+    pub const fn new(manifest_json: &'static str, icon_svg: &'static [u8]) -> Self {
+        Self {
+            manifest_json,
+            icon: Some(EmbeddedIcon {
+                content_type: "image/svg+xml",
+                bytes: icon_svg,
+            }),
+        }
+    }
+
+    /// A module with an embedded PNG icon.
+    pub const fn with_png(manifest_json: &'static str, icon_png: &'static [u8]) -> Self {
+        Self {
+            manifest_json,
+            icon: Some(EmbeddedIcon {
+                content_type: "image/png",
+                bytes: icon_png,
+            }),
+        }
+    }
+
+    /// A module with an embedded icon of an explicit content type. Used by the
+    /// `embedded_module!()` macro, which discovers the icon file at compile time
+    /// and passes the MIME derived from its extension.
+    pub const fn with_icon(
+        manifest_json: &'static str,
+        icon_bytes: &'static [u8],
+        content_type: &'static str,
+    ) -> Self {
+        Self {
+            manifest_json,
+            icon: Some(EmbeddedIcon {
+                content_type,
+                bytes: icon_bytes,
+            }),
+        }
+    }
+
+    /// A module with no packaged icon.
+    pub const fn iconless(manifest_json: &'static str) -> Self {
+        Self {
+            manifest_json,
+            icon: None,
+        }
+    }
+}
+
+impl Module for EmbeddedModule {
+    fn manifest(&self) -> ModuleManifest {
+        serde_json::from_str(self.manifest_json).expect("valid embedded module.json")
+    }
+
+    // Deliberately no `register` override: `ModuleRegistration::contribute`
+    // records only `(point, id)`, so re-declaring would drop the `label` /
+    // `fields` / `flow` the manifest declared.
+
+    fn icon(&self) -> Option<ModuleIcon> {
+        self.icon.map(|i| ModuleIcon {
+            content_type: i.content_type,
+            bytes: i.bytes,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::Registry;
+
+    #[test]
+    fn embedded_contributions_keep_ui_metadata() {
+        const MANIFEST: &str = r#"{
+            "id": "tv.kroma.engine.example",
+            "name": "Example engine",
+            "version": "0.1.0",
+            "contributes": [{
+                "point": "tv.kroma.torrents/download-client",
+                "id": "example",
+                "label": "Example",
+                "fields": [
+                    { "key": "url", "label": "field.url", "type": "string", "required": true },
+                    { "key": "password", "label": "field.password", "type": "string", "secret": true }
+                ]
+            }]
+        }"#;
+        let mut reg = Registry::new();
+        reg.register(Box::new(EmbeddedModule::iconless(MANIFEST)));
+        let m = reg
+            .manifests()
+            .into_iter()
+            .find(|m| m.id == "tv.kroma.engine.example")
+            .unwrap();
+        let contribution = &m.contributes[0];
+        assert_eq!(contribution.point, "tv.kroma.torrents/download-client");
+        assert_eq!(contribution.label.as_deref(), Some("Example"));
+        assert_eq!(contribution.fields.len(), 2);
+        assert!(
+            contribution.fields[1].secret,
+            "the secret flag must survive registration"
+        );
+    }
+
+    const BARE: &str = r#"{ "id": "tv.kroma.example", "name": "Example", "version": "0.1.0" }"#;
+
+    #[test]
+    fn each_constructor_labels_the_icon_with_the_content_type_the_route_will_serve() {
+        let svg = EmbeddedModule::new(BARE, b"<svg/>")
+            .icon()
+            .expect("an svg icon");
+        assert_eq!(svg.content_type, "image/svg+xml");
+        assert_eq!(svg.bytes, b"<svg/>");
+
+        let png = EmbeddedModule::with_png(BARE, b"\x89PNG")
+            .icon()
+            .expect("a png icon");
+        assert_eq!(png.content_type, "image/png");
+        assert_eq!(png.bytes, b"\x89PNG");
+
+        let webp = EmbeddedModule::with_icon(BARE, b"RIFF", "image/webp")
+            .icon()
+            .expect("a webp icon");
+        assert_eq!(webp.content_type, "image/webp");
+
+        assert!(EmbeddedModule::iconless(BARE).icon().is_none());
+    }
+
+    #[test]
+    fn the_registry_serves_an_embedded_modules_icon_by_id() {
+        let mut reg = Registry::new();
+        reg.register(Box::new(EmbeddedModule::new(BARE, b"<svg/>")));
+        assert_eq!(
+            reg.icon_of("tv.kroma.example").expect("icon").content_type,
+            "image/svg+xml"
+        );
+        assert!(reg.icon_of("tv.kroma.absent").is_none());
+    }
+}

package/rust/kroma-module-manifest/src/event.rs

@@ -0,0 +1,74 @@
+//! The open, module-authored event envelope.
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+/// An event emitted by a module.
+///
+/// The server's broadcast bus carries a *closed* `ServerEvent` enum today, so a
+/// module cannot introduce its own event without editing that enum. This
+/// envelope is the open alternative: a module publishes `{ module, tag,
+/// payload }` and any subscriber filters by `module` / `tag`. The existing
+/// typed events keep flowing unchanged; module events ride alongside them on
+/// the same broadcast channel (serialized to JSON like the rest).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ModuleEvent {
+    pub module: String,
+    pub tag: String,
+    #[serde(default)]
+    pub payload: Value,
+}
+
+impl ModuleEvent {
+    pub fn new(module: impl Into<String>, tag: impl Into<String>, payload: Value) -> Self {
+        Self {
+            module: module.into(),
+            tag: tag.into(),
+            payload,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn new_sets_the_three_fields() {
+        let ev = ModuleEvent::new(
+            "tv.kroma.downloads",
+            "download.progress",
+            json!({ "pct": 12 }),
+        );
+        assert_eq!(ev.module, "tv.kroma.downloads");
+        assert_eq!(ev.tag, "download.progress");
+        assert_eq!(ev.payload["pct"], 12);
+    }
+
+    #[test]
+    fn serializes_to_the_wire_envelope() {
+        let ev = ModuleEvent::new("m", "t", json!({ "a": 1 }));
+        let v = serde_json::to_value(&ev).unwrap();
+        assert_eq!(
+            v,
+            json!({ "module": "m", "tag": "t", "payload": { "a": 1 } })
+        );
+    }
+
+    #[test]
+    fn payload_defaults_to_null_when_absent() {
+        // The `#[serde(default)]` on `payload` lets a producer omit it entirely.
+        let ev: ModuleEvent = serde_json::from_value(json!({ "module": "m", "tag": "t" })).unwrap();
+        assert_eq!(ev.module, "m");
+        assert_eq!(ev.tag, "t");
+        assert!(ev.payload.is_null());
+    }
+
+    #[test]
+    fn round_trips_through_json() {
+        let ev = ModuleEvent::new("m", "t", json!([1, 2, 3]));
+        let back: ModuleEvent = serde_json::from_str(&serde_json::to_string(&ev).unwrap()).unwrap();
+        assert_eq!(back, ev);
+    }
+}

package/rust/kroma-module-manifest/src/lib.rs

@@ -0,0 +1,57 @@
+//! The KROMA server module contract: a module describes itself and declares
+//! what it needs and answers. [`Registry`] resolves the dependency graph;
+//! [`ModuleManifest`]/[`Contribution`] is the wire shape the frontend
+//! `@kroma/module-sdk` mirrors.
+
+mod compat;
+mod embedded;
+mod event;
+mod manifest;
+mod registry;
+
+pub use compat::{engines_satisfied, is_newer, range_matches, version_satisfies, KNOWN_ENGINES};
+pub use embedded::EmbeddedModule;
+pub use event::ModuleEvent;
+/// `embedded_module!()` builds a module's `MODULE` const from the `module.json`
+/// and `icon.<ext>` beside it. Re-exported here (as well as from
+/// `kroma_module_sdk`) so the modules that sit below the SDK facade (e.g. scene)
+/// can use it without depending on the facade.
+pub use kroma_module_macros::embedded_module;
+pub use manifest::MODULE_SCHEMA_VERSION;
+pub use manifest::{
+    ConfigField, Contribution, CoreScope, Dependency, FeRemote, ModuleManifest, PointDef, PointReq,
+    Storage, Version,
+};
+pub use registry::{ModuleRegistration, Registry, ResolveError};
+
+/// A module's packaged icon: an `icon.svg` / `icon.png` sitting next to the
+/// module's `module.json`, embedded at build time via `include_bytes!` and
+/// served at `GET /api/modules/<id>/icon`.
+pub struct ModuleIcon {
+    pub content_type: &'static str,
+    pub bytes: &'static [u8],
+}
+
+/// A server module.
+///
+/// The host gathers every module into a [`Registry`], resolves the graph, then
+/// serves the manifests. Implementors return a static self-description from
+/// [`manifest`](Module::manifest) and record the capabilities they provide in
+/// [`register`](Module::register).
+pub trait Module: Send + Sync {
+    // Static self-description: id, version, and declared dependencies.
+    //
+    // The `provides` field is filled in by the registry from
+    // [`register`](Module::register); implementors may leave it empty.
+    fn manifest(&self) -> ModuleManifest;
+
+    // Record the capabilities this module contributes. Called once at startup
+    // with a fresh [`ModuleRegistration`]. The default registers nothing.
+    fn register(&self, _reg: &mut ModuleRegistration) {}
+
+    // The module's packaged icon (`icon.svg` / `icon.png` next to its
+    // `module.json`), embedded at build time. Default: none.
+    fn icon(&self) -> Option<ModuleIcon> {
+        None
+    }
+}