@kromatv/sdk 0.1.39-canary.3579809

package/rust/kroma-module-runtime/src/env.rs

@@ -0,0 +1,57 @@
+use std::path::PathBuf;
+
+pub(crate) struct Env {
+    pub(crate) module_id: String,
+    pub(crate) port: u16,
+    pub(crate) core_url: String,
+    pub(crate) host_token: String,
+    pub(crate) module_token: String,
+    // Only read under `storage`: a module that declares none never learns where
+    // the core database is, which is the capability said in one more place.
+    #[cfg(feature = "storage")]
+    pub(crate) db_path: PathBuf,
+    pub(crate) data_dir: PathBuf,
+}
+
+impl Env {
+    pub(crate) fn from_process() -> anyhow::Result<Self> {
+        let get = |k: &str| std::env::var(k).map_err(|_| anyhow::anyhow!("{k} not set"));
+        Ok(Self {
+            module_id: get("KROMA_MODULE_ID")?,
+            port: get("KROMA_MODULE_PORT")?.parse()?,
+            core_url: get("KROMA_CORE_URL")?,
+            host_token: get("KROMA_HOST_TOKEN")?,
+            // A host that predates per-module tokens sends none, and the fabric
+            // token still authenticates; it just does not name this module, so
+            // the callback answers it nothing that wants a declaration.
+            module_token: std::env::var("KROMA_MODULE_TOKEN")
+                .or_else(|_| get("KROMA_HOST_TOKEN"))?,
+            #[cfg(feature = "storage")]
+            db_path: PathBuf::from(get("KROMA_DB_PATH")?),
+            data_dir: PathBuf::from(get("KROMA_DATA_DIR")?),
+        })
+    }
+
+    /// The grant the core spawned this module with, as its manifest declared it.
+    /// Absent or unreadable is the empty grant: a pool that answers nothing,
+    /// never an unscoped one.
+    #[cfg(feature = "storage")]
+    pub(crate) fn grant(&self) -> kroma_sqlite::Grant {
+        let Ok(json) = std::env::var("KROMA_MODULE_GRANT") else {
+            return kroma_sqlite::Grant::none();
+        };
+        serde_json::from_str(&json).unwrap_or_else(|error| {
+            tracing::error!(%error, "core sent a storage grant this build cannot read; denying all");
+            kroma_sqlite::Grant::none()
+        })
+    }
+
+    /// The module's own database, beside the files the core unpacked it into.
+    #[cfg(feature = "storage")]
+    pub(crate) fn store_path(&self) -> PathBuf {
+        self.data_dir
+            .join("modules")
+            .join(&self.module_id)
+            .join("module.sqlite")
+    }
+}

package/rust/kroma-module-runtime/src/events.rs

@@ -0,0 +1,102 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use axum::http::StatusCode;
+use kroma_module_host::host_token::{require_host_token, HostToken};
+use kroma_module_host::ServerModule;
+
+use crate::remote_host::RemoteHost;
+
+// Deduplicated: two modules in one process may both want a topic, and the core
+// should be told about it once.
+pub(crate) fn wanted_topics(modules: &[Box<dyn ServerModule<RemoteHost>>]) -> Vec<String> {
+    let mut seen: Vec<String> = Vec::new();
+    for topic in modules.iter().flat_map(|module| module.events()) {
+        if !seen.iter().any(|t| t == topic) {
+            seen.push(topic.to_string());
+        }
+    }
+    seen
+}
+
+// Which modules in this process asked for which topic. Held as trait objects
+// because delivery dispatches on the topic at request time, not at wiring time.
+pub(crate) struct Subscribers {
+    modules: Arc<Vec<Box<dyn ServerModule<RemoteHost>>>>,
+    by_topic: HashMap<String, Vec<usize>>,
+}
+
+impl Subscribers {
+    pub(crate) fn new(
+        modules: Arc<Vec<Box<dyn ServerModule<RemoteHost>>>>,
+        topics: &[String],
+    ) -> Self {
+        let mut by_topic: HashMap<String, Vec<usize>> = HashMap::new();
+        for topic in topics {
+            let want = modules
+                .iter()
+                .enumerate()
+                .filter(|(_, m)| m.events().iter().any(|t| t == topic))
+                .map(|(i, _)| i)
+                .collect();
+            by_topic.insert(topic.clone(), want);
+        }
+        Self { modules, by_topic }
+    }
+}
+
+pub(crate) fn event_router(
+    subscribers: Arc<Subscribers>,
+    token: String,
+) -> axum::Router<RemoteHost> {
+    axum::Router::new()
+        .route("/_event/{topic}", axum::routing::post(deliver_event))
+        .route_layer(axum::middleware::from_fn_with_state(
+            HostToken(token),
+            require_host_token,
+        ))
+        .layer(axum::Extension(subscribers))
+}
+
+// Answers before the handlers run: the core is fanning out to every subscriber
+// and must not be held up by one module's work, and it has nothing to do with a
+// failure anyway. A handler that needs to report something publishes or notifies.
+async fn deliver_event(
+    axum::extract::State(host): axum::extract::State<RemoteHost>,
+    axum::Extension(subscribers): axum::Extension<Arc<Subscribers>>,
+    axum::extract::Path(topic): axum::extract::Path<String>,
+    axum::Json(payload): axum::Json<serde_json::Value>,
+) -> StatusCode {
+    let Some(want) = subscribers.by_topic.get(&topic) else {
+        tracing::debug!(%topic, "event delivered for a topic this process did not ask for");
+        return StatusCode::NOT_FOUND;
+    };
+    let want = want.clone();
+    let modules = subscribers.modules.clone();
+    tokio::spawn(async move {
+        for index in want {
+            modules[index]
+                .on_event(host.clone(), topic.clone(), payload.clone())
+                .await;
+        }
+    });
+    StatusCode::ACCEPTED
+}
+
+pub(crate) fn register_events(url: &str, module_id: &str, host_token: &str, topics: &[String]) {
+    let body = serde_json::json!({ "moduleId": module_id, "topics": topics });
+    match kroma_http::Loopback::new()
+        .header("authorization", format!("Bearer {host_token}"))
+        .post_json(url, &body)
+    {
+        Ok(resp) if (200..300).contains(&resp.status) => {
+            tracing::info!(?topics, "subscribed to core events");
+        }
+        Ok(resp) => tracing::warn!(
+            status = resp.status,
+            "core rejected the event subscription: {}",
+            resp.text()
+        ),
+        Err(e) => tracing::warn!("could not subscribe to core events: {e:#}"),
+    }
+}

package/rust/kroma-module-runtime/src/host_ctx.rs

@@ -0,0 +1,208 @@
+use std::any::{Any, TypeId};
+use std::path::Path;
+use std::sync::Arc;
+
+use axum::http::StatusCode;
+use axum::response::Response;
+use kroma_module_host::{json_error, Event, HostCtx};
+use kroma_module_wire::{Permission, User};
+
+use crate::remote_host::RemoteHost;
+
+impl HostCtx for RemoteHost {
+    fn data_dir(&self) -> &Path {
+        &self.inner.data_dir
+    }
+
+    // Asked of the core rather than read from the `sessions` table.
+    fn session_user(&self, token: &str) -> Option<User> {
+        // POSTed, not queried: the token is the caller's live session.
+        self.callback()
+            .post_json(
+                &self.host_url("session"),
+                &serde_json::json!({ "token": token }),
+            )
+            .ok()?
+            .json::<Option<User>>()
+            .ok()
+            .flatten()
+    }
+
+    fn require(&self, user: &User, perm: Permission) -> Result<(), Response> {
+        if user.can(perm) {
+            Ok(())
+        } else {
+            Err(json_error(StatusCode::FORBIDDEN, "forbidden"))
+        }
+    }
+
+    fn require_any_admin(&self, user: &User) -> Result<(), Response> {
+        if user.is_any_admin() {
+            Ok(())
+        } else {
+            Err(json_error(StatusCode::FORBIDDEN, "forbidden"))
+        }
+    }
+
+    fn lerr(&self, _user: &User, status: StatusCode, key: &str) -> Response {
+        // No i18n catalogs out-of-process; the frontend localizes known error keys.
+        json_error(status, key)
+    }
+
+    fn setting_str(&self, key: &str, default: &str) -> String {
+        self.callback()
+            .query("key", key)
+            .query("kind", "str")
+            .query("default", default)
+            .get_json::<serde_json::Value>(&self.host_url("setting"))
+            .ok()
+            .and_then(|v| v.get("value").and_then(|x| x.as_str().map(str::to_string)))
+            .unwrap_or_else(|| default.to_string())
+    }
+
+    fn setting_bool(&self, key: &str, default: bool) -> bool {
+        self.callback()
+            .query("key", key)
+            .query("kind", "bool")
+            .query("default", default.to_string())
+            .get_json::<serde_json::Value>(&self.host_url("setting"))
+            .ok()
+            .and_then(|v| v.get("value").and_then(serde_json::Value::as_bool))
+            .unwrap_or(default)
+    }
+
+    fn setting_i64(&self, key: &str, default: i64) -> i64 {
+        self.callback()
+            .query("key", key)
+            .query("kind", "i64")
+            .query("default", default.to_string())
+            .get_json::<serde_json::Value>(&self.host_url("setting"))
+            .ok()
+            .and_then(|v| v.get("value").and_then(serde_json::Value::as_i64))
+            .unwrap_or(default)
+    }
+
+    fn set_settings(&self, patch: std::collections::BTreeMap<String, serde_json::Value>) {
+        let _ = self.callback().post_json(
+            &self.host_url("settings"),
+            &serde_json::json!({ "patch": patch }),
+        );
+    }
+
+    fn publish(&self, event: Event) {
+        let _ = self.callback().post_json(
+            &self.host_url("events"),
+            &serde_json::json!({ "topic": event.topic, "payload": event.payload }),
+        );
+    }
+
+    fn publish_to(&self, user_id: &str, event: Event) {
+        let _ = self.callback().post_json(
+            &self.host_url("events_to"),
+            &serde_json::json!({ "userId": user_id, "topic": event.topic, "payload": event.payload }),
+        );
+    }
+
+    fn notify(
+        &self,
+        audience: &kroma_module_host::Audience,
+        spec: &kroma_module_host::NotificationSpec,
+    ) -> usize {
+        // The core resolves, filters, persists and pushes; this only ships the intent.
+        let body = serde_json::json!({ "audience": audience, "spec": spec });
+        self.callback()
+            .post_json(&self.host_url("notify"), &body)
+            .ok()
+            .and_then(|r| r.json::<serde_json::Value>().ok())
+            .and_then(|v| v.get("sent").and_then(serde_json::Value::as_u64))
+            .unwrap_or(0) as usize
+    }
+
+    fn trigger_job(&self, key: &'static str, reason: &'static str) {
+        let _ = self.callback().post_json(
+            &self.host_url("job"),
+            &serde_json::json!({ "key": key, "reason": reason }),
+        );
+    }
+
+    fn module_enabled(&self, id: &str) -> bool {
+        self.callback()
+            .query("id", id)
+            .get_json::<serde_json::Value>(&self.host_url("enabled"))
+            .ok()
+            .and_then(|v| v.get("enabled").and_then(serde_json::Value::as_bool))
+            // A module process only runs while enabled, so default to true.
+            .unwrap_or(true)
+    }
+
+    fn library_folders(&self) -> Vec<kroma_module_host::LibraryFolders> {
+        // The core owns Settings + Config; this process never links the engine.
+        self.callback()
+            .get_json(&self.host_url("libraries"))
+            .unwrap_or_default()
+    }
+
+    fn secret(&self, name: &str) -> Option<String> {
+        self.callback()
+            .query("name", name)
+            .get_json::<Option<String>>(&self.host_url("secret"))
+            .ok()
+            .flatten()
+    }
+
+    fn metadata_language(&self) -> String {
+        if let Some(v) = self.inner.language.read().unwrap().clone() {
+            return v;
+        }
+        let asked = self
+            .callback()
+            .get_json::<String>(&self.host_url("metadata-language"))
+            .ok()
+            .filter(|v| !v.is_empty());
+        // Only a real answer is cached, so a transient failure retries rather
+        // than pinning the fallback for the life of the process.
+        match asked {
+            Some(v) => {
+                *self.inner.language.write().unwrap() = Some(v.clone());
+                v
+            }
+            None => "en-US".to_string(),
+        }
+    }
+
+    // Asked of the core, which holds the provider credential.
+    fn metadata_candidates(
+        &self,
+        query: &str,
+        kind: &str,
+        year: Option<u32>,
+    ) -> Vec<kroma_module_wire::MatchCandidate> {
+        let mut call = self.callback().query("q", query).query("kind", kind);
+        if let Some(year) = year {
+            call = call.query("year", year.to_string());
+        }
+        call.get_json::<Vec<kroma_module_wire::MatchCandidate>>(&self.host_url("metadata-search"))
+            .unwrap_or_default()
+    }
+
+    fn metadata_episodes(&self, tmdb_id: u64, season: u32) -> Vec<kroma_module_wire::EpisodeInfo> {
+        self.callback()
+            .query("tmdbId", tmdb_id.to_string())
+            .query("season", season.to_string())
+            .get_json::<Vec<kroma_module_wire::EpisodeInfo>>(&self.host_url("metadata-episodes"))
+            .unwrap_or_default()
+    }
+
+    // Asked of the core, which owns the supervisor: a sidecar cannot see which
+    // of its peers is installed or running, and must not care.
+    fn contributions(&self, point: &str) -> Vec<kroma_module_host::Contribution> {
+        self.callback()
+            .query("point", point)
+            .get_json::<Vec<kroma_module_host::Contribution>>(&self.host_url("contributions"))
+            .unwrap_or_default()
+    }
+
+    fn get_service(&self, type_id: TypeId) -> Option<Arc<dyn Any + Send + Sync>> {
+        self.inner.services.read().unwrap().get(&type_id).cloned()
+    }
+}

package/rust/kroma-module-runtime/src/jobs.rs

@@ -0,0 +1,111 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use axum::http::StatusCode;
+use axum::response::{IntoResponse, Response};
+use kroma_module_host::host_token::{require_host_token, HostToken};
+use kroma_module_host::ServerModule;
+
+use crate::remote_host::RemoteHost;
+
+// What this process serves and what it asks the core for, gathered before the
+// router is built. Kept out of [`serve`] because each is a loop over the modules
+// with its own rule, and `serve`'s own job is the order the parts come up in.
+pub(crate) fn collect_jobs(
+    modules: &[Box<dyn ServerModule<RemoteHost>>],
+) -> (HashMap<&'static str, JobFn>, Vec<JobSpec>) {
+    // job_fns backs /_job/run/{key}; job_specs registers with the core scheduler.
+    let mut job_fns: HashMap<&'static str, JobFn> = HashMap::new();
+    let mut job_specs: Vec<JobSpec> = Vec::new();
+    for job in modules.iter().flat_map(|module| module.jobs()) {
+        job_fns.insert(job.key, job.run);
+        job_specs.push(JobSpec {
+            key: job.key.to_string(),
+            category: job.category.to_string(),
+            schedule: job.schedule.map(str::to_string),
+        });
+    }
+    (job_fns, job_specs)
+}
+
+pub(crate) type JobFn = fn(&RemoteHost) -> anyhow::Result<()>;
+
+pub(crate) struct JobSpec {
+    pub(crate) key: String,
+    pub(crate) category: String,
+    pub(crate) schedule: Option<String>,
+}
+
+pub(crate) fn job_router(
+    job_fns: HashMap<&'static str, JobFn>,
+    token: String,
+) -> axum::Router<RemoteHost> {
+    axum::Router::new()
+        .route("/_job/run/{key}", axum::routing::post(run_job))
+        .route_layer(axum::middleware::from_fn_with_state(
+            HostToken(token),
+            require_host_token,
+        ))
+        .layer(axum::Extension(Arc::new(job_fns)))
+}
+
+async fn run_job(
+    axum::extract::State(host): axum::extract::State<RemoteHost>,
+    axum::Extension(job_fns): axum::Extension<Arc<HashMap<&'static str, JobFn>>>,
+    axum::extract::Path(key): axum::extract::Path<String>,
+) -> Response {
+    let Some(&run) = job_fns.get(key.as_str()) else {
+        tracing::warn!(job = %key, "run requested for a job this process does not have");
+        return (StatusCode::NOT_FOUND, format!("unknown job {key}")).into_response();
+    };
+    tracing::info!(job = %key, "job starting");
+    let started = std::time::Instant::now();
+    let outcome = tokio::task::spawn_blocking(move || run(&host)).await;
+    let elapsed_ms = started.elapsed().as_millis();
+    match outcome {
+        Ok(Ok(())) => {
+            tracing::info!(job = %key, elapsed_ms, "job done");
+            StatusCode::OK.into_response()
+        }
+        Ok(Err(e)) => {
+            tracing::error!(job = %key, elapsed_ms, error = %format!("{e:#}"), "job failed");
+            (StatusCode::INTERNAL_SERVER_ERROR, format!("{e:#}")).into_response()
+        }
+        Err(e) => {
+            tracing::error!(job = %key, elapsed_ms, error = %e, "job panicked");
+            (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                format!("job panicked: {e}"),
+            )
+                .into_response()
+        }
+    }
+}
+
+pub(crate) fn register_jobs(url: &str, module_id: &str, host_token: &str, specs: &[JobSpec]) {
+    for spec in specs {
+        let body = serde_json::json!({
+            "moduleId": module_id,
+            "key": spec.key,
+            "category": spec.category,
+            "schedule": spec.schedule,
+        });
+        match kroma_http::Loopback::new()
+            .header("authorization", format!("Bearer {host_token}"))
+            .post_json(url, &body)
+        {
+            Ok(resp) if (200..300).contains(&resp.status) => {
+                tracing::info!(job = %spec.key, "registered job with core scheduler");
+            }
+            Ok(resp) => tracing::warn!(
+                job = %spec.key,
+                status = resp.status,
+                "core rejected job registration: {}",
+                resp.text()
+            ),
+            Err(e) => {
+                tracing::warn!(job = %spec.key, error = %format!("{e:#}"), "job registration failed")
+            }
+        }
+    }
+}

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

@@ -0,0 +1,20 @@
+//! The out-of-process module runtime: each module is its own binary. `main()`
+//! calls [`serve`], which builds a [`RemoteHost`] ([`HostCtx`]) proxying
+//! settings, events, sessions and jobs to the core over `/api/_host/*`.
+//!
+//! Databases are a CAPABILITY, not part of the runtime: only a module built with
+//! the `storage` feature opens one, and it opens two -- its own file, and the
+//! core database behind the grant its manifest declared. A module without the
+//! feature does not link SQLite at all, which is most of the size of a sidecar
+//! that never had a table.
+
+mod env;
+mod events;
+mod host_ctx;
+mod jobs;
+mod migrations;
+mod remote_host;
+mod serve;
+
+pub use remote_host::RemoteHost;
+pub use serve::{serve, serve_one};

package/rust/kroma-module-runtime/src/migrations.rs

@@ -0,0 +1,48 @@
+use kroma_module_host::ServerModule;
+
+use crate::remote_host::RemoteHost;
+
+// A module's `migrations()` run against its OWN database, never the shared one:
+// the core database's schema is the core's, and a module that could add a table
+// to it could add a trigger to one it cannot read.
+#[cfg(feature = "storage")]
+pub(crate) fn apply_module_migrations(
+    host: &RemoteHost,
+    modules: &[Box<dyn ServerModule<RemoteHost>>],
+) -> anyhow::Result<()> {
+    use kroma_module_host::HostStorage;
+    let owners: Vec<_> = modules
+        .iter()
+        .filter(|module| !module.migrations().is_empty())
+        .collect();
+    anyhow::ensure!(
+        owners.len() <= 1,
+        "one process holds one module database, and {} modules declare a schema",
+        owners.len()
+    );
+    for module in owners {
+        kroma_sqlite::migrate_store(
+            host.store(),
+            module.id(),
+            module.migrations(),
+            module.steps(),
+        )?;
+    }
+    Ok(())
+}
+
+#[cfg(not(feature = "storage"))]
+pub(crate) fn apply_module_migrations(
+    _host: &RemoteHost,
+    modules: &[Box<dyn ServerModule<RemoteHost>>],
+) -> anyhow::Result<()> {
+    for module in modules {
+        anyhow::ensure!(
+            module.migrations().is_empty(),
+            "'{}' declares migrations but was built without the storage capability; add \
+             `storage` to its module.json and enable the SDK's `storage` feature",
+            module.id(),
+        );
+    }
+    Ok(())
+}

package/rust/kroma-module-runtime/src/remote_host.rs

@@ -0,0 +1,91 @@
+use std::any::{Any, TypeId};
+use std::collections::HashMap;
+use std::path::PathBuf;
+use std::sync::{Arc, RwLock};
+
+use crate::env::Env;
+
+/// The out-of-process [`HostCtx`]: settings, events, sessions and jobs go to the
+/// core over the callback API; the databases (behind `storage`) are opened here,
+/// because SQLite in WAL mode is multi-process and a query has no business
+/// becoming an HTTP round-trip.
+#[derive(Clone)]
+pub struct RemoteHost {
+    pub(crate) inner: Arc<Inner>,
+}
+
+pub(crate) struct Inner {
+    pub(crate) module_id: String,
+    pub(crate) data_dir: PathBuf,
+    #[cfg(feature = "storage")]
+    pub(crate) store: kroma_sqlite::Pool,
+    #[cfg(feature = "storage")]
+    pub(crate) core: kroma_sqlite::Pool,
+    pub(crate) core_url: String,
+    pub(crate) module_token: String,
+    pub(crate) services: RwLock<HashMap<TypeId, Arc<dyn Any + Send + Sync>>>,
+    // The metadata language, cached: it is one env-derived string, and every
+    // caller that renames a file asks for it.
+    pub(crate) language: RwLock<Option<String>>,
+}
+
+impl RemoteHost {
+    pub(crate) fn new(env: &Env) -> anyhow::Result<Self> {
+        Ok(Self {
+            inner: Arc::new(Inner {
+                module_id: env.module_id.clone(),
+                data_dir: env.data_dir.clone(),
+                // `open`, not `init`: the module's own file has no core schema
+                // in it, only whatever its own `migrations()` create below.
+                #[cfg(feature = "storage")]
+                store: kroma_sqlite::open(&env.store_path())?,
+                #[cfg(feature = "storage")]
+                core: kroma_sqlite::init_scoped(&env.db_path, &env.module_id, &env.grant())?,
+                core_url: env.core_url.clone(),
+                module_token: env.module_token.clone(),
+                services: RwLock::new(HashMap::new()),
+                language: RwLock::new(None),
+            }),
+        })
+    }
+
+    pub fn module_id(&self) -> &str {
+        &self.inner.module_id
+    }
+
+    /// Register a module-owned concrete service so its own code can resolve it by
+    /// type through `service::<T>(host)`. Keyed like the in-process registry:
+    /// concrete `TypeId::of::<T>()`, single `Arc`.
+    pub fn register_service<T: Any + Send + Sync>(&self, service: Arc<T>) {
+        self.inner
+            .services
+            .write()
+            .unwrap()
+            .insert(TypeId::of::<T>(), service as Arc<dyn Any + Send + Sync>);
+    }
+
+    pub(crate) fn callback(&self) -> kroma_http::Loopback {
+        kroma_http::Loopback::new().header(
+            "authorization",
+            format!("Bearer {}", self.inner.module_token),
+        )
+    }
+
+    pub(crate) fn host_url(&self, path: &str) -> String {
+        format!(
+            "{}/api/_host/{path}",
+            self.inner.core_url.trim_end_matches('/')
+        )
+    }
+}
+
+#[cfg(feature = "storage")]
+impl kroma_module_host::HostStorage for RemoteHost {
+    fn db(&self) -> &kroma_sqlite::Pool {
+        &self.inner.core
+    }
+
+    fn store(&self) -> &kroma_sqlite::Pool {
+        &self.inner.store
+    }
+}