@kromatv/sdk 0.1.39-canary.3579809

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

@@ -0,0 +1,347 @@
+//! The request builder and the executors that send it.
+
+use std::path::PathBuf;
+
+use anyhow::{Context, Result};
+use serde::de::DeserializeOwned;
+
+use crate::config::{header_line, option_line};
+use crate::curl::run;
+use crate::multipart::{part_line, FormPart};
+use crate::response::Response;
+
+/// A prepared request: builder-style options, then one of the executors
+/// ([`Fetch::get`], [`Fetch::post_json`], [`Fetch::post_form`]).
+#[derive(Debug, Clone)]
+pub struct Fetch {
+    headers: Vec<(String, String)>,
+    query: Vec<(String, String)>,
+    socks5: Option<String>,
+    cookie_jar: Option<PathBuf>,
+    digest: Option<(String, String)>,
+    max_time_secs: u32,
+    max_bytes: Option<u64>,
+    http2: bool,
+}
+
+impl Default for Fetch {
+    fn default() -> Self {
+        Self {
+            headers: Vec::new(),
+            query: Vec::new(),
+            socks5: None,
+            cookie_jar: None,
+            digest: None,
+            max_time_secs: 30,
+            max_bytes: None,
+            http2: false,
+        }
+    }
+}
+
+crate::builder::request_builder!(
+    Fetch,
+    query = "URL-encoded query parameter (GET only; sent via `--get --data-urlencode`)."
+);
+
+impl Fetch {
+    /// Route this request through a SOCKS5 proxy (`host:port` or a full
+    /// `socks5://user:pass@host:port` URL). Uses `--socks5-hostname` so DNS
+    /// resolves on the proxy side too (no local DNS leak).
+    pub fn socks5(mut self, proxy: impl Into<String>) -> Self {
+        let p = proxy.into();
+        if !p.trim().is_empty() {
+            self.socks5 = Some(p);
+        }
+        self
+    }
+
+    /// Refuse a response body larger than `bytes`, so a third-party answer is
+    /// bounded before anything parses it.
+    pub fn max_bytes(mut self, bytes: u64) -> Self {
+        self.max_bytes = Some(bytes);
+        self
+    }
+
+    /// Read + write cookies at `jar` across calls (qBittorrent's SID auth).
+    pub fn cookie_jar(mut self, jar: impl Into<PathBuf>) -> Self {
+        self.cookie_jar = Some(jar.into());
+        self
+    }
+
+    /// Answer an HTTP digest challenge as `user` (Roku's developer installer
+    /// serves one). The credentials travel in the config on curl's stdin, so
+    /// they never reach argv.
+    pub fn digest(mut self, user: &str, password: impl Into<String>) -> Self {
+        self.digest = Some((user.to_string(), password.into()));
+        self
+    }
+
+    /// Require HTTP/2 for this request.
+    ///
+    /// Not a preference: APNs serves HTTP/2 only and refuses an HTTP/1.1
+    /// request, so a caller that needs it must be able to say so. Needs a curl
+    /// built with nghttp2 (`curl --version` lists `HTTP2`).
+    pub fn http2(mut self) -> Self {
+        self.http2 = true;
+        self
+    }
+
+    pub fn get(&self, url: &str) -> Result<Response> {
+        let mut config = self.base_config();
+        if !self.query.is_empty() {
+            config.push_str("get\n");
+            for (k, v) in &self.query {
+                config.push_str(&option_line("data-urlencode", &format!("{k}={v}")));
+            }
+        }
+        config.push_str(&option_line("url", url));
+        run(config)
+    }
+
+    pub fn post_json(&self, url: &str, body: &serde_json::Value) -> Result<Response> {
+        let mut config = self.base_config();
+        config.push_str(&header_line("content-type", "application/json"));
+        config.push_str(&option_line("data-binary", &serde_json::to_string(body)?));
+        config.push_str(&option_line("url", url));
+        run(config)
+    }
+
+    /// POST a raw byte body (Web Push's `aes128gcm` ciphertext).
+    ///
+    /// The bytes go through a temp file, not an argv entry: an encrypted body is
+    /// arbitrary binary, and a command-line argument cannot carry a NUL and
+    /// would be mangled by any non-UTF-8 byte.
+    pub fn post_bytes(&self, url: &str, content_type: &str, body: &[u8]) -> Result<Response> {
+        use std::io::Write;
+
+        let mut file = tempfile::Builder::new()
+            .prefix("kroma-http-body-")
+            .tempfile()
+            .context("create the curl request body")?;
+        file.write_all(body)
+            .context("write the curl request body")?;
+        file.flush().context("write the curl request body")?;
+
+        let mut config = self.base_config();
+        config.push_str(&header_line("content-type", content_type));
+        config.push_str(&option_line(
+            "data-binary",
+            &format!("@{}", file.path().display()),
+        ));
+        config.push_str(&option_line("url", url));
+        run(config)
+    }
+
+    /// `application/x-www-form-urlencoded` POST (qBittorrent login/actions).
+    /// With no fields it is a POST with an empty body rather than a GET, which
+    /// is what Roku's ECP wants: the arguments in the query string, nothing else.
+    pub fn post_form(&self, url: &str, fields: &[(&str, &str)]) -> Result<Response> {
+        run(self.form_config(url, fields))
+    }
+
+    /// `multipart/form-data` POST (Roku's developer installer takes the channel
+    /// zip this way).
+    pub fn post_multipart(&self, url: &str, parts: &[(&str, FormPart<'_>)]) -> Result<Response> {
+        run(self.multipart_config(url, parts))
+    }
+
+    /// GET expecting a 2xx JSON body; the common happy path in one call.
+    pub fn get_json<T: DeserializeOwned>(&self, url: &str) -> Result<T> {
+        self.get(url)?.ensure_ok()?.json()
+    }
+
+    fn form_config(&self, url: &str, fields: &[(&str, &str)]) -> String {
+        let mut config = self.base_config();
+        // Only with no fields: a data line is what makes curl POST, and naming
+        // the method outright would also make it re-POST to a redirect instead
+        // of following with GET, which an indexer's HTML login form expects.
+        if fields.is_empty() {
+            config.push_str(&option_line("request", "POST"));
+            config.push_str(&option_line("data", ""));
+        }
+        for (k, v) in fields {
+            config.push_str(&option_line("data-urlencode", &format!("{k}={v}")));
+        }
+        config.push_str(&option_line("url", url));
+        config
+    }
+
+    fn multipart_config(&self, url: &str, parts: &[(&str, FormPart<'_>)]) -> String {
+        let mut config = self.base_config();
+        for (name, part) in parts {
+            config.push_str(&part_line(name, *part));
+        }
+        config.push_str(&option_line("url", url));
+        config
+    }
+
+    fn base_config(&self) -> String {
+        // location: indexer download links commonly redirect. No fail: we surface
+        // the status ourselves so error bodies (and 409 handshakes) stay readable.
+        let mut config = String::from("silent\nshow-error\nlocation\n");
+        config.push_str(&option_line("max-time", &self.max_time_secs.to_string()));
+        if let Some(bytes) = self.max_bytes {
+            config.push_str(&option_line("max-filesize", &bytes.to_string()));
+        }
+        if self.http2 {
+            config.push_str("http2\n");
+        }
+        if let Some(proxy) = &self.socks5 {
+            // ipv4: the only SOCKS proxy (a WireGuard bridge) is IPv4-only, and a
+            // dual-stack host can otherwise resolve to an AAAA the tunnel can't route.
+            config.push_str("ipv4\n");
+            config.push_str(&option_line("socks5-hostname", proxy));
+        }
+        if let Some((user, password)) = &self.digest {
+            config.push_str("digest\n");
+            config.push_str(&option_line("user", &format!("{user}:{password}")));
+        }
+        if let Some(jar) = &self.cookie_jar {
+            let jar = jar.to_string_lossy();
+            config.push_str(&option_line("cookie-jar", &jar));
+            config.push_str(&option_line("cookie", &jar));
+        }
+        for (k, v) in &self.headers {
+            config.push_str(&header_line(k, v));
+        }
+        config
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::Path;
+
+    use super::*;
+
+    #[test]
+    fn empty_socks5_is_ignored() {
+        let f = Fetch::new().socks5("  ");
+        assert!(f.socks5.is_none());
+    }
+
+    #[test]
+    fn socks5_forces_ipv4() {
+        let config = Fetch::new()
+            .socks5("socks5://127.0.0.1:25345")
+            .base_config();
+        assert!(config.contains("\nipv4\n"), "{config}");
+        assert!(
+            config.contains(r#"socks5-hostname = "socks5://127.0.0.1:25345""#),
+            "{config}"
+        );
+        assert!(!Fetch::new().base_config().contains("ipv4"), "{config}");
+    }
+
+    #[test]
+    fn base_config_carries_headers_cookie_jar_and_max_time() {
+        let config = Fetch::new()
+            .header("X-Test", "v")
+            .max_time(99)
+            .cookie_jar("/tmp/jar")
+            .base_config();
+        assert!(config.contains(r#"header = "X-Test: v""#), "{config}");
+        assert!(config.contains(r#"max-time = "99""#), "{config}");
+        assert!(config.contains(r#"cookie-jar = "/tmp/jar""#), "{config}");
+        assert!(config.contains(r#"cookie = "/tmp/jar""#), "{config}");
+    }
+
+    #[test]
+    fn a_body_cap_reaches_curl_only_when_asked_for() {
+        assert!(Fetch::new()
+            .max_bytes(1024)
+            .base_config()
+            .contains(r#"max-filesize = "1024""#));
+        assert!(!Fetch::new().base_config().contains("max-filesize"));
+    }
+
+    #[test]
+    fn http2_is_requested_only_when_asked_for() {
+        assert!(Fetch::new().http2().base_config().contains("\nhttp2\n"));
+        assert!(!Fetch::new().base_config().contains("http2"));
+    }
+
+    #[test]
+    fn a_header_value_cannot_inject_a_second_curl_option() {
+        let smuggled = "k\"\r\noutput = \"/tmp/pwned\"\nheader = \"X-Injected: 1\\";
+        let config = Fetch::new().header("X-Api-Key", smuggled).base_config();
+
+        let options: Vec<&str> = config.lines().collect();
+        assert_eq!(options.len(), 5, "one line per option: {config}");
+        assert!(
+            options[4].starts_with(r#"header = "X-Api-Key: k\""#),
+            "{config}"
+        );
+        assert!(options[4].ends_with(r#"X-Injected: 1\\""#), "{config}");
+    }
+
+    #[test]
+    fn only_a_form_post_with_no_fields_names_the_method_itself() {
+        let empty = Fetch::new().form_config("http://box:8060/launch/dev?server=x", &[]);
+        assert!(empty.contains("request = \"POST\"\n"), "{empty}");
+        assert!(empty.contains("data = \"\"\n"), "{empty}");
+
+        let filled = Fetch::new().form_config("http://box/api", &[("user", "ana")]);
+        assert!(!filled.contains("request = "), "{filled}");
+        assert!(!filled.contains("data = \"\"\n"), "{filled}");
+        assert!(
+            filled.contains("data-urlencode = \"user=ana\"\n"),
+            "{filled}"
+        );
+    }
+
+    #[test]
+    fn a_multipart_post_carries_one_line_per_part_and_the_url_last() {
+        let config = Fetch::new().multipart_config(
+            "http://box/plugin_install",
+            &[
+                ("mysubmit", FormPart::Text("Replace")),
+                ("archive", FormPart::File(Path::new("/data/channel.zip"))),
+            ],
+        );
+
+        let options: Vec<&str> = config.lines().collect();
+        assert_eq!(
+            options[4], r#"form-string = "mysubmit=Replace""#,
+            "{config}"
+        );
+        assert_eq!(
+            options[5], r#"form = "archive=@\"/data/channel.zip\"""#,
+            "{config}"
+        );
+        assert_eq!(
+            options[6], r#"url = "http://box/plugin_install""#,
+            "{config}"
+        );
+    }
+
+    #[test]
+    fn a_digest_password_cannot_smuggle_a_second_curl_option() {
+        let smuggled = "pa\"ss\nurl = \"http://evil\"";
+        let config = Fetch::new().digest("rokudev", smuggled).base_config();
+
+        let options: Vec<&str> = config.lines().collect();
+        assert_eq!(options.len(), 6, "one line per option: {config}");
+        assert_eq!(options[4], "digest", "{config}");
+        assert!(
+            options[5].starts_with(r#"user = "rokudev:pa\"ss\nurl"#),
+            "{config}"
+        );
+        assert!(!Fetch::new().base_config().contains("digest"));
+    }
+
+    #[test]
+    fn builder_setters_record_options() {
+        let f = Fetch::new()
+            .query("q", "hello world")
+            .header("A", "b")
+            .max_time(5);
+        assert_eq!(f.query, vec![("q".to_string(), "hello world".to_string())]);
+        assert_eq!(f.headers, vec![("A".to_string(), "b".to_string())]);
+        assert_eq!(f.max_time_secs, 5);
+        assert_eq!(Fetch::new().max_time_secs, 30);
+        assert!(!Fetch::new().http2);
+        assert!(Fetch::new().http2().http2);
+    }
+}

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

@@ -0,0 +1,27 @@
+//! KROMA's two HTTP transports, split by who is on the other end.
+//!
+//! [`Fetch`] reaches the outside world -- Torznab indexers, Transmission and
+//! qBittorrent RPC, VPN checks -- over the system `curl` binary. Deliberately
+//! not streaming: every payload here fits in memory. Response headers are
+//! captured via `dump-header` because some protocols carry state there
+//! (Transmission's `X-Transmission-Session-Id` rides a 409 response), which is
+//! also why requests never enable `fail`: callers read [`Response::status`]
+//! instead of losing the body on HTTP errors. Options reach curl through a
+//! config file on its stdin, never through argv.
+//!
+//! [`Loopback`] reaches a process KROMA started itself -- the core from a
+//! module, a module from the core. It holds no transport of its own: a
+//! [`Transport`] is chosen per URL.
+
+mod builder;
+mod config;
+mod curl;
+mod fetch;
+pub mod loopback;
+mod multipart;
+mod response;
+
+pub use fetch::Fetch;
+pub use loopback::{Loopback, Method, Request, Transport, MAX_BODY_BYTES};
+pub use multipart::FormPart;
+pub use response::Response;

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

@@ -0,0 +1,220 @@
+//! The transport for the internal seam: the core and its module sidecars
+//! calling each other on this machine.
+
+mod tcp;
+mod transport;
+
+use std::sync::{Arc, OnceLock, RwLock};
+use std::time::Duration;
+
+use anyhow::{bail, Result};
+
+use crate::response::Response;
+pub use tcp::{Tcp, MAX_BODY_BYTES};
+pub use transport::{Method, Request, Transport};
+
+const DEFAULT_MAX_TIME_SECS: u32 = 30;
+
+fn registry() -> &'static RwLock<Vec<Arc<dyn Transport>>> {
+    static REGISTRY: OnceLock<RwLock<Vec<Arc<dyn Transport>>>> = OnceLock::new();
+    REGISTRY.get_or_init(|| RwLock::new(vec![Arc::new(Tcp)]))
+}
+
+/// Add a transport ahead of the built-in ones, for the URLs its
+/// [`Transport::accepts`] claims. Registered last wins.
+pub fn register(transport: Arc<dyn Transport>) {
+    registry()
+        .write()
+        .expect("the transport registry was poisoned")
+        .push(transport);
+}
+
+fn transport_for(url: &str) -> Result<Arc<dyn Transport>> {
+    let transports = registry()
+        .read()
+        .expect("the transport registry was poisoned");
+    if let Some(transport) = transports.iter().rev().find(|t| t.accepts(url)) {
+        return Ok(Arc::clone(transport));
+    }
+    let declined = transports.iter().map(|t| t.name()).collect::<Vec<_>>();
+    bail!(
+        "no loopback transport reaches {url} (declined by: {})",
+        declined.join(", ")
+    )
+}
+
+/// A prepared exchange with another KROMA process.
+///
+/// Builder-style options, then one of the executors ([`Loopback::get`],
+/// [`Loopback::post_json`], [`Loopback::post_bytes`]). Each blocks the calling
+/// thread.
+#[derive(Debug, Clone)]
+pub struct Loopback {
+    headers: Vec<(String, String)>,
+    query: Vec<(String, String)>,
+    max_time_secs: u32,
+}
+
+impl Default for Loopback {
+    fn default() -> Self {
+        Self {
+            headers: Vec::new(),
+            query: Vec::new(),
+            max_time_secs: DEFAULT_MAX_TIME_SECS,
+        }
+    }
+}
+
+crate::builder::request_builder!(Loopback, query = "URL-encoded query parameter.");
+
+impl Loopback {
+    pub fn get(&self, url: &str) -> Result<Response> {
+        self.send(Method::Get, url, None)
+    }
+
+    /// GET expecting a 2xx JSON body.
+    pub fn get_json<T: serde::de::DeserializeOwned>(&self, url: &str) -> Result<T> {
+        self.get(url)?.ensure_ok()?.json()
+    }
+
+    pub fn post_json(&self, url: &str, body: &serde_json::Value) -> Result<Response> {
+        let bytes = serde_json::to_vec(body)?;
+        self.send(Method::Post, url, Some(("application/json", &bytes)))
+    }
+
+    pub fn post_bytes(&self, url: &str, content_type: &str, body: &[u8]) -> Result<Response> {
+        self.send(Method::Post, url, Some((content_type, body)))
+    }
+
+    fn with_query(&self, url: &str) -> String {
+        if self.query.is_empty() {
+            return url.to_string();
+        }
+        let encoded = form_urlencoded::Serializer::new(String::new())
+            .extend_pairs(self.query.iter().map(|(k, v)| (k.as_str(), v.as_str())))
+            .finish();
+        let (before, fragment) = match url.split_once('#') {
+            Some((before, fragment)) => (before, Some(fragment)),
+            None => (url, None),
+        };
+        let separator = if before.contains('?') { '&' } else { '?' };
+        match fragment {
+            Some(fragment) => format!("{before}{separator}{encoded}#{fragment}"),
+            None => format!("{before}{separator}{encoded}"),
+        }
+    }
+
+    fn send(&self, method: Method, url: &str, body: Option<(&str, &[u8])>) -> Result<Response> {
+        let url = self.with_query(url);
+        transport_for(&url)?.send(&Request {
+            method,
+            url: &url,
+            headers: &self.headers,
+            body,
+            timeout: Duration::from_secs(u64::from(self.max_time_secs)),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[derive(Debug)]
+    struct Stub(&'static str);
+
+    impl Transport for Stub {
+        fn name(&self) -> &'static str {
+            "stub"
+        }
+
+        fn accepts(&self, url: &str) -> bool {
+            url.starts_with(self.0)
+        }
+
+        fn send(&self, request: &Request<'_>) -> Result<Response> {
+            Ok(Response {
+                status: 200,
+                headers: vec![("x-transport".into(), self.name().into())],
+                body: format!("{} {}", request.method.as_str(), request.url).into_bytes(),
+            })
+        }
+    }
+
+    #[test]
+    fn a_url_no_transport_claims_is_an_error_naming_it() {
+        let err = Loopback::new()
+            .get("http://example.com/_port/x")
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("example.com"), "{err}");
+    }
+
+    #[test]
+    fn a_registered_transport_takes_the_urls_it_claims() {
+        register(Arc::new(Stub("stub://")));
+
+        let resp = Loopback::new().get("stub://peer/_port/x").unwrap();
+
+        assert_eq!(resp.status, 200);
+        assert_eq!(resp.header("x-transport"), Some("stub"));
+        assert_eq!(resp.text(), "GET stub://peer/_port/x");
+    }
+
+    #[test]
+    fn a_post_carries_its_query_rather_than_dropping_it() {
+        register(Arc::new(Stub("stub://")));
+
+        let resp = Loopback::new()
+            .query("id", "a b")
+            .post_json("stub://peer/_port/x", &serde_json::json!({}))
+            .unwrap();
+
+        assert_eq!(resp.text(), "POST stub://peer/_port/x?id=a+b");
+    }
+
+    #[test]
+    fn a_query_goes_before_a_fragment_rather_than_inside_it() {
+        let call = Loopback::new().query("k", "v");
+        assert_eq!(
+            call.with_query("http://127.0.0.1:9/x#frag"),
+            "http://127.0.0.1:9/x?k=v#frag"
+        );
+    }
+
+    #[test]
+    fn a_query_is_form_encoded_onto_the_url() {
+        let call = Loopback::new()
+            .query("q", "the matrix")
+            .query("cat", "2000&2010");
+
+        assert_eq!(
+            call.with_query("http://127.0.0.1:9/search"),
+            "http://127.0.0.1:9/search?q=the+matrix&cat=2000%262010"
+        );
+    }
+
+    #[test]
+    fn a_url_that_already_carries_a_query_gains_the_pairs_rather_than_a_second_question_mark() {
+        let call = Loopback::new().query("key", "a b");
+        assert_eq!(
+            call.with_query("http://127.0.0.1:9/setting?scope=x"),
+            "http://127.0.0.1:9/setting?scope=x&key=a+b"
+        );
+        assert_eq!(
+            Loopback::new().with_query("http://127.0.0.1:9/setting"),
+            "http://127.0.0.1:9/setting"
+        );
+    }
+
+    #[test]
+    fn the_builder_accumulates_headers_and_a_budget() {
+        let call = Loopback::new()
+            .header("authorization", "Bearer tok")
+            .header("x-extra", "1")
+            .max_time(5);
+        assert_eq!(call.headers.len(), 2);
+        assert_eq!(call.max_time_secs, 5);
+        assert_eq!(Loopback::new().max_time_secs, DEFAULT_MAX_TIME_SECS);
+    }
+}