@kromatv/sdk 0.1.39-canary.3579809

package/rust/kroma-module-runtime/src/serve.rs

@@ -0,0 +1,175 @@
+use std::sync::Arc;
+
+use kroma_module_host::host_token::{require_host_token, HostToken};
+use kroma_module_host::ServerModule;
+
+use crate::env::Env;
+use crate::events::register_events;
+use crate::events::{event_router, wanted_topics, Subscribers};
+use crate::jobs::{collect_jobs, job_router, register_jobs, JobSpec};
+use crate::migrations::apply_module_migrations;
+use crate::remote_host::RemoteHost;
+
+/// Run a module process serving one `ServerModule`. Convenience over [`serve`].
+pub async fn serve_one(
+    setup: impl FnOnce(&RemoteHost),
+    module: Box<dyn ServerModule<RemoteHost>>,
+) -> anyhow::Result<()> {
+    serve(
+        |host| {
+            setup(host);
+            axum::Router::new()
+        },
+        vec![module],
+    )
+    .await
+}
+
+// A module is a separate process, so it does not inherit the core's subscriber:
+// without this it logged at a hardcoded `info` and there was no way to turn it
+// up. `KROMA_MODULE_LOG` overrides `RUST_LOG` for the sidecars alone, so the
+// core can stay quiet while one module is put under a microscope.
+fn init_tracing() {
+    let filter = std::env::var("KROMA_MODULE_LOG")
+        .or_else(|_| std::env::var("RUST_LOG"))
+        .unwrap_or_else(|_| "info".to_string());
+    tracing_subscriber::fmt()
+        .with_env_filter(tracing_subscriber::EnvFilter::new(filter))
+        .with_target(true)
+        .try_init()
+        .ok();
+}
+
+/// Run a module process: `wire` builds the process's own services and port
+/// providers against the live host and hands back whatever extra routes it
+/// serves, each module's `admin_routes` are mounted beside them on the assigned
+/// port, and every module's `on_enable` runs. A process may host several modules
+/// or none (a port-provider-only process).
+///
+/// `wire` takes the host rather than running before it, because a provider that
+/// answers out of a database has to be built holding that database: the port
+/// contract it implements names only [`HostCtx`], so the pools cannot arrive
+/// through the call.
+pub async fn serve(
+    wire: impl FnOnce(&RemoteHost) -> axum::Router<RemoteHost>,
+    modules: Vec<Box<dyn ServerModule<RemoteHost>>>,
+) -> anyhow::Result<()> {
+    init_tracing();
+    let env = Env::from_process()?;
+    let host = RemoteHost::new(&env)?;
+    tracing::info!(module = %env.module_id, port = env.port, "module process starting");
+
+    apply_module_migrations(&host, &modules)?;
+    // Shared from here on: the event delivery route dispatches to a module at
+    // request time, so the set has to outlive this function.
+    let modules = Arc::new(modules);
+    let extra = wire(&host);
+
+    for module in modules.iter() {
+        module.on_enable(host.clone()).await;
+    }
+
+    let (job_fns, job_specs) = collect_jobs(&modules);
+    let topics = wanted_topics(&modules);
+
+    // `extra`'s `/_port/*` routes are ALSO reachable through the core reverse
+    // proxy, which sits outside the session gate: without this guard an
+    // unauthenticated client could invoke privileged port actions. Applied before
+    // `_health` so the liveness probe stays unauthenticated. The `_ready` route
+    // anchors the layer: axum panics on `route_layer` over an empty router, and
+    // a module without port routes hands one in (`serve_one`).
+    let extra = extra
+        .route("/_port/_ready", axum::routing::get(|| async { "ok" }))
+        .route_layer(axum::middleware::from_fn_with_state(
+            HostToken(env.host_token.clone()),
+            require_host_token,
+        ));
+
+    let mut app = extra.route("/_health", axum::routing::get(|| async { "ok" }));
+    for module in modules.iter() {
+        if let Some(routes) = module.admin_routes(&host) {
+            app = app.merge(routes);
+        }
+    }
+    if !job_fns.is_empty() {
+        app = app.merge(job_router(job_fns, env.host_token.clone()));
+    }
+    if !topics.is_empty() {
+        let subscribers = Arc::new(Subscribers::new(modules.clone(), &topics));
+        app = app.merge(event_router(subscribers, env.host_token.clone()));
+    }
+    let shutdown_host = host.clone();
+    let app = app.with_state(host);
+
+    let addr = std::net::SocketAddr::from(([127, 0, 0, 1], env.port));
+    let listener = tokio::net::TcpListener::bind(addr).await?;
+    tracing::info!(%addr, "module listening");
+
+    announce_to_core(&env, job_specs, &topics);
+
+    let module_id = env.module_id.clone();
+    axum::serve(listener, app)
+        .with_graceful_shutdown(async move {
+            stop_signal().await;
+            // The hooks run BEFORE the connection drain, not after: draining can
+            // take as long as the slowest in-flight request, and the supervisor
+            // only waits so long before killing us. Whatever a module owns
+            // outside this process (the remote module's `cloudflared` child)
+            // must be released while we still have a process to release it from.
+            tracing::info!(module = %module_id, "stopping: releasing module resources");
+            for module in modules.iter() {
+                module.on_disable(shutdown_host.clone()).await;
+            }
+        })
+        .await?;
+    Ok(())
+}
+
+// Jobs and event topics, announced only after the listener is bound, so a run the
+// core fires immediately queues on the accept backlog rather than failing to
+// connect. Best-effort: a failed registration leaves the job or the subscription
+// absent until respawn.
+fn announce_to_core(env: &Env, job_specs: Vec<JobSpec>, topics: &[String]) {
+    let host_url = |path: &str| format!("{}/api/_host/{path}", env.core_url.trim_end_matches('/'));
+    if !job_specs.is_empty() {
+        let url = host_url("register-job");
+        let module_id = env.module_id.clone();
+        let host_token = env.host_token.clone();
+        tokio::task::spawn_blocking(move || {
+            register_jobs(&url, &module_id, &host_token, &job_specs);
+        });
+    }
+    if !topics.is_empty() {
+        let url = host_url("register-events");
+        let module_id = env.module_id.clone();
+        let host_token = env.host_token.clone();
+        let topics = topics.to_vec();
+        tokio::task::spawn_blocking(move || {
+            register_events(&url, &module_id, &host_token, &topics);
+        });
+    }
+}
+
+/// Resolves when the supervisor asks this process to stop. A sidecar is a plain
+/// child process, so SIGTERM is the only notice it gets before SIGKILL.
+async fn stop_signal() {
+    #[cfg(unix)]
+    {
+        use tokio::signal::unix::{signal, SignalKind};
+        let mut term = match signal(SignalKind::terminate()) {
+            Ok(s) => s,
+            Err(e) => {
+                tracing::warn!(error = %e, "cannot listen for SIGTERM; no clean shutdown");
+                return std::future::pending().await;
+            }
+        };
+        tokio::select! {
+            _ = term.recv() => {}
+            _ = tokio::signal::ctrl_c() => {}
+        }
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = tokio::signal::ctrl_c().await;
+    }
+}

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

@@ -0,0 +1,52 @@
+[package]
+name = "kroma-module-sdk"
+version = "0.1.39-canary.3579809"
+edition = "2021"
+rust-version = "1.88"
+description = "The KROMA module SDK: the single crate every server module depends on. Re-exports the manifest layer plus the engine/host/domain/http/i18n/db surface, so modules never depend on core crates directly."
+license = "AGPL-3.0-or-later"
+
+[dependencies]
+# Manifest layer (below engine): EmbeddedModule / Registry / ModuleManifest.
+kroma-module-manifest = { path = "../kroma-module-manifest" }
+# The embedded_module!() proc-macro, re-exported so modules write one line.
+kroma-module-macros = { path = "../kroma-module-macros" }
+# Host contract: ServerModule, HostCtx, service/port resolution, async_trait.
+kroma-module-host = { path = "../kroma-module-host" }
+# Reading and re-encoding one input, behind `transcode`.
+kroma-media = { path = "../kroma-media", optional = true }
+# What a sidecar links: the wire types, the HTTP client, the i18n engine its
+# own catalogs resolve against, the SQLite pool.
+kroma-module-wire = { path = "../kroma-module-wire" }
+kroma-http = { path = "../kroma-http" }
+kroma-i18n = { path = "../kroma-i18n" }
+kroma-sqlite = { path = "../kroma-sqlite", optional = true }
+kroma-primitives = { path = "../kroma-primitives" }
+# `testing::{TempDir, temp_dir}`, the scratch dir every module test writes in.
+kroma-testing = { path = "../kroma-testing", optional = true }
+# Both ends of every port contract live beside its trait: the provider mounts
+# axum routes, the consumer proxies over them.
+axum = { version = "0.8", features = ["macros", "ws"] }
+tokio = { version = "1", features = ["full"] }
+# The port contract types derive serde and return anyhow::Result.
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1" }
+anyhow = { version = "1" }
+
+[features]
+# Everything a module's tests reach: the `StubHost` double, `test_serve`, a
+# throwaway pool and a self-deleting scratch dir. Never `engine`: a round-trip
+# test must not link the whole core.
+testing = ["kroma-module-host/testing", "storage", "kroma-sqlite/testing", "dep:kroma-testing"]
+# The `storage` capability: `host::HostStorage` and the `db` facade. A module
+# enables it when its `module.json` declares `storage`, and only then does its
+# binary link SQLite -- which is 1.5 MB of the 3.3 MB a sidecar used to be.
+storage = ["dep:kroma-sqlite", "kroma-module-host/storage"]
+# The `transcode` capability: `media::{hls, probe, program, stream}`, for a module
+# that holds a media file and has to describe or re-encode it. Never `core`,
+# `domain` or `engine`: a module transcodes without a catalog, and a crate with no
+# database is what lets it.
+transcode = ["dep:kroma-media"]
+
+[lints.rust]
+unexpected_cfgs = { level = "allow", check-cfg = ['cfg(feature, values("core"))', 'cfg(feature, values("domain"))', 'cfg(feature, values("engine"))'] }

package/rust/kroma-module-sdk/src/lib.rs

@@ -0,0 +1,155 @@
+//! The KROMA module SDK: the ONE crate a server module depends on.
+//!
+//! A module must not depend on `kroma-engine`, `kroma-db`, `kroma-domain`,
+//! `kroma-sqlite`, `kroma-module-wire`, `kroma-http` or `kroma-i18n` directly.
+
+pub use kroma_module_manifest::*;
+
+/// `embedded_module!()` builds a module's `MODULE` const by discovering its
+/// `module.json` + `icon.<ext>` at compile time. Write
+/// `pub const MODULE: EmbeddedModule = kroma_module_sdk::embedded_module!();`.
+pub use kroma_module_macros::embedded_module;
+
+/// `embedded_locales!()` collects a module's `locales/<code>.json` at compile
+/// time into the `&[(code, json)]` [`i18n::engine`] takes. Write
+/// `const LOCALES: &[(&str, &str)] = kroma_module_sdk::embedded_locales!();`.
+pub use kroma_module_macros::embedded_locales;
+
+/// Host contract: the `ServerModule` trait, `HostCtx`, the point resolvers and
+/// the `service` helper, and the `async_trait` re-export module impls need.
+pub mod host {
+    pub use kroma_module_host::*;
+}
+
+/// The application surface: `state::SharedState`, `services::*`, `model::*`.
+/// Behind the `engine` feature: this is the whole core.
+#[cfg(feature = "engine")]
+pub mod engine {
+    pub use kroma_engine::*;
+}
+
+/// What the host and a module exchange: the session user and its permissions,
+/// notifications and their audience, metadata answers. Behind the `domain`
+/// feature, the whole of `kroma-domain` on top, for a first-party module that
+/// reads the core's own shapes.
+pub mod domain {
+    #[cfg(feature = "domain")]
+    pub use kroma_domain::*;
+    // Only where `kroma-domain` is absent: it re-exports the wire types itself, and
+    // a second glob over the same names resolves through neither.
+    #[cfg(not(feature = "domain"))]
+    pub use kroma_module_wire::*;
+}
+
+/// Reading and re-encoding one media input. Behind the `transcode` feature,
+/// which brings no database and no catalog with it: an input is a path or a URL,
+/// and a module tells the engine which directory it may write its sessions in.
+#[cfg(feature = "transcode")]
+pub mod media {
+    pub use kroma_media::*;
+}
+
+/// The outbound HTTP client (`Fetch`, `Response`).
+pub mod http {
+    pub use kroma_http::*;
+}
+
+/// The catalogs a module ships in `locales/`, resolved by the same engine the
+/// core resolves its own with, so a plural or a `{name}` behaves the same in a
+/// sidecar as it does on a screen.
+pub mod i18n {
+    pub use kroma_i18n::*;
+
+    pub const FALLBACK_LOCALE: &str = "en";
+
+    /// An engine over the catalogs [`crate::embedded_locales!`] found. A module
+    /// that ships no English falls back to its first catalog instead; one that
+    /// ships none at all is an error rather than an engine answering every key
+    /// with itself.
+    pub fn engine(catalogs: &[(&str, &str)]) -> Result<I18n, BuildError> {
+        let fallback = catalogs
+            .iter()
+            .map(|(code, _)| *code)
+            .find(|code| *code == FALLBACK_LOCALE)
+            .or_else(|| catalogs.first().map(|(code, _)| *code))
+            .unwrap_or(FALLBACK_LOCALE);
+        catalogs
+            .iter()
+            .fold(
+                I18n::builder().default_locale(fallback).plural_rule(cldr),
+                |builder, (code, json)| builder.catalog_json(*code, *json),
+            )
+            .build()
+    }
+
+    #[cfg(test)]
+    mod tests {
+        use super::*;
+
+        const EN: &str = r#"{ "items": "{count} items", "items_one": "{count} item" }"#;
+        const FR: &str = r#"{ "items": "{count} objets", "items_one": "{count} objet" }"#;
+        const CATALOGS: &[(&str, &str)] = &[("en", EN), ("fr", FR)];
+
+        #[test]
+        fn a_count_picks_the_variant_the_readers_own_language_declares() {
+            let i18n = engine(CATALOGS).expect("two catalogs");
+
+            assert_eq!(i18n.t("fr", "items", &[("count", "0")]), "0 objet");
+            assert_eq!(i18n.t("en", "items", &[("count", "0")]), "0 items");
+            assert_eq!(i18n.t("fr", "items", &[("count", "2")]), "2 objets");
+        }
+
+        #[test]
+        fn english_leads_whatever_order_the_catalogs_arrived_in() {
+            let reversed: Vec<(&str, &str)> = CATALOGS.iter().rev().copied().collect();
+
+            assert_eq!(engine(&reversed).unwrap().default_locale(), "en");
+            assert_eq!(engine(CATALOGS).unwrap().default_locale(), "en");
+        }
+
+        #[test]
+        fn a_module_with_no_english_resolves_against_the_catalog_it_does_ship() {
+            let only_french = engine(&CATALOGS[1..]).expect("one catalog");
+
+            assert_eq!(only_french.default_locale(), "fr");
+            assert_eq!(only_french.t("en", "items", &[("count", "1")]), "1 objet");
+            assert!(engine(&[]).is_err());
+        }
+    }
+}
+
+/// Direct SQLite access: the pool, the grant and a module's own migrations.
+/// Behind the `storage` feature, which a module turns on when its `module.json`
+/// declares `storage`; the pools themselves come from `host::HostStorage`, not
+/// from here. Under `engine`, every query the core makes of its own database as
+/// well.
+#[cfg(feature = "storage")]
+pub mod db {
+    #[cfg(feature = "engine")]
+    pub use kroma_db::*;
+    pub use kroma_sqlite::{
+        apply_migrations, init_scoped, migrate_store, open, open_with, Grant, Pool, PoolInner,
+        PooledConn, Run, Step,
+    };
+    #[cfg(all(any(test, feature = "testing"), not(feature = "core")))]
+    pub use kroma_sqlite::testing;
+    /// `temp_pool` stamps the core schema, for a grant test that has to run
+    /// against the real tables rather than a copy of them.
+    #[cfg(all(any(test, feature = "testing"), feature = "core"))]
+    pub use kroma_db::testing;
+}
+
+/// Small shared primitives (`now_ms`, ...).
+pub mod primitives {
+    pub use kroma_primitives::*;
+}
+
+/// What a module's tests reach: `serve` / `blocking` stand a point's provider up
+/// on a real socket for a test that drives both ends, and `TempDir` / `temp_dir`
+/// are the self-deleting scratch dir. The `StubHost` double is
+/// `host::testing::StubHost`, and a throwaway pool is `db::testing::temp_pool`.
+#[cfg(any(test, feature = "testing"))]
+pub mod testing {
+    pub use kroma_module_host::test_serve::*;
+    pub use kroma_testing::*;
+}

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

@@ -0,0 +1,10 @@
+[package]
+name = "kroma-module-wire"
+version = "0.1.39-canary.3579809"
+edition = "2021"
+rust-version = "1.88"
+description = "The JSON a module and the host exchange: the session user, notifications and their audience, metadata answers. Serde only."
+license = "AGPL-3.0-or-later"
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }

package/rust/kroma-module-wire/src/accounts.rs

@@ -0,0 +1,238 @@
+//! The account a session resolves to, and the capabilities it may hold.
+
+use serde::{Deserialize, Serialize};
+
+/// A user account. `password_hash` lives only in the DB layer and is never part
+/// of this (serialized) shape, so a `User` is always safe to send to clients.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct User {
+    pub id: String,
+    pub email: String,
+    pub username: String,
+    #[serde(rename = "avatarUrl", skip_serializing_if = "Option::is_none")]
+    pub avatar_url: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub language: Option<String>,
+    // An ISO-639 code; `None` falls back to the file's default track. Independent
+    // of the UI `language` above (you might browse in French, watch in Japanese).
+    #[serde(rename = "audioLanguage", skip_serializing_if = "Option::is_none")]
+    pub audio_language: Option<String>,
+    // An ISO-639 code, or the sentinel `"off"` to force subtitles off; `None` is
+    // no preference.
+    #[serde(rename = "subtitleLanguage", skip_serializing_if = "Option::is_none")]
+    pub subtitle_language: Option<String>,
+    pub permissions: Vec<Permission>,
+    pub libraries: LibraryScope,
+    #[serde(rename = "createdAt")]
+    pub created_at: String,
+    #[serde(rename = "hasPin")]
+    pub has_pin: bool,
+}
+
+/// Which libraries an account may browse, search and play (ACCT-20). Serializes
+/// as `null` for [`LibraryScope::All`] and as an array of library ids otherwise,
+/// so a stored `NULL` and an absent field both read as every library: an upgrade
+/// never narrows an account that was never narrowed on purpose.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(from = "Option<Vec<String>>", into = "Option<Vec<String>>")]
+pub enum LibraryScope {
+    #[default]
+    All,
+    Only(Vec<String>),
+}
+
+impl LibraryScope {
+    pub fn admits(&self, library: &str) -> bool {
+        match self {
+            LibraryScope::All => true,
+            LibraryScope::Only(ids) => ids.iter().any(|id| id == library),
+        }
+    }
+}
+
+impl From<Option<Vec<String>>> for LibraryScope {
+    fn from(value: Option<Vec<String>>) -> Self {
+        match value {
+            None => LibraryScope::All,
+            Some(ids) => LibraryScope::Only(ids),
+        }
+    }
+}
+
+impl From<LibraryScope> for Option<Vec<String>> {
+    fn from(value: LibraryScope) -> Self {
+        match value {
+            LibraryScope::All => None,
+            LibraryScope::Only(ids) => Some(ids),
+        }
+    }
+}
+
+impl User {
+    /// Whether this user holds a given permission. Gates the invite/admin
+    /// endpoints via `crate::api::users`'s `require`.
+    pub fn can(&self, perm: Permission) -> bool {
+        self.permissions.contains(&perm)
+    }
+
+    /// Whether this account may see `library`, and so browse, find and play what
+    /// is in it. An account that can edit users, libraries or settings always
+    /// may: it can lift its own restriction in one request, so enforcing one
+    /// against it would hide the server from the people who run it.
+    pub fn sees_library(&self, library: &str) -> bool {
+        self.sees_every_library() || self.libraries.admits(library)
+    }
+
+    pub fn sees_every_library(&self) -> bool {
+        self.can(Permission::UsersManage)
+            || self.can(Permission::LibraryManage)
+            || self.can(Permission::SettingsManage)
+    }
+
+    /// Whether this user holds ANY management capability (unlocks the admin
+    /// console shell). `requests.manage` counts: a requests moderator needs the
+    /// console for the demandes queue even without user/library/settings rights.
+    pub fn is_any_admin(&self) -> bool {
+        self.can(Permission::UsersManage)
+            || self.can(Permission::LibraryManage)
+            || self.can(Permission::SettingsManage)
+            || self.can(Permission::RequestsManage)
+            || self.can(Permission::ReportsManage)
+    }
+}
+
+/// A granular capability. Stored on each user as a JSON array of the string keys
+/// below. Extend this enum (and the TS mirror in `@kromatv/core`) to add more
+/// e.g. a `stats.view` for the upcoming stats pages.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum Permission {
+    #[serde(rename = "users.manage")]
+    UsersManage,
+    #[serde(rename = "library.manage")]
+    LibraryManage,
+    #[serde(rename = "settings.manage")]
+    SettingsManage,
+    #[serde(rename = "playback")]
+    Playback,
+    #[serde(rename = "requests.create")]
+    RequestsCreate,
+    #[serde(rename = "requests.manage")]
+    RequestsManage,
+    #[serde(rename = "requests.auto")]
+    RequestsAuto,
+    #[serde(rename = "reports.manage")]
+    ReportsManage,
+}
+
+impl Permission {
+    /// Parse a stored key; `None` for unknown keys (tolerant forward-compat).
+    pub fn parse(s: &str) -> Option<Permission> {
+        match s {
+            "users.manage" => Some(Permission::UsersManage),
+            "library.manage" => Some(Permission::LibraryManage),
+            "settings.manage" => Some(Permission::SettingsManage),
+            "playback" => Some(Permission::Playback),
+            "requests.create" => Some(Permission::RequestsCreate),
+            "requests.manage" => Some(Permission::RequestsManage),
+            "requests.auto" => Some(Permission::RequestsAuto),
+            "reports.manage" => Some(Permission::ReportsManage),
+            _ => None,
+        }
+    }
+
+    /// Every permission granted to the owner account.
+    pub fn all() -> Vec<Permission> {
+        vec![
+            Permission::UsersManage,
+            Permission::LibraryManage,
+            Permission::SettingsManage,
+            Permission::Playback,
+            Permission::RequestsCreate,
+            Permission::RequestsManage,
+            Permission::RequestsAuto,
+            Permission::ReportsManage,
+        ]
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn user(permissions: Vec<Permission>, libraries: LibraryScope) -> User {
+        User {
+            id: "u1".into(),
+            email: "a@b.c".into(),
+            username: "alice".into(),
+            avatar_url: None,
+            language: None,
+            audio_language: None,
+            subtitle_language: None,
+            permissions,
+            libraries,
+            created_at: String::new(),
+            has_pin: false,
+        }
+    }
+
+    #[test]
+    fn an_account_with_no_grant_on_record_sees_every_library() {
+        let alice = user(vec![Permission::Playback], LibraryScope::All);
+
+        assert!(alice.sees_library("films"));
+        assert!(alice.sees_library("anything-at-all"));
+    }
+
+    #[test]
+    fn a_granted_account_sees_the_named_libraries_and_nothing_else() {
+        let alice = user(
+            vec![Permission::Playback],
+            LibraryScope::Only(vec!["films".into()]),
+        );
+
+        assert!(alice.sees_library("films"));
+        assert!(!alice.sees_library("series"));
+    }
+
+    #[test]
+    fn an_empty_grant_sees_nothing() {
+        let alice = user(vec![Permission::Playback], LibraryScope::Only(Vec::new()));
+
+        assert!(!alice.sees_library("films"));
+    }
+
+    #[test]
+    fn an_account_that_runs_the_server_sees_a_library_it_was_not_granted() {
+        for perm in [
+            Permission::UsersManage,
+            Permission::LibraryManage,
+            Permission::SettingsManage,
+        ] {
+            let admin = user(vec![perm], LibraryScope::Only(Vec::new()));
+            assert!(admin.sees_library("films"), "{perm:?}");
+        }
+
+        let moderator = user(
+            vec![Permission::RequestsManage, Permission::ReportsManage],
+            LibraryScope::Only(Vec::new()),
+        );
+        assert!(!moderator.sees_library("films"));
+    }
+
+    #[test]
+    fn the_scope_crosses_the_wire_as_null_or_a_list_of_ids() {
+        assert_eq!(serde_json::to_string(&LibraryScope::All).unwrap(), "null");
+        assert_eq!(
+            serde_json::to_string(&LibraryScope::Only(vec!["films".into()])).unwrap(),
+            r#"["films"]"#
+        );
+        assert_eq!(
+            serde_json::from_str::<LibraryScope>("null").unwrap(),
+            LibraryScope::All
+        );
+        assert_eq!(
+            serde_json::from_str::<LibraryScope>(r#"["films"]"#).unwrap(),
+            LibraryScope::Only(vec!["films".into()])
+        );
+    }
+}