@kromatv/sdk 0.1.39-canary.3579809

package/rust/kroma-sqlite/src/grant.rs

@@ -0,0 +1,241 @@
+//! Scoped access to the core database, enforced by SQLite itself.
+//!
+//! A [`Grant`] carries what the module's `module.json` declares, and
+//! [`init_scoped`] hands back a pool whose connections apply it through an
+//! `sqlite3_set_authorizer` callback.
+//!
+//! The authorizer fires for every action while a statement is being PREPARED, so
+//! the scope cannot be talked around by building the SQL as a string: an
+//! ungranted table fails at `prepare`, before a row is read. It is per-connection,
+//! which is what lets one database serve two modules with different scopes.
+use std::collections::{BTreeMap, BTreeSet};
+use std::path::Path;
+use std::sync::Arc;
+
+use anyhow::Result;
+use rusqlite::hooks::{AuthAction, AuthContext, Authorization};
+use rusqlite::Connection;
+use serde::{Deserialize, Serialize};
+
+use crate::Pool;
+
+/// Reading a table's schema is not reading its data, and denying it breaks
+/// `PRAGMA table_info` and rusqlite's own column lookups for statements that are
+/// otherwise allowed.
+const SCHEMA_TABLES: [&str; 3] = ["sqlite_master", "sqlite_schema", "sqlite_temp_master"];
+
+/// Which core tables and columns a module may reach.
+///
+/// The wire shape is the `storage.core` object of a `module.json`: a list of
+/// `"table"` (whole table) or `"table.column"` (that column only) entries per
+/// verb. Anything not listed is denied, which is what makes an empty grant --
+/// the default -- a pool that answers nothing. A column entry under `write`
+/// covers `UPDATE` of that column only: `INSERT` and `DELETE` touch the whole
+/// row, so they need the whole table.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Grant {
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub read: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub write: Vec<String>,
+}
+
+impl Grant {
+    /// A grant that allows nothing. What a module with no declared `storage.core`
+    /// gets, so `core()` is always a pool and the refusal is a named denial at
+    /// the call site.
+    pub fn none() -> Self {
+        Self::default()
+    }
+
+    /// Compile the declared entries into the lookup the authorizer runs per
+    /// action. Unparseable entries are dropped rather than failing the module:
+    /// a typo in a manifest costs that one grant, loudly, not the whole boot.
+    fn compile(&self) -> Compiled {
+        Compiled {
+            read: columns_by_table(&self.read),
+            write: columns_by_table(&self.write),
+        }
+    }
+}
+
+// `None` as the column set means the whole table.
+type Tables = BTreeMap<String, Option<BTreeSet<String>>>;
+
+struct Compiled {
+    read: Tables,
+    write: Tables,
+}
+
+fn columns_by_table(entries: &[String]) -> Tables {
+    let mut out: Tables = BTreeMap::new();
+    for entry in entries {
+        let entry = entry.trim();
+        if entry.is_empty() {
+            continue;
+        }
+        match entry.split_once('.') {
+            None => {
+                out.insert(entry.to_ascii_lowercase(), None);
+            }
+            Some((table, column)) => {
+                let slot = out
+                    .entry(table.trim().to_ascii_lowercase())
+                    .or_insert_with(|| Some(BTreeSet::new()));
+                // A whole-table entry beside a column entry keeps the wider one.
+                if let Some(cols) = slot {
+                    cols.insert(column.trim().to_ascii_lowercase());
+                }
+            }
+        }
+    }
+    out
+}
+
+fn allows(tables: &Tables, table: &str, column: &str) -> bool {
+    match tables.get(&table.to_ascii_lowercase()) {
+        None => false,
+        Some(None) => true,
+        // SQLite passes an empty column for a table-level touch (`count(*)`).
+        Some(Some(cols)) => column.is_empty() || cols.contains(&column.to_ascii_lowercase()),
+    }
+}
+
+// INSERT writes every column of a row and DELETE removes every column of one,
+// so neither is expressible as a column grant: they need the whole table.
+fn allows_whole_table(tables: &Tables, table: &str) -> bool {
+    matches!(tables.get(&table.to_ascii_lowercase()), Some(None))
+}
+
+/// Where a denial happened, for the log line. A bare `SQLITE_AUTH` says only
+/// "not authorized", which is unhelpful three layers down a module's data access.
+fn describe(action: &AuthAction<'_>) -> String {
+    match action {
+        AuthAction::Read {
+            table_name,
+            column_name,
+        } => format!("read {table_name}.{column_name}"),
+        AuthAction::Insert { table_name } => format!("insert into {table_name}"),
+        AuthAction::Update {
+            table_name,
+            column_name,
+        } => {
+            format!("update {table_name}.{column_name}")
+        }
+        AuthAction::Delete { table_name } => format!("delete from {table_name}"),
+        AuthAction::Attach { filename } => format!("attach {filename}"),
+        AuthAction::Pragma { pragma_name, .. } => format!("pragma {pragma_name}"),
+        other => format!("{other:?}"),
+    }
+}
+
+fn decide(module_id: &str, grant: &Compiled, ctx: &AuthContext<'_>) -> Authorization {
+    let allow = match &ctx.action {
+        // The umbrella actions a legal statement always raises. They carry no
+        // table, so the per-table checks below are what actually gate the data.
+        AuthAction::Select
+        | AuthAction::Function { .. }
+        | AuthAction::Transaction { .. }
+        | AuthAction::Savepoint { .. } => true,
+
+        AuthAction::Read {
+            table_name,
+            column_name,
+        } => SCHEMA_TABLES.contains(table_name) || allows(&grant.read, table_name, column_name),
+        AuthAction::Insert { table_name } => allows_whole_table(&grant.write, table_name),
+        AuthAction::Delete { table_name } => allows_whole_table(&grant.write, table_name),
+        AuthAction::Update {
+            table_name,
+            column_name,
+        } => allows(&grant.write, table_name, column_name),
+
+        // Everything else -- DDL, ATTACH, PRAGMA, extension loading, REINDEX --
+        // is denied outright. A module's own schema belongs in its own file, and
+        // ATTACH would otherwise re-open the core database under a name the
+        // per-table rules above never see.
+        _ => false,
+    };
+    if allow {
+        Authorization::Allow
+    } else {
+        tracing::warn!(
+            module = %module_id,
+            denied = %describe(&ctx.action),
+            "module storage grant does not cover this statement"
+        );
+        Authorization::Deny
+    }
+}
+
+/// A pool over `path` whose every connection refuses anything `grant` does not
+/// cover. `module_id` only names the module in the denial log.
+///
+/// The database is NOT created or migrated here: the core owns the file and has
+/// already done both by the time a module is spawned.
+pub fn init_scoped(path: &Path, module_id: &str, grant: &Grant) -> Result<Pool> {
+    let scope = Scope {
+        module_id: module_id.to_string(),
+        grant: Arc::new(grant.compile()),
+    };
+    crate::open::pool_at(path, 4, Some(scope))
+}
+
+/// The authorizer a scoped [`Pool`] installs on each connection it opens.
+pub(crate) struct Scope {
+    module_id: String,
+    grant: Arc<Compiled>,
+}
+
+impl Scope {
+    pub(crate) fn install(&self, conn: &Connection) -> Result<()> {
+        let (module_id, grant) = (self.module_id.clone(), Arc::clone(&self.grant));
+        conn.authorizer(Some(move |ctx: AuthContext<'_>| {
+            decide(&module_id, &grant, &ctx)
+        }))?;
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn grant(read: &[&str], write: &[&str]) -> Grant {
+        Grant {
+            read: read.iter().map(ToString::to_string).collect(),
+            write: write.iter().map(ToString::to_string).collect(),
+        }
+    }
+
+    #[test]
+    fn a_grant_round_trips_through_the_manifest_shape() {
+        let g: Grant =
+            serde_json::from_str(r#"{ "read": ["requests", "users.username"], "write": ["wanted"] }"#)
+                .unwrap();
+        assert_eq!(g.read, ["requests", "users.username"]);
+        assert_eq!(g.write, ["wanted"]);
+        assert_eq!(
+            serde_json::from_value::<Grant>(serde_json::to_value(&g).unwrap()).unwrap(),
+            g
+        );
+        // An absent object is the empty grant, not an error.
+        assert_eq!(serde_json::from_str::<Grant>("{}").unwrap(), Grant::none());
+    }
+
+    #[test]
+    fn table_and_column_entries_for_one_table_keep_the_wider_grant() {
+        let compiled = grant(&["users.username", "users"], &[]).compile();
+        assert!(allows(&compiled.read, "users", "email"));
+        // Order must not matter.
+        let compiled = grant(&["users", "users.username"], &[]).compile();
+        assert!(allows(&compiled.read, "users", "email"));
+    }
+
+    #[test]
+    fn a_table_name_matches_whatever_case_the_sql_used() {
+        let compiled = grant(&["Requests.Title"], &[]).compile();
+        assert!(allows(&compiled.read, "requests", "title"));
+        assert!(allows(&compiled.read, "REQUESTS", "TITLE"));
+        assert!(!allows(&compiled.read, "requests", "status"));
+    }
+}

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

@@ -0,0 +1,35 @@
+//! A module's window onto SQLite: the WAL pool, the grant that scopes it to the
+//! core tables a manifest declares, and the versioned migrations every database
+//! takes, the core's and a module's own. The mechanism and nothing of the schema, so a sidecar links this
+//! and never `kroma-db`.
+
+mod grant;
+mod migrate;
+mod open;
+mod pool;
+#[cfg(any(test, feature = "testing"))]
+pub mod testing;
+
+pub use grant::{init_scoped, Grant};
+pub use migrate::{migrate, user_version, Legacy, Migrated, Run, Schema, Step, KEPT_SNAPSHOTS};
+pub use open::{apply_migrations, migrate_store, open, open_with};
+pub use pool::{Pool, PoolInner, PooledConn};
+
+/// The pragmas every pooled connection applies on open.
+pub const PRAGMAS: &str = "
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = NORMAL;
+    PRAGMA foreign_keys = ON;
+    PRAGMA temp_store = MEMORY;
+    -- A write that waits behind a slow commit (a NAS paging to disk holds the
+    -- lock for seconds) waits rather than failing the work it was saving.
+    PRAGMA busy_timeout = 30000;
+    PRAGMA mmap_size = 268435456;
+    PRAGMA cache_size = -16000;
+    -- ~40 MB checkpoints instead of the 4 MB default: frequent checkpoints
+    -- stall readers on HDD during scan/probe bursts.
+    PRAGMA wal_autocheckpoint = 10000;
+    -- The WAL file shrinks back to this after a checkpoint; without it, it
+    -- stays at its high-water mark.
+    PRAGMA journal_size_limit = 67108864;
+";

package/rust/kroma-sqlite/src/migrate/tests.rs

@@ -0,0 +1,208 @@
+use rusqlite::Connection;
+
+use super::*;
+
+const BASELINE: &str = "CREATE TABLE notes (id TEXT PRIMARY KEY, body TEXT NOT NULL)";
+
+const ADD_PINNED: Step = Step {
+    name: "notes_pinned",
+    run: Run::Sql("ALTER TABLE notes ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0"),
+    rebuilds: false,
+};
+
+const SCHEMA: Schema<'static> = Schema {
+    name: "the test database",
+    baseline: BASELINE,
+    baseline_version: 1,
+    steps: &[ADD_PINNED],
+    legacy: Some(Legacy::Code(adopt_legacy)),
+};
+
+fn adopt_legacy(conn: &Connection) -> Result<()> {
+    conn.execute_batch(
+        "ALTER TABLE notes ADD COLUMN body TEXT NOT NULL DEFAULT '';
+         CREATE TABLE IF NOT EXISTS adopted (at INTEGER);
+         INSERT INTO adopted VALUES (1);",
+    )?;
+    Ok(())
+}
+
+fn columns(conn: &Connection, table: &str) -> Vec<String> {
+    conn.prepare("SELECT name FROM pragma_table_info(?1)")
+        .unwrap()
+        .query_map([table], |r| r.get(0))
+        .unwrap()
+        .collect::<rusqlite::Result<_>>()
+        .unwrap()
+}
+
+fn count(conn: &Connection, sql: &str) -> i64 {
+    conn.query_row(sql, [], |r| r.get(0)).unwrap()
+}
+
+#[test]
+fn a_new_file_starts_from_the_baseline_and_runs_every_step() {
+    let mut conn = Connection::open_in_memory().unwrap();
+
+    let migrated = migrate(&mut conn, &SCHEMA, None).unwrap();
+
+    assert_eq!(migrated, Migrated::Created);
+    assert_eq!(user_version(&conn).unwrap(), 2);
+    assert_eq!(columns(&conn, "notes"), ["id", "body", "pinned"]);
+}
+
+#[test]
+fn an_up_to_date_database_is_left_alone() {
+    let mut conn = Connection::open_in_memory().unwrap();
+    migrate(&mut conn, &SCHEMA, None).unwrap();
+    let cookie = count(&conn, "PRAGMA schema_version");
+
+    let migrated = migrate(&mut conn, &SCHEMA, None).unwrap();
+
+    assert_eq!(migrated, Migrated::Current);
+    assert_eq!(count(&conn, "PRAGMA schema_version"), cookie);
+}
+
+#[test]
+fn a_database_a_newer_build_wrote_is_refused() {
+    let mut conn = Connection::open_in_memory().unwrap();
+    migrate(&mut conn, &SCHEMA, None).unwrap();
+    conn.pragma_update(None, "user_version", 9).unwrap();
+
+    let err = migrate(&mut conn, &SCHEMA, None).unwrap_err();
+
+    assert!(format!("{err:#}").contains("newer KROMA"), "{err:#}");
+}
+
+#[test]
+fn a_database_older_than_the_baseline_is_refused() {
+    let squashed = Schema {
+        baseline_version: 5,
+        ..SCHEMA
+    };
+    let mut conn = Connection::open_in_memory().unwrap();
+    conn.execute_batch(BASELINE).unwrap();
+    conn.pragma_update(None, "user_version", 3).unwrap();
+
+    let err = migrate(&mut conn, &squashed, None).unwrap_err();
+
+    assert!(format!("{err:#}").contains("earlier release"), "{err:#}");
+}
+
+#[test]
+fn a_database_from_before_versioning_is_adopted_once_and_then_takes_the_steps() {
+    let mut conn = Connection::open_in_memory().unwrap();
+    conn.execute_batch("CREATE TABLE notes (id TEXT PRIMARY KEY)")
+        .unwrap();
+
+    let first = migrate(&mut conn, &SCHEMA, None).unwrap();
+    let second = migrate(&mut conn, &SCHEMA, None).unwrap();
+
+    assert_eq!(first, Migrated::Upgraded { from: 0, to: 2 });
+    assert_eq!(second, Migrated::Current);
+    assert_eq!(count(&conn, "SELECT COUNT(*) FROM adopted"), 1);
+    assert_eq!(columns(&conn, "notes"), ["id", "body", "pinned"]);
+}
+
+#[test]
+fn a_database_from_before_versioning_is_refused_when_nothing_can_adopt_it() {
+    let strict = Schema {
+        legacy: None,
+        ..SCHEMA
+    };
+    let mut conn = Connection::open_in_memory().unwrap();
+    conn.execute_batch(BASELINE).unwrap();
+
+    let err = migrate(&mut conn, &strict, None).unwrap_err();
+
+    assert!(format!("{err:#}").contains("no schema version"), "{err:#}");
+}
+
+#[test]
+fn a_failing_step_leaves_the_database_at_the_version_before_it() {
+    let broken = Schema {
+        steps: &[
+            ADD_PINNED,
+            Step {
+                name: "broken",
+                run: Run::Sql("ALTER TABLE notes ADD COLUMN tag TEXT; SELECT * FROM missing"),
+                rebuilds: false,
+            },
+        ],
+        ..SCHEMA
+    };
+    let mut conn = Connection::open_in_memory().unwrap();
+
+    let err = migrate(&mut conn, &broken, None).unwrap_err();
+
+    assert!(format!("{err:#}").contains("step 3 (broken)"), "{err:#}");
+    assert_eq!(user_version(&conn).unwrap(), 2);
+    assert_eq!(columns(&conn, "notes"), ["id", "body", "pinned"]);
+}
+
+#[test]
+fn a_rebuild_runs_without_foreign_keys_and_refuses_to_leave_a_row_dangling() {
+    fn rebuild_notes(conn: &Connection) -> rusqlite::Result<()> {
+        conn.execute_batch(
+            "CREATE TABLE notes_new (id TEXT PRIMARY KEY, body TEXT);
+             INSERT INTO notes_new SELECT id, body FROM notes WHERE id <> 'gone';
+             DROP TABLE notes;
+             ALTER TABLE notes_new RENAME TO notes;",
+        )
+    }
+    let rebuild = Schema {
+        baseline: "CREATE TABLE notes (id TEXT PRIMARY KEY, body TEXT NOT NULL);
+                   CREATE TABLE links (note TEXT REFERENCES notes(id));",
+        steps: &[Step {
+            name: "rebuild_notes",
+            run: Run::Code(rebuild_notes),
+            rebuilds: true,
+        }],
+        ..SCHEMA
+    };
+    let mut conn = Connection::open_in_memory().unwrap();
+    conn.execute_batch("PRAGMA foreign_keys = ON").unwrap();
+    create(&mut conn, &rebuild).unwrap();
+    conn.execute_batch(
+        "INSERT INTO notes VALUES ('kept', 'a'), ('gone', 'b');
+         INSERT INTO links VALUES ('gone');",
+    )
+    .unwrap();
+
+    let err = migrate(&mut conn, &rebuild, None).unwrap_err();
+
+    assert!(
+        format!("{err:#}").contains("rows point at a row"),
+        "{err:#}"
+    );
+    assert_eq!(user_version(&conn).unwrap(), 1);
+    assert_eq!(count(&conn, "SELECT COUNT(*) FROM notes"), 2);
+    assert_eq!(count(&conn, "PRAGMA foreign_keys"), 1);
+}
+
+#[test]
+fn an_upgrade_keeps_a_copy_of_the_file_and_only_the_last_two() {
+    let dir = kroma_testing::temp_dir("migrate-snapshots");
+    let path = dir.path().join("notes.db");
+    let mut conn = Connection::open(&path).unwrap();
+    conn.execute_batch(BASELINE).unwrap();
+    let mut seen = Vec::new();
+
+    for version in 1..=3 {
+        conn.pragma_update(None, "user_version", version).unwrap();
+        let schema = Schema {
+            baseline_version: version,
+            steps: &[ADD_PINNED],
+            ..SCHEMA
+        };
+        let _ = conn.execute_batch("ALTER TABLE notes DROP COLUMN pinned");
+        migrate(&mut conn, &schema, Some(&path)).unwrap();
+        std::thread::sleep(std::time::Duration::from_millis(20));
+        seen.push(snapshot_path(&path, version).exists());
+    }
+
+    assert_eq!(seen, [true, true, true]);
+    assert!(!snapshot_path(&path, 1).exists());
+    assert!(snapshot_path(&path, 2).exists());
+    assert!(snapshot_path(&path, 3).exists());
+}