bookclerk_library::scope
Plugin-scoped library access.
First-party and third-party content sources share the same boundary:
a SourceScope can only read/write rows whose plugin_key / provider
matches the provenance-qualified PluginKey it was opened for. Rows are not
tied to a plugin instance: every instance of that plugin, on any host,
sees the same accounts, credentials, and books. Host code that needs the
full store keeps its own LibraryStore handle — this type does not
expose one.
| Item | Kind | Summary |
|---|---|---|
SourceScope |
struct | Host-enforced view of LibraryStore for one content-source plugin. |
RefreshKeeping |
enum | How a storefront's sign-ins may be held, as its manifest declares it, for SourceScope::replace_refreshed_credentials. |
pub struct SourceScope {
/* private fields */
}
Host-enforced view of LibraryStore for one content-source plugin.
Both in-repo first-party adapters and external plugins must use this type
(via a bookclerk_source::ContentSource adapter or the external host
adapter). Secrets and books for other plugin keys are invisible. A
third-party package that reuses a first-party alias has a different key
and therefore sees nothing.
pub fn new(
store: LibraryStore,
plugin_key: impl Into<String>,
source_id: impl Into<String>,
) -> Self
Build a scope for plugin_key over store, labelling rows source_id.
pub fn plugin_key(&self) -> &str
Provenance-qualified PluginKey this scope isolates on.
pub fn source_id(&self) -> &str
Display alias (audible, libro, external plugin.toml id, …).
pub async fn upsert_account(
&self,
account_id: &str,
marketplace: &str,
label: Option<&str>,
scan_enabled: bool,
) -> Result<AccountRecord>
Upsert an account row; source is forced to this plugin id.
Returns an error when the operation fails.
pub async fn ensure_account(
&self,
account_id: &str,
marketplace: &str,
label: Option<&str>,
) -> Result<AccountRecord>
Ensure an account exists without flipping scan_enabled on conflict.
Returns an error when the operation fails.
pub async fn list_accounts(&self) -> Result<Vec<AccountRecord>>
Lists all store accounts in the library database.
Result<Vec<AccountRecord>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn get_account(&self, account_id: &str) -> Result<Option<AccountRecord>>
Fetch one account if it belongs to this plugin.
Returns an error when the operation fails.
pub async fn upsert_book(&self, book: &NewBook) -> Result<AcquireTitle>
Records a title an account of this plugin holds (see
LibraryStore::upsert_book); plugin_key and source are forced
to this plugin.
pub async fn upsert_scanned_title(&self, title: &ScannedTitle) -> Result<AcquireTitle>
Records a scanned title as this plugin's (see
LibraryStore::upsert_scanned_title).
As LibraryStore::upsert_scanned_title.
pub async fn upsert_scanned_titles(&self, titles: &[ScannedTitle]) -> Result<usize>
Records a page of scanned titles as this plugin's, resolving their
listings as one page (see LibraryStore::upsert_scanned_titles).
How many of titles were recorded.
As LibraryStore::upsert_scanned_titles.
pub async fn scan_state(&self, account_id: &str) -> Result<Option<ScanState>>
Where one of this plugin's accounts' scan stands.
Returns an error when the read fails.
pub async fn save_scan_checkpoint(
&self,
account_id: &str,
cursor: &str,
pass_token: &str,
pass_id: &str,
) -> Result<()>
Checkpoints a pass of one of this plugin's accounts after a page.
Returns an error when the write fails.
pub async fn mark_holdings_seen(
&self,
account_id: &str,
pass_id: &str,
product_ids: &[String],
) -> Result<()>
Stamps scan pass pass_id on one of this plugin's accounts' holdings
of product_ids (see LibraryStore::mark_holdings_seen).
Returns an error when a write fails.
pub async fn remove_account_holdings(
&self,
account_id: &str,
selection: HoldingSelection<'_>,
) -> Result<usize>
Removes one of this plugin's accounts' holdings that selection
names, publishing holding_removed for each (see
LibraryStore::remove_account_holdings).
How many holdings were selected for removal.
Returns an error when a read or write fails.
pub async fn finish_scan_pass(
&self,
account_id: &str,
sync_token: &str,
complete: bool,
) -> Result<()>
Records the end of a pass of one of this plugin's accounts.
Returns an error when the write fails.
pub async fn reset_scan_state(&self, account_id: &str) -> Result<()>
Forgets the sync token and resume cursor of one of this plugin's accounts.
Returns an error when the write fails.
pub async fn held_title(
&self,
title_id: &str,
account_id: &str,
) -> Result<Option<AcquireTitle>>
The title one of this plugin's accounts holds that title_id names
(holding id, product id, ASIN or ISBN; see
LibraryStore::held_title).
Returns crate::LibraryError::Conflict when the name is
ambiguous, or the database error.
pub async fn save_source_auth(
&self,
account_id: &str,
name: &str,
plaintext: &[u8],
) -> Result<()>
Seal and store a source_auth credential for account_id.
Returns an error when the operation fails.
pub async fn save_secret(
&self,
kind: &str,
account_id: &str,
name: &str,
plaintext: &[u8],
) -> Result<()>
Seal and store an arbitrary secret kind under this plugin's provider.
Used for Widevine CDMs (secret_kind::WIDEVINE) and similar. Provider is
always this plugin key.
Returns an error when the operation fails.
pub async fn load_source_auth(
&self,
account_id: &str,
name: &str,
) -> Result<Option<Vec<u8>>>
Load and unseal a source_auth credential for this plugin only.
Returns an error when the operation fails.
pub async fn load_secret(
&self,
kind: &str,
account_id: &str,
name: &str,
) -> Result<Option<Vec<u8>>>
Load and unseal a secret for this plugin only.
Returns an error when the operation fails.
pub async fn get_source_auth_record(
&self,
account_id: &str,
name: &str,
) -> Result<Option<EncryptedSecretRecord>>
Fetch the sealed record (for formats that need custom unseal, e.g. Audible).
Returns an error when the operation fails.
pub async fn get_secret_record(
&self,
kind: &str,
account_id: &str,
name: &str,
) -> Result<Option<EncryptedSecretRecord>>
Fetch a sealed record of any kind for this plugin (custom unseal / legacy formats).
Returns an error when the operation fails.
pub async fn list_source_auth(&self) -> Result<Vec<EncryptedSecretRecord>>
List source_auth secrets for this plugin only (never other providers).
Returns an error when the operation fails.
pub async fn delete_source_auth(&self, account_id: &str, name: &str) -> Result<()>
Delete a source_auth secret for this plugin.
Returns an error when the operation fails.
pub async fn delete_secret(&self, kind: &str, account_id: &str, name: &str) -> Result<()>
Delete a secret of any kind for this plugin.
Returns an error when the operation fails.
pub async fn save_credentials_json(
&self,
account_id: &str,
credentials: &Value,
) -> Result<()>
Upsert opaque JSON credentials (external plugin login blob).
Returns an error when the operation fails.
pub async fn keeping_branch(&self, account_id: &str) -> Result<Option<String>>
The branch that keeps this account's login fresh for this library
(the branch it was shared with, once that branch has pushed a
sign-in here; see crate::control_plane::confirmed_keeping_branch),
or None when this install keeps it. For a single-keeper storefront the host then saves
none of its own refreshes of the account: the branch pushes them.
Returns the read error.
pub async fn replace_refreshed_credentials(
&self,
account_id: &str,
sent: &Value,
refreshed: &[u8],
keeping: RefreshKeeping,
) -> Result<bool>
Stores the credentials a guest handed back after refreshing them
(ScanPage.refreshedCredentials, PlainFetch.refreshedCredentials)
in place of sent, the credentials the host gave it.
Written only while the stored credentials are still sent: when the
account was signed in again (or refreshed by another call) after
sent was read, the newer credentials stay and nothing is written.
The check and the write are one host batch guarded on the sealed row
read, so a sign-in that lands in between wins. Nothing is written
when the account has no stored credentials (it was disconnected),
nor, for a RefreshKeeping::SingleKeeper storefront, once a branch
has taken the account's sign-in over for this library (it has applied
a push from one, a node: row in account_credential_revisions),
checked in the same batch so a first push that lands in between wins
too. A shared storefront ignores those rows: no branch takes its
sign-ins over, so a row left from when it kept a single sign-in
never blocks its saves.
The new value is registered with log redaction before it is stored.
account_id- The account the guest refreshed.sent- The credentials the host sent the guest.refreshed- The credentials the guest handed back, already checked as one JSON object within the ABI bound.keeping- How the storefront's manifest says its sign-ins may be held, which decides whether a keeping branch fences the write.
True when the refreshed credentials were stored.
Returns an error when refreshed is not JSON, or a read, the seal or
the write fails.
pub async fn load_credentials_json(&self, account_id: &str) -> Result<Option<Value>>
Load opaque JSON credentials for an external (or first-party) account.
Returns an error when the operation fails.
Implements: Clone, Debug
pub enum RefreshKeeping {
Shared,
SingleKeeper,
}
How a storefront's sign-ins may be held, as its manifest declares it,
for SourceScope::replace_refreshed_credentials.
Variants
Shared: Every holder refreshes on its own; no branch takes a sign-in over, so the library always saves its own refreshes.SingleKeeper: One install refreshes each sign-in; once a branch keeps an account for this library, the library's own refreshes of it are not saved.
Implements: Clone, Copy, Debug, Eq, PartialEq
Generated from crates/bookclerk-library at main · View as Markdown