@kromatv/sdk 0.1.39-canary.3579809

package/rust/kroma-module-host/src/testing/stub/tests.rs

@@ -0,0 +1,206 @@
+use axum::http::StatusCode;
+use serde_json::json;
+
+use kroma_module_wire::Permission;
+
+use super::super::fixtures::{candidate, episode, user};
+use super::*;
+use crate::{Event, HostCtx, HostStorage};
+
+// Every crate that tests against the seam now leans on these answers, so a
+// change to any of them shifts behaviour in tests that never mention this
+// file. That is what makes pinning them worth doing.
+
+#[test]
+fn an_unconfigured_stub_answers_neutrally() {
+    let host = StubHost::new();
+
+    // Settings hand back the CALLER'S default, so code under test sees its
+    // own fallback rather than a value this file invented.
+    assert_eq!(host.setting_str("anything", "fallback"), "fallback");
+    assert!(host.setting_bool("anything", true));
+    assert!(!host.setting_bool("anything", false));
+    assert_eq!(host.setting_i64("anything", -7), -7);
+
+    // Gates allow: a test about a handler's behaviour should not have to
+    // grant permissions first. Tests about GATING use a real host.
+    assert!(host.require(&user(), Permission::LibraryManage).is_ok());
+    assert!(host.require_any_admin(&user()).is_ok());
+
+    assert!(host.module_enabled("tv.kroma.anything"));
+    assert!(host.library_folders().is_empty());
+    assert!(host.secret("tmdb").is_none());
+    assert_eq!(host.metadata_language(), "en");
+    assert!(host.metadata_candidates("Dune", "movie", None).is_empty());
+    assert!(host.metadata_episodes(1399, 1).is_empty());
+    assert!(host.get_service(TypeId::of::<u32>()).is_none());
+    assert!(host.data_dir().is_dir());
+}
+
+#[test]
+fn each_builder_overrides_exactly_its_own_answer() {
+    let host = StubHost::new()
+        .with_tmdb_key("k")
+        .with_metadata_language("fr-FR")
+        .with_metadata_candidates(vec![candidate()])
+        .with_metadata_episodes(vec![episode()])
+        .with_module_enabled(false)
+        .with_libraries(vec![LibraryFolders {
+            id: "lib1".into(),
+            kind: "movies".into(),
+            name: "Films".into(),
+            folders: vec!["/media/films".into()],
+        }])
+        .with_setting("str", json!("set"))
+        .with_setting("flag", json!(true))
+        .with_setting("num", json!(42));
+
+    assert_eq!(host.secret("tmdb").as_deref(), Some("k"));
+    assert_eq!(host.metadata_language(), "fr-FR");
+    assert_eq!(
+        host.metadata_candidates("anything", "movie", None)[0].tmdb_id,
+        438631
+    );
+    assert_eq!(host.metadata_episodes(1399, 2)[0].episode, 1);
+    assert!(!host.module_enabled("tv.kroma.anything"));
+    assert_eq!(host.library_folders()[0].folders, ["/media/films"]);
+    assert_eq!(host.setting_str("str", "fallback"), "set");
+    assert!(host.setting_bool("flag", false));
+    assert_eq!(host.setting_i64("num", 0), 42);
+
+    // An unseeded key still falls back, next to the seeded ones.
+    assert_eq!(host.setting_str("other", "fallback"), "fallback");
+}
+
+#[test]
+fn a_string_settings_source_takes_over_from_the_seeded_map() {
+    // The source sees the CALLER'S default, so a store with its own
+    // registered defaults can answer through the seam exactly as it would
+    // directly - which is the only reason this hook exists.
+    let host = StubHost::new()
+        .with_setting("k", json!("from the map"))
+        .with_string_settings(|key, default| format!("{key}/{default}"));
+
+    assert_eq!(host.setting_str("k", "fallback"), "k/fallback");
+    assert_eq!(host.setting_str("other", "d"), "other/d");
+    // Only strings route through it; the map still answers the rest.
+    assert!(host.setting_bool("flag", true));
+}
+
+#[test]
+fn a_seeded_setting_that_is_not_a_string_still_reads_as_one() {
+    // Settings are stored as JSON, and a caller asking for a string should
+    // get the value rather than an empty default that hides the mismatch.
+    let host = StubHost::new().with_setting("num", json!(42));
+    assert_eq!(host.setting_str("num", "fallback"), "42");
+}
+
+#[test]
+fn services_resolve_by_the_type_they_were_registered_under() {
+    struct Manager(u32);
+    struct Other;
+    let host = StubHost::new().with_service(Arc::new(Manager(42)));
+
+    let got = crate::service::<Manager>(&host).expect("registered");
+    assert_eq!(got.0, 42);
+    assert!(crate::service::<Other>(&host).is_none());
+}
+
+#[test]
+fn a_stub_without_a_database_says_so_instead_of_handing_one_out() {
+    let host = StubHost::new();
+    // `Pool` is not Debug, so map the Ok side away before unwrapping.
+    let err = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        let _ = host.db();
+    }))
+    .unwrap_err();
+    let msg = err
+        .downcast_ref::<String>()
+        .expect("expect() panics with a String");
+    assert!(msg.contains("StubHost::with_db"), "{msg}");
+}
+
+#[test]
+fn a_seeded_session_resolves_and_an_unknown_token_does_not() {
+    let host = StubHost::new().with_session("tok", user());
+    assert_eq!(
+        host.session_user("tok").map(|u| u.id),
+        Some("u1".to_string())
+    );
+    assert!(host.session_user("other").is_none());
+}
+
+#[test]
+fn with_db_hands_out_a_writable_pool_and_never_the_same_file_twice() {
+    let a = StubHost::with_db("selftest");
+    let b = StubHost::with_db("selftest");
+    let ddl = "CREATE TABLE settings (key TEXT PRIMARY KEY, value TEXT NOT NULL)";
+    for host in [&a, &b] {
+        host.db().get().unwrap().execute(ddl, []).unwrap();
+    }
+    // Separate: a row in one is not in the other. Two tests running in
+    // parallel threads of one process must not share a database.
+    a.db()
+        .get()
+        .unwrap()
+        .execute("INSERT INTO settings (key, value) VALUES ('k', 'v')", [])
+        .unwrap();
+    let n: i64 = b
+        .db()
+        .get()
+        .unwrap()
+        .query_row("SELECT count(*) FROM settings WHERE key = 'k'", [], |r| {
+            r.get(0)
+        })
+        .unwrap();
+    assert_eq!(n, 0);
+}
+
+#[test]
+fn lerr_carries_the_status_it_was_given() {
+    let host = StubHost::new();
+    assert_eq!(
+        host.lerr(&user(), StatusCode::NOT_FOUND, "k").status(),
+        StatusCode::NOT_FOUND
+    );
+}
+
+#[test]
+fn the_stub_answers_every_required_method_neutrally() {
+    // The seam has ~25 methods and a double is only useful if the ones a
+    // test is NOT about stay out of the way: settings hand back the caller's
+    // own default, gates allow, and the optional capabilities are absent.
+    let host = StubHost::new();
+    host.publish(Event::new("scan.finished", json!({})));
+    assert_eq!(host.topics(), ["scan.finished"]);
+    assert_eq!(host.setting_str("k", "fallback"), "fallback");
+    assert!(host.setting_bool("k", true));
+    assert_eq!(host.setting_i64("k", 9), 9);
+    assert!(host.require(&user(), Permission::LibraryManage).is_ok());
+    assert!(host.require_any_admin(&user()).is_ok());
+    assert_eq!(
+        host.lerr(&user(), StatusCode::NOT_FOUND, "k").status(),
+        StatusCode::NOT_FOUND
+    );
+    assert!(host.module_enabled("x"));
+    assert!(host.library_folders().is_empty());
+    assert!(host.secret("tmdb").is_none());
+    assert_eq!(host.metadata_language(), "en");
+    assert!(host.get_service(TypeId::of::<u32>()).is_none());
+    assert!(host.data_dir().is_dir());
+    host.set_settings(BTreeMap::from([("k".to_string(), json!("v"))]));
+    assert_eq!(host.setting_str("k", "fallback"), "v");
+    host.trigger_job("library.scan", "test");
+    assert_eq!(host.jobs(), [("library.scan", "test")]);
+}
+
+#[test]
+fn the_stub_defaults_to_something_usable() {
+    // `Default` exists so a double can be dropped into a `#[derive(Default)]`
+    // harness; it must not differ from `new()`.
+    assert_eq!(
+        StubHost::default().metadata_language(),
+        StubHost::new().metadata_language()
+    );
+    assert!(StubHost::default().published().is_empty());
+}

package/rust/kroma-module-host/src/testing/stub.rs

@@ -0,0 +1,267 @@
+//! [`StubHost`]: a [`HostCtx`] with no app behind it, every answer neutral
+//! until a builder overrides it.
+
+use std::any::{Any, TypeId};
+use std::collections::BTreeMap;
+use std::sync::{Arc, Mutex};
+
+use kroma_sqlite::testing::TempPool;
+use kroma_sqlite::Pool;
+use kroma_module_wire::{Audience, EpisodeInfo, MatchCandidate, NotificationSpec, User};
+use kroma_testing::TempDir;
+
+use super::log::{Log, Published};
+use crate::LibraryFolders;
+
+// A host service, as the registry stores it: keyed by the `TypeId` the caller
+// will look it up with.
+type Service = (TypeId, Arc<dyn Any + Send + Sync>);
+
+// A stand-in for the app's real settings store: `(key, caller's default) ->
+// value`, the exact shape of [`HostCtx::setting_str`].
+type StringSettings = Arc<dyn Fn(&str, &str) -> String + Send + Sync>;
+
+/// A [`HostCtx`] with no app behind it.
+///
+/// Every answer is the neutral one until configured: settings hand back the
+/// caller's own default, both gates allow, the module is enabled, there are no
+/// libraries and no TMDB key. The bus methods record instead of delivering, so
+/// a test asserts on [`published`](Self::published) /
+/// [`notifications`](Self::notifications) / [`jobs`](Self::jobs).
+///
+/// `data_dir()` is a scratch directory of this host's own, removed once the last
+/// clone drops, so anything the code under test writes there goes with it.
+///
+/// `db()` / `store()` panic unless the host was built with
+/// [`with_db`](Self::with_db) - louder than handing out a pool to a test that did
+/// not ask for one.
+#[derive(Clone)]
+pub struct StubHost {
+    db: Option<Pool>,
+    store: Option<Pool>,
+    sessions: Arc<Mutex<BTreeMap<String, User>>>,
+    data_dir: Arc<TempDir>,
+    tmdb_key: Option<String>,
+    metadata_language: String,
+    metadata_candidates: Vec<MatchCandidate>,
+    metadata_episodes: Vec<EpisodeInfo>,
+    module_enabled: bool,
+    libraries: Vec<LibraryFolders>,
+    settings: Arc<Mutex<BTreeMap<String, serde_json::Value>>>,
+    string_settings: Option<StringSettings>,
+    services: Arc<Mutex<Vec<Service>>>,
+    points: Arc<Mutex<Vec<crate::Contribution>>>,
+    log: Arc<Log>,
+}
+
+impl Default for StubHost {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl StubHost {
+    /// A host with no database. `db()` / `store()` panic if reached.
+    pub fn new() -> Self {
+        Self::in_dir(kroma_testing::temp_dir("stub-host"))
+    }
+
+    /// A host over a real, empty SQLite database inside this host's own scratch
+    /// directory, plus the module-private store beside it. Neither carries a
+    /// schema: a test that needs the core tables hands a migrated pool to
+    /// [`with_pool`](Self::with_pool). `tag` only shapes that directory's name,
+    /// to make a stray one identifiable.
+    pub fn with_db(tag: &str) -> Self {
+        let data_dir = kroma_testing::temp_dir(tag);
+        let db = kroma_sqlite::open(&data_dir.path().join("kroma.db")).expect("open test db");
+        // `open`, like the real runtime: a module's own file carries no core
+        // schema, only what its own migrations put there.
+        let store =
+            kroma_sqlite::open(&data_dir.path().join("module.sqlite")).expect("open test store");
+        Self {
+            db: Some(db),
+            store: Some(store),
+            ..Self::in_dir(data_dir)
+        }
+    }
+
+    fn in_dir(data_dir: TempDir) -> Self {
+        Self {
+            db: None,
+            store: None,
+            sessions: Arc::new(Mutex::new(BTreeMap::new())),
+            data_dir: Arc::new(data_dir),
+            tmdb_key: None,
+            metadata_language: "en".into(),
+            metadata_candidates: Vec::new(),
+            metadata_episodes: Vec::new(),
+            module_enabled: true,
+            libraries: Vec::new(),
+            settings: Arc::new(Mutex::new(BTreeMap::new())),
+            string_settings: None,
+            services: Arc::new(Mutex::new(Vec::new())),
+            points: Arc::new(Mutex::new(Vec::new())),
+            log: Arc::new(Log::default()),
+        }
+    }
+
+    /// A host over a core database the caller built, with the module-private
+    /// store beside it. The core schema is not this crate's to know: a test that
+    /// needs it hands over `kroma_db::testing::temp_pool`, whose directory this
+    /// host then keeps for as long as it lives.
+    pub fn with_core(core: TempPool) -> Self {
+        let (db, data_dir) = core.into_parts();
+        let store =
+            kroma_sqlite::open(&data_dir.path().join("module.sqlite")).expect("open test store");
+        Self {
+            db: Some(db),
+            store: Some(store),
+            ..Self::in_dir(data_dir)
+        }
+    }
+
+    /// A host whose MODULE store is `pool`, with a fresh, empty core database
+    /// beside it. For a module testing its own tables: those live in its own file,
+    /// so a test that seeded them has to hand them over as the store and not as
+    /// the core.
+    pub fn with_store(pool: Pool) -> Self {
+        let data_dir = kroma_testing::temp_dir("stub-core");
+        let db = kroma_sqlite::open(&data_dir.path().join("kroma.db")).expect("open test db");
+        Self {
+            db: Some(db),
+            store: Some(pool),
+            ..Self::in_dir(data_dir)
+        }
+    }
+
+    /// Answer `session_user(token)` with `user`. A token nobody seeded is an
+    /// unknown session, the way the real host answers one.
+    pub fn with_session(self, token: &str, user: User) -> Self {
+        self.sessions
+            .lock()
+            .unwrap()
+            .insert(token.to_string(), user);
+        self
+    }
+
+    /// Answer `secret("tmdb")` with `key`.
+    pub fn with_tmdb_key(mut self, key: &str) -> Self {
+        self.tmdb_key = Some(key.into());
+        self
+    }
+
+    /// Answer `metadata_episodes()` with `episodes` (default: none).
+    pub fn with_metadata_episodes(mut self, episodes: Vec<EpisodeInfo>) -> Self {
+        self.metadata_episodes = episodes;
+        self
+    }
+
+    /// Answer `metadata_candidates()` with `candidates`, whatever is asked
+    /// (default: none, i.e. nothing matched).
+    pub fn with_metadata_candidates(mut self, candidates: Vec<MatchCandidate>) -> Self {
+        self.metadata_candidates = candidates;
+        self
+    }
+
+    /// Answer `metadata_language()` with `tag` (default `"en"`).
+    pub fn with_metadata_language(mut self, tag: &str) -> Self {
+        self.metadata_language = tag.into();
+        self
+    }
+
+    /// Answer `module_enabled()` with `on` for every id (default `true`).
+    pub fn with_module_enabled(mut self, on: bool) -> Self {
+        self.module_enabled = on;
+        self
+    }
+
+    /// Answer `library_folders()` with `libraries` (default empty).
+    pub fn with_libraries(mut self, libraries: Vec<LibraryFolders>) -> Self {
+        self.libraries = libraries;
+        self
+    }
+
+    /// Answer every `setting_str` through `f` instead of the seeded map.
+    ///
+    /// For the one shape the map cannot imitate: a test whose SUBJECT is a real
+    /// settings store read through the seam, where the store's own registered
+    /// defaults - not the caller's - are what the assertion is about. `f` gets
+    /// the key and the caller's default, exactly as `setting_str` does.
+    pub fn with_string_settings(
+        mut self,
+        f: impl Fn(&str, &str) -> String + Send + Sync + 'static,
+    ) -> Self {
+        self.string_settings = Some(Arc::new(f));
+        self
+    }
+
+    /// Seed a persisted setting. Unseeded keys still return the caller's default,
+    /// which is what makes the un-configured host neutral.
+    pub fn with_setting(self, key: &str, value: serde_json::Value) -> Self {
+        self.settings.lock().unwrap().insert(key.into(), value);
+        self
+    }
+
+    /// Register a service for `service::<T>()` to resolve.
+    pub fn with_service<T: Any + Send + Sync>(self, value: Arc<T>) -> Self {
+        self.services
+            .lock()
+            .unwrap()
+            .push((TypeId::of::<T>(), value));
+        self
+    }
+
+    /// Register an already-built `(TypeId, value)` pair, as
+    /// [`port_service`](crate::port_service) produces for a `dyn` port - its key
+    /// is `TypeId::of::<Arc<dyn P>>()`, which the generic method above cannot
+    /// name.
+    pub fn with_service_raw(self, entry: Service) -> Self {
+        self.services.lock().unwrap().push(entry);
+        self
+    }
+
+    /// Answer `point` with a provider this test stood up (see
+    /// [`test_serve::serve`](crate::test_serve::serve)). A point resolves over
+    /// HTTP, so a fake is served rather than injected. Call it again with another
+    /// `instance` to give the point two contributors and exercise fan-out.
+    pub fn with_point(self, point: &str, instance: Option<&str>, base: &str, token: &str) -> Self {
+        self.points.lock().unwrap().push(crate::Contribution {
+            module_id: format!("test.{point}"),
+            instance: instance.map(str::to_string),
+            base_url: base.to_string(),
+            token: token.to_string(),
+        });
+        self
+    }
+
+    /// Everything published, as `(addressee, topic)`; the addressee is `None`
+    /// for a broadcast and `Some(user_id)` for a `publish_to`.
+    pub fn published(&self) -> Vec<Published> {
+        self.log.published()
+    }
+
+    /// Published topics, in order, ignoring who they were addressed to.
+    pub fn topics(&self) -> Vec<String> {
+        self.log.topics()
+    }
+
+    /// Every `notify()` call, with its audience.
+    pub fn notifications(&self) -> Vec<(Audience, NotificationSpec)> {
+        self.log.notifications()
+    }
+
+    /// Every `trigger_job()` call, as `(key, reason)`.
+    pub fn jobs(&self) -> Vec<(&'static str, &'static str)> {
+        self.log.jobs()
+    }
+
+    /// Every `set_settings()` patch, in order.
+    pub fn settings_written(&self) -> Vec<BTreeMap<String, serde_json::Value>> {
+        self.log.settings_written()
+    }
+}
+
+mod answers;
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,12 @@
+[package]
+name = "kroma-module-macros"
+version = "0.1.39-canary.3579809"
+edition = "2021"
+rust-version = "1.88"
+description = "Proc-macros for KROMA modules: embedded_module!() discovers a module's module.json + icon at compile time so the MODULE const is one line."
+license = "AGPL-3.0-or-later"
+
+[lib]
+proc-macro = true
+
+[dependencies]