@kromatv/sdk 0.1.40-canary.0

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

@@ -0,0 +1,115 @@
+//! The backend contract a module crate implements to own its server-side
+//! vertical, and the scheduled jobs it contributes.
+
+use super::HostCtx;
+
+use async_trait::async_trait;
+
+/// One scheduled job a module contributes to the core JobManager. Its `run` pass
+/// executes in-process on the sidecar, which serves the `/_job/run/{key}`
+/// endpoint the core scheduler calls.
+pub struct ModuleJob<S> {
+    // `key` is dotted (`"acquisition.import"`) and doubles as DB key, URL segment
+    // and i18n base. `category` is one of `maintenance`, `library`,
+    // `recommendations`, `pipeline`, `acquisition`. `schedule` is cron,
+    // admin-overridable, `None` for manual-only.
+    pub key: &'static str,
+    pub category: &'static str,
+    pub schedule: Option<&'static str>,
+    pub run: fn(&S) -> anyhow::Result<()>,
+}
+
+/// The backend contract a module crate implements to own its server-side
+/// vertical. Generic over the host state `S` so the crate depends only on this
+/// seam, never on the app; the binary instantiates it at `S = SharedState`.
+#[async_trait]
+pub trait ServerModule<S>: Send + Sync
+where
+    S: HostCtx + Clone + Send + Sync + 'static,
+{
+    // Matches its `module.json` and frontend package.
+    fn id(&self) -> &'static str;
+
+    // SQL run at DB init, after the core schema. `IF NOT EXISTS` DDL only; runs
+    // on every boot.
+    fn migrations(&self) -> &'static str {
+        ""
+    }
+
+    // Routes served under `/api/admin`. Mounted behind the module's enabled-gate
+    // by the host, so they 404 while it is disabled.
+    fn admin_routes(&self, _host: &S) -> Option<axum::Router<S>> {
+        None
+    }
+
+    fn jobs(&self) -> Vec<ModuleJob<S>> {
+        Vec::new()
+    }
+
+    // Event topics this module wants delivered, as they appear in an event's
+    // `type`. Opt-in one topic at a time rather than by wildcard, because the bus
+    // carries high-rate traffic (playback progress) a module has no use for and
+    // each delivery is an HTTP call to its process.
+    //
+    // Without this a module could publish onto the bus and never hear it, so it
+    // could be called BY another module but never react to one.
+    fn events(&self) -> Vec<&'static str> {
+        Vec::new()
+    }
+
+    // One event this module subscribed to. `payload` is the whole event object
+    // including its `type`, because a module that subscribed to several topics
+    // dispatches on it.
+    //
+    // Delivery is best-effort and unordered: it is an HTTP call to this process,
+    // and a module that was restarting missed whatever fired meanwhile. Anything
+    // that must not be missed belongs in a job that reconciles state, not here.
+    async fn on_event(&self, _host: S, _topic: String, _payload: serde_json::Value) {}
+
+    // Called when the module is enabled at runtime AND at boot for an
+    // already-enabled module. Awaited, not detached, so a slow start completes
+    // before a following disable can race it. Takes the state itself rather than
+    // an `Arc<dyn HostCtx>`, which would erase whatever the module declared
+    // beyond the base seam.
+    async fn on_enable(&self, _host: S) {}
+
+    // Called when the module is disabled at runtime AND at boot for a disabled
+    // module, so nothing is left running. Awaited.
+    async fn on_disable(&self, _host: S) {}
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+
+    use super::*;
+
+    use crate::testing;
+
+    #[test]
+    fn a_module_that_declares_nothing_gets_empty_defaults() {
+        struct Bare;
+        #[async_trait]
+        impl ServerModule<Arc<testing::StubHost>> for Bare {
+            fn id(&self) -> &'static str {
+                "tv.kroma.bare"
+            }
+        }
+        assert_eq!(Bare.id(), "tv.kroma.bare");
+        assert_eq!(Bare.migrations(), "");
+        assert!(Bare
+            .admin_routes(&Arc::new(testing::StubHost::new()))
+            .is_none());
+        assert!(Bare.jobs().is_empty());
+        assert!(Bare.events().is_empty());
+
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .build()
+            .unwrap();
+        rt.block_on(async {
+            let host = Arc::new(testing::StubHost::new());
+            Bare.on_enable(host.clone()).await;
+            Bare.on_disable(host).await;
+        });
+    }
+}

package/rust/kroma-module-host/src/port.rs

@@ -0,0 +1,163 @@
+//! Cross-module point plumbing: resolving whichever modules currently answer a
+//! point, calling one over the wire, and the service registry a host reaches its
+//! own singletons through.
+
+use std::any::{Any, TypeId};
+use std::sync::Arc;
+
+use axum::Json;
+
+use super::HostCtx;
+
+/// One live answer to a point: which module contributes it, under which instance
+/// name (`None` when the point takes a single contribution), and where to reach
+/// that module's process.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct Contribution {
+    pub module_id: String,
+    #[serde(default)]
+    pub instance: Option<String>,
+    pub base_url: String,
+    pub token: String,
+}
+
+/// Resolves the module currently answering a point: its `(base_url, auth_token)`,
+/// or `None` when nothing installed and running answers it. Called on EVERY
+/// cross-module request, so a provider that restarted on a new port is picked
+/// up without anyone re-wiring.
+pub type Resolver = Arc<dyn Fn() -> Option<(String, String)> + Send + Sync>;
+
+/// A [`Resolver`] for whichever module contributes `point`
+/// (`"tv.kroma.indexer/engine"`), narrowed to one `instance` when the point takes
+/// several. Which module answers is the supervisor's business and changes as
+/// modules are installed, so this re-resolves on every call rather than pinning
+/// an endpoint.
+pub fn point_resolver(host: Arc<dyn HostCtx>, point: &str, instance: Option<&str>) -> Resolver {
+    let point = point.to_string();
+    let want = instance.map(str::to_string);
+    Arc::new(move || {
+        let found = host
+            .contributions(&point)
+            .into_iter()
+            .find(|c| match &want {
+                Some(id) => c.instance.as_deref() == Some(id.as_str()),
+                None => true,
+            })?;
+        Some((found.base_url, found.token))
+    })
+}
+
+/// A [`Resolver`] pinned to `point`'s contribution as it is right now, for a
+/// caller holding a bare `&dyn HostCtx` and making one call. It does not
+/// re-resolve, so anything outliving the call should hold a [`point_resolver`].
+pub fn pinned_resolver(
+    host: &dyn HostCtx,
+    point: &str,
+    instance: Option<&str>,
+) -> Option<Resolver> {
+    let found = host
+        .contributions(point)
+        .into_iter()
+        .find(|c| match instance {
+            Some(id) => c.instance.as_deref() == Some(id),
+            None => true,
+        })?;
+    let endpoint = (found.base_url, found.token);
+    Some(Arc::new(move || Some(endpoint.clone())))
+}
+
+/// Serialize `body`, POST it to the provider's `/_port/<path>` with the bearer
+/// token, and unwrap the `Result<T, String>` envelope it returns.
+pub fn call<B: serde::Serialize, T: serde::de::DeserializeOwned>(
+    resolve: &Resolver,
+    path: &str,
+    body: &B,
+) -> anyhow::Result<T> {
+    let out: Result<T, String> = call_raw(resolve, path, body)?;
+    out.map_err(|e| anyhow::anyhow!(e))
+}
+
+/// [`call`] with the path derived from the point name, as `<point>/<method>`, so
+/// a caller holds one string rather than a point name and an unrelated URL prefix.
+pub fn call_point<B: serde::Serialize, T: serde::de::DeserializeOwned>(
+    resolve: &Resolver,
+    point: &str,
+    method: &str,
+    body: &B,
+) -> anyhow::Result<T> {
+    call(resolve, &format!("{point}/{method}"), body)
+}
+
+/// Like [`call`] but the provider returns `T` directly (no `Result` envelope),
+/// for point methods returning `Option<_>` / infallible values.
+pub fn call_raw<B: serde::Serialize, T: serde::de::DeserializeOwned>(
+    resolve: &Resolver,
+    path: &str,
+    body: &B,
+) -> anyhow::Result<T> {
+    let (base, token) =
+        resolve().ok_or_else(|| anyhow::anyhow!("no module contributes this point"))?;
+    let resp = kroma_http::Loopback::new()
+        .header("authorization", format!("Bearer {token}"))
+        .post_json(
+            &format!("{base}/_port/{path}"),
+            &serde_json::to_value(body)?,
+        )?
+        .ensure_ok()?;
+    resp.json()
+}
+
+/// Wrap a provider-side point handler: run the blocking work off the runtime and
+/// answer with the `Result<T, String>` envelope [`call`] expects.
+pub async fn port_reply<T>(
+    job: impl FnOnce() -> anyhow::Result<T> + Send + 'static,
+) -> Json<Result<T, String>>
+where
+    T: Send + 'static,
+{
+    let out = tokio::task::spawn_blocking(job)
+        .await
+        .map_err(|e| e.to_string())
+        .and_then(|r| r.map_err(|e| format!("{e:#}")));
+    Json(out)
+}
+
+pub fn service<T: Any + Send + Sync>(host: &dyn HostCtx) -> Option<Arc<T>> {
+    host.get_service(TypeId::of::<T>())?.downcast::<T>().ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use crate::testing;
+
+    fn offline() -> Resolver {
+        Arc::new(|| None)
+    }
+
+    #[test]
+    fn call_errors_when_nothing_contributes_the_point() {
+        let err = call::<_, serde_json::Value>(&offline(), "any/path", &serde_json::json!({}))
+            .unwrap_err();
+        assert!(err.to_string().contains("no module contributes this point"));
+    }
+
+    #[test]
+    fn call_raw_errors_when_nothing_contributes_the_point() {
+        let err = call_raw::<_, serde_json::Value>(&offline(), "any/path", &serde_json::json!({}))
+            .unwrap_err();
+        assert!(err.to_string().contains("no module contributes this point"));
+    }
+
+    #[test]
+    fn service_resolves_a_concrete_type() {
+        struct Manager(u32);
+        let host = testing::StubHost::new().with_service(Arc::new(Manager(42)));
+        let got = service::<Manager>(&host).expect("service resolves");
+        assert_eq!(got.0, 42);
+
+        struct Other;
+        assert!(service::<Other>(&host).is_none());
+    }
+}

package/rust/kroma-module-host/src/storage.rs

@@ -0,0 +1,97 @@
+//! The `storage` capability: the two databases a module can be granted, and the
+//! helper for running a query off the async runtime.
+//!
+//! This is deliberately NOT on [`HostCtx`](crate::HostCtx). A pool on the base
+//! trait is ambient authority: every sidecar gets unrestricted read/write on the
+//! whole core database whether or not it has a single table, and it links the
+//! bundled SQLite amalgamation to get it. Behind a capability, a module that
+//! declares no storage neither links SQLite nor can reach a row.
+
+use axum::response::Response;
+use kroma_db::Pool;
+
+use crate::{blocking, HostCtx};
+
+/// The databases a module holding the `storage` capability can reach.
+///
+/// The two are not interchangeable. [`store`](Self::store) is the module's own
+/// file and it owns it outright; [`db`](Self::db) is the SHARED application
+/// database, and every statement prepared on it passes the authorizer built from
+/// what the module's `module.json` declares. A module that declared no grant
+/// still gets a `db()` pool -- one that denies every table, so the failure is a
+/// named denial at the call site rather than a missing method the module could
+/// not have compiled against. The core implements both as its own database: it
+/// is not scoped against itself.
+pub trait HostStorage: HostCtx {
+    /// The shared core database, scoped to the module's declared grant.
+    fn db(&self) -> &Pool;
+
+    /// The module's private database (`<data>/modules/<id>/module.sqlite`), where
+    /// its own `migrations()` are applied. No authorizer: it is the module's file.
+    fn store(&self) -> &Pool;
+}
+
+impl<T: HostStorage + ?Sized> HostStorage for std::sync::Arc<T> {
+    fn db(&self) -> &Pool {
+        (**self).db()
+    }
+    fn store(&self) -> &Pool {
+        (**self).store()
+    }
+}
+
+/// [`blocking`], with the closure handed its own clone of the [`Pool`].
+pub async fn query<T, F>(pool: &Pool, f: F) -> Result<T, Response>
+where
+    F: FnOnce(Pool) -> anyhow::Result<T> + Send + 'static,
+    T: Send + 'static,
+{
+    let pool = pool.clone();
+    blocking(move || f(pool)).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn query_hands_the_closure_its_own_pool() {
+        let pool = kroma_db::testing::temp_pool("host-query");
+        let n: Result<i64, Response> = query(&pool, |p| {
+            let conn = p.get()?;
+            let v: i64 = conn.query_row("SELECT 1 + 1", [], |r| r.get(0))?;
+            Ok(v)
+        })
+        .await;
+        assert_eq!(n.unwrap(), 2);
+    }
+
+    #[tokio::test]
+    async fn the_two_databases_stay_distinct_through_an_arc() {
+        let host = std::sync::Arc::new(crate::testing::StubHost::with_db("storage-arc"));
+        let via_arc: &dyn HostStorage = &host;
+        via_arc
+            .store()
+            .get()
+            .unwrap()
+            .execute("CREATE TABLE IF NOT EXISTS mine (id TEXT PRIMARY KEY)", [])
+            .unwrap();
+
+        // The private store is the module's own file, so a table created there
+        // is not visible in the core database.
+        let in_core: i64 = via_arc
+            .db()
+            .get()
+            .unwrap()
+            .query_row(
+                "SELECT count(*) FROM sqlite_master WHERE name = 'mine'",
+                [],
+                |r| r.get(0),
+            )
+            .unwrap();
+        assert_eq!(
+            in_core, 0,
+            "the private store must not write into the core database"
+        );
+    }
+}

package/rust/kroma-module-host/src/test_serve.rs

@@ -0,0 +1,33 @@
+//! Standing a port's provider end up on a real localhost port, for the tests
+//! that drive a contract across the wire it actually crosses.
+//!
+//! Behind its own feature rather than [`testing`](crate::testing) because a
+//! contract crate testing both ends of an HTTP port has no database: `testing`
+//! pulls `kroma-db`, and a torznab or VPN contract must not link SQLite to run
+//! its round-trip test.
+
+use std::sync::Arc;
+
+use axum::Router;
+
+use crate::Resolver;
+
+/// Serve a provider's port routes on an ephemeral localhost port and hand back a
+/// [`Resolver`] pointing at it, so a port's two ends can be tested against each
+/// other over the real wire. The token is `"test-token"`.
+pub async fn serve<S: Clone + Send + Sync + 'static>(router: Router<S>, state: S) -> Resolver {
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    let app = router.with_state(state);
+    tokio::spawn(async move {
+        let _ = axum::serve(listener, app).await;
+    });
+    let base = format!("http://{addr}");
+    Arc::new(move || Some((base.clone(), "test-token".to_string())))
+}
+
+/// Run a port client's blocking call off the async runtime, panicking on a join
+/// failure. Port methods are sync, so a `#[tokio::test]` cannot call one directly.
+pub async fn blocking<T: Send + 'static>(job: impl FnOnce() -> T + Send + 'static) -> T {
+    tokio::task::spawn_blocking(job).await.unwrap()
+}

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

@@ -0,0 +1,145 @@
+//! What the two doubles record: the shared event-bus log, and the three
+//! intercepting methods written once so both hosts capture traffic alike.
+
+use std::collections::BTreeMap;
+use std::sync::Mutex;
+
+use kroma_domain::{Audience, NotificationSpec};
+
+/// One thing that went onto the event bus: the addressee (`None` for a
+/// broadcast) and the event's topic.
+pub type Published = (Option<String>, String);
+
+// The three calls both hosts RECORD rather than answer, written once.
+//
+// `Recording` wraps a real host and forwards everything else to it, and
+// `StubHost` has nothing behind it to forward to - but these three are the
+// traffic a test asserts on, so both must intercept them and both must do it
+// the same way. A test reading `log.published` should not have to know which
+// host it happens to be holding.
+macro_rules! records_into_log {
+    () => {
+        fn publish(&self, event: Event) {
+            self.log.published.lock().unwrap().push((None, event.topic));
+        }
+        fn publish_to(&self, user_id: &str, event: Event) {
+            self.log
+                .published
+                .lock()
+                .unwrap()
+                .push((Some(user_id.to_string()), event.topic));
+        }
+        fn notify(&self, audience: &Audience, spec: &NotificationSpec) -> usize {
+            self.log
+                .notified
+                .lock()
+                .unwrap()
+                .push((audience.clone(), spec.clone()));
+            1
+        }
+    };
+}
+
+pub(super) use records_into_log;
+
+/// What a [`StubHost`] or [`Recording`] saw. Shared behind an `Arc` so a clone
+/// of the host - axum takes its state by value - observes the same traffic.
+#[derive(Default)]
+pub(super) struct Log {
+    pub(super) published: Mutex<Vec<Published>>,
+    pub(super) notified: Mutex<Vec<(Audience, NotificationSpec)>>,
+    pub(super) jobs: Mutex<Vec<(&'static str, &'static str)>>,
+    pub(super) settings_written: Mutex<Vec<BTreeMap<String, serde_json::Value>>>,
+}
+
+impl Log {
+    pub(super) fn published(&self) -> Vec<Published> {
+        self.published.lock().unwrap().clone()
+    }
+    pub(super) fn topics(&self) -> Vec<String> {
+        self.published
+            .lock()
+            .unwrap()
+            .iter()
+            .map(|(_, t)| t.clone())
+            .collect()
+    }
+    pub(super) fn notifications(&self) -> Vec<(Audience, NotificationSpec)> {
+        self.notified.lock().unwrap().clone()
+    }
+    pub(super) fn jobs(&self) -> Vec<(&'static str, &'static str)> {
+        self.jobs.lock().unwrap().clone()
+    }
+    pub(super) fn settings_written(&self) -> Vec<BTreeMap<String, serde_json::Value>> {
+        self.settings_written.lock().unwrap().clone()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::super::fixtures::spec;
+    use super::super::StubHost;
+    use super::*;
+    use crate::{Event, HostCtx};
+
+    #[test]
+    fn the_bus_is_recorded_rather_than_delivered() {
+        let host = StubHost::new();
+        host.publish(Event::new("scan.finished", json!({})));
+        host.publish_to("ana", Event::new("notification.created", json!({})));
+        assert_eq!(host.notify(&Audience::user("ana"), &spec()), 1);
+        host.trigger_job("library.scan", "test");
+
+        assert_eq!(
+            host.published(),
+            [
+                (None, "scan.finished".to_string()),
+                (Some("ana".to_string()), "notification.created".to_string()),
+            ]
+        );
+        assert_eq!(host.topics(), ["scan.finished", "notification.created"]);
+        assert_eq!(host.notifications().len(), 1);
+        assert_eq!(host.jobs(), [("library.scan", "test")]);
+    }
+
+    #[test]
+    fn a_clone_sees_the_same_traffic_as_the_original() {
+        // axum takes router state BY VALUE, so a handler always works on a clone.
+        // If the log were not shared, every assertion after a request would read
+        // an empty vec.
+        let host = StubHost::new();
+        let clone = host.clone();
+        clone.publish(Event::new("download.progress", json!({})));
+        assert_eq!(host.topics(), ["download.progress"]);
+    }
+
+    #[test]
+    fn a_written_setting_is_recorded_and_readable_back() {
+        let host = StubHost::new();
+        host.set_settings(BTreeMap::from([("k".to_string(), json!("v"))]));
+
+        assert_eq!(host.setting_str("k", "fallback"), "v");
+        assert_eq!(host.settings_written().len(), 1);
+        assert_eq!(host.settings_written()[0]["k"], json!("v"));
+    }
+
+    #[test]
+    fn an_addressed_send_does_not_leak_into_the_broadcast_channel() {
+        // `publish_to` carries personal content ("your request was denied" names
+        // its recipient), so it must never reach the channel every client reads.
+        // The trait makes implementing it mandatory; this is the other half -
+        // that an implementation keeps the two buses apart.
+        let host = StubHost::new();
+        host.publish_to("ana", Event::new("notification.created", json!({})));
+        assert_eq!(
+            host.published(),
+            [(Some("ana".to_string()), "notification.created".to_string())]
+        );
+        assert!(
+            host.published().iter().all(|(to, _)| to.is_some()),
+            "an addressed event leaked into the broadcast bus"
+        );
+    }
+}

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

@@ -0,0 +1,72 @@
+//! Shared [`HostCtx`] test doubles, in two shapes:
+//!
+//! * [`StubHost`] a host that is not backed by an app at all. Its answers are
+//!   the neutral ones (settings return the caller's default, gates allow, the
+//!   bus records rather than delivers) and each is overridable.
+//! * [`Recording`] a decorator over a REAL host, forwarding everything but
+//!   capturing the bus traffic. For tests that need the app's true behaviour and
+//!   only want to see what it published.
+//!
+//! Gated on the `testing` feature so it never reaches a release build; the
+//! crates that use it enable it as a dev-dependency.
+
+mod log;
+mod recording;
+mod stub;
+
+pub use log::Published;
+pub use recording::Recording;
+pub use stub::StubHost;
+
+#[cfg(test)]
+mod fixtures {
+    use kroma_domain::metadata::{EpisodeInfo, MatchCandidate};
+    use kroma_domain::{NotificationEvent, NotificationSpec, User};
+
+    pub fn candidate() -> MatchCandidate {
+        MatchCandidate {
+            tmdb_id: 438631,
+            title: "Dune".into(),
+            original_title: None,
+            year: Some(2021),
+            poster_url: None,
+            overview: None,
+            rating: None,
+            score: 0.98,
+            current: false,
+        }
+    }
+
+    pub fn episode() -> EpisodeInfo {
+        EpisodeInfo {
+            episode: 1,
+            name: Some("Winter Is Coming".into()),
+            overview: None,
+            air_date: Some("2011-04-17".into()),
+            still_url: None,
+        }
+    }
+
+    pub fn spec() -> NotificationSpec {
+        NotificationSpec::new(
+            NotificationEvent::RequestApproved,
+            "notifications.request.approved.title",
+            "notifications.request.approved.body",
+        )
+    }
+
+    pub fn user() -> User {
+        User {
+            id: "u1".into(),
+            email: "a@b.c".into(),
+            username: "ana".into(),
+            avatar_url: None,
+            language: None,
+            audio_language: None,
+            subtitle_language: None,
+            permissions: Vec::new(),
+            created_at: "2024-01-01T00:00:00Z".into(),
+            has_pin: false,
+        }
+    }
+}