@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-db/src/backup.rs

@@ -0,0 +1,306 @@
+//! Portable backup: dump the *non-reproducible* identity + config state
+//! (accounts, settings, acquisition indexers / download clients, watch history,
+//! resume positions, invites, cron overrides) to a JSON document and restore it
+//! on another server.
+//!
+//! The catalogue itself is **not** exported it's regenerated by a re-scan on
+//! the target, which reproduces *identical* item IDs because the library
+//! definitions (and their stable IDs) travel inside the `settings` rows. See
+//! `crate::services::scan::ids` for the id derivation.
+//!
+//! Restore runs on a connection with `foreign_keys = OFF` so `progress` rows
+//! insert even before the catalogue exists; rows whose item isn't present yet
+//! sit inert and reconnect once the admin points the library at its media and
+//! re-scans (same `lib_id` ⇒ same item id). Order-independent, no data loss.
+
+use std::collections::BTreeMap;
+
+use anyhow::{Context, Result};
+use rusqlite::types::{Value as SqlValue, ValueRef};
+use rusqlite::Connection;
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+
+use super::{now_or_blank, Pool};
+
+mod module_stores;
+mod rows;
+
+#[cfg(test)]
+mod test_support;
+
+use module_stores::{dump_store, module_stores, restore_modules};
+use rows::{dump_query, restore_rows};
+
+// On-disk shape version; bump on an incompatible change.
+const VERSION: u32 = 1;
+
+// Tables carried by a portable backup. Everything else (catalogue, embeddings,
+// AI sections, sessions, job run history, and the machine-specific `downloads`
+// torrent state) is regenerated and left out. `settings` carries the VPN /
+// naming / acquisition preferences; `requests` + `wanted` carry the users' media
+// wishlist and its episode ledger. `progress`/`watched`/`my_list` are item-keyed
+// user state that re-links by `item_id` once a re-scan recreates the catalogue
+// with matching ids.
+//
+// A module's own tables are NOT named here any more -- they are not in this
+// database. Each installed module's private store is walked whole (see
+// [`module_stores`]), which is both how the admin's indexer keys and download
+// client passwords still travel and how this list stopped needing to know which
+// modules exist.
+const TABLES: &[&str] = &[
+    "users",
+    "settings",
+    "requests",
+    "wanted",
+    "invites",
+    "play_history",
+    "job_schedules",
+    "progress",
+    "watched",
+    "my_list",
+];
+
+/// A portable backup: one row-set per exported table, plus metadata. Serde-only
+/// (the clients treat the file as an opaque blob), so no ts-rs wire type.
+#[derive(Debug, Serialize, Deserialize)]
+pub struct BackupDoc {
+    pub version: u32,
+    pub exported_at: String,
+    // table name → rows, each row a `{column: value}` object.
+    pub tables: BTreeMap<String, Vec<Map<String, Value>>>,
+    // User-uploaded files the rows reference but that live outside the DB
+    // (custom avatars in the image cache): cache filename → hex of the bytes.
+    // Populated by `services::backup`, not the DB layer. `default` so older
+    // (pre-assets) backups still deserialize.
+    #[serde(default)]
+    pub assets: BTreeMap<String, String>,
+    // Each installed module's own database: module id → table → rows. `default`
+    // so a backup taken before modules had their own file still deserializes.
+    #[serde(default)]
+    pub modules: BTreeMap<String, BTreeMap<String, Vec<Map<String, Value>>>>,
+}
+
+/// Dump every portable table, plus every installed module's own database, to a
+/// [`BackupDoc`]. A table that is absent is skipped rather than erroring, which
+/// is the normal state of a database whose optional features were never used.
+pub fn export_portable(pool: &Pool, data_dir: &std::path::Path) -> Result<BackupDoc> {
+    let conn = pool.get()?;
+    let mut tables = BTreeMap::new();
+    for &t in TABLES {
+        if !table_exists(&conn, t)? {
+            continue;
+        }
+        tables.insert(
+            t.to_string(),
+            dump_query(&conn, &format!("SELECT * FROM {t}"))?,
+        );
+    }
+    let mut modules = BTreeMap::new();
+    for (id, path) in module_stores(data_dir) {
+        // One unreadable module store must not cost the operator the rest of the
+        // backup; it is reported and the export goes on.
+        match dump_store(&path) {
+            Ok(store) if !store.is_empty() => {
+                modules.insert(id, store);
+            }
+            Ok(_) => {}
+            Err(error) => {
+                tracing::warn!(module = %id, %error, "module database not backed up")
+            }
+        }
+    }
+    Ok(BackupDoc {
+        version: VERSION,
+        exported_at: now_or_blank(),
+        tables,
+        assets: BTreeMap::new(),
+        modules,
+    })
+}
+
+// Whether `name` is a table in the current database (module-owned tables may not
+// be, see [`export_portable`]).
+fn table_exists(conn: &Connection, name: &str) -> Result<bool> {
+    let n: i64 = conn.query_row(
+        "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
+        [name],
+        |r| r.get(0),
+    )?;
+    Ok(n > 0)
+}
+
+/// Restore a [`BackupDoc`] into the database, replacing rows by primary key.
+/// Runs in one transaction with foreign keys disabled (see module docs). When
+/// `reset` is set, the portable tables are emptied first (a true A→B clone)
+/// still inside the same transaction, so a crash mid-restore rolls back wholesale.
+/// Returns `(table, rows_written)` pairs in restore order.
+pub fn import_portable(
+    pool: &Pool,
+    data_dir: &std::path::Path,
+    doc: &BackupDoc,
+    reset: bool,
+) -> Result<Vec<(String, usize)>> {
+    if doc.version > VERSION {
+        anyhow::bail!(
+            "backup version {} is newer than supported {VERSION}",
+            doc.version
+        );
+    }
+    let mut conn = pool.get()?;
+    // Insert across the catalogue gap: `progress.item_id` references rows that a
+    // fresh target doesn't have yet. Orphans are inert and reconnect on re-scan.
+    // The pragma must toggle *outside* a transaction; restore it before the
+    // connection returns to the pool (pooled conns reapply PRAGMAS only on open).
+    conn.execute_batch("PRAGMA foreign_keys = OFF;")?;
+    let result = restore_all(&mut conn, doc, reset);
+    let _ = conn.execute_batch("PRAGMA foreign_keys = ON;");
+    let mut summary = result?;
+    summary.extend(restore_modules(data_dir, doc, reset));
+    Ok(summary)
+}
+
+// The transactional body of [`import_portable`], split out so the caller can
+// restore `foreign_keys` whether it succeeds or fails.
+fn restore_all(
+    conn: &mut rusqlite::Connection,
+    doc: &BackupDoc,
+    reset: bool,
+) -> Result<Vec<(String, usize)>> {
+    let tx = conn.transaction()?;
+    if reset {
+        for &t in TABLES {
+            if table_exists(&tx, t)? {
+                tx.execute(&format!("DELETE FROM {t}"), [])?;
+            }
+        }
+    }
+    let mut summary = Vec::new();
+    for &t in TABLES {
+        if let Some(rows) = doc.tables.get(t) {
+            // Skip a table the target lacks (a module present in the source but
+            // absent here); its config simply isn't restored.
+            if !table_exists(&tx, t)? {
+                continue;
+            }
+            let n = restore_rows(&tx, t, rows).with_context(|| format!("restoring {t}"))?;
+            summary.push((t.to_string(), n));
+        }
+    }
+    tx.commit()?;
+    Ok(summary)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::backup::test_support::*;
+
+    #[test]
+    fn roundtrip_restores_state_and_keeps_orphan_progress() {
+        let src = fresh_pool("src");
+        {
+            let c = src.get().unwrap();
+            c.execute("INSERT INTO libraries (id,name,kind,path,added_at) VALUES ('lib','L','movie','/x','t')", []).unwrap();
+            c.execute("INSERT INTO items (id,kind,title,container,library,added_at) VALUES ('it1','movie','Film','mkv','lib','t')", []).unwrap();
+            c.execute("INSERT INTO users (id,email,username,password_hash,created_at) VALUES ('u1','a@b.c','Al','ph','t')", []).unwrap();
+            c.execute("INSERT INTO settings (key,value,updated_at) VALUES ('serverName','\"My KROMA\"','t')", []).unwrap();
+            c.execute("INSERT INTO progress (user_id,item_id,position_ms,duration_ms,updated_at) VALUES ('u1','it1',1000,5000,'t')", []).unwrap();
+            c.execute("INSERT INTO play_history (id,kind,title,started_at,ended_at) VALUES ('h1','movie','Film',1,2)", []).unwrap();
+            c.execute(
+                "INSERT INTO watched (user_id,item_id,watched_at) VALUES ('u1','it1','t')",
+                [],
+            )
+            .unwrap();
+            c.execute(
+                "INSERT INTO my_list (user_id,item_id,added_at) VALUES ('u1','it1','t')",
+                [],
+            )
+            .unwrap();
+            // A user's media request (wishlist) + its episode ledger.
+            c.execute("INSERT INTO requests (id,kind,tmdb_id,title,status,created_at,updated_at) VALUES ('rq1','movie',603,'The Matrix','approved',1,1)", []).unwrap();
+            c.execute("INSERT INTO wanted (id,request_id,kind,tmdb_id,title,status,updated_at) VALUES ('wt1','rq1','movie',603,'The Matrix','wanted',1)", []).unwrap();
+        }
+
+        let doc = export_portable(&src, &data_dir(&src)).unwrap();
+        assert_eq!(doc.tables["users"].len(), 1);
+        assert_eq!(doc.tables["progress"].len(), 1);
+        assert_eq!(doc.tables["watched"].len(), 1);
+        assert_eq!(doc.tables["my_list"].len(), 1);
+        assert_eq!(doc.tables["requests"].len(), 1);
+        assert_eq!(doc.tables["wanted"].len(), 1);
+        // The catalogue is NOT exported only the portable identity tables.
+        assert!(!doc.tables.contains_key("items"));
+
+        // Fresh target with no catalogue (items table empty).
+        let dst = fresh_pool("dst");
+        import_portable(&dst, &data_dir(&dst), &doc, false).unwrap();
+
+        assert_eq!(count(&dst, "users"), 1);
+        assert_eq!(count(&dst, "play_history"), 1);
+        // The orphan progress row survives the missing item (FK off on import) and
+        // will reconnect once a re-scan recreates `it1` with the same id.
+        assert_eq!(count(&dst, "items"), 0);
+        assert_eq!(count(&dst, "progress"), 1);
+        assert_eq!(count(&dst, "watched"), 1);
+        assert_eq!(count(&dst, "my_list"), 1);
+        assert_eq!(count(&dst, "requests"), 1);
+        assert_eq!(count(&dst, "wanted"), 1);
+
+        let server_name: String = dst
+            .get()
+            .unwrap()
+            .query_row(
+                "SELECT value FROM settings WHERE key='serverName'",
+                [],
+                |r| r.get(0),
+            )
+            .unwrap();
+        assert_eq!(server_name, "\"My KROMA\"");
+
+        // foreign_keys must be back ON for the next user of any pooled connection.
+        let fk: i64 = dst
+            .get()
+            .unwrap()
+            .query_row("PRAGMA foreign_keys", [], |r| r.get(0))
+            .unwrap();
+        assert_eq!(fk, 1);
+    }
+
+    #[test]
+    fn a_backup_from_a_newer_server_is_refused_rather_than_half_restored() {
+        let dst = fresh_pool("newer");
+        let doc = BackupDoc {
+            version: VERSION + 1,
+            ..empty_doc()
+        };
+        let err = import_portable(&dst, &data_dir(&dst), &doc, false)
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("newer than supported"), "{err}");
+    }
+
+    #[test]
+    fn a_table_the_target_does_not_have_is_skipped_rather_than_failing_the_restore() {
+        let dst = crate::testing::temp_pool("bkp-no-module");
+        let mut doc = empty_doc();
+        doc.tables.insert(
+            "indexers".into(),
+            vec![Map::from_iter([("id".to_string(), Value::from("ix1"))])],
+        );
+        doc.tables.insert(
+            "users".into(),
+            vec![Map::from_iter([
+                ("id".to_string(), Value::from("u1")),
+                ("email".to_string(), Value::from("a@b.c")),
+                ("username".to_string(), Value::from("Al")),
+                ("password_hash".to_string(), Value::from("ph")),
+                ("created_at".to_string(), Value::from("t")),
+            ])],
+        );
+
+        let summary = import_portable(&dst, &data_dir(&dst), &doc, true).unwrap();
+        assert_eq!(summary, vec![("users".to_string(), 1)]);
+        assert_eq!(count(&dst, "users"), 1);
+    }
+}

package/rust/kroma-db/src/catalog_query/find_titles.rs

@@ -0,0 +1,316 @@
+//! The filtered title listing a curating model browses with.
+
+use anyhow::Result;
+use rusqlite::types::Value as SqlValue;
+
+use crate::rows::parse_metadata;
+use crate::Pool;
+
+use super::{CAT_CTE, DIRECTING_JOBS_SQL};
+
+// Caps a single `find_titles` call so tool results re-entering the model's
+// context stay bounded.
+const MAX_LIMIT: usize = 50;
+const DEFAULT_LIMIT: usize = 25;
+
+/// A title in brief form (one `find_titles` row).
+pub struct TitleBrief {
+    pub id: String,
+    pub title: String,
+    pub year: Option<u32>,
+    pub kind: String,
+    pub rating: Option<f32>,
+    pub genres: Vec<String>,
+}
+
+/// Composable `find_titles` filters all optional, AND-ed together.
+#[derive(Default)]
+pub struct TitleFilter {
+    pub genre: Option<String>,
+    pub director: Option<String>,
+    pub actor: Option<String>,
+    pub keyword: Option<String>,
+    pub kind: Option<String>,
+    pub year_min: Option<u32>,
+    pub year_max: Option<u32>,
+    pub min_rating: Option<f32>,
+    pub sort: Option<String>,
+    pub limit: Option<usize>,
+}
+
+/// List titles matching `filter`, ordered + capped. The heavy lifting is in
+/// SQL; genres/rating are pulled from the parsed metadata so the struct stays
+/// faithful to the model types.
+pub fn find_titles(pool: &Pool, filter: &TitleFilter) -> Result<Vec<TitleBrief>> {
+    let mut sql = String::from(CAT_CTE);
+    sql.push_str("SELECT id,title,year,kind,metadata FROM cat WHERE 1=1");
+    let mut p: Vec<SqlValue> = Vec::new();
+
+    if let Some(g) = clean(&filter.genre) {
+        sql.push_str(" AND EXISTS (SELECT 1 FROM json_each(cat.metadata,'$.genres') g WHERE g.value = ? COLLATE NOCASE)");
+        p.push(SqlValue::Text(g));
+    }
+    if let Some(d) = clean(&filter.director) {
+        sql.push_str(&format!(
+            " AND EXISTS (SELECT 1 FROM json_each(cat.metadata,'$.crew') c \
+              WHERE json_extract(c.value,'$.name') = ? COLLATE NOCASE \
+              AND json_extract(c.value,'$.job') IN {DIRECTING_JOBS_SQL})"
+        ));
+        p.push(SqlValue::Text(d));
+    }
+    if let Some(a) = clean(&filter.actor) {
+        sql.push_str(" AND EXISTS (SELECT 1 FROM json_each(cat.metadata,'$.cast') c WHERE json_extract(c.value,'$.name') = ? COLLATE NOCASE)");
+        p.push(SqlValue::Text(a));
+    }
+    if let Some(k) = clean(&filter.keyword) {
+        sql.push_str(" AND (cat.title LIKE ? COLLATE NOCASE OR IFNULL(json_extract(cat.metadata,'$.overview'),'') LIKE ? COLLATE NOCASE)");
+        let like = format!("%{k}%");
+        p.push(SqlValue::Text(like.clone()));
+        p.push(SqlValue::Text(like));
+    }
+    if let Some(k) = clean(&filter.kind) {
+        sql.push_str(" AND cat.kind = ?");
+        p.push(SqlValue::Text(normalize_kind(&k)));
+    }
+    if let Some(y) = filter.year_min {
+        sql.push_str(" AND cat.year >= ?");
+        p.push(SqlValue::Integer(y as i64));
+    }
+    if let Some(y) = filter.year_max {
+        sql.push_str(" AND cat.year <= ?");
+        p.push(SqlValue::Integer(y as i64));
+    }
+    if let Some(r) = filter.min_rating {
+        sql.push_str(" AND CAST(json_extract(cat.metadata,'$.rating') AS REAL) >= ?");
+        p.push(SqlValue::Real(r as f64));
+    }
+
+    sql.push(' ');
+    sql.push_str(order_clause(filter.sort.as_deref()));
+    let lim = filter.limit.unwrap_or(DEFAULT_LIMIT).clamp(1, MAX_LIMIT);
+    sql.push_str(&format!(" LIMIT {lim}"));
+
+    let conn = pool.get()?;
+    let mut stmt = conn.prepare(&sql)?;
+    let rows = stmt
+        .query_map(rusqlite::params_from_iter(p.iter()), |r| {
+            let meta = parse_metadata(r.get::<_, Option<String>>(4)?);
+            Ok(TitleBrief {
+                id: r.get(0)?,
+                title: r.get(1)?,
+                year: r.get(2)?,
+                kind: r.get(3)?,
+                rating: meta.as_ref().and_then(|m| m.rating),
+                genres: meta.map(|m| m.genres).unwrap_or_default(),
+            })
+        })?
+        .collect::<rusqlite::Result<Vec<_>>>()?;
+    Ok(rows)
+}
+
+// `ORDER BY` for the requested sort. Unrated titles sink last under `rating`
+// (SQLite sorts NULL last under `DESC`).
+fn order_clause(sort: Option<&str>) -> &'static str {
+    match sort.map(str::trim).unwrap_or("rating") {
+        "year" => "ORDER BY cat.year DESC",
+        "title" => "ORDER BY cat.title COLLATE NOCASE ASC",
+        _ => "ORDER BY CAST(json_extract(cat.metadata,'$.rating') AS REAL) DESC, cat.year DESC",
+    }
+}
+
+fn normalize_kind(k: &str) -> String {
+    match k.trim().to_ascii_lowercase().as_str() {
+        "show" | "series" | "tv" | "serie" => "show".to_string(),
+        _ => "movie".to_string(),
+    }
+}
+
+// Trim a filter string and treat blank as absent.
+fn clean(s: &Option<String>) -> Option<String> {
+    s.as_deref()
+        .map(str::trim)
+        .filter(|t| !t.is_empty())
+        .map(str::to_string)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::catalog_query::test_support::*;
+
+    #[test]
+    fn genre_filter_and_kind() {
+        let pool = seeded_pool();
+        let horror = find_titles(
+            &pool,
+            &TitleFilter {
+                genre: Some("Horror".into()),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+        let ids: Vec<&str> = horror.iter().map(|t| t.id.as_str()).collect();
+        assert_eq!(ids, ["m3", "m4"]); // rating DESC: Shining 8.4 then Hereditary 7.3
+
+        // Sci-fi spans a movie + a show; kind filter narrows to the show.
+        let scifi = find_titles(
+            &pool,
+            &TitleFilter {
+                genre: Some("science fiction".into()),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+        assert_eq!(scifi.len(), 2);
+        let show_only = find_titles(
+            &pool,
+            &TitleFilter {
+                genre: Some("Science Fiction".into()),
+                kind: Some("series".into()),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+        assert_eq!(
+            show_only.iter().map(|t| t.id.as_str()).collect::<Vec<_>>(),
+            ["s1"]
+        );
+        assert_eq!(show_only[0].kind, "show");
+    }
+
+    #[test]
+    fn director_and_actor_filters() {
+        let pool = seeded_pool();
+        let dv = find_titles(
+            &pool,
+            &TitleFilter {
+                director: Some("Denis Villeneuve".into()),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+        assert_eq!(
+            dv.iter().map(|t| t.id.as_str()).collect::<Vec<_>>(),
+            ["m1", "m2"]
+        );
+        let blunt = find_titles(
+            &pool,
+            &TitleFilter {
+                actor: Some("Emily Blunt".into()),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+        assert_eq!(
+            blunt.iter().map(|t| t.id.as_str()).collect::<Vec<_>>(),
+            ["m2"]
+        );
+    }
+
+    #[test]
+    fn rating_year_sort_and_limit() {
+        let pool = seeded_pool();
+        let top = find_titles(
+            &pool,
+            &TitleFilter {
+                min_rating: Some(8.0),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+        // ≥8.0: Severance 8.7, Shining 8.4, Dune 8.0 newest sort would differ.
+        assert_eq!(
+            top.iter().map(|t| t.id.as_str()).collect::<Vec<_>>(),
+            ["s1", "m3", "m1"]
+        );
+
+        let newest = find_titles(
+            &pool,
+            &TitleFilter {
+                sort: Some("year".into()),
+                limit: Some(2),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+        assert_eq!(newest.len(), 2);
+        assert_eq!(newest[0].id, "s1"); // 2022 newest
+
+        // Episodes never appear in the catalog.
+        let all = find_titles(
+            &pool,
+            &TitleFilter {
+                limit: Some(50),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+        assert!(all.iter().all(|t| t.id != "e1"));
+        assert_eq!(all.len(), 6); // 5 movies + 1 show
+    }
+
+    #[test]
+    fn the_keyword_filter_matches_the_title_or_the_overview() {
+        let pool = seeded_pool();
+        let ids = |filter: TitleFilter| {
+            find_titles(&pool, &filter)
+                .unwrap()
+                .into_iter()
+                .map(|t| t.id)
+                .collect::<Vec<_>>()
+        };
+
+        assert_eq!(
+            ids(TitleFilter {
+                keyword: Some("shin".into()),
+                ..Default::default()
+            }),
+            ["m3"]
+        );
+        let by_overview = ids(TitleFilter {
+            keyword: Some("A FILM ABOUT".into()),
+            limit: Some(50),
+            ..Default::default()
+        });
+        assert!(by_overview.contains(&"m1".to_string()), "{by_overview:?}");
+        assert!(
+            !by_overview.contains(&"m5".to_string()),
+            "m5 has no overview: {by_overview:?}"
+        );
+        assert!(ids(TitleFilter {
+            keyword: Some("nothing matches".into()),
+            ..Default::default()
+        })
+        .is_empty());
+    }
+
+    #[test]
+    fn the_year_bounds_are_inclusive_on_both_ends() {
+        let pool = seeded_pool();
+        let ids = |min, max| {
+            find_titles(
+                &pool,
+                &TitleFilter {
+                    year_min: min,
+                    year_max: max,
+                    sort: Some("year".into()),
+                    limit: Some(50),
+                    ..Default::default()
+                },
+            )
+            .unwrap()
+            .into_iter()
+            .map(|t| t.id)
+            .collect::<Vec<_>>()
+        };
+
+        assert_eq!(ids(Some(2018), None), ["s1", "m1", "m4"]);
+        assert_eq!(ids(None, Some(1990)), ["m5", "m3"]);
+        assert_eq!(
+            ids(Some(1980), Some(1980)),
+            ["m3"],
+            "both bounds include their year"
+        );
+        assert!(ids(Some(2030), None).is_empty());
+    }
+}