@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-http/src/loopback/tcp.rs

@@ -0,0 +1,182 @@
+//! Built on hyper's own client rather than a batteries-included one: axum
+//! already puts hyper in every sidecar, and a peer at 127.0.0.1 needs none of
+//! the TLS, proxy or cookie machinery the size would buy. It also cannot follow
+//! a redirect, which is what this seam wants -- a sidecar answering 302 is
+//! trying to move the core somewhere, and the only correct destination is the
+//! one the supervisor named.
+
+use std::sync::OnceLock;
+
+use anyhow::{bail, Context, Result};
+use bytes::Bytes;
+use http_body_util::{BodyExt, Full, Limited};
+use hyper_util::client::legacy::connect::HttpConnector;
+use hyper_util::client::legacy::Client;
+use hyper_util::rt::TokioExecutor;
+
+use super::transport::{Request, Transport};
+use crate::response::Response;
+
+/// Memory guard on a response body: what one wrong peer may make this process
+/// allocate, not a size any real payload on the seam approaches.
+pub const MAX_BODY_BYTES: usize = 64 * 1024 * 1024;
+
+/// Pooled HTTP/1.1 to another process on this machine.
+#[derive(Debug, Default)]
+pub struct Tcp;
+
+impl Transport for Tcp {
+    fn name(&self) -> &'static str {
+        "tcp"
+    }
+
+    fn accepts(&self, url: &str) -> bool {
+        is_loopback(url).unwrap_or(false)
+    }
+
+    fn send(&self, request: &Request<'_>) -> Result<Response> {
+        ensure_loopback(request.url)?;
+        let mut prepared = hyper::Request::builder()
+            .method(request.method.as_str())
+            .uri(request.url);
+        for (name, value) in request.headers {
+            prepared = prepared.header(name, value);
+        }
+        let body = match request.body {
+            Some((content_type, bytes)) => {
+                prepared = prepared.header("content-type", content_type);
+                Bytes::copy_from_slice(bytes)
+            }
+            None => Bytes::new(),
+        };
+        let prepared = prepared
+            .body(Full::new(body))
+            .context("build the loopback request")?;
+        let timeout = request.timeout;
+        block_on(async move {
+            let response = tokio::time::timeout(timeout, client().request(prepared))
+                .await
+                .context("the loopback peer did not answer in time")?
+                .context("send the loopback request")?;
+            let status = response.status().as_u16();
+            let headers = response
+                .headers()
+                .iter()
+                .map(|(name, value)| {
+                    (
+                        name.as_str().to_string(),
+                        String::from_utf8_lossy(value.as_bytes()).into_owned(),
+                    )
+                })
+                .collect();
+            let body = Limited::new(response.into_body(), MAX_BODY_BYTES)
+                .collect()
+                .await
+                .map_err(|e| anyhow::anyhow!("read the loopback response body: {e}"))?;
+            Ok(Response {
+                status,
+                headers,
+                body: body.to_bytes().to_vec(),
+            })
+        })
+    }
+}
+
+fn client() -> &'static Client<HttpConnector, Full<Bytes>> {
+    static CLIENT: OnceLock<Client<HttpConnector, Full<Bytes>>> = OnceLock::new();
+    CLIENT.get_or_init(|| Client::builder(TokioExecutor::new()).build_http())
+}
+
+// `Handle::block_on` panics on a worker thread and `spawn_blocking` threads still
+// carry the ambient handle, so the work goes to a runtime that is not the
+// caller's.
+fn runtime() -> &'static tokio::runtime::Runtime {
+    static RUNTIME: OnceLock<tokio::runtime::Runtime> = OnceLock::new();
+    RUNTIME.get_or_init(|| {
+        tokio::runtime::Builder::new_multi_thread()
+            .worker_threads(1)
+            .thread_name("kroma-loopback")
+            .enable_all()
+            .build()
+            .expect("build the loopback runtime")
+    })
+}
+
+// A sidecar builds with `panic = "abort"`, so a panic here would take the whole
+// module process down where the caller expects a recoverable error.
+fn block_on<T>(future: impl std::future::Future<Output = Result<T>> + Send + 'static) -> Result<T>
+where
+    T: Send + 'static,
+{
+    let (tx, rx) = std::sync::mpsc::sync_channel(1);
+    runtime().spawn(async move {
+        let _ = tx.send(future.await);
+    });
+    match rx.recv() {
+        Ok(outcome) => outcome,
+        Err(_) => bail!("the loopback exchange ended without a response"),
+    }
+}
+
+fn is_loopback(url: &str) -> Result<bool> {
+    let uri: hyper::Uri = url.parse().with_context(|| format!("parse the URL: {url}"))?;
+    if uri.scheme_str() != Some("http") {
+        return Ok(false);
+    }
+    let Some(host) = uri.host() else {
+        return Ok(false);
+    };
+    // An IPv6 host keeps its brackets through `host`, and loopback is a range
+    // rather than the one literal the supervisor happens to hand out, so this
+    // parses rather than matching strings.
+    let bare = host.trim_start_matches('[').trim_end_matches(']');
+    Ok(bare == "localhost"
+        || bare
+            .parse::<std::net::IpAddr>()
+            .is_ok_and(|ip| ip.is_loopback()))
+}
+
+fn ensure_loopback(url: &str) -> Result<()> {
+    if !is_loopback(url)? {
+        bail!("the tcp transport refuses {url}: not plain http on this machine");
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_host_that_is_not_loopback_is_refused() {
+        let err = ensure_loopback("http://example.com/_port/x")
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("example.com"), "{err}");
+    }
+
+    #[test]
+    fn every_spelling_of_this_machine_is_accepted() {
+        assert!(Tcp.accepts("http://127.0.0.1:9/_port/x"));
+        assert!(Tcp.accepts("http://localhost:9/_port/x"));
+        assert!(Tcp.accepts("http://[::1]:9/_port/x"));
+        assert!(Tcp.accepts("http://127.0.0.2:9/_port/x"));
+    }
+
+    #[test]
+    fn an_address_outside_the_loopback_range_is_refused() {
+        assert!(!Tcp.accepts("http://10.0.0.5:9/_port/x"));
+        assert!(!Tcp.accepts("http://169.254.169.254/latest/meta-data"));
+    }
+
+    #[test]
+    fn a_tls_url_is_refused_because_this_seam_has_no_tls_stack() {
+        assert!(!Tcp.accepts("https://127.0.0.1:9/_port/x"));
+    }
+
+    #[test]
+    fn an_unparseable_url_is_refused_rather_than_panicking() {
+        assert!(!Tcp.accepts("not a url"));
+        assert!(ensure_loopback("not a url").is_err());
+    }
+}

package/rust/kroma-http/src/loopback/transport.rs

@@ -0,0 +1,42 @@
+use std::time::Duration;
+
+use anyhow::Result;
+
+use crate::response::Response;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Method {
+    Get,
+    Post,
+}
+
+impl Method {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Get => "GET",
+            Self::Post => "POST",
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct Request<'a> {
+    pub method: Method,
+    pub url: &'a str,
+    pub headers: &'a [(String, String)],
+    /// `(content-type, bytes)`, absent on a GET.
+    pub body: Option<(&'a str, &'a [u8])>,
+    pub timeout: Duration,
+}
+
+/// A way for one KROMA process to reach another.
+///
+/// [`Transport::send`] blocks the calling thread. An implementation built on
+/// async internals owns that bridge itself.
+pub trait Transport: Send + Sync + 'static {
+    fn name(&self) -> &'static str;
+
+    fn accepts(&self, url: &str) -> bool;
+
+    fn send(&self, request: &Request<'_>) -> Result<Response>;
+}

package/rust/kroma-http/src/response.rs

@@ -0,0 +1,130 @@
+//! The rendered outcome of one exchange.
+
+use anyhow::{bail, Context, Result};
+use serde::de::DeserializeOwned;
+
+/// One HTTP exchange: final status + final header block + body bytes.
+#[derive(Debug)]
+pub struct Response {
+    pub status: u16,
+    pub headers: Vec<(String, String)>,
+    pub body: Vec<u8>,
+}
+
+impl Response {
+    /// First header with this name, case-insensitively.
+    pub fn header(&self, name: &str) -> Option<&str> {
+        self.headers
+            .iter()
+            .find(|(k, _)| k.eq_ignore_ascii_case(name))
+            .map(|(_, v)| v.as_str())
+    }
+
+    pub fn text(&self) -> String {
+        String::from_utf8_lossy(&self.body).into_owned()
+    }
+
+    pub fn json<T: DeserializeOwned>(&self) -> Result<T> {
+        serde_json::from_slice(&self.body)
+            .with_context(|| format!("parse JSON response: {}", snippet(&self.body)))
+    }
+
+    /// Error out (with a body snippet) unless the status is 2xx.
+    pub fn ensure_ok(self) -> Result<Self> {
+        if !(200..300).contains(&self.status) {
+            bail!("HTTP {}: {}", self.status, snippet(&self.body));
+        }
+        Ok(self)
+    }
+}
+
+fn snippet(body: &[u8]) -> String {
+    let text = String::from_utf8_lossy(body);
+    let trimmed = text.trim();
+    let mut s: String = trimmed.chars().take(200).collect();
+    if trimmed.chars().count() > 200 {
+        s.push_str("...");
+    }
+    s
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn header_lookup_is_case_insensitive() {
+        let resp = Response {
+            status: 409,
+            headers: vec![(
+                "X-Transmission-Session-Id".to_string(),
+                "abc123".to_string(),
+            )],
+            body: Vec::new(),
+        };
+        assert_eq!(resp.header("x-transmission-session-id"), Some("abc123"));
+        assert_eq!(resp.header("missing"), None);
+    }
+
+    #[test]
+    fn ensure_ok_rejects_non_2xx_with_snippet() {
+        let resp = Response {
+            status: 500,
+            headers: Vec::new(),
+            body: b"boom".to_vec(),
+        };
+        let err = resp.ensure_ok().unwrap_err().to_string();
+        assert!(err.contains("500"), "{err}");
+        assert!(err.contains("boom"), "{err}");
+    }
+
+    #[test]
+    fn snippet_trims_and_truncates_long_bodies() {
+        assert_eq!(snippet(b"  hi there  "), "hi there");
+        let long = "a".repeat(500);
+        let s = snippet(long.as_bytes());
+        assert_eq!(s.chars().count(), 203, "200 kept chars + the ... suffix");
+        assert!(s.ends_with("..."));
+        let exact = "b".repeat(200);
+        let s = snippet(exact.as_bytes());
+        assert_eq!(s.chars().count(), 200);
+        assert!(!s.ends_with("..."));
+    }
+
+    #[test]
+    fn response_text_and_json_round_trip_and_error() {
+        let resp = Response {
+            status: 200,
+            headers: Vec::new(),
+            body: br#"{"a":1}"#.to_vec(),
+        };
+        assert_eq!(resp.text(), r#"{"a":1}"#);
+        let v: serde_json::Value = resp.json().unwrap();
+        assert_eq!(v["a"], 1);
+
+        let bad = Response {
+            status: 200,
+            headers: Vec::new(),
+            body: b"not json at all".to_vec(),
+        };
+        let err = bad.json::<serde_json::Value>().unwrap_err().to_string();
+        assert!(err.contains("parse JSON"), "{err}");
+        assert!(err.contains("not json"), "{err}");
+    }
+
+    #[test]
+    fn ensure_ok_accepts_2xx() {
+        let resp = Response {
+            status: 204,
+            headers: Vec::new(),
+            body: Vec::new(),
+        };
+        assert!(resp.ensure_ok().is_ok());
+        let redirect = Response {
+            status: 300,
+            headers: Vec::new(),
+            body: b"moved".to_vec(),
+        };
+        assert!(redirect.ensure_ok().is_err());
+    }
+}

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

@@ -0,0 +1,36 @@
+[package]
+name = "kroma-module-host"
+version = "0.1.40-canary.0"
+edition = "2021"
+rust-version = "1.88"
+description = "The host seam: the narrow HostCtx contract + shared HTTP extractors a module crate's backend needs, without depending on the whole app (kroma-engine)."
+license = "MIT"
+
+[features]
+# Compiles `testing::{StubHost, Recording}`, the shared HostCtx doubles. Off by
+# default so nothing reaches a release build; crates that test against the seam
+# turn it on in their dev-dependencies.
+testing = ["dep:kroma-testing", "storage", "test-serve"]
+# `test_serve::{serve, blocking}` alone: an axum router on an ephemeral localhost
+# port. Separate from `testing` because a port contract's round-trip test needs
+# the wire and not a database.
+test-serve = []
+# The `storage` capability: `HostStorage`, the two pools, and the `query` helper.
+# Off by default, and that default is the point -- a module that declares no
+# storage must not link `kroma-db`, which is what drags the whole bundled SQLite
+# amalgamation (1.5 MB of machine code) into a sidecar that never opens a
+# database. Enabled through `kroma-module-sdk/storage` by the modules that do.
+storage = ["dep:kroma-db"]
+
+[dependencies]
+kroma-domain = { path = "../kroma-domain" }
+kroma-db = { path = "../kroma-db", optional = true }
+kroma-http = { path = "../kroma-http" }
+kroma-testing = { path = "../kroma-testing", optional = true }
+axum = { version = "0.8", features = ["macros", "ws"] }
+async-trait = { version = "0.1" }
+tokio = { version = "1", features = ["full"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1" }
+anyhow = { version = "1" }
+tracing = { version = "0.1" }

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

@@ -0,0 +1,221 @@
+//! The axum request guards a module's routes use: an authenticated caller
+//! resolved through the host's session seam, and the bearer-token reader.
+
+use axum::extract::FromRequestParts;
+use axum::http::request::Parts;
+use axum::http::StatusCode;
+use axum::response::Response;
+
+use kroma_domain::User;
+
+use super::{json_error, HostCtx};
+
+/// An authenticated user, resolved from an `Authorization: Bearer <token>`
+/// header through [`HostCtx::session_user`]. A missing, expired or unknown token
+/// yields `401`.
+pub struct AuthUser(pub User);
+
+// Resolution is blocking, so it runs on a blocking thread and the state has to
+// be owned there -- which is why these two want `Clone`. Every router state
+// already is one (axum requires it).
+async fn resolve_session<S: HostCtx + Clone>(parts: &Parts, state: &S) -> Option<User> {
+    let token = bearer_from_headers(&parts.headers)?;
+    let state = state.clone();
+    tokio::task::spawn_blocking(move || state.session_user(&token))
+        .await
+        .ok()
+        .flatten()
+}
+
+impl<S: HostCtx + Clone> FromRequestParts<S> for AuthUser {
+    type Rejection = Response;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        if bearer_from_headers(&parts.headers).is_none() {
+            return Err(json_error(StatusCode::UNAUTHORIZED, "missing bearer token"));
+        }
+        let user = resolve_session(parts, state)
+            .await
+            .ok_or_else(|| json_error(StatusCode::UNAUTHORIZED, "invalid or expired session"))?;
+        Ok(AuthUser(user))
+    }
+}
+
+/// `Some(user)` for a valid Bearer token, `None` otherwise. Never rejects, for
+/// endpoints that are public but personalise when signed in.
+pub struct OptionalAuthUser(pub Option<User>);
+
+impl<S: HostCtx + Clone> FromRequestParts<S> for OptionalAuthUser {
+    type Rejection = std::convert::Infallible;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        Ok(OptionalAuthUser(resolve_session(parts, state).await))
+    }
+}
+
+pub fn bearer_from_headers(headers: &axum::http::HeaderMap) -> Option<String> {
+    let h = headers.get(axum::http::header::AUTHORIZATION)?;
+    let s = h.to_str().ok()?;
+    s.strip_prefix("Bearer ")
+        .or_else(|| s.strip_prefix("bearer "))
+        .map(|t| t.trim().to_string())
+        .filter(|t| !t.is_empty())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use crate::testing;
+
+    #[test]
+    fn bearer_from_headers_extracts_case_insensitively_and_trims() {
+        use axum::http::{header::AUTHORIZATION, HeaderMap, HeaderValue};
+
+        let mut h = HeaderMap::new();
+        h.insert(AUTHORIZATION, HeaderValue::from_static("Bearer abc123"));
+        assert_eq!(bearer_from_headers(&h).as_deref(), Some("abc123"));
+
+        let mut h = HeaderMap::new();
+        h.insert(AUTHORIZATION, HeaderValue::from_static("bearer   tok  "));
+        assert_eq!(bearer_from_headers(&h).as_deref(), Some("tok"));
+
+        assert!(bearer_from_headers(&HeaderMap::new()).is_none());
+
+        let mut h = HeaderMap::new();
+        h.insert(AUTHORIZATION, HeaderValue::from_static("Basic Zm9v"));
+        assert!(bearer_from_headers(&h).is_none());
+
+        let mut h = HeaderMap::new();
+        h.insert(AUTHORIZATION, HeaderValue::from_static("Bearer    "));
+        assert!(bearer_from_headers(&h).is_none());
+    }
+
+    #[tokio::test]
+    async fn optional_auth_is_none_when_the_request_carries_no_bearer() {
+        let (mut parts, ()) = axum::http::Request::builder()
+            .body(())
+            .unwrap()
+            .into_parts();
+        let host = testing::StubHost::new();
+        let OptionalAuthUser(user) = OptionalAuthUser::from_request_parts(&mut parts, &host)
+            .await
+            .unwrap();
+        assert!(
+            user.is_none(),
+            "a public endpoint must not reject an anonymous caller"
+        );
+    }
+
+    fn bearer(token: &str) -> Parts {
+        axum::http::Request::builder()
+            .header(axum::http::header::AUTHORIZATION, format!("Bearer {token}"))
+            .body(())
+            .unwrap()
+            .into_parts()
+            .0
+    }
+
+    fn someone() -> User {
+        User {
+            id: "u1".into(),
+            email: "ana@t.dev".into(),
+            username: "ana".into(),
+            avatar_url: None,
+            language: None,
+            audio_language: None,
+            subtitle_language: None,
+            permissions: Vec::new(),
+            created_at: "now".into(),
+            has_pin: false,
+        }
+    }
+
+    #[tokio::test]
+    async fn both_extractors_resolve_through_the_host_rather_than_a_database() {
+        let host = testing::StubHost::new().with_session("live", someone());
+
+        let AuthUser(user) = AuthUser::from_request_parts(&mut bearer("live"), &host)
+            .await
+            .unwrap();
+        assert_eq!(user.id, "u1");
+
+        let OptionalAuthUser(user) =
+            OptionalAuthUser::from_request_parts(&mut bearer("live"), &host)
+                .await
+                .unwrap();
+        assert_eq!(user.map(|u| u.id).as_deref(), Some("u1"));
+    }
+
+    #[tokio::test]
+    async fn a_token_the_host_does_not_know_is_a_401_and_not_a_500() {
+        let host = testing::StubHost::new().with_session("live", someone());
+
+        // `AuthUser` is not Debug, so map the Ok side away before unwrapping.
+        let status = |r: Result<AuthUser, Response>| r.map(|_| ()).unwrap_err().status();
+        assert_eq!(
+            status(AuthUser::from_request_parts(&mut bearer("stale"), &host).await),
+            StatusCode::UNAUTHORIZED
+        );
+        assert_eq!(
+            status(
+                AuthUser::from_request_parts(
+                    &mut axum::http::Request::builder()
+                        .body(())
+                        .unwrap()
+                        .into_parts()
+                        .0,
+                    &host,
+                )
+                .await
+            ),
+            StatusCode::UNAUTHORIZED
+        );
+
+        let OptionalAuthUser(user) =
+            OptionalAuthUser::from_request_parts(&mut bearer("stale"), &host)
+                .await
+                .unwrap();
+        assert!(user.is_none());
+    }
+
+    #[test]
+    fn a_bearer_token_is_read_case_insensitively_and_trimmed() {
+        let header = |v: &str| {
+            let mut h = axum::http::HeaderMap::new();
+            h.insert(axum::http::header::AUTHORIZATION, v.parse().unwrap());
+            h
+        };
+        assert_eq!(
+            bearer_from_headers(&header("Bearer abc123")).as_deref(),
+            Some("abc123")
+        );
+        assert_eq!(
+            bearer_from_headers(&header("bearer abc123")).as_deref(),
+            Some("abc123")
+        );
+        assert_eq!(
+            bearer_from_headers(&header("Bearer   abc123  ")).as_deref(),
+            Some("abc123")
+        );
+    }
+
+    #[test]
+    fn anything_that_is_not_a_bearer_token_is_no_token() {
+        // An empty token must not read as valid, or `Authorization: Bearer `
+        // would look authenticated to the session lookup.
+        let header = |v: &str| {
+            let mut h = axum::http::HeaderMap::new();
+            h.insert(axum::http::header::AUTHORIZATION, v.parse().unwrap());
+            h
+        };
+        assert!(bearer_from_headers(&header("Bearer ")).is_none());
+        assert!(bearer_from_headers(&header("Bearer    ")).is_none());
+        assert!(bearer_from_headers(&header("Basic dXNlcjpwYXNz")).is_none());
+        assert!(
+            bearer_from_headers(&header("abc123")).is_none(),
+            "a bare token is not a bearer"
+        );
+        assert!(bearer_from_headers(&axum::http::HeaderMap::new()).is_none());
+    }
+}