@kromatv/sdk 0.1.39-canary.3579809

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

@@ -0,0 +1,153 @@
+//! The host-token guard.
+//!
+//! One random token the supervisor mints at boot authenticates the hops where
+//! the caller's identity does not change the answer: the core's
+//! `/_host/register-job` and `/_host/register-events` endpoints, and a sidecar's
+//! `/_job/run/*`, `/_event/*` and `/_port/*` routes. A peer holds it too, which
+//! is why it cannot also name its holder.
+//!
+//! The `/api/_host/*` callbacks are the exception and are guarded by the
+//! supervisor instead, against a token minted per module process, because what a
+//! module may read of the settings store depends on which module is asking.
+
+use axum::extract::{Request, State};
+use axum::http::{HeaderMap, StatusCode};
+use axum::middleware::Next;
+use axum::response::{IntoResponse, Response};
+
+/// Middleware state for [`require_host_token`]: the shared host token. Pass it to
+/// `axum::middleware::from_fn_with_state` alongside [`require_host_token`].
+#[derive(Clone)]
+pub struct HostToken(pub String);
+
+/// Reject a request whose bearer does not match the shared host token.
+pub async fn require_host_token(
+    State(token): State<HostToken>,
+    headers: HeaderMap,
+    req: Request,
+    next: Next,
+) -> Response {
+    let ok = headers
+        .get(axum::http::header::AUTHORIZATION)
+        .and_then(|v| v.to_str().ok())
+        .and_then(|v| v.strip_prefix("Bearer "))
+        .is_some_and(|t| ct_eq(t.as_bytes(), token.0.as_bytes()));
+    if ok {
+        next.run(req).await
+    } else {
+        (StatusCode::UNAUTHORIZED, "bad host token").into_response()
+    }
+}
+
+/// Constant-time byte equality, so matching a host token never leaks a shared
+/// prefix through timing. Length is compared first and in the clear, which a
+/// token's length already is.
+pub fn ct_eq(a: &[u8], b: &[u8]) -> bool {
+    if a.len() != b.len() {
+        return false;
+    }
+    let mut diff = 0u8;
+    for (x, y) in a.iter().zip(b) {
+        diff |= x ^ y;
+    }
+    diff == 0
+}
+
+#[cfg(test)]
+mod tests {
+    use axum::body::Body;
+    use axum::middleware::from_fn_with_state;
+    use axum::routing::get;
+    use axum::Router;
+    use tower::ServiceExt as _;
+
+    use super::*;
+
+    const TOKEN: &str = "s3cret-host-token";
+
+    fn guarded() -> Router {
+        Router::new()
+            .route("/_host/ping", get(|| async { "pong" }))
+            .layer(from_fn_with_state(
+                HostToken(TOKEN.to_string()),
+                require_host_token,
+            ))
+    }
+
+    async fn call(auth: Option<&str>) -> StatusCode {
+        let mut builder = Request::builder().uri("/_host/ping");
+        if let Some(v) = auth {
+            builder = builder.header(axum::http::header::AUTHORIZATION, v);
+        }
+        guarded()
+            .oneshot(builder.body(Body::empty()).unwrap())
+            .await
+            .unwrap()
+            .status()
+    }
+
+    #[tokio::test]
+    async fn the_shared_token_is_let_through() {
+        assert_eq!(call(Some(&format!("Bearer {TOKEN}"))).await, StatusCode::OK);
+    }
+
+    #[tokio::test]
+    async fn everything_else_is_rejected() {
+        assert_eq!(
+            call(None).await,
+            StatusCode::UNAUTHORIZED,
+            "no header at all"
+        );
+        assert_eq!(
+            call(Some("")).await,
+            StatusCode::UNAUTHORIZED,
+            "empty header"
+        );
+        assert_eq!(
+            call(Some(TOKEN)).await,
+            StatusCode::UNAUTHORIZED,
+            "no Bearer scheme"
+        );
+        assert_eq!(
+            call(Some(&format!("bearer {TOKEN}"))).await,
+            StatusCode::UNAUTHORIZED,
+            "the scheme is case-sensitive here, unlike the user-facing one",
+        );
+        assert_eq!(
+            call(Some(&format!("Basic {TOKEN}"))).await,
+            StatusCode::UNAUTHORIZED,
+            "a different scheme",
+        );
+        assert_eq!(
+            call(Some("Bearer ")).await,
+            StatusCode::UNAUTHORIZED,
+            "empty token"
+        );
+    }
+
+    #[tokio::test]
+    async fn a_token_that_merely_starts_right_is_rejected() {
+        assert_eq!(call(Some("Bearer s3cret")).await, StatusCode::UNAUTHORIZED);
+        assert_eq!(
+            call(Some(&format!("Bearer {TOKEN}-extra"))).await,
+            StatusCode::UNAUTHORIZED
+        );
+        assert_eq!(
+            call(Some(&format!("Bearer {}", &TOKEN[..TOKEN.len() - 1]))).await,
+            StatusCode::UNAUTHORIZED
+        );
+    }
+
+    #[test]
+    fn the_comparison_is_length_checked_then_constant_time() {
+        assert!(ct_eq(b"", b""));
+        assert!(ct_eq(b"abc", b"abc"));
+        assert!(!ct_eq(b"abc", b"abd"), "last byte differs");
+        assert!(!ct_eq(b"abc", b"xbc"), "first byte differs");
+        assert!(!ct_eq(b"abc", b"ab"), "shorter");
+        assert!(!ct_eq(b"ab", b"abc"), "longer");
+        // Non-UTF8 bytes compare the same way; the token is bytes, not text.
+        assert!(ct_eq(&[0xff, 0x00, 0x7f], &[0xff, 0x00, 0x7f]));
+        assert!(!ct_eq(&[0xff, 0x00], &[0xff, 0x01]));
+    }
+}

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

@@ -0,0 +1,143 @@
+//! The host seam between the running app and a module's backend: a module crate
+//! names only the [`HostCtx`] trait here, never `kroma-engine`, so the two do not
+//! form a dependency cycle.
+
+// The axum `Response` is deliberately the Err type of request guards so handlers
+// short-circuit with `?`.
+#![allow(clippy::result_large_err)]
+
+pub mod host_token;
+
+/// The `storage` capability: the module-private and scoped-core databases. Off
+/// unless the module declares storage, which is what keeps SQLite out of the
+/// eight sidecars that never open one.
+#[cfg(feature = "storage")]
+pub mod storage;
+
+#[cfg(any(test, feature = "testing"))]
+pub mod testing;
+
+/// [`test_serve::serve`] and [`test_serve::blocking`]: the wire-level helpers a
+/// point contract's round-trip test needs, without the database `testing` drags in.
+#[cfg(any(test, feature = "test-serve"))]
+pub mod test_serve;
+
+mod auth;
+mod host_ctx;
+mod module;
+mod port;
+mod setting_reach;
+
+pub use auth::*;
+pub use host_ctx::*;
+pub use module::*;
+pub use port::*;
+pub use setting_reach::*;
+
+use axum::http::StatusCode;
+use axum::response::{IntoResponse, Response};
+use axum::Json;
+
+pub use async_trait::async_trait;
+pub use kroma_module_wire::{
+    ActionKind, ActionSpec, ActionStyle, Audience, NotificationCategory, NotificationEvent,
+    NotificationSpec, PushCategory,
+};
+
+/// Build a JSON error response `{ "error": "<message>" }` with the given status.
+pub fn json_error(status: StatusCode, message: &str) -> Response {
+    (status, Json(serde_json::json!({ "error": message }))).into_response()
+}
+
+/// Run a blocking DB closure off the async runtime, mapping any failure to a
+/// uniform 500.
+pub async fn blocking<T, F>(f: F) -> Result<T, Response>
+where
+    F: FnOnce() -> anyhow::Result<T> + Send + 'static,
+    T: Send + 'static,
+{
+    match tokio::task::spawn_blocking(f).await {
+        Ok(Ok(v)) => Ok(v),
+        Ok(Err(e)) => {
+            tracing::error!(error = %e, "database error");
+            Err(json_error(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "internal error",
+            ))
+        }
+        Err(e) => {
+            tracing::error!(error = %e, "task join error");
+            Err(json_error(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "internal error",
+            ))
+        }
+    }
+}
+
+#[cfg(feature = "storage")]
+pub use storage::{query, HostStorage};
+
+/// A real-time event a module publishes onto the host's bus, fanned out to
+/// WebSocket clients as `{ "type": <topic>, ...payload }`.
+pub struct Event {
+    pub topic: String,
+    pub payload: serde_json::Value,
+}
+
+impl Event {
+    pub fn new(topic: impl Into<String>, payload: serde_json::Value) -> Self {
+        Self {
+            topic: topic.into(),
+            payload,
+        }
+    }
+}
+
+/// One configured library, in the leaf shape a module needs to place files.
+/// `kind` is `movies` or `shows`.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct LibraryFolders {
+    pub id: String,
+    pub kind: String,
+    pub name: String,
+    pub folders: Vec<String>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn json_error_carries_the_status() {
+        let resp = json_error(StatusCode::NOT_FOUND, "gone");
+        assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+        let resp = json_error(StatusCode::FORBIDDEN, "no");
+        assert_eq!(resp.status(), StatusCode::FORBIDDEN);
+    }
+
+    #[test]
+    fn event_new_keeps_topic_and_payload() {
+        let ev = Event::new("download.progress", serde_json::json!({ "pct": 42 }));
+        assert_eq!(ev.topic, "download.progress");
+        assert_eq!(ev.payload["pct"], 42);
+    }
+
+    #[tokio::test]
+    async fn blocking_returns_value_and_maps_failure_to_500() {
+        let ok: Result<i32, Response> = blocking(|| Ok(21 * 2)).await;
+        assert_eq!(ok.unwrap(), 42);
+
+        let err = blocking::<i32, _>(|| Err(anyhow::anyhow!("db down"))).await;
+        assert_eq!(err.unwrap_err().status(), StatusCode::INTERNAL_SERVER_ERROR);
+    }
+
+    #[tokio::test]
+    async fn a_panicking_blocking_task_becomes_a_500_rather_than_taking_the_server_down() {
+        let panicked = blocking::<i32, _>(|| panic!("a module's closure panicked")).await;
+        assert_eq!(
+            panicked.unwrap_err().status(),
+            StatusCode::INTERNAL_SERVER_ERROR
+        );
+    }
+}

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

@@ -0,0 +1,124 @@
+//! 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;
+
+    // The baseline of the module's own database: what a new file is created
+    // with, and what a file from before `steps()` is brought up to.
+    fn migrations(&self) -> &'static str {
+        ""
+    }
+
+    // Every change to the module's database since `migrations()`, oldest first,
+    // each applied once. A step that has shipped is never edited.
+    #[cfg(feature = "storage")]
+    fn steps(&self) -> &'static [kroma_sqlite::Step] {
+        &[]
+    }
+
+    // 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(), "");
+        #[cfg(feature = "storage")]
+        assert!(Bare.steps().is_empty());
+        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,171 @@
+//! 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,
+}
+
+impl Contribution {
+    /// A [`Resolver`] pinned to this one answer, for a caller that has already
+    /// picked which of a point's contributions it means. It does not re-resolve.
+    pub fn resolver(&self) -> Resolver {
+        let endpoint = (self.base_url.clone(), self.token.clone());
+        Arc::new(move || Some(endpoint.clone()))
+    }
+}
+
+/// 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,
+        })?;
+    Some(found.resolver())
+}
+
+/// 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/setting_reach.rs

@@ -0,0 +1,27 @@
+//! How far one settings key reaches out of the core.
+
+/// What the module host callback may do with a settings key. The core declares
+/// it beside the key's default; the supervisor carries the answer and never
+/// decides it.
+///
+/// [`Self::Declared`] is the narrow one: the key is handed to a module because a
+/// module is what consumes it, and to no module that did not say in its manifest
+/// that it reads or writes it. A caller the callback cannot name holds no
+/// declaration, so it reaches none of these.
+///
+/// [`Self::Unknown`] is withheld like [`Self::CoreOnly`] and separate from it only
+/// so the refusal can be logged for what it is: a module asking for the mail
+/// password is worth an operator's attention, one asking for a key the core has
+/// never heard of is a typo or a feature that left.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum SettingReach {
+    Unknown,
+    CoreOnly,
+    Declared,
+    Any,
+}
+
+/// Asks the core how far a settings key reaches. The supervisor holds this and
+/// nothing else about what any key means.
+#[derive(Clone, Copy)]
+pub struct SettingReachOf(pub fn(&str) -> SettingReach);