@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-db/src/playback/up_next.rs

@@ -0,0 +1,208 @@
+//! The episode to play next, and the ones after it.
+
+use anyhow::Result;
+use rusqlite::{params, OptionalExtension};
+
+use crate::hydrate::attach_files;
+use crate::pool::Pool;
+use crate::rows::row_to_item;
+use crate::schema::ITEM_COLS;
+use kroma_domain::MediaItem;
+
+/// The episode to play to CONTINUE a show, for a user: the most-recent in-progress
+/// episode (resume), else the first unwatched episode in order, else the first.
+/// Returns the hydrated episode plus whether it has a saved resume position.
+pub fn up_next_episode(
+    pool: &Pool,
+    user_id: &str,
+    show_id: &str,
+) -> Result<Option<(MediaItem, bool)>> {
+    let conn = pool.get()?;
+    let mut stmt = conn.prepare(&format!(
+        "SELECT {ITEM_COLS} FROM items \
+         WHERE show_id = ?1 AND kind = 'episode' ORDER BY season, episode"
+    ))?;
+    let episodes: Vec<MediaItem> = stmt
+        .query_map(params![show_id], row_to_item)?
+        .collect::<rusqlite::Result<Vec<_>>>()?;
+    drop(stmt);
+    if episodes.is_empty() {
+        return Ok(None);
+    }
+
+    // Resume: the most-recently-updated in-progress episode of this show.
+    let mut rs = conn.prepare(
+        "SELECT p.item_id FROM progress p JOIN items i ON i.id = p.item_id \
+         WHERE p.user_id = ?1 AND i.show_id = ?2 AND p.position_ms > 15000 \
+           AND (p.duration_ms IS NULL OR p.position_ms < p.duration_ms * 95 / 100) \
+         ORDER BY p.updated_at DESC LIMIT 1",
+    )?;
+    let resume_id = rs
+        .query_map(params![user_id, show_id], |r| r.get::<_, String>(0))?
+        .next()
+        .transpose()?;
+    drop(rs);
+
+    let (mut chosen, resume) = if let Some(id) = resume_id {
+        match episodes.iter().find(|e| e.id == id).cloned() {
+            Some(e) => (e, true),
+            None => (episodes[0].clone(), false),
+        }
+    } else {
+        // The episode AFTER the last (highest, by season/episode) watched one, so
+        // finishing E2 continues at E3 even if an earlier episode is unwatched
+        // (Plex/Netflix "on deck"). Caught up / nothing watched → the first.
+        let mut ws = conn.prepare(
+            "SELECT w.item_id FROM watched w JOIN items i ON i.id = w.item_id \
+             WHERE w.user_id = ?1 AND i.show_id = ?2",
+        )?;
+        let seen: std::collections::HashSet<String> = ws
+            .query_map(params![user_id, show_id], |r| r.get::<_, String>(0))?
+            .collect::<rusqlite::Result<_>>()?;
+        drop(ws);
+        // `episodes` is ordered by (season, episode); the next after the last seen.
+        let next = match episodes.iter().rposition(|e| seen.contains(&e.id)) {
+            Some(i) => episodes.get(i + 1).or_else(|| episodes.first()).cloned(),
+            None => episodes.first().cloned(),
+        };
+        (next.unwrap_or_else(|| episodes[0].clone()), false)
+    };
+
+    attach_files(&conn, &mut chosen)?;
+    Ok(Some((chosen, resume)))
+}
+
+/// The next `n` episodes after `item_id` in its show, by `(season, episode)`
+/// order. Empty for a movie / loose video / the last episode. Drives the
+/// player's "up next" episode rail (autoplay is the `n == 1` case).
+pub fn following_episodes(pool: &Pool, item_id: &str, n: usize) -> Result<Vec<MediaItem>> {
+    if n == 0 {
+        return Ok(Vec::new());
+    }
+    let conn = pool.get()?;
+    let coords: Option<(Option<String>, Option<i64>, Option<i64>)> = conn
+        .query_row(
+            "SELECT show_id, season, episode FROM items WHERE id = ?1",
+            params![item_id],
+            |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)),
+        )
+        .optional()?;
+    let Some((Some(show_id), Some(season), Some(episode))) = coords else {
+        return Ok(Vec::new());
+    };
+    let mut stmt = conn.prepare(&format!(
+        "SELECT {ITEM_COLS} FROM items \
+         WHERE show_id = ?1 AND kind = 'episode' \
+           AND (season > ?2 OR (season = ?2 AND episode > ?3)) \
+         ORDER BY season, episode LIMIT ?4"
+    ))?;
+    let mut items: Vec<MediaItem> = stmt
+        .query_map(params![show_id, season, episode, n as i64], row_to_item)?
+        .collect::<rusqlite::Result<_>>()?;
+    drop(stmt);
+    // Batch-hydrate (files + markers in one query each) instead of N queries per
+    // episode - this rail can be up to UP_NEXT_EPISODES rows on every watch load.
+    super::attach_files_batch(&conn, &mut items)?;
+    Ok(items)
+}
+
+/// The next episode after `item_id` in its show, by `(season, episode)` order.
+/// `None` for a movie / loose video / the last episode.
+pub fn next_episode(pool: &Pool, item_id: &str) -> Result<Option<MediaItem>> {
+    Ok(following_episodes(pool, item_id, 1)?.into_iter().next())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::playback::test_support::*;
+    use crate::playback::{mark_watched, unmark_watched, upsert_progress};
+
+    #[test]
+    fn up_next_and_next_episode() {
+        let (pool, uid) = pool_with_user();
+        {
+            let conn = pool.get().unwrap();
+            conn.execute(
+                "INSERT INTO shows (id,library,title,added_at) VALUES ('s1','lib','Show','t')",
+                [],
+            )
+            .unwrap();
+            for (id, s, e) in [("e1", 1, 1), ("e2", 1, 2), ("e3", 1, 3)] {
+                conn.execute(
+                    "INSERT INTO items (id,kind,title,container,library,show_id,season,episode,added_at) \
+                     VALUES (?1,'episode','Ep','mkv','lib','s1',?2,?3,'t')",
+                    params![id, s, e],
+                )
+                .unwrap();
+            }
+        }
+
+        // Fresh: nothing watched / in progress → first episode, not a resume.
+        let (item, resume) = up_next_episode(&pool, &uid, "s1").unwrap().unwrap();
+        assert_eq!(item.id, "e1");
+        assert!(!resume);
+
+        // e1 watched → continue after the last watched = e2.
+        mark_watched(&pool, &uid, "e1").unwrap();
+        let (item, resume) = up_next_episode(&pool, &uid, "s1").unwrap().unwrap();
+        assert_eq!(item.id, "e2");
+        assert!(!resume);
+
+        // Only e2 watched (e1 NOT) → still continue AFTER the highest watched = e3,
+        // not the first unwatched (e1). This is the on-deck behaviour.
+        unmark_watched(&pool, &uid, "e1").unwrap();
+        mark_watched(&pool, &uid, "e2").unwrap();
+        let (item, resume) = up_next_episode(&pool, &uid, "s1").unwrap().unwrap();
+        assert_eq!(item.id, "e3");
+        assert!(!resume);
+
+        // e2 in progress → resume e2 (takes priority over on-deck).
+        upsert_progress(&pool, &uid, "e2", 60_000, Some(600_000)).unwrap();
+        let (item, resume) = up_next_episode(&pool, &uid, "s1").unwrap().unwrap();
+        assert_eq!(item.id, "e2");
+        assert!(resume);
+
+        // Sequence: next after e2 is e3; e3 is last; movies have no next.
+        assert_eq!(
+            next_episode(&pool, "e2").unwrap().map(|i| i.id),
+            Some("e3".into())
+        );
+        assert!(next_episode(&pool, "e3").unwrap().is_none());
+        assert!(next_episode(&pool, "m1").unwrap().is_none());
+
+        // The "up next" EPISODE rail: the next N in order, capped by `n`, empty
+        // for the last episode / a movie / n == 0.
+        let ids = |v: Vec<MediaItem>| v.into_iter().map(|i| i.id).collect::<Vec<_>>();
+        assert_eq!(
+            ids(following_episodes(&pool, "e1", 10).unwrap()),
+            vec!["e2", "e3"]
+        );
+        assert_eq!(ids(following_episodes(&pool, "e1", 1).unwrap()), vec!["e2"]); // capped by n
+        assert!(following_episodes(&pool, "e3", 10).unwrap().is_empty()); // last episode
+        assert!(following_episodes(&pool, "m1", 10).unwrap().is_empty()); // a movie
+        assert!(following_episodes(&pool, "e1", 0).unwrap().is_empty()); // n == 0
+    }
+
+    #[test]
+    fn a_resume_row_on_something_that_is_not_an_episode_falls_back_to_the_first() {
+        let (pool, uid) = pool_with_user();
+        seed_show(&pool, "s1", "e", 3);
+        pool.get()
+            .unwrap()
+            .execute(
+                "INSERT INTO items (id,kind,title,container,library,show_id,added_at) \
+                 VALUES ('extra','video','Behind the scenes','mkv','lib','s1','t')",
+                [],
+            )
+            .unwrap();
+        upsert_progress(&pool, &uid, "extra", 60_000, Some(600_000)).unwrap();
+
+        let (item, resume) = up_next_episode(&pool, &uid, "s1").unwrap().unwrap();
+        assert_eq!(item.id, "e1");
+        assert!(
+            !resume,
+            "a bonus feature carries no episode resume position"
+        );
+    }
+}

package/rust/kroma-db/src/playback/watch_state.rs

@@ -0,0 +1,129 @@
+//! The per-user flags on an item: watched, and on my list.
+
+use anyhow::Result;
+use rusqlite::params;
+
+use crate::now_or_blank;
+use crate::pool::Pool;
+
+/// Mark an item as watched for a user, and drop any resume position so it leaves
+/// "Continue watching". Idempotent (re-marking just refreshes `watched_at`).
+pub fn mark_watched(pool: &Pool, user_id: &str, item_id: &str) -> Result<()> {
+    let conn = pool.get()?;
+    conn.execute(
+        "INSERT INTO watched (user_id,item_id,watched_at) VALUES (?1,?2,?3) \
+         ON CONFLICT(user_id,item_id) DO UPDATE SET watched_at=excluded.watched_at",
+        params![user_id, item_id, now_or_blank()],
+    )?;
+    conn.execute(
+        "DELETE FROM progress WHERE user_id = ?1 AND item_id = ?2",
+        params![user_id, item_id],
+    )?;
+    Ok(())
+}
+
+/// Clear an item's watched flag for a user. Idempotent.
+pub fn unmark_watched(pool: &Pool, user_id: &str, item_id: &str) -> Result<()> {
+    let conn = pool.get()?;
+    conn.execute(
+        "DELETE FROM watched WHERE user_id = ?1 AND item_id = ?2",
+        params![user_id, item_id],
+    )?;
+    Ok(())
+}
+
+/// Every item id the user has marked (or finished) as watched clients hydrate a
+/// set once and badge cards from it.
+pub fn list_watched(pool: &Pool, user_id: &str) -> Result<Vec<String>> {
+    let conn = pool.get()?;
+    let mut stmt = conn.prepare("SELECT item_id FROM watched WHERE user_id = ?1")?;
+    let rows = stmt.query_map(params![user_id], |r| r.get::<_, String>(0))?;
+    Ok(rows.collect::<rusqlite::Result<Vec<_>>>()?)
+}
+
+/// Add a title to the user's list. Idempotent (re-adding refreshes `added_at`).
+pub fn add_to_list(pool: &Pool, user_id: &str, item_id: &str) -> Result<()> {
+    let conn = pool.get()?;
+    conn.execute(
+        "INSERT INTO my_list (user_id,item_id,added_at) VALUES (?1,?2,?3) \
+         ON CONFLICT(user_id,item_id) DO UPDATE SET added_at=excluded.added_at",
+        params![user_id, item_id, now_or_blank()],
+    )?;
+    Ok(())
+}
+
+/// Remove a title from the user's list. Idempotent.
+pub fn remove_from_list(pool: &Pool, user_id: &str, item_id: &str) -> Result<()> {
+    let conn = pool.get()?;
+    conn.execute(
+        "DELETE FROM my_list WHERE user_id = ?1 AND item_id = ?2",
+        params![user_id, item_id],
+    )?;
+    Ok(())
+}
+
+/// Every item id in the user's list, most-recently-added first.
+pub fn list_my_list(pool: &Pool, user_id: &str) -> Result<Vec<String>> {
+    let conn = pool.get()?;
+    let mut stmt =
+        conn.prepare("SELECT item_id FROM my_list WHERE user_id = ?1 ORDER BY added_at DESC")?;
+    let rows = stmt.query_map(params![user_id], |r| r.get::<_, String>(0))?;
+    Ok(rows.collect::<rusqlite::Result<Vec<_>>>()?)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::playback::test_support::*;
+    use crate::playback::{get_progress, upsert_progress};
+
+    #[test]
+    fn mark_unmark_round_trips_and_clears_progress() {
+        let (pool, uid) = pool_with_user();
+        assert!(list_watched(&pool, &uid).unwrap().is_empty());
+
+        // A resume position that mark_watched should wipe.
+        upsert_progress(&pool, &uid, "m1", 60_000, Some(120_000)).unwrap();
+        mark_watched(&pool, &uid, "m1").unwrap();
+        assert_eq!(list_watched(&pool, &uid).unwrap(), vec!["m1".to_string()]);
+        assert!(
+            get_progress(&pool, &uid, "m1").unwrap().is_none(),
+            "marking watched clears resume"
+        );
+
+        // Idempotent: marking again keeps a single row.
+        mark_watched(&pool, &uid, "m1").unwrap();
+        assert_eq!(list_watched(&pool, &uid).unwrap().len(), 1);
+
+        // Shows (ids not in `items`) can be marked too the column has no items FK.
+        mark_watched(&pool, &uid, "show-7").unwrap();
+        let mut ids = list_watched(&pool, &uid).unwrap();
+        ids.sort();
+        assert_eq!(ids, vec!["m1".to_string(), "show-7".to_string()]);
+
+        unmark_watched(&pool, &uid, "m1").unwrap();
+        assert_eq!(
+            list_watched(&pool, &uid).unwrap(),
+            vec!["show-7".to_string()]
+        );
+    }
+
+    #[test]
+    fn my_list_add_remove_round_trips() {
+        let (pool, uid) = pool_with_user();
+        assert!(list_my_list(&pool, &uid).unwrap().is_empty());
+
+        add_to_list(&pool, &uid, "m1").unwrap();
+        add_to_list(&pool, &uid, "show-7").unwrap(); // show ids allowed (no items FK)
+        add_to_list(&pool, &uid, "m1").unwrap(); // idempotent
+        let mut ids = list_my_list(&pool, &uid).unwrap();
+        ids.sort();
+        assert_eq!(ids, vec!["m1".to_string(), "show-7".to_string()]);
+
+        remove_from_list(&pool, &uid, "m1").unwrap();
+        assert_eq!(
+            list_my_list(&pool, &uid).unwrap(),
+            vec!["show-7".to_string()]
+        );
+    }
+}

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

@@ -0,0 +1,196 @@
+//! Per-user playback state: resume positions, and everything derived from them.
+//!
+//! Re-exported flat here so the public `db::<item>` paths resolve unchanged:
+//! [`continue_watching`] turns resume rows into cards, [`watch_state`] holds the
+//! watched / my-list flags, [`show_progress`] the percent through a show, and
+//! [`up_next`] which episode comes next.
+
+use super::*;
+use kroma_domain::ProgressEntry;
+
+mod continue_watching;
+mod on_deck;
+mod show_progress;
+mod up_next;
+mod watch_state;
+
+#[cfg(test)]
+mod test_support;
+
+pub use continue_watching::*;
+pub use show_progress::*;
+pub use up_next::*;
+pub use watch_state::*;
+
+pub(crate) const RESUME_FLOOR_MS: i64 = 15_000;
+pub(crate) const FINISHED_PERCENT: i64 = 95;
+
+pub(crate) fn resumable_sql() -> String {
+    format!(
+        "p.position_ms > {RESUME_FLOOR_MS} \
+         AND (p.duration_ms IS NULL OR p.position_ms < p.duration_ms * {FINISHED_PERCENT} / 100)"
+    )
+}
+
+/// Upsert one item's playback position for a user.
+pub fn upsert_progress(
+    pool: &Pool,
+    user_id: &str,
+    item_id: &str,
+    position_ms: i64,
+    duration_ms: Option<i64>,
+) -> Result<()> {
+    let conn = pool.get()?;
+    conn.execute(
+        "INSERT INTO progress (user_id,item_id,position_ms,duration_ms,updated_at) \
+         VALUES (?1,?2,?3,?4,?5) \
+         ON CONFLICT(user_id,item_id) DO UPDATE SET \
+            position_ms=excluded.position_ms, duration_ms=excluded.duration_ms, \
+            updated_at=excluded.updated_at",
+        params![user_id, item_id, position_ms, duration_ms, now_or_blank()],
+    )?;
+    Ok(())
+}
+
+/// One item's saved progress for a user, if any.
+pub fn get_progress(pool: &Pool, user_id: &str, item_id: &str) -> Result<Option<ProgressEntry>> {
+    let conn = pool.get()?;
+    let mut stmt = conn.prepare(
+        "SELECT item_id,position_ms,duration_ms,updated_at FROM progress \
+         WHERE user_id = ?1 AND item_id = ?2",
+    )?;
+    let mut rows = stmt.query_map(params![user_id, item_id], row_to_progress)?;
+    match rows.next() {
+        Some(p) => Ok(Some(p?)),
+        None => Ok(None),
+    }
+}
+
+/// Every saved progress row for a user (newest first).
+pub fn list_progress(pool: &Pool, user_id: &str) -> Result<Vec<ProgressEntry>> {
+    let conn = pool.get()?;
+    let mut stmt = conn.prepare(
+        "SELECT item_id,position_ms,duration_ms,updated_at FROM progress \
+         WHERE user_id = ?1 ORDER BY updated_at DESC",
+    )?;
+    let rows = stmt.query_map(params![user_id], row_to_progress)?;
+    Ok(rows.collect::<rusqlite::Result<Vec<_>>>()?)
+}
+
+/// Remove a saved position (e.g. finished, or "remove from Continue Watching").
+pub fn delete_progress(pool: &Pool, user_id: &str, item_id: &str) -> Result<()> {
+    let conn = pool.get()?;
+    conn.execute(
+        "DELETE FROM progress WHERE user_id = ?1 AND item_id = ?2",
+        params![user_id, item_id],
+    )?;
+    Ok(())
+}
+
+// Map a row of `item_id,position_ms,duration_ms,updated_at` to a [`ProgressEntry`].
+fn row_to_progress(r: &Row) -> rusqlite::Result<ProgressEntry> {
+    Ok(ProgressEntry {
+        item_id: r.get(0)?,
+        position_ms: r.get(1)?,
+        duration_ms: r.get(2)?,
+        updated_at: r.get(3)?,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::playback::test_support::*;
+
+    #[test]
+    fn progress_upsert_get_list_delete() {
+        let (pool, uid) = pool_with_user(); // has item m1
+        seed_movie(&pool, "m2");
+        seed_movie(&pool, "m3");
+
+        // Nothing saved yet.
+        assert!(get_progress(&pool, &uid, "m1").unwrap().is_none());
+        assert!(list_progress(&pool, &uid).unwrap().is_empty());
+
+        // Insert path.
+        upsert_progress(&pool, &uid, "m1", 1000, Some(2000)).unwrap();
+        let p = get_progress(&pool, &uid, "m1").unwrap().unwrap();
+        assert_eq!(p.item_id, "m1");
+        assert_eq!(p.position_ms, 1000);
+        assert_eq!(p.duration_ms, Some(2000));
+
+        // ON CONFLICT update path: new position, duration cleared to NULL, still one row.
+        upsert_progress(&pool, &uid, "m1", 5000, None).unwrap();
+        let p = get_progress(&pool, &uid, "m1").unwrap().unwrap();
+        assert_eq!(p.position_ms, 5000);
+        assert_eq!(p.duration_ms, None);
+        assert_eq!(list_progress(&pool, &uid).unwrap().len(), 1);
+
+        // list_progress is newest (updated_at DESC) first; control timestamps for a
+        // deterministic order (RFC3339 text sorts chronologically).
+        upsert_progress(&pool, &uid, "m2", 100, Some(1000)).unwrap();
+        upsert_progress(&pool, &uid, "m3", 200, Some(1000)).unwrap();
+        {
+            let conn = pool.get().unwrap();
+            for (id, at) in [
+                ("m1", "2021-01-01T00:00:00Z"),
+                ("m2", "2021-01-03T00:00:00Z"),
+                ("m3", "2021-01-02T00:00:00Z"),
+            ] {
+                conn.execute(
+                    "UPDATE progress SET updated_at=?2 WHERE item_id=?1",
+                    params![id, at],
+                )
+                .unwrap();
+            }
+        }
+        let ids: Vec<String> = list_progress(&pool, &uid)
+            .unwrap()
+            .into_iter()
+            .map(|p| p.item_id)
+            .collect();
+        assert_eq!(
+            ids,
+            vec!["m2".to_string(), "m3".to_string(), "m1".to_string()]
+        );
+
+        // Delete one; deleting a missing id is a harmless no-op.
+        delete_progress(&pool, &uid, "m2").unwrap();
+        let ids: Vec<String> = list_progress(&pool, &uid)
+            .unwrap()
+            .into_iter()
+            .map(|p| p.item_id)
+            .collect();
+        assert_eq!(ids, vec!["m3".to_string(), "m1".to_string()]);
+        delete_progress(&pool, &uid, "does-not-exist").unwrap();
+        assert_eq!(list_progress(&pool, &uid).unwrap().len(), 2);
+    }
+
+    // Guards the `cast` reserved-keyword quoting in season_meta SQL.
+    #[test]
+    fn season_cast_round_trips() {
+        use kroma_domain::CastMember;
+        let (pool, _uid) = pool_with_user();
+        {
+            let conn = pool.get().unwrap();
+            conn.execute(
+                "INSERT INTO shows (id,library,title,added_at) VALUES ('s1','lib','Show','t')",
+                [],
+            )
+            .unwrap();
+        }
+        assert!(crate::seasons_with_cast(&pool, "s1").unwrap().is_empty());
+        let cast = vec![CastMember {
+            name: "Alice".into(),
+            tmdb_id: None,
+            character: Some("Lead".into()),
+            profile_url: None,
+        }];
+        crate::set_season_cast(&pool, "s1", 1, &cast).unwrap();
+        crate::set_season_cast(&pool, "s1", 1, &cast).unwrap(); // idempotent upsert
+        assert!(crate::seasons_with_cast(&pool, "s1").unwrap().contains(&1));
+        let casts = crate::season_casts(&pool, "s1").unwrap();
+        assert_eq!(casts.get(&1).map(|c| c.len()), Some(1));
+        assert_eq!(casts[&1][0].name, "Alice");
+    }
+}

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

@@ -0,0 +1,117 @@
+//! The WAL connection pool.
+
+use std::ops::{Deref, DerefMut};
+use std::path::PathBuf;
+use std::sync::{Arc, Mutex};
+
+use anyhow::{Context, Result};
+use rusqlite::Connection;
+
+use super::PRAGMAS;
+
+/// A small, cheap-to-clone WAL connection pool. Cloning shares the same idle
+/// connection set (it's an `Arc` inside). Read queries on separate
+/// `spawn_blocking` threads each check out their own connection, so WAL readers
+/// run concurrently with the single writer.
+pub type Pool = Arc<PoolInner>;
+
+pub struct PoolInner {
+    pub(crate) path: PathBuf,
+    pub(crate) idle: Mutex<Vec<Connection>>,
+    pub(crate) max_idle: usize,
+    // `None` for the core's own pool: the app is not scoped against itself. A
+    // module's pool carries the grant its manifest declared (see [`Grant`]).
+    pub(crate) scope: Option<crate::grant::Scope>,
+}
+
+impl PoolInner {
+    /// The database file this pool opens.
+    pub fn path(&self) -> &std::path::Path {
+        &self.path
+    }
+
+    fn open(&self) -> Result<Connection> {
+        let conn = Connection::open(&self.path).context("open sqlite connection")?;
+        conn.execute_batch(PRAGMAS).context("apply pragmas")?;
+        // After the pragmas, never before: the authorizer denies PRAGMA, and
+        // these are the host's own, not the module's.
+        if let Some(scope) = &self.scope {
+            scope.install(&conn).context("install storage grant")?;
+        }
+        Ok(conn)
+    }
+
+    /// Check out a connection (reused or freshly opened). Returned to the pool on
+    /// drop, up to `max_idle`.
+    pub fn get(self: &Arc<Self>) -> Result<PooledConn> {
+        let reused = self.idle.lock().unwrap().pop();
+        let conn = match reused {
+            Some(c) => c,
+            None => self.open()?,
+        };
+        Ok(PooledConn {
+            inner: Some(conn),
+            pool: Arc::clone(self),
+        })
+    }
+}
+
+/// RAII connection handle; derefs to [`rusqlite::Connection`].
+pub struct PooledConn {
+    inner: Option<Connection>,
+    pool: Pool,
+}
+
+impl Deref for PooledConn {
+    type Target = Connection;
+    fn deref(&self) -> &Connection {
+        self.inner.as_ref().expect("connection present")
+    }
+}
+
+impl DerefMut for PooledConn {
+    fn deref_mut(&mut self) -> &mut Connection {
+        self.inner.as_mut().expect("connection present")
+    }
+}
+
+impl Drop for PooledConn {
+    fn drop(&mut self) {
+        if let Some(conn) = self.inner.take() {
+            let mut idle = self.pool.idle.lock().unwrap();
+            if idle.len() < self.pool.max_idle {
+                idle.push(conn);
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod pool_tests {
+    #[test]
+    fn a_returned_connection_is_reused_and_the_idle_set_stays_capped() {
+        let pool = crate::testing::temp_pool("pool-cap");
+        let max_idle = pool.max_idle;
+
+        {
+            let first = pool.get().unwrap();
+            first
+                .query_row("SELECT 1", [], |r| r.get::<_, i64>(0))
+                .unwrap();
+        }
+        assert_eq!(
+            pool.idle.lock().unwrap().len(),
+            1,
+            "a dropped connection goes back"
+        );
+
+        let checked_out: Vec<_> = (0..max_idle + 3).map(|_| pool.get().unwrap()).collect();
+        assert!(pool.idle.lock().unwrap().is_empty());
+        drop(checked_out);
+        assert_eq!(
+            pool.idle.lock().unwrap().len(),
+            max_idle,
+            "connections past the cap are closed, not hoarded"
+        );
+    }
+}