bookclerk_library
Canonical Bookclerk library database.
LibraryStore is SeaORM-backed: every backend is a
sea_orm::DatabaseConnection. Engine connect/migrate/proxy quirks live in
the database plugin (bookclerk-plugin-database-sqlite (and optional d1/postgres guests)); hosts open the store via
the external guest RPC. This crate owns the greenfield schema
(migrations), typed entities, and the store API. See
docs/server/database.md.
| Item | Kind | Summary |
|---|---|---|
AtomicTxnBackend |
trait | Backend that runs crate::LibraryStore named security operations as a single guest atomic batch. |
TypedAtomicExec |
trait | Runs a host-authorized typed bookclerk_plugin_abi::ExecuteRequest as one guest executeAtomic. |
NamedAtomicRunner |
trait | Runs one compiled named plan as a single atomic batch. |
DbAtomicResult |
struct | Host-interpreted result of a named atomic operation. |
BackendMigrateOptions |
struct | Options for a backend-to-backend library copy. |
BackendMigrateSummary |
struct | Per-table row counts copied (or that would be copied in dry-run mode). |
BackupRepository |
struct | On-disk backup repository rooted at files_dir/backups. |
BackupListEntry |
struct | Catalog entry used by bookclerk db backup list. |
BackupManifest |
struct | On-disk recovery-point metadata (manifests/<id>.json). |
BackupOutcome |
struct | Result of publishing a recovery point. |
BackupRequest |
struct | Inputs for an automatic or CLI backup. |
BackupUnit |
struct | One logical database in a recovery point (library or plugin binding). |
CanonicalDatabaseSchema |
struct | Admitted canonical schema used to export or restore one database unit. |
CanonicalExportOpts |
struct | Options for a consistent canonical export. |
CanonicalRestoreOpts |
struct | Negotiated limits for parameterized canonical restore. |
CanonicalTableSchema |
struct | One admitted CREATE TABLE plus its parsed IR. |
IdentityHighWater |
struct | Identity high-water for one generated column. |
PreparedPluginUnit |
struct | Open plugin binding captured through the active adapter session. |
RestorePlan |
struct | Library restore result plus plugin units for the host to apply. |
SchemaBackupOpts |
struct | Optional in-place backup taken before applying ups or downs. |
ValidatedBackup |
struct | Recovery point whose objects, schema, and typed rows have been verified. |
Missing |
struct | What a LibraryError::NotFound could not find: the kind of row and, when the caller named one, its id. |
SchemaApplyOptions |
struct | Options for apply_host_schema_with_options. |
SchemaBatch |
struct | Canonical schema apply batch: already-separate host statements plus marker. |
InProcessSqlite |
struct | Runs compiled named plans on a local SeaORM SQLite connection. |
PluginMigrationHistory |
struct | Ordered durable plugin migration history. |
PluginMigrationSequence |
struct | Proven, ordered plugin migration sequence. |
ProvenPluginMigration |
struct | One proven registered migration. |
AccountLinkRecord |
struct | Link between a portal identity and a bookstore account. |
AccountRecord |
struct | Account row stored in the Bookclerk DB. |
AcquireStatusCounts |
struct | Held work counts per AcquireStatus, read in one grouped query (see LibraryStore::count_works_by_status). |
BranchRequestTarget |
struct | What a JobKind::BranchRequest asks its branch for: a work of this library, and the store listing the branch answered for it (control_plane::catalog_lookup). The branch is told the work by its identifiers, never by this id. |
ClaimTicketRecord |
struct | Claim ticket metadata (token plaintext is never stored). |
DomainEventRecord |
struct | Immutable outbox envelope. |
EmbeddingRecord |
struct | Stored embedding vector metadata (blob fetched separately when needed). |
EnqueueJobSpec |
struct | Admission request for crate::LibraryStore::enqueue_job. |
EventCatalogSubscription |
struct | One [capabilities.events.subscriptions] row persisted in event_subscriber_nodes. |
EventDeliveryFence |
struct | Claim fence for an event delivery (mirrors JobFence). |
EventDeliveryMetrics |
struct | Operator-visible delivery-queue counters for GET /api/status. |
EventDeliveryRecord |
struct | Per-subscriber delivery row. |
EventStreamPage |
struct | One page of EventStreamRead. |
EventStreamRead |
struct | One page request over the domain-event outbox (EventPublisher.read). |
EventSubscriber |
struct | Subscriber snapshot used when creating deliveries for one event. |
EventSubscriberCatalogRecord |
struct | Library-authoritative catalog row after collapsing live nodes by plugin_id. |
EventSubscriberNodeRecord |
struct | Live per-node catalog row (event_subscriber_nodes). |
EventWakeGrant |
struct | Host-derived wake grant: schema versions plus an intersected payload filter. |
GlobalQueueEntry |
struct | Aggregated global request-queue entry (one work, many wishers). |
JobClaimCursor |
struct | Where the next page of routed-claim candidates starts (keyset paging). |
JobClaimPage |
struct | One page of routed-claim candidates. |
JobFence |
struct | Lease identity a worker must present to mutate a running job. |
JobPayload |
struct | JSON command envelope stored on a job row. |
JobRecord |
struct | Durable job row returned to the daemon API and worker. |
JobTempPath |
struct | Scratch path registered against a job for crash cleanup. |
ListeningProgressRecord |
struct | Listening progress snapshot from an external player (e.g. AudioBookshelf). |
OidcClientRecord |
struct | Registered OIDC authorization-server client (Bookclerk as IdP). |
OperatorSessionRecord |
struct | Durable operator session metadata (hashed token is never exposed). |
PendingWakeProgress |
struct | How far one claimed wake tick got. |
PortalIdentity |
struct | Portal identity bound to an external provider user (e.g. ABS). |
PortalSessionRecord |
struct | Portal session row for session lists (includes hash for current-session match). |
PublishDomainEventSpec |
struct | Producer-side domain event (or queue message) to persist in the outbox. |
QueueWisher |
struct | Compact wisher shown on the global queue (avatar + label). |
SecurityAuditEvent |
struct | Security audit event (elevate / impersonate / login / provision). |
StoredPasskey |
struct | Stored WebAuthn credential (passkey JSON plus the label shown in Settings). |
TasteHolder |
struct | A storefront account that holds a work, as a TasteTitle lists it. |
TasteTitle |
struct | One work the library holds, as Discover reads it for taste and seeds. |
TitleRequestRecord |
struct | Personal wishlist row (also contributes to the shared global queue while open). |
TitleRequestSourceRecord |
struct | Per-storefront catalog/pricing snapshot attached to a wishlist row. |
UserIntegrationHint |
struct | Storefront / integration connection summary for admin user lists. |
UserInviteRecord |
struct | Invite ticket for provisioning a User (token plaintext never stored). |
UserListeningHint |
struct | Recent unfinished listening hint for admin user lists. |
UserPreferences |
struct | Per-user GUI / Discover preferences (operator or portal identity). |
UserPresenceExtras |
struct | Presence + connection extras for administrator user management. |
UserRecord |
struct | First-party Bookclerk user (security principal for portal paths). |
UserSsoPicture |
struct | IdP-supplied avatar available as a profile-picture choice. |
UserTitleState |
struct | One user's own state for one work (user_title_state). |
WishlistPurchaseHint |
struct | Snapshotted purchase link/price for a wishlist title. |
WishlistStoreEdition |
struct | Storefront edition key for wishlist / queue payloads. |
WorkRecord |
struct | Canonical work spanning one or more ownership rows / editions. |
NamedAtomicBackend |
struct | An AtomicTxnBackend that compiles every named operation and hands the plan to a NamedAtomicRunner. |
SchemaWalk |
struct | Result of walking a host migration plan from one version to another. |
SessionClientInfo |
struct | Parsed client presentation for a session row. |
FacetValue |
struct | One value of a facet value list. |
FacetValuesPage |
struct | One page of a facet value list. |
LibraryWorkRow |
struct | One row of the page index, as list views show it. |
UnheldItem |
struct | What a catalog item the library does not hold says about itself, read by WorkScope::admits_unheld. People are comma- or semicolon-separated, genres as the page index splits them. |
WorkCursor |
struct | Where the next page of a WorkSort order starts: the sort values of the last row returned. |
WorkPage |
struct | One page of library works. |
WorkPageQuery |
struct | Filters and position of one page of library works. |
WorkScope |
struct | The part of the library a patron may see, as the page index applies it. |
EditionDetail |
struct | One edition of a work with its expression and listings. |
EditionListing |
struct | One store listing of an edition. |
ListingHolding |
struct | One holding of a listing. |
WorkDetail |
struct | A top-level work with everything its detail view shows. |
WorkSearchDoc |
struct | The searchable text of one held top-level work. |
WorkTag |
struct | One library tag on a work. |
WorkTagsBody |
struct | PUT /api/library/works/{id}/tags body: the tags an Administrator sets. |
WorkTagsRequest |
struct | A validated WorkTagsBody: at most MAX_WORK_TAGS distinct tags (by facet_key), trimmed, each 1 to MAX_WORK_TAG_BYTES bytes, in the order sent with the first spelling kept. |
CatalogListing |
struct | One title a store's catalog answer reported. |
CatalogListingRecord |
struct | A stored catalog listing, as Discover and the wishlist read it. |
ListingDetail |
struct | The store's own text for a listing, beyond the title the resolver sees. |
ListingOffer |
struct | One price a store quoted for one listing and audience. |
RecordedListings |
struct | What LibraryStore::record_catalog_listings stored for one answer. |
Chapter |
struct | One chapter of a checked list. |
ChapterClaim |
struct | One stored chapter claim, without its list. |
ChapterClaimWrite |
struct | A claim to record (LibraryStore::record_chapter_claim). |
ChapterDigest |
struct | Lower-case hex SHA-256 naming one stored chapter list (ChapterList::digest). |
ChapterInput |
struct | One chapter as a source states it, before it is checked. |
ChapterList |
struct | A checked chapter list, in pre-order with starts never decreasing. |
ChapterSpan |
struct | One chapter as a player seeks between them: where it starts and ends on the edition's timeline (ChapterList::spans). |
EditionChapters |
struct | The chapters an edition resolved to. |
ChapterEditBody |
struct | PUT /api/library/editions/{id}/chapters body: the edition's chapters as an Administrator sets them, in pre-order. An empty list clears them. |
ChapterEditEntry |
struct | One chapter of an edit, as JSON carries it. |
ChapterPinBody |
struct | PUT /api/library/editions/{id}/chapters/pin body: the claim to pin. |
ChapterPinRequest |
struct | A checked pin request. |
TitleQuery |
struct | A title someone asks about (a wish, a catalog card): what the resolver needs to say which work it belongs to. |
WorkEnrichment |
struct | Enrichment fields for LibraryStore::set_work_enrichment. |
ListeningIdentifiers |
struct | The identifiers a listening item names its book by, as the provider reported them (any case and punctuation; normalised here). |
ListeningMatch |
struct | What one listening item resolved to in the library. |
ListeningProgressWrite |
struct | One stored listening row a batched write produced. |
ConflictCursor |
struct | Where a conflicts page stopped: the last row's key, in key order. |
ResolutionConflict |
struct | One conflict the resolver recorded for an Administrator. |
AccountPaceState |
struct | One account's pacing state as stored. |
DownloadId |
struct | One store download's ledger identity. |
Bookmark |
struct | A place one person marked in one edition. |
NewPlaybackSession |
struct | A play session to open (LibraryStore::open_playback_session). |
PlaybackChange |
struct | The result of a sync or of setting progress outright. |
PlaybackEdition |
struct | What the player needs to know of an edition before it plays (LibraryStore::playback_edition). |
PlaybackMs |
struct | A length of time on a recording's timeline, in milliseconds: a position, a duration or time listened. At most MAX_PLAYBACK_MS. |
PlaybackProgress |
struct | How far one person has listened to one edition. |
PlaybackProgressEdit |
struct | Progress to set outright (LibraryStore::set_playback_progress): a seek from a page with no session, Mark finished, or Start over. |
PlaybackSession |
struct | One stretch of listening on one player. |
PlaybackSync |
struct | What a player reports about a playing session (LibraryStore::sync_playback_session). |
ProgressCursor |
struct | A page position of LibraryStore::list_playback_progress: the last row of the page before. |
BookmarkEditBody |
struct | PUT /api/playback/bookmarks/{id} body: what to change. A field left out keeps its stored value. |
BookmarkEditRequest |
struct | A checked change to a bookmark. |
NewBookmarkBody |
struct | POST /api/library/editions/{id}/bookmarks body. |
NewBookmarkRequest |
struct | A checked bookmark to add. |
OpenSessionBody |
struct | POST /api/playback/sessions body. |
OpenSessionRequest |
struct | A checked request to open a play session. |
PlaybackSyncBody |
struct | POST /api/playback/sessions/{id}/sync and .../close body: where the listener is. |
ProgressEditBody |
struct | PUT /api/playback/progress/{edition_id} body: what to set. A field left out keeps its stored value. |
TrackPath |
struct | The file a stream request names (parse_track_path). |
NewPlayerCard |
struct | A new player card (LibraryStore::mint_player_card). |
PlayerCard |
struct | A live player card, as an access token resolves to it. |
PlayerCardTokens |
struct | What signing a card in or refreshing it hands out, as digests: the caller holds the tokens themselves. |
PlayerPassword |
struct | A player password as its owner sees it in Account settings. |
PlayerFacet |
struct | One value of the page index on an item: its key and how it is written. |
PlayerItem |
struct | What the player API shows of one item (LibraryStore::player_items). |
PluginDatabaseRecord |
struct | One provisioned plugin database binding registry row. |
KvEntry |
struct | One live key/value row. |
KvListPage |
struct | One page of LibraryStore::kv_list. |
KvWriteSpec |
struct | A write plus the namespace limits it must satisfy. |
PassStart |
struct | How the next pass of one account starts. |
QualityCheckState |
struct | Where the quality-upgrade check of one account stands. |
ScanState |
struct | Where one account's scan stands. |
UserStateEdit |
struct | A change to one user's state for one work, applied by LibraryStore::edit_user_title_state. |
WorkSplitBody |
struct | POST /api/library/works/{id}/split body: the expressions to move. |
WorkSplitRequest |
struct | A validated WorkSplitBody: 1 to MAX_SPLIT_EXPRESSIONS distinct expression ids, each 1 to MAX_SPLIT_EXPRESSION_ID_BYTES bytes, sorted. |
AcquireTitle |
struct | One title an account holds, as acquire reads it from the library model. |
AcquireTitlePage |
struct | One page of LibraryStore::acquire_titles_page. |
AcquiredTitleKey |
struct | One account's title of an edition acquired with a stored file, without its metadata. |
AcquiredTitleKeyPage |
struct | One page of AcquiredTitleKeys. |
AudioStream |
struct | What a probe found about the audio stream of one file, besides its FileProbe: the encoding, channels, sample rate and the running time a player sees. |
CandidateRef |
struct | One title a store returned for a subject, as written: the shared listing it is, plus why the subject got it. |
ChangedObject |
struct | One object whose row changed after a reader's last sequence. |
DestinationFeed |
struct | How one destination's outside changes are followed. |
EditionAcquisition |
struct | An edition's acquire state (edition_acquisitions). |
EditionAsin |
struct | An ASIN a catalog match found for an edition. |
EditionCopy |
struct | One edition's copy at one destination. |
EditionEnrichment |
struct | What an enricher fills on one edition; None fields are left alone. |
EditionFile |
struct | Who holds a recorded file key, and what the file is. |
EnrichCandidate |
struct | One held edition, with what an enricher needs to look it up and the fields it may fill. |
EnrichCandidatePage |
struct | One page of LibraryStore::enrich_candidates_page. |
FileProbe |
struct | What a probe found in one stored audio file, and where the copy came from (edition_files). |
HeldIdentifiers |
struct | Which of a set of store identifiers belong to titles the library holds. |
LibraryStore |
struct | Handle to the Bookclerk library database. |
LostCopies |
struct | What LibraryStore::lose_copies did with the stored copies whose file is gone. |
NewBook |
struct | One title as a library sync (or an import) reports it: the account that holds it, the store listing it describes and the store's text. |
NewListeningProgress |
struct | Input for upserting listening progress. |
NewTitleRequest |
struct | Input for creating a title request / wishlist row. |
NewTitleRequestSource |
struct | Input for upserting a per-storefront wishlist snapshot. |
ProbedAudioFile |
struct | One audio file of an edition as LibraryStore::edition_audio_files reads it back. |
QueueRank |
struct | The taste ranking of one queue entry, as the ranking job computed it. |
SavedFilterRecord |
struct | Saved Lucene-style quick filter. |
ScannedTitle |
struct | One title a storefront scan reported. |
SeenObject |
struct | One object as a listing or a change feed reports it. |
StoreCallHit |
struct | One listing a cached storefront call answered. |
StoredCandidate |
struct | One stored storefront candidate of a subject: the shared listing joined with what is personal to the subject. |
StoredDiscoverTaste |
struct | One subject's stored Discover taste. |
StoredFeed |
struct | One subject's stored, ranked Discover feed. |
StoredQueueRank |
struct | One stored queue ranking row. |
TitleHolding |
struct | The edition a library title sells and the account holding it is held by: the key its acquire writes are recorded under. |
UserBookFields |
struct | Partial update for user-defined book fields. |
WishWork |
struct | The work a wish is for, read from a store listing in the shared pool. |
NotifyCursor |
struct | Where a page of the delivery log or an inbox starts: the last row of the previous page (newest first). |
NotifyPage |
struct | One page of a newest-first listing. |
NotifyQueueLimits |
struct | Queue limits a notify_send admission uses (the daemon's [jobs]). |
DbAtomicParams |
enum | Named atomic library operation compiled by the host into a generic plan. |
CanonicalObject |
enum | One immutable canonical object (hashed before compression). |
BackupReason |
enum | Why a backup was written. |
BackupResolve |
enum | How resolve_backup_spec located a recovery point. |
CanonicalRestoreKind |
enum | How restore applies DDL companions. |
DatabaseUnitKind |
enum | Logical kind of one database unit in a recovery point. |
EntityKind |
enum | The kind of thing a LibraryError::NotFound could not find. |
LibraryError |
enum | Failures from library store, schema apply, secrets, or config. |
AcquireStatus |
enum | Acquire / download state for a title. |
EnqueueOutcome |
enum | Result of admitting a job into the durable queue. |
EventStreamStart |
enum | Where one event stream read starts. |
JobKind |
enum | Kind of durable daemon work stored in the jobs table. |
JobResourceClass |
enum | Concurrency class that bounds how many jobs of this type run at once. |
JobState |
enum | Lifecycle state of a durable job row. |
JobTrigger |
enum | Who admitted the job (API vs periodic scheduler). |
PortalSessionKind |
enum | Where a user's session token is presented. |
PublishDomainEventOutcome |
enum | Result of crate::LibraryStore::publish_domain_event. |
RequestStatus |
enum | Wishlist row status (open while wishlisted; cancelled after un-wishlist). |
UserRole |
enum | First-party user role (owner | administrator | member). |
UserStatus |
enum | First-party user status. |
SchemaState |
enum | Durable Bookclerk library schema state. |
FacetValuesOf |
enum | Whose values a facet value list reads. |
WorkFacet |
enum | A filter value list of the page index (library_work_facets). |
WorkFilter |
enum | One filter on a page of library works. |
WorkSort |
enum | How a page of library works is ordered. |
HoldingHolder |
enum | Who holds a listing. |
WorkTagSource |
enum | Where a library tag came from (work_tags.source). |
OfferAudience |
enum | Who a ListingOffer price is for. |
ChapterCheck |
enum | How strictly ChapterList::new reads its input. |
ChapterSource |
enum | Who states a chapter claim, as a writer names it. |
ChapterSourceKind |
enum | The kind of source a chapter claim came from (source_kind). |
ChaptersOutcome |
enum | What a chapter write changed. |
ClaimQuality |
enum | Where a machine source ranks within its kind (quality). |
MarkerKind |
enum | What a store says its markers are. |
ProviderQuality |
enum | How a provider found the edition, and how exact its offsets are. |
EventPruneStep |
enum | One delete of LibraryStore::prune_event_deliveries, in run order. |
PinOutcome |
enum | What LibraryStore::pin_listing did. |
DownloadStarter |
enum | Who started a download, for the ledger. |
PlaybackEvent |
enum | A host event about someone's listening, published after the write it describes (LibraryStore::publish_playback_event). |
PlayerKind |
enum | What kind of player opened a play session. |
PlayerKindParam |
enum | The kind of first-party player that opens a session. Outside player apps open theirs through the player API. |
KvPutOutcome |
enum | Why a write was refused, so the binding can map it onto a wire code. |
RecordPruneStep |
enum | One delete of LibraryStore::prune_record_step, in run order. |
FieldEdit |
enum | One field of a UserStateEdit. |
SplitOutcome |
enum | What LibraryStore::split_work did. |
CopyState |
enum | Where an edition's copy at one destination stands. |
DiscoverSubject |
enum | Whose Discover shelves a stored row belongs to. |
FeedState |
enum | The state of a destination's change feed. |
FileOwner |
enum | Who a recorded file key belongs to. |
FileRole |
enum | What a recorded file is. |
HoldingSelection |
enum | Which holdings of one account a removal takes. |
NodeHoldingSelection |
enum | Which holdings of one branch (node) a removal takes. |
SeedScope |
enum | Which seeds a subject's candidates and feed were built from. |
migrate_library_backend |
function | Copy the whole library from source into dest. |
restore_backup_unit |
function | Destructively replaces one logical database with unit. Never merges. |
library_ddl_for_schema_state |
function | Library DDL that matches state, not necessarily this binary's latest pack. |
sort_tables_by_foreign_keys |
function | FK-safe table order (parents before children). Cycles fail closed. |
verify_recovery_point |
function | Parses the manifest, rejects unsupported formats, and verifies every referenced object before the caller starts a destructive restore. |
admit_canonical_schema |
function | Parses and fully admits a diagnostic/imported canonical SQL script. |
admit_canonical_statements |
function | Admits already-separated canonical CREATE TABLE / CREATE INDEX statements. |
apply_admitted_sql |
function | Applies admitted canonical DDL plus binding companions (tests / bootstrap). |
archive_backup |
function | Packages one recovery point (manifest + referenced objects) as .tar.gz. |
backup_library |
function | Writes a crash-safe recovery point under files_dir/backups/. |
extract_backup_archive |
function | Extracts a .tar.gz recovery-point archive into dest (a backups root). |
filter_library_pack_ddl |
function | Library migration packs may include seed INSERTs. Those are table data (captured from rows), not schema objects. This keeps admitted CREATE TABLE / CREATE INDEX and skips seed DML. Any other statement fails closed. |
library_canonical_schema |
function | Admitted library schema for this binary's current pack (frozen ups + unreleased). |
library_canonical_schema_for_state |
function | Admitted library schema for state. |
list_backups |
function | Lists published recovery points oldest-first. |
plugin_canonical_schema_from_ddl_catalog |
function | Rebuilds plugin schema from durable bookclerk_sql_ddl on an open connection. |
prune_automatic_backups |
function | Deletes oldest automatic pre-migrate recovery points. Never deletes manual. |
resolve_backup_spec |
function | Resolves a recovery-point id, timestamp prefix, or archive path. |
restore_backup |
function | Restores the library unit after verifying all objects and units. |
restore_backup_in_repo |
function | Restores from an already-open repository (extracted archives). |
apply_binding_bootstrap |
function | Applies host-owned binding bootstrap when the binding is uninitialized. |
binding_bootstrap_plan |
function | Statements to apply for state, or None when the binding already matches. |
db_atomic_operation_id |
function | Caller-owned idempotency key for an atomic attempt. |
db_atomic_request_hash |
function | SHA-256 hex digest of the idempotency-relevant fields of op. |
execute_db_atomic |
function | Runs a compiled named atomic as one native SQL transaction. |
execute_named_atomic |
function | Compiles params and runs the plan as one native SQL transaction. |
apply_host_schema |
function | Applies pending host-authored DDL from the canonical migration plan. |
apply_host_schema_with_batch |
function | Applies schema using run_batch (typed executeAtomic) for each version. |
apply_host_schema_with_batch_opts |
function | Applies schema with backups using run_batch for each version. |
apply_host_schema_with_options |
function | Applies pending host schema with optional in-place backups. |
current_schema_state |
function | Reads explicit SchemaState in the Bookclerk host/bootstrap namespace. |
current_schema_state_in |
function | Reads explicit SchemaState for one ledger namespace. |
current_schema_version |
function | Frozen revision when the database is SchemaState::Frozen; otherwise 0. |
ensure_restore_target_is_replaceable |
function | Fails closed when this binary cannot interpret the target database's schema history well enough to drop every unknown table before restore. |
migrate_host_schema_to |
function | Migrates toward target, including reversible downs for CLI rollback. |
migrate_host_schema_to_with_batch |
function | Migrates toward target using run_batch (typed executeAtomic) per version. |
require_schema_migrations |
function | Requires the schemaMigrations versioning contract from typed bookclerk_plugin_abi::DbCapabilities. |
schema_state_compatible |
function | True when state is exactly the schema this binary applies: a start against it neither migrates nor fails closed. |
apply_plugin_migrations |
function | Applies the pending registered suffix. Idempotent when history already matches. |
history_from_execute_reply |
function | Parses journal rows from a typed select reply. |
load_plugin_migration_history |
function | Reads the host-private plugin migration journal. |
next_pending_plugin_migration |
function | Next registered migration after a verified durable prefix, if any. |
plugin_apply_statements |
function | One atomic apply unit: serialization slot, registered ops, host journal append. |
plugin_binding_type_env |
function | Binding catalog after host bootstrap plus schema ops from the first applied registered migrations. |
plugin_history_session_matches |
function | True when a binding session's captured history digest still matches durable history. |
plugin_journal_has_entry |
function | True when history already contains this (ordinal, id, checksum) row. |
plugin_journal_select_request |
function | Typed SELECT used by RPC hosts to read the plugin migration journal. |
prove_plugin_migration_sequence |
function | Proves a complete registration with one evolving SqlTypeEnv. |
require_history_prefix |
function | Fail closed unless durable history is an exact prefix of registered. |
sql_string_literal |
function | SQL string literal with ' doubled. |
branch_request_dedup_key |
function | Dedup key of a JobKind::BranchRequest: one active request per (branch node, work). |
catalog_subscribers_for_event |
function | Enabled catalog rows that match event type, schema version, and filter. |
collapse_live_subscriber_nodes |
function | Collapse live per-node rows into one catalog record per plugin_id. |
content_kind_from_classic |
function | Map classic EF ContentType to bookclerk content_kind. |
content_kind_to_classic |
function | Classic EF ContentType enum value. |
event_filter_matches |
function | True when filter is absent/empty or every filter key equals the payload object value. |
event_matches_wake_grants |
function | True when an event matches persisted wake grants, or legacy type+filter rows. |
intersect_event_filters |
function | Merge declared and requested payload filters; None on a same-key conflict. |
is_downloadable |
function | True when the title can be downloaded (classic WithoutParents). |
is_valid_queue_name |
function | True when name is a-z0-9* and at most MAX_QUEUE_NAME_LEN chars. |
job_backoff_run_after |
function | Next run_after after a failed attempt, exponential from a 5s base (capped). |
normalize_theme |
function | Canonical appearance preference; unknown values become system. |
plugin_scheduled_dedup_key |
function | Dedup key of a JobKind::PluginScheduled fire: one active fire per (instance, cron). |
portal_prefs_key |
function | Subject key for a portal identity (legacy; prefer user_prefs_key). |
push_queue_wisher |
function | Adds wisher when they are not already present (capped at MAX_QUEUE_WISHERS). |
queue_name_or_bus |
function | Resolves an optional queue name: empty means CORE_EVENTS_QUEUE. |
subscription_matches_event |
function | True when one catalog subscription matches event type, schema, class, and filter. |
user_prefs_key |
function | Subject key for a first-party user. |
wake_grants_from_subscriptions |
function | Build wake grants from declared subscriptions for wake_type. |
plan_schema_walk |
function | Plans ups or downs from from toward to using plan. |
plan_schema_walk_from_state |
function | Plans a frozen walk from an explicit SchemaState. |
classify_session_client |
function | Classify a User-Agent (or missing UA for API/bearer clients). |
compile_claim_event_delivery |
function | Compiles a host-side CAS claim for one pending event_deliveries row. |
compile_named_request |
function | Compiles a named atomic request into canonical Bookclerk SQL. |
interpret_typed_exec |
function | Maps a typed ExecuteReply onto a host DbAtomicResult. |
validate_execute_reply |
function | Rejects a guest ExecuteReply that does not echo the sent request or exceeds negotiated caps. |
validate_streamed_execute_reply |
function | validate_execute_reply for a reply reassembled from executeStreamed frames. |
facet_key |
function | The key a facet value or tag is stored and matched under: trimmed and lower-cased, so "Fantasy" and "fantasy " are one value. |
sort_title |
function | The sort key of a title: lower case, with one leading English article dropped, so "The Hobbit" sorts under h. |
normalize_work_tags |
function | Trims, drops empties and duplicates (by facet_key, first spelling kept) and checks the bounds. |
parse_work_tags_request |
function | Parses and validates a PUT /api/library/works/{id}/tags body from its raw bytes, sans IO, the way the route reads it: JSON into WorkTagsBody, then WorkTagsBody::validate. |
apply_user_states |
function | Applies the state of users to titles, merged per work. |
resolve_chapters |
function | Picks the claim an edition's chapters resolve to. |
parse_chapter_edit_request |
function | Parses and checks a chapter edit body from its raw bytes, sans IO, the way the route reads it. |
parse_chapter_pin_request |
function | Parses and checks a pin body from its raw bytes, sans IO. |
copy_retry_delay |
function | The delay before the next background attempt of a copy that has now failed attempts times (1 for the first failure): COPY_RETRY_BASE_DELAY doubled per earlier failure, capped at COPY_RETRY_MAX_DELAY. |
deliver_after_for |
function | RFC 3339 earliest delivery time for spec; empty when it may deliver now. |
prepare_publish_domain_event |
function | Mint an event id when empty and reject oversized or blank publish fields. |
fallback_work_key |
function | Local fallback when callers do not supply a discover work_map_key. |
inject_dispatch_page_failures |
function | Fail after the next n successful dispatch pages (tests only). |
call_number |
function | The <call number> of edition edition_id: its first 40 bits as 8 lower-case Crockford base32 characters (no i, l, o or u). An id that is not a UUID falls back to its first 8 ASCII letters and digits. Returns None when that leaves nothing. |
edition_id_for_listing |
function | The id of an edition first seen through the store listing key: a version 5 UUID over its plugin key, marketplace and product id. Two nodes (or one library rebuilt from a fresh scan) that resolve the same listing first give its edition the same id, and so the same <call number> in file names. |
holding_from_book |
function | The holding a flat library row describes. |
listing_from_book |
function | The structured listing a flat library row describes, for paths that only have a NewBook (imports, seeds, tests). |
reaches_end |
function | True when position in a recording duration long counts as having reached its end: within the last one percent, or within the last thirty seconds of a recording longer than a minute. |
parse_bookmark_edit_request |
function | Parses and validates a PUT /api/playback/bookmarks/{id} body from its raw bytes, sans IO. |
parse_new_bookmark_request |
function | Parses and validates a POST /api/library/editions/{id}/bookmarks body from its raw bytes, sans IO. |
parse_open_session_request |
function | Parses and validates a POST /api/playback/sessions body from its raw bytes, sans IO: JSON into OpenSessionBody, then OpenSessionBody::validate. |
parse_playback_sync_request |
function | Parses and validates a sync or close body from its raw bytes, sans IO, the way the routes read it: JSON into PlaybackSyncBody, then PlaybackSyncBody::validate. |
parse_progress_cursor |
function | Parses the cursor of GET /api/playback/progress, sans IO. |
parse_progress_edit_request |
function | Parses and validates a PUT /api/playback/progress/{edition_id} body from its raw bytes, sans IO. |
parse_track_path |
function | Parses the two path parts of GET /api/playback/sessions/{id}/tracks/{n}, sans IO. |
progress_cursor_token |
function | The opaque token of a progress cursor: unpadded URL-safe Base64 of the row's change time, a |, and its edition id. |
plan_pass |
function | Decides how the next pass of an account starts. |
set_dispatch_chunk_for_test |
function | Override subscribers-per-plan for dispatch paging tests. |
parse_work_split_request |
function | Parses and validates a POST /api/library/works/{id}/split body from its raw bytes, sans IO, the way the route reads it: JSON into WorkSplitBody, then WorkSplitBody::validate. |
derive_claim_password_fingerprint |
function | Stable, non-secret fingerprint of an invite/reset password for idempotency. |
derive_claim_session_token |
function | Derive the portal session token for a claim ticket plus browser nonce. |
hash_token |
function | SHA-256 hex digest of a raw ticket/session token for durable storage. |
parse_claim_redeem_nonce |
function | Accept a browser-generated claim-redeem nonce. |
apply_merged_sources |
function | Apply merged bib / editions / hints onto a wishlist row from its source snapshots. |
pick_better_description |
function | Prefer HTML blurbs over plain text; otherwise the longer string wins. |
Result |
type alias | Result alias for LibraryError. |
InProcessSqliteAtomic |
type alias | The crate::AtomicTxnBackend over a local SQLite connection. |
LEFT_BEHIND_TABLES |
constant | Tables the copy leaves behind on purpose, each with the reason. |
CHUNK_TARGET_UNCOMPRESSED_BYTES |
constant | Target uncompressed JSON size for one table-data chunk. |
BACKUPS_DIR |
constant | Subdirectory of $BOOKCLERK_FILES_DIR holding the backup repository. |
BACKUP_FORMAT_VERSION |
constant | Manifest format written by this binary. |
BACKUP_RETENTION |
constant | Automatic pre-migrate recovery points retained after prune. |
LIBRARY_SKIP_TABLES |
constant | Library registry rows are environment-local (unit_ref is not portable). |
MIGRATION_LEASE_TTL |
constant | How long a schema migration lease lasts without renewal. The migrator renews it every third of this while it works. |
MIGRATION_LEASE_WAIT |
constant | How long a starter waits for another starter's migration before it fails closed. Longer than MIGRATION_LEASE_TTL, so a migrator that died is replaced by a waiter rather than failing every waiter. |
BOOKCLERK_SCHEMA_NAMESPACE |
constant | Ledger namespace for host library schema and Bookclerk-owned binding bootstrap. |
MAX_PLUGIN_MIGRATION_APPLY_ATTEMPTS |
constant | Bounded retries for one expected plugin migration apply unit. |
CORE_EVENTS_QUEUE |
constant | Queue that carries the domain-event bus ([events] producers and consumers). |
EDITION_ACQUIRE_CHANGED |
constant | Host event type published with an edition's acquire state change other than becoming acquired (payload editionId, titleId, status). |
EVENT_DELIVERY_DEFAULT_RETENTION_SECS |
constant | How long a delivery may wait, due but never leased, before the host expires it when its consumer declares no message_retention_period: one day. A consumer that is deployed but not running stops accumulating work after this, and catches up through the event stream instead. |
EVENT_DELIVERY_MAX_ATTEMPTS |
constant | Default max delivery attempts before dead-letter. |
EVENT_RESOURCE_CLASS_NETWORK |
constant | Default delivery resource class (network). |
EVENT_SUBSCRIBER_HEARTBEAT_TTL_SECS |
constant | Live catalog rows quieter than this many seconds are ignored at dispatch. |
HOST_CONSUMER_PREFIX |
constant | Prefix of subscriber ids the daemon itself consumes under (host:discover, host:search-index:<node>). Their deliveries never expire. |
INGEST_BATCH_FINISHED |
constant | Host event type published when an ingest batch (an upload or a storage intake) reaches a final state (payload batchId, state, source, intakeInstance, detail). |
JOB_PAYLOAD_VERSION |
constant | Current job command envelope version stored in JobPayload::v. |
LISTENING_SYNCED |
constant | Host event published when a listening sync changed what Discover reads from a stored row: its owner, matched book or work, authors, or how far they got (started, quarter, finished). |
MAX_QUEUE_NAME_LEN |
constant | Longest queue name. |
MAX_QUEUE_WISHERS |
constant | Maximum distinct people serialized on a global-queue or Discover card. |
NODE_QUEUE_PREFIX |
constant | Prefix of the per-node queues (node.<node_id>) node subsystems consume. |
OPERATOR_PREFS_KEY |
constant | Subject key for the shared operator account. |
QUEUE_CONTENT_TYPE_BYTES |
constant | Queue message body is raw bytes stored as base64 text. |
QUEUE_CONTENT_TYPE_JSON |
constant | Queue message body is UTF-8 JSON text. |
QUEUE_CONTENT_TYPE_TEXT |
constant | Queue message body is plain UTF-8 text. |
WISHLIST_CHANGED |
constant | Host event published when a wishlist entry is added or changes status, or an open entry is deleted with its user. |
SCHEMA_STATE_FROZEN |
constant | On-disk bookclerk_schema_migrations.state for a frozen plan version. |
SCHEMA_STATE_UNRELEASED |
constant | On-disk bookclerk_schema_migrations.state for an unreleased development pack. |
EVENT_STREAM_SCAN_FACTOR |
constant | Rows one LibraryStore::read_event_stream call may examine per event it may return. |
EVENT_STREAM_SETTLE_SECS |
constant | Seconds an outbox row must age before LibraryStore::read_event_stream returns it. created_at is stamped before the insert commits, so a publication can commit after a newer one; a read that stops short of the last few seconds never moves its cursor past a row that has yet to appear. Newer events still reach subscribers through delivery. |
LIBRARY_INDEX_LAYOUT |
constant | Layout of library_work_rows this binary writes. A library with no finished build of this layout is rebuilt; bump it when a change to how rows are derived needs every row rewritten. |
MAX_WORK_TAGS |
constant | Most tags an Administrator may set on one work. With the delete this fits one batch of the smallest statement count a database plugin may advertise (40). |
MAX_WORK_TAG_BYTES |
constant | Longest tag, in UTF-8 bytes after trimming: the longest value the page index keeps under a facet, and the longest value a scope rule matches. |
CATALOG_LISTING_REFRESH |
constant | How long a catalog listing counts as current: a store answer for a listing seen more recently than this refreshes only its prices, not its resolution or text, so overlapping tastes cost one resolve a day. |
MAX_CHAPTERS |
constant | Most chapters one list holds, the same cap as a metadata file's (maxMetadataFileChapters in plugin.capnp). |
MAX_CHAPTER_DEPTH |
constant | Deepest nesting stored; 0 is a top-level chapter. A machine source's deeper chapter is lifted to this depth; an edit's is refused. |
MAX_CHAPTER_START_MS |
constant | Latest chapter start stored, in milliseconds: sixty days, the playback core's longest position (crate::MAX_PLAYBACK_MS). |
MAX_CHAPTER_TITLE_BYTES |
constant | Longest chapter title stored, in UTF-8 bytes. A machine source's longer title is cut at a character boundary; an edit's is refused. |
MAX_CHAPTER_EDIT_BYTES |
constant | Largest chapter edit body the route reads, in bytes: room for MAX_CHAPTERS chapters with titles at MAX_CHAPTER_TITLE_BYTES, some of them escaped. |
MAX_CHAPTER_PIN_BYTES |
constant | Largest pin body the route reads, in bytes. |
MAX_CHAPTER_SOURCE_ID_BYTES |
constant | Longest source_id a pin names, in bytes; a PluginKey is far shorter. |
MAX_CONFLICT_PAGE |
constant | Largest conflicts page LibraryStore::list_resolution_conflicts reads. |
MAX_BOOKMARKS_PER_EDITION |
constant | Most bookmarks one person keeps in one edition. |
MAX_BOOKMARK_TITLE_BYTES |
constant | Longest bookmark title, in bytes (well inside the minimum database profile's cell size). |
MAX_PLAYBACK_MS |
constant | The longest position or duration the player stores: sixty days, far past any recording, and small enough that sums of two stay exact in every database profile's integer. |
MAX_PLAYER_NAME_BYTES |
constant | Longest player name a session stores, in bytes. |
MAX_EDITION_ID_BYTES |
constant | Longest edition id a session is opened for, in bytes; a real one is a 36-byte UUID. |
MAX_PLAYBACK_BODY_BYTES |
constant | Largest body the other playback parsers read, in bytes: room for an escaped bookmark title or a long player name. |
MAX_PLAYBACK_SYNC_BYTES |
constant | Largest sync body the routes read, in bytes; a real one is under 100. |
MAX_PLAYBACK_TRACKS |
constant | Most tracks a play session lists: a stream path's index is below it. |
MAX_PROGRESS_CURSOR_BYTES |
constant | Longest progress cursor token the route reads, in bytes; a real one is about 100. |
MAX_PLAYER_PASSWORDS |
constant | Most player passwords one patron keeps. |
MAX_PLAYER_PASSWORD_LABEL_BYTES |
constant | Longest player password label, in bytes. |
PLAYER_ACCESS_TTL_SECS |
constant | Lifetime of a player card's access token. |
PLAYER_REFRESH_GRACE_SECS |
constant | How long the other refresh tokens of a card keep working after one of them is used: long enough for two refreshes that raced with the same token to both succeed, and for a phone whose refresh answer was lost while it slept to try again (the apps expect ten minutes). |
PLAYER_REFRESH_TTL_DAYS |
constant | Lifetime of a player card's refresh token; each refresh starts it again. |
KV_LIST_DEFAULT_LIMIT |
constant | Default page size for LibraryStore::kv_list when the caller passes 0. |
AUDIT_RETENTION_DAYS |
constant | Days security_audit_events and configuration_audit rows are kept. |
CONFIGURATION_CHANGE_RETENTION_DAYS |
constant | Days configuration_changes notices are kept. They only signal that a document changed; the document and its audit row hold the content. |
STORAGE_SCAN_STALE_DAYS |
constant | Days without a heartbeat after which a jobless storage-scan generation (a CLI scan) is treated as abandoned. |
TOKEN_HISTORY_DAYS |
constant | Days an expired claim ticket, user invite, or node enrollment link stays listed (as expired or redeemed) before it is deleted. |
UPLOAD_HISTORY_DAYS |
constant | Days a committed or aborted host upload is kept past its token's expiry. |
FULL_PASS_INTERVAL |
constant | Longest time since the last complete pass before the host asks for a full pass again, so a store whose deltas miss edits or removals is corrected. |
RESUME_CURSOR_TTL |
constant | Longest time a stopped pass's cursor is resumed; an older one restarts the pass (store cursors expire). |
MAX_SPLIT_EXPRESSIONS |
constant | Most expressions one split moves: the batch's widest statement binds each id twice, and the minimum database profile allows 32 binds. |
MAX_SPLIT_EXPRESSION_ID_BYTES |
constant | Longest expression id a split body may name, in bytes; ids are UUIDs. |
ACQUIRED_KEYS_MAX_PAGE |
constant | Upper clamp for the editions one LibraryStore::acquired_title_keys_page read covers. |
ACQUIRE_WRITER |
constant | The writer of a key an acquire run on this node wrote. |
COPY_RETRY_BASE_DELAY |
constant | Delay before the first background retry of a failed copy; each later failure doubles it, up to COPY_RETRY_MAX_DELAY. |
COPY_RETRY_MAX_DELAY |
constant | The longest delay between two background retries of one copy. |
HOLDING_REMOVED |
constant | Event type published when a holding is removed. |
MAX_COPY_ATTEMPTS |
constant | Failed attempts after which a pending copy turns CopyState::Failed and is no longer retried in the background. |
MAX_QUEUE_REASONS |
constant | Most taste reasons one stored row keeps, so a row stays small whatever the ranking explains. |
OBJECT_TOMBSTONE_DAYS |
constant | Days a removed object's tombstone is kept for readers that page changes. |
MAX_NOTIFY_PAGE |
constant | Most rows one page of the delivery log or the inbox returns. |
CLAIM_REDEEM_NONCE_HEX_LEN |
constant | Hex length of a browser-generated claim-redeem nonce (32 bytes). |
bookclerk_keystore::CREDENTIAL_NAMEasSYSTEMD_CREDENTIAL_NAMEbookclerk_plugin_abi::AdapterBackupOpsbookclerk_plugin_abi::GuestSqlPolicybookclerk_plugin_abi::SharedAdapterBackupOpsbookclerk_resolve::Abridgementbookclerk_resolve::Entitlementbookclerk_resolve::ExpressionKindbookclerk_resolve::MediaKindbookclerk_resolve::WorkKindbookclerk_storefront::text::decode_html_entitiesbookclerk_storefront::text::decode_html_entities_cowbookclerk_storefront::text::decode_html_entities_in_placebookclerk_storefront::text::decode_html_entities_optbookclerk_storefront::text::decode_html_entities_opt_in_placebookclerk_storefront::text::str_maybe_html_entityemail::gravatar_hashmaster_key::configure_master_keymaster_key::configure_master_key_withmaster_key::discard_minted_master_keymaster_key::encode_master_key_filemaster_key::export_master_keymaster_key::import_master_keymaster_key::inspect_master_keymaster_key::install_master_keymaster_key::key_store_preferencemaster_key::master_key_envelopemaster_key::master_key_fingerprintmaster_key::master_key_is_wrappedmaster_key::master_key_pathmaster_key::move_master_keymaster_key::prepare_master_key_dirmaster_key::require_master_keymaster_key::resolve_master_key_detailedmaster_key::set_key_store_preferencemaster_key::set_keychain_vaultmaster_key::set_systemd_creds_vaultmaster_key::store_master_keymaster_key::uncache_master_keymaster_key::warn_unwrapped_master_keymaster_key::wrap_master_keymaster_key::KeyStorePreferencemaster_key::MasterKeymaster_key::MasterKeyFormatmaster_key::MasterKeyResolutionmaster_key::StoredMasterKeymaster_key::SystemdCredsFactorymaster_key::AUTH_PASSWORD_ENVasMASTER_KEY_AUTH_PASSWORD_ENVmaster_key_recovery::record_recovery_copymaster_key_recovery::recovery_copy_statemaster_key_recovery::recovery_record_pathmaster_key_recovery::RecoveryCopyChoicemaster_key_recovery::RecoveryCopyStatemigrations::binding_bootstrap_type_envmigrations::host_migration_planmigrations::min_supported_schema_versionmigrations::LIBRARY_LEASES_DDLmigrations::SCHEMA_MIGRATIONS_DDLmigrations::SCHEMA_VERSIONmodels::is_episodemodels::is_podcast_parentoperator_token::read_or_create_operator_tokenoperator_token::resolve_operator_tokenoperator_token::rotate_operator_tokenoperator_token::ResolveOperatorTokenpassword::hash_passwordpassword::verify_passwordproxy_txn::consume_begin_injectionproxy_txn::consume_commit_injectionproxy_txn::current_exec_budgetproxy_txn::inject_atomic_interruptproxy_txn::inject_atomic_interrupt_afterproxy_txn::inject_begin_failuresproxy_txn::inject_commit_failuresproxy_txn::inject_savepoint_release_failuresproxy_txn::inject_savepoint_rollback_failuresproxy_txn::is_txn_brokenproxy_txn::note_begin_failedproxy_txn::note_commit_failedproxy_txn::query_rows_seenproxy_txn::take_txn_faultproxy_txn::txn_broken_errproxy_txn::AtomicInterruptKindproxy_txn::AtomicInterruptPhaseproxy_txn::ExecBudgetscope::RefreshKeepingscope::SourceScopesecrets::b64_string_to_bytessecrets::build_sealed_recordsecrets::bytes_to_b64_stringsecrets::delete_secretsecrets::delete_secrets_for_accountsecrets::get_secretsecrets::list_secretssecrets::unseal_secretsecrets::upsert_secretsecrets::EncryptedSecretRecordsecrets::SecretStoresecrets::FORMAT_SEALED_V1sql_plan::authorize_typed_requestsql_plan::execute_guest_atomic_withsql_plan::proxy_insert_returning_identitysql_plan::proxy_read_kindsql_plan::proxy_write_kindsql_plan::unquote_sea_identifierssql_plan::validate_plansql_plan::wake_page_for_max_bindssql_plan::AtomicSessionsql_plan::CompiledAtomic
column_read: Column reads that stay correct on the host's proxied store connection.control_plane: Database-backed control plane: node identity and typed configuration.email: Contact-email normalization and library-backed validation.entities: SeaORM entities mirroring the greenfield schema incrate::migrations.library_link: Named-atomic parameters for writing a resolved listing.master_key: Data-encryption key (DEK) forencrypted_secrets.master_key_recovery: What an install's operator did about a recovery copy of its key.migrations: Host library schema: frozen plan steps plus the unreleased development pack.notifications: Notifications: the router's rules and the shapes the library stores (docs/adr/notifications.md,docs/server/notifications.md).operator_token: Durable operator API token inencrypted_secrets.pacing: Download pacing per store account: the limits, the operator's override, and the decision whether a download may start now.password: Argon2id password hashing for first-party local login.proxy_txn: Fail-closed transaction injects re-exported frombookclerk_db_exec.quality: When a store's offer is a better file than the one the library holds.scope: Plugin-scoped library access.secrets: Encrypted secrets store — DB-backed credential storage.sql_plan: Host-owned generic SQL atomic plans for database adapters. Host-owned SQL atomic plans for database plugins.test_support: A library store that behaves like one opened on an external database plugin, for tests.atomic_status: Application status strings produced by host plan interpretation.secret_account_type: Ownership namespace forencrypted_secrets.account_type.secret_kind: Well-knownkindvalues for theencrypted_secretstable.
pub trait AtomicTxnBackend: Send + Sync {
fn delete_user<'life0, 'async_trait>(
&'life0 self,
id: i64,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
fn set_user_status<'life0, 'async_trait>(
&'life0 self,
id: i64,
status: UserStatus,
) -> Pin<Box<dyn Future<Output = Result<UserRecord>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
fn set_user_password_hash<'life0, 'life1, 'async_trait>(
&'life0 self,
id: i64,
password_hash: Option<&'life1 str>,
) -> Pin<Box<dyn Future<Output = Result<UserRecord>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn set_user_role<'life0, 'async_trait>(
&'life0 self,
id: i64,
role: UserRole,
) -> Pin<Box<dyn Future<Output = Result<UserRecord>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
fn redeem_claim_ticket_to_session<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>(
&'life0 self,
token_hash: &'life1 str,
session_hash: &'life2 str,
expires_at: DateTime<Utc>,
client: Option<&'life3 SessionClientInfo>,
new_password_hash: Option<&'life4 str>,
password_fingerprint: Option<&'life5 str>,
) -> Pin<Box<dyn Future<Output = Result<PortalIdentity>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
'life5: 'async_trait,;
fn take_oidc_rp_state<'life0, 'life1, 'async_trait>(
&'life0 self,
state_hash: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<(String, String, String, String, Option<i64>)>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn take_webauthn_challenge<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
challenge_id: &'life1 str,
kind: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<Option<(Option<i64>, String)>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,;
fn enqueue_job<'life0, 'async_trait>(
&'life0 self,
spec: EnqueueJobSpec,
) -> Pin<Box<dyn Future<Output = Result<EnqueueOutcome>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
fn claim_next_job<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
resource_class: JobResourceClass,
owner: &'life1 str,
lease_secs: u64,
operation_id: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<Option<JobRecord>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,;
fn reserve_job_temp_path<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
job_id: &'life1 str,
path: &'life2 str,
reserved_bytes: u64,
quota_bytes: u64,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,;
fn confirm_totp_enrollment<'life0, 'life1, 'async_trait>(
&'life0 self,
user_id: i64,
record: &'life1 EncryptedSecretRecord,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn disable_user_totp<'life0, 'async_trait>(
&'life0 self,
user_id: i64,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
fn publish_domain_event<'life0, 'async_trait>(
&'life0 self,
spec: PublishDomainEventSpec,
) -> Pin<Box<dyn Future<Output = Result<PublishDomainEventOutcome>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
fn set_acquire_status<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
holding: &'life1 TitleHolding,
status: AcquireStatus,
storage_key: Option<&'life2 str>,
error_message: Option<&'life3 str>,
event: PublishDomainEventSpec,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,;
fn dispatch_event_deliveries<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
event_id: &'life1 str,
subscribers: &'life2 [EventSubscriber],
operation_id: &'life3 str,
mark_dispatched: bool,
) -> Pin<Box<dyn Future<Output = Result<u32>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,;
fn link_listing<'life0, 'async_trait>(
&'life0 self,
params: ListingLinkParams,
) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
fn write_credits<'life0, 'async_trait>(
&'life0 self,
params: CreditBatchParams,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
fn claim_event_delivery<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>(
&'life0 self,
delivery_id: &'life1 str,
owner: &'life2 str,
lease_secs: u64,
operation_id: &'life3 str,
plugin_id: &'life4 str,
resource_class: &'life5 str,
max_in_flight: u32,
) -> Pin<Box<dyn Future<Output = Result<Option<EventDeliveryRecord>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
'life5: 'async_trait,;
}
Backend that runs crate::LibraryStore named security operations as a
single guest atomic batch.
Implementations must preserve the same fail-closed semantics as the SeaORM
path: last-owner refusals mutate nothing; a failed claim redeem must not
consume the ticket or write a password/session; consume-once OIDC/WebAuthn
rows must not be observable by a concurrent caller; TOTP enroll/disable must
keep encrypted_secrets and users.totp_enabled in the same transaction.
fn delete_user<'life0, 'async_trait>(
&'life0 self,
id: i64,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Delete a first-party user and personal data (last-owner guarded).
fn set_user_status<'life0, 'async_trait>(
&'life0 self,
id: i64,
status: UserStatus,
) -> Pin<Box<dyn Future<Output = Result<UserRecord>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Set user status (active / disabled; last-owner guarded).
fn set_user_password_hash<'life0, 'life1, 'async_trait>(
&'life0 self,
id: i64,
password_hash: Option<&'life1 str>,
) -> Pin<Box<dyn Future<Output = Result<UserRecord>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Set or clear the Argon2id password hash and bump security_version.
fn set_user_role<'life0, 'async_trait>(
&'life0 self,
id: i64,
role: UserRole,
) -> Pin<Box<dyn Future<Output = Result<UserRecord>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Set user role (last-owner guarded on demotion).
fn redeem_claim_ticket_to_session<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>(
&'life0 self,
token_hash: &'life1 str,
session_hash: &'life2 str,
expires_at: DateTime<Utc>,
client: Option<&'life3 SessionClientInfo>,
new_password_hash: Option<&'life4 str>,
password_fingerprint: Option<&'life5 str>,
) -> Pin<Box<dyn Future<Output = Result<PortalIdentity>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
'life5: 'async_trait,
Consume a claim ticket, optionally set a first password, mint a session.
fn take_oidc_rp_state<'life0, 'life1, 'async_trait>(
&'life0 self,
state_hash: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<(String, String, String, String, Option<i64>)>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Consume a one-time OIDC RP state. Ok(None) if missing or expired.
Tuple is (provider_id, pkce_verifier, nonce, purpose, user_id).
fn take_webauthn_challenge<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
challenge_id: &'life1 str,
kind: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<Option<(Option<i64>, String)>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Consume a one-time WebAuthn challenge. Ok(None) if missing or expired.
Tuple is (user_id, state_json).
fn enqueue_job<'life0, 'async_trait>(
&'life0 self,
spec: EnqueueJobSpec,
) -> Pin<Box<dyn Future<Output = Result<EnqueueOutcome>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Admit a durable job in one atomic transaction.
fn claim_next_job<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
resource_class: JobResourceClass,
owner: &'life1 str,
lease_secs: u64,
operation_id: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<Option<JobRecord>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Claim the next ready job; operation_id makes a lost response replay-safe.
fn reserve_job_temp_path<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
job_id: &'life1 str,
path: &'life2 str,
reserved_bytes: u64,
quota_bytes: u64,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Reserve scratch-quota bytes for path on job_id.
fn confirm_totp_enrollment<'life0, 'life1, 'async_trait>(
&'life0 self,
user_id: i64,
record: &'life1 EncryptedSecretRecord,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Promote a sealed TOTP secret to primary and set totp_enabled.
fn disable_user_totp<'life0, 'async_trait>(
&'life0 self,
user_id: i64,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Delete TOTP secrets and clear totp_enabled.
fn publish_domain_event<'life0, 'async_trait>(
&'life0 self,
spec: PublishDomainEventSpec,
) -> Pin<Box<dyn Future<Output = Result<PublishDomainEventOutcome>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Persist a domain event in the outbox.
fn set_acquire_status<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
holding: &'life1 TitleHolding,
status: AcquireStatus,
storage_key: Option<&'life2 str>,
error_message: Option<&'life3 str>,
event: PublishDomainEventSpec,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
Write an edition's acquire state for the account holding that made the write, and publish its event, in one batch.
Only the holding that acquired an edition, while it exists, changes it.
Returns crate::LibraryError::NotFound when the holding no longer
holds the edition, or the database error.
fn dispatch_event_deliveries<'life0, 'life1, 'life2, 'life3, 'async_trait>(
&'life0 self,
event_id: &'life1 str,
subscribers: &'life2 [EventSubscriber],
operation_id: &'life3 str,
mark_dispatched: bool,
) -> Pin<Box<dyn Future<Output = Result<u32>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
Create deliveries for subscribers. mark_dispatched finishes the parent event.
fn link_listing<'life0, 'async_trait>(
&'life0 self,
params: ListingLinkParams,
) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Write one resolved listing as one guarded batch.
Returns the batch status: ok, or retry when another writer
changed the rows the plan was resolved against.
fn write_credits<'life0, 'async_trait>(
&'life0 self,
params: CreditBatchParams,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Write one batch of contributors, credits, series and series entries.
fn claim_event_delivery<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>(
&'life0 self,
delivery_id: &'life1 str,
owner: &'life2 str,
lease_secs: u64,
operation_id: &'life3 str,
plugin_id: &'life4 str,
resource_class: &'life5 str,
max_in_flight: u32,
) -> Pin<Box<dyn Future<Output = Result<Option<EventDeliveryRecord>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
'life5: 'async_trait,
CAS-claim one pending delivery after the host has filtered eligibility.
Implemented by: NamedAtomicBackend<R>
pub trait TypedAtomicExec: Send + Sync {
fn execute_typed<'life0, 'async_trait>(
&'life0 self,
envelope: AdapterExecuteRequest,
) -> Pin<Box<dyn Future<Output = Result<ExecuteReply, PluginError>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
}
Runs a host-authorized typed bookclerk_plugin_abi::ExecuteRequest as one guest executeAtomic.
First-party hosts attach this alongside AtomicTxnBackend so granted job
sessions do not round-trip through the SeaORM proxy (BEGIN + nested
query/execute). In-process tests leave it unset and run the same
request on the local connection.
fn execute_typed<'life0, 'async_trait>(
&'life0 self,
envelope: AdapterExecuteRequest,
) -> Pin<Box<dyn Future<Output = Result<ExecuteReply, PluginError>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Executes req as one typed atomic batch.
Returns a plugin ABI error when validation, transport, or the engine rejects the batch.
Implemented by: ProfileExec
pub trait NamedAtomicRunner: Send + Sync {
fn run_compiled<'life0, 'async_trait>(
&'life0 self,
compiled: CompiledAtomic,
operation_id: String,
) -> Pin<Box<dyn Future<Output = Result<DbAtomicResult>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
}
Runs one compiled named plan as a single atomic batch.
A runner is the transport under a [NamedAtomicBackend]: it receives the
plan the backend compiled and answers with the interpreted result. It
must apply the whole plan or none of it, and must return application
outcomes (notFound, lastOwner, empty, …) as the result's status,
not as errors.
fn run_compiled<'life0, 'async_trait>(
&'life0 self,
compiled: CompiledAtomic,
operation_id: String,
) -> Pin<Box<dyn Future<Output = Result<DbAtomicResult>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Runs compiled under operation_id, the idempotency key a retry
after a lost reply resumes.
Returns LibraryError::LimitExceeded when the plan or its result
exceeds a negotiated cap, LibraryError::Unavailable when the reply
was lost and the batch may have been applied, and another
LibraryError when the engine refused the batch.
Implemented by: InProcessSqlite, ProfileAtomic
pub struct DbAtomicResult {
pub status: String,
pub payload: Option<Value>,
pub operation_id: String,
pub replayed: bool,
pub receipt_created_at: Option<String>,
pub timing: Option<DbTiming>,
}
Host-interpreted result of a named atomic operation.
Fields
status: Application outcome (ok,empty,notFound,lastOwner, …).payload: Op-specific record whenstatusisok, or the existing record aduplicatefolded into (enqueueJob,publishDomainEvent).operation_id: Echo of the requestoperationId.replayed: True when this result was loaded from a durable receipt.receipt_created_at: RFC 3339 timestamp when the receipt was first written.timing: Handler/engine timing. Not hashed for idempotency.
pub fn ok(payload: JsonValue) -> Self
Successful operation with a JSON payload.
pub fn ok_unit() -> Self
Successful operation with no payload (deleteUser).
pub fn with_status(status: &str) -> Self
Application failure or empty consume-once result (no payload).
Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize
pub struct BackendMigrateOptions {
pub dry_run: bool,
pub force: bool,
}
Options for a backend-to-backend library copy.
Fields
dry_run: When true, report counts only — do not write to the destination.force: Allow copying into a destination that already has library rows.
Implements: Clone, Debug
pub struct BackendMigrateSummary {
pub tables: BTreeMap<String, usize>,
pub dry_run: bool,
}
Per-table row counts copied (or that would be copied in dry-run mode).
Fields
tables: Map of table name → rows copied (or counted in dry-run).plugin_artifactscounts archives; their chunks are not counted.dry_run: When true, counts rows without writing to the destination.
pub fn total_rows(&self) -> usize
Sums row counts across all tables in the summary, leaving out
plugin_artifacts, which counts archives rather than rows.
Implements: Clone, Debug, Default, Serialize
pub struct BackupRepository {
/* private fields */
}
On-disk backup repository rooted at files_dir/backups.
pub fn open(files_dir: &Path) -> Result<Self>
Opens (creating) the repository under files_dir/backups.
Returns when the backups directory cannot be created.
pub fn open_root(root: &Path) -> Result<Self>
Opens root as a backups repository (manifests/ + objects/).
Returns when the directories cannot be created.
pub fn root(&self) -> &Path
Repository root (…/backups).
pub fn lock_exclusive(&self) -> Result<RepoLockGuard<'_>>
Exclusive lock covering object publication and GC/prune.
Same-thread reentry is allowed so Self::put_object can nest under a
backup that already holds the lock. Other threads wait. Other processes
block on backups/.lock.
Returns when the lock file cannot be created or flocked.
pub fn put_object(&self, object: &CanonicalObject) -> Result<String>
Writes object if missing. Returns the uncompressed SHA-256 hex.
The write uses a unique same-directory temp file, fsyncs it, then installs with a no-clobber hard link. An existing object is reused only after its bytes verify; a truncated or corrupt file is replaced.
Returns when encoding, compression, or the filesystem write fails.
pub fn get_object(&self, digest: &str) -> Result<CanonicalObject>
Loads and verifies one object by uncompressed digest.
Returns when the object is missing, corrupt, or the digest mismatches.
pub fn object_exists(&self, digest: &str) -> bool
True when an object file exists (does not imply the bytes are valid).
pub fn publish_manifest(&self, manifest: &BackupManifest) -> Result<PathBuf>
Publishes manifest only after all referenced objects exist and
verify.
Writes JSON then a sibling .sha256 of the exact file bytes. Incomplete
staging uses manifests/.staging-<id>.json and is ignored by list/GC.
Returns when a referenced object is missing or corrupt, or the filesystem write fails.
pub fn read_manifest(&self, id: &str) -> Result<BackupManifest>
Reads and integrity-checks a published manifest.
Returns when the file is missing, JSON is malformed, the sidecar hash mismatches, or the embedded id does not match the filename.
pub fn list_manifests(&self) -> Vec<BackupManifest>
Lists published recovery-point manifests oldest-first. Staging files and unreadable manifests are skipped.
pub fn list_manifests_strict(&self) -> Result<Vec<BackupManifest>>
Lists every published recovery-point manifest, failing if any cannot be verified. Staging files (dot-prefixed) are ignored.
Use this for prune/GC. Self::list_manifests stays best-effort for
non-destructive listing.
Returns when the manifests directory cannot be read, a published
*.json fails Self::read_manifest, or an unexpected non-sidecar
file is present.
pub fn delete_manifest(&self, id: &str) -> Result<bool>
Deletes one published manifest (not its objects). Returns whether a file was removed.
Returns when the id is unsafe or unlink fails for a reason other than not found.
pub fn gc_unreferenced_objects(&self) -> Result<usize>
Deletes objects not referenced by any retained published manifest.
Reachability is computed from a strict enumeration of published manifests. An unreadable retained manifest fails closed instead of treating its objects as garbage.
Returns when a published manifest cannot be verified, a directory cannot be read, or an unreferenced object cannot be unlinked.
Implements: Clone, Debug
pub struct BackupListEntry {
pub manifest: BackupManifest,
}
Catalog entry used by bookclerk db backup list.
Fields
manifest: Parsed manifest.
Implements: Clone, Debug
pub struct BackupManifest {
pub format_version: u32,
pub id: String,
pub created_at: String,
pub schema_state: String,
pub schema_checksum: Option<String>,
pub frozen_version: Option<i64>,
pub sql_contract_version: u32,
pub app_version: String,
pub reason: BackupReason,
pub migrate_to: i64,
pub include_plugin_databases: bool,
pub units: Vec<BackupUnit>,
}
On-disk recovery-point metadata (manifests/<id>.json).
Fields
format_version: Catalog format (1for content-addressed canonical objects).id: Stable recovery-point id (UUID).created_at: RFC 3339 UTC timestamp.schema_state:SchemaState::displayat capture.schema_checksum: SHA-256 recorded on the library schema state marker.frozen_version: Frozen revision when the source library was frozen.sql_contract_version: Bookclerk SQL contract of the library unit.app_version: Bookclerk version that wrote the backup.reason: Operator vs automatic.migrate_to: Target frozen version a following migrate step was heading toward.include_plugin_databases: When true, every registered plugin binding was required at capture.units: Logical database units (library first).
pub fn referenced_objects(&self) -> BTreeSet<String>
Union of every object digest referenced by this recovery point.
pub fn library_unit(&self) -> Result<&BackupUnit>
Library unit from this manifest.
Returns when the library unit is missing or duplicated.
pub fn plugin_units(&self) -> Vec<&BackupUnit>
Plugin binding units.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct BackupOutcome {
pub dir: PathBuf,
pub manifest: BackupManifest,
}
Result of publishing a recovery point.
Fields
dir: Repository root (files_dir/backups).manifest: Parsed manifest.
Implements: Clone, Debug
pub struct BackupRequest {
pub files_dir: PathBuf,
pub schema_state: SchemaState,
pub reason: BackupReason,
pub to_version: i64,
pub include_plugin_databases: bool,
pub consistent_backup_read: bool,
pub backend_at_capture: String,
pub max_result_rows: u32,
pub max_result_bytes: u32,
pub max_atomic_result_bytes: u32,
pub plugin_units: Vec<PreparedPluginUnit>,
pub adapter: Option<SharedAdapterBackupOps>,
pub in_process: bool,
}
Inputs for an automatic or CLI backup.
Fields
files_dir:$BOOKCLERK_FILES_DIR.schema_state: Durable library schema state at capture.SchemaState::Uninitializedskips.reason: Operator vs pre-migrate.to_version: Version the upcoming migrate step will target (0for manual).include_plugin_databases: Include every registered plugin-owned database binding.consistent_backup_read: Guest advertised consistent backup read.backend_at_capture: Adapter id at capture (diagnostic; not used to branch restore).max_result_rows: NegotiatedmaxResultRows(clamped).max_result_bytes: NegotiatedmaxResultBytesfor one SELECT page.max_atomic_result_bytes: NegotiatedmaxAtomicResultBytes(capture page budget is the min of both).plugin_units: Plugin sessions prepared by the host (must match the registry when inclusion is on).adapter: Library adapter hooks.Noneuses the in-process SDK (tests).in_process: True when leftover SQL is physically lowered on the opened connection.
Implements: Clone, Debug
pub struct BackupUnit {
pub kind: DatabaseUnitKind,
pub plugin_id: Option<String>,
pub binding: Option<String>,
pub backend_at_capture: String,
pub sql_contract_version: u32,
pub schema_object: String,
pub identity_object: String,
pub tables: Vec<BackupTable>,
pub plugin_schema_namespace: Option<String>,
pub plugin_schema_state: Option<String>,
pub plugin_schema_checksum: Option<String>,
}
One logical database in a recovery point (library or plugin binding).
Fields
kind: Library vs plugin binding.plugin_id: Plugin id whenDatabaseUnitKind::PluginBinding.binding: Binding name whenDatabaseUnitKind::PluginBinding.backend_at_capture: Adapter that captured this unit (diagnostic only; restore is cross-adapter).sql_contract_version: Bookclerk SQL grammar/ABI contract, not a library schema revision.schema_object: SHA-256 of the schema object.identity_object: SHA-256 of the identity object.tables: User-visible tables (not catalog/identity companions).plugin_schema_namespace: Plugin id whenDatabaseUnitKind::PluginBinding(owner identity).plugin_schema_state:crate::PluginMigrationHistory::displayat capture (history@{n}+{digest}).plugin_schema_checksum: Digest of the complete ordered(migration_id, checksum)journal.
pub fn restore_kind(&self) -> CanonicalRestoreKind
Restore companion kind for this unit.
pub fn referenced_objects(&self) -> BTreeSet<String>
Object digests this unit needs to restore.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct CanonicalDatabaseSchema {
pub sql_contract_version: u32,
pub tables: Vec<CanonicalTableSchema>,
pub indexes: Vec<CreateIndexSchema>,
}
Admitted canonical schema used to export or restore one database unit.
Fields
sql_contract_version: Bookclerk SQL grammar/ABI contract, not a library schema revision.tables:CREATE TABLEstatements in FK-safe order aftercrate::sort_tables_by_foreign_keys.indexes:CREATE INDEXstatements (after tables).
pub fn schema_sql(&self) -> Vec<String>
Ordered canonical DDL (tables then indexes).
pub fn table_names(&self) -> Vec<String>
Folded user table names in CREATE order.
Implements: Clone, Debug, Eq, PartialEq
pub struct CanonicalExportOpts {
pub consistent_backup_read: bool,
pub skip_tables: BTreeSet<String>,
pub max_result_rows: u32,
pub max_result_bytes: u32,
pub max_atomic_result_bytes: u32,
pub chunk_target_bytes: usize,
pub adapter: Option<SharedAdapterBackupOps>,
pub in_process: bool,
}
Options for a consistent canonical export.
Fields
consistent_backup_read: Guest advertisedDbCapabilities::supports_consistent_backup_read.skip_tables: Folded table names omitted from row capture (libraryplugin_databases).max_result_rows: Page size forSELECT … LIMIT(honors adaptermaxResultRows).max_result_bytes: Encoded-byte budget for one SELECT page (maxResultBytes).max_atomic_result_bytes: Encoded-byte budget for one atomic reply (maxAtomicResultBytes).chunk_target_bytes: Uncompressed JSON target for one table-data chunk.adapter: Adapter snapshot/identity hooks.Noneuses the in-process SDK (tests).in_process: True when leftover SQL is physically lowered on the opened connection.
pub fn from_caps(caps: &DbCapabilities) -> Self
Page-size and result-byte limits from negotiated adapter capabilities.
pub fn page_byte_budget(&self) -> usize
Effective encoded-byte budget for one capture SELECT page.
Implements: Clone, Debug, Default
pub struct CanonicalRestoreOpts {
pub atomic_unit_restore: bool,
pub max_binds: u32,
pub max_payload_bytes: u32,
pub max_request_bytes: u32,
pub adapter: Option<SharedAdapterBackupOps>,
pub in_process: bool,
}
Negotiated limits for parameterized canonical restore.
Fields
atomic_unit_restore: Guest advertisedatomicUnitRestore.max_binds: Maximum bound parameters per INSERT (maxBinds).max_payload_bytes: Maximum UTF-8 bytes of SQL plus binds per statement (maxPayloadBytes).max_request_bytes: Maximum encoded bytes of onebookclerk_plugin_abi::ExecuteRequest.adapter: Adapter restore hooks.Noneuses the in-process SDK (tests).in_process: True when leftover SQL is physically lowered on the opened connection.
pub fn from_caps(caps: &DbCapabilities) -> Result<Self>
Restore limits copied from negotiated adapter capabilities.
The versioning contract is checked with require_schema_migrations,
never inferred from SeaORM sea_orm::DbBackend. Host policy requires
schemaMigrations.
Returns when caps is not a known versioning contract (schemaMigrations
missing).
Implements: Clone, Debug, Default
pub struct CanonicalTableSchema {
pub create_sql: String,
pub parsed: CreateTableSchema,
}
One admitted CREATE TABLE plus its parsed IR.
Fields
create_sql: Original canonical SQL (no trailing semicolon).parsed: Parsed columns, constraints, and identity.
Implements: Clone, Debug, Eq, PartialEq
pub struct IdentityHighWater {
pub column: String,
pub last: i64,
}
Identity high-water for one generated column.
Fields
column: Identity column name.last: Highest generated or stored value that must not be reused.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PreparedPluginUnit {
pub plugin_id: String,
pub binding: String,
pub backend_at_capture: String,
pub db: DatabaseConnection,
pub max_result_rows: u32,
pub max_result_bytes: u32,
pub max_atomic_result_bytes: u32,
pub adapter: Option<SharedAdapterBackupOps>,
}
Open plugin binding captured through the active adapter session.
Fields
plugin_id: Owning plugin id.binding: Binding name.backend_at_capture: Adapter that produced this unit (diagnostic).db: SeaORM connection opened via the active adapter (not a native dump).max_result_rows: NegotiatedmaxResultRowsfor this binding session.max_result_bytes: NegotiatedmaxResultBytesfor this binding session.max_atomic_result_bytes: NegotiatedmaxAtomicResultBytesfor this binding session.adapter: Binding-scoped adapter hooks.Noneuses the in-process SDK (tests).
Implements: Clone, Debug
pub struct RestorePlan {
pub manifest: BackupManifest,
pub plugin_units: Vec<BackupUnit>,
}
Library restore result plus plugin units for the host to apply.
Plugin databases are restored separately after this returns. A failure while restoring a later unit leaves earlier units replaced (no bundle-level atomicity). Each unit still uses complete replacement semantics.
Fields
manifest: Verified manifest.plugin_units: Plugin units to restore onto the target adapter.
Implements: Clone, Debug
pub struct SchemaBackupOpts {
pub files_dir: PathBuf,
pub include_plugin_databases: bool,
pub consistent_backup_read: bool,
pub backend_at_capture: String,
pub max_result_rows: u32,
pub max_result_bytes: u32,
pub max_atomic_result_bytes: u32,
pub plugin_units: Vec<PreparedPluginUnit>,
pub adapter: Option<SharedAdapterBackupOps>,
}
Optional in-place backup taken before applying ups or downs.
Fields
files_dir:$BOOKCLERK_FILES_DIRroot forbackups/.include_plugin_databases: Include every registered plugin-owned database binding.consistent_backup_read: Guest advertised consistent backup read.backend_at_capture: Adapter id at capture (diagnostic).max_result_rows: Negotiated page size.max_result_bytes: Negotiated encoded SELECT-page budget.max_atomic_result_bytes: Negotiated encoded atomic-reply budget.plugin_units: Plugin sessions prepared by the host when inclusion is requested.adapter: Library adapter hooks.Noneuses the in-process SDK (tests).
Implements: Clone, Debug, Default
pub struct ValidatedBackup {
pub manifest: BackupManifest,
pub library: BackupUnit,
pub plugin_units: Vec<BackupUnit>,
}
Recovery point whose objects, schema, and typed rows have been verified.
Fields
manifest: Parsed, supported manifest.library: Library unit metadata (objects already verified in the repository).plugin_units: Plugin binding units (already verified).
Implements: Clone, Debug
pub struct Missing {
pub entity: EntityKind,
pub id: Option<String>,
}
What a LibraryError::NotFound could not find: the kind of row and,
when the caller named one, its id.
Displays as <entity> <id> not found, or <entity> not found without
an id, so an error body names the missing thing rather than presuming a
book.
Fields
entity: The kind of row.id: The id the caller asked for, when it named one.
Implements: Clone, Debug, Display, Eq, PartialEq
pub struct SchemaApplyOptions {
pub backup: Option<SchemaBackupOpts>,
}
Options for apply_host_schema_with_options.
Fields
backup: When set, write a recovery point before applying DDL to a non-empty database.
Implements: Clone, Debug, Default
pub struct SchemaBatch {
pub statements: Vec<String>,
}
Canonical schema apply batch: already-separate host statements plus marker.
Adapters lower each statement at execution; they must not re-split SQL.
Fields
statements: Ordered SQL strings; the last statement is the version/state marker.
pub fn from_statements_and_marker(
stmts: impl IntoIterator<Item = impl Into<String>>,
marker: impl Into<String>,
) -> Self
Builds a batch from an ordered statement list plus a trailing marker.
pub fn unreleased(
stmts: impl IntoIterator<Item = impl Into<String>>,
checksum: &str,
) -> Self
Unreleased development pack plus bookclerk_schema_migrations unreleased row.
Implements: Clone, Debug, Eq, PartialEq
pub struct InProcessSqlite {
/* private fields */
}
Runs compiled named plans on a local SeaORM SQLite connection.
Implements: Clone, Debug, NamedAtomicRunner
pub struct PluginMigrationHistory {
pub entries: Vec<PluginJournalEntry>,
}
Ordered durable plugin migration history.
Fields
entries: Journal rows in ordinal order.
pub fn digest(&self) -> String
SHA-256 digest of the complete ordered (migration_id, checksum) list.
pub fn len(&self) -> usize
Number of applied journal rows.
pub fn is_empty(&self) -> bool
True when no plugin migrations have been applied.
pub fn display(&self) -> String
Operator-facing history label (history@{n}+{digest}).
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct PluginMigrationSequence {
pub migrations: Vec<ProvenPluginMigration>,
}
Proven, ordered plugin migration sequence.
Fields
migrations: Registration-order migrations with checksums.
Implements: Clone, Debug, Eq, PartialEq
pub struct ProvenPluginMigration {
pub id: String,
pub operations: Vec<PluginMigrationOp>,
pub checksum: String,
}
One proven registered migration.
Fields
id: Opaque plugin-chosen identity.operations: Ordered operations.checksum: Deterministic checksum of(id, classified ops).
Implements: Clone, Debug, Eq, PartialEq
pub struct AccountLinkRecord {
pub id: i64,
pub identity_id: i64,
pub plugin_key: String,
pub account_id: String,
pub source: String,
pub created_at: DateTime<Utc>,
}
Link between a portal identity and a bookstore account.
Fields
id: Surrogate primary key assigned by the database.identity_id: Foreign key toportal_identities.id.plugin_key: Provenance-qualified PluginKey that owns the account.account_id: Store or operator account id this row belongs to.source: Display alias of the owning plugin (audible,libro, …).created_at: RFC 3339 timestamp when the row was inserted.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct AccountRecord {
pub id: i64,
pub plugin_key: String,
pub account_id: String,
pub source: String,
pub marketplace: String,
pub label: Option<String>,
pub scan_enabled: bool,
pub connection_status: String,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
Account row stored in the Bookclerk DB.
Fields
id: Surrogate primary key assigned by the database.plugin_key: Provenance-qualified PluginKey that owns this account. Any instance of that plugin, on any node, may act for it.account_id: Store or operator account id, unique within one plugin key.source: Display alias of the owning plugin (audible,libro, …).marketplace: Store marketplace / locale code (for exampleus,uk).label: Optional operator-facing display label.scan_enabled: When nonzero/true, scheduled scans include this account.connection_status:activeorrevoked(credentials and holdings removed; books retained).created_at: RFC 3339 timestamp when the row was inserted.updated_at: RFC 3339 timestamp when the row was last modified.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct AcquireStatusCounts {
pub total: i64,
pub not_acquired: i64,
pub queued: i64,
pub downloading: i64,
pub acquired: i64,
pub error: i64,
}
Held work counts per AcquireStatus, read in one grouped query
(see LibraryStore::count_works_by_status).
Fields
total: Every work, including any with a status this build does not know.not_acquired: Works inAcquireStatus::NotAcquired.queued: Works inAcquireStatus::Queued.downloading: Works inAcquireStatus::Downloading.acquired: Works inAcquireStatus::Acquired.error: Works inAcquireStatus::Error.
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub struct BranchRequestTarget {
pub work_id: String,
pub store: String,
pub marketplace: String,
pub product_id: String,
}
What a JobKind::BranchRequest asks its branch for: a work of this
library, and the store listing the branch answered for it
(control_plane::catalog_lookup). The branch is told the work by its
identifiers, never by this id.
Fields
work_id: This library's work id.store: Store of the branch listing, as its plain id (audible).marketplace: Lower-cased marketplace of the listing; empty when the store has none.product_id: The store's product id of the listing.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct ClaimTicketRecord {
pub id: i64,
pub token_hash: String,
pub identity_id: Option<i64>,
pub expires_at: DateTime<Utc>,
pub redeemed_at: Option<DateTime<Utc>>,
pub created_by: String,
pub created_at: DateTime<Utc>,
}
Claim ticket metadata (token plaintext is never stored).
Fields
id: Surrogate primary key assigned by the database.token_hash: SHA-256 hex digest of the opaque token (plaintext never stored).identity_id: Foreign key toportal_identities.id.expires_at: RFC 3339 expiry for the ticket, session, or code.redeemed_at: RFC 3339 time when the ticket/invite was redeemed, if any.created_by: Actor that created the row (user id or operator label).created_at: RFC 3339 timestamp when the row was inserted.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct DomainEventRecord {
pub id: String,
pub event_type: String,
pub schema_version: i64,
pub occurred_at: DateTime<Utc>,
pub account_id: String,
pub source: String,
pub correlation_id: String,
pub causation_id: String,
pub dedup_key: String,
pub payload: String,
pub ordering_key: String,
pub dispatch_state: String,
pub created_at: DateTime<Utc>,
pub wake_pending: bool,
pub queue_name: String,
pub content_type: String,
pub deliver_after: Option<DateTime<Utc>>,
}
Immutable outbox envelope.
Fields
id: Event id.event_type: Event type.schema_version: Payload schema version.occurred_at: Occurrence time.account_id: Tenant / account id.source: Producer plugin id (audible, …); empty when unknown.correlation_id: Trace correlation id.causation_id: Causing id.dedup_key: Producer idempotency key.payload: Bounded JSON payload.ordering_key: Producer FIFO key copied onto each delivery.dispatch_state:pendingordispatched.created_at: Insert time.wake_pending: True until a wake pass for this event has completed.queue_name: Queue this row belongs to (core.eventsfor domain events).content_type: Body encoding ofpayload(json,text,bytes).deliver_after: Earliest delivery time for a delayed queue message.
pub fn is_queue_message(&self) -> bool
True for a plugin-owned queue message (not a domain event).
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct EmbeddingRecord {
pub id: i64,
pub target_kind: String,
pub target_id: String,
pub model: String,
pub dims: i64,
pub text_hash: String,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
Stored embedding vector metadata (blob fetched separately when needed).
Fields
id: Surrogate primary key assigned by the database.target_kind: Embedding target kind (book,work, …).target_id: Id of the embedded target withintarget_kind.model: Embedding model identifier used to producevector.dims: Dimensionality of the stored embedding vector.text_hash: Hash of the text that was embedded (skip re-embed when unchanged).created_at: RFC 3339 timestamp when the row was inserted.updated_at: RFC 3339 timestamp when the row was last modified.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct EnqueueJobSpec {
pub kind: JobKind,
pub payload: JobPayload,
pub priority: i64,
pub max_attempts: i64,
pub max_pending: i64,
pub run_after: Option<DateTime<Utc>>,
}
Admission request for crate::LibraryStore::enqueue_job.
Fields
kind: Job kind to run.payload: Kind-specific filters and trigger metadata.priority: Higher values are claimed first (default 0).max_attempts: Maximum claims before a failure is terminal.max_pending: Global cap on pending+running rows; enqueue fails when at the cap.run_after: Optional delay before the job becomes claimable.
Implements: Clone, Debug
pub struct EventCatalogSubscription {
pub event_type: String,
pub schema_versions: Vec<u32>,
pub supports_suspend: bool,
pub resource_class: String,
pub filter: Option<Value>,
pub queue: String,
pub max_retries: Option<u32>,
pub dead_letter_queue: Option<String>,
pub retry_delay_secs: u32,
pub message_retention_secs: Option<u32>,
}
One [capabilities.events.subscriptions] row persisted in event_subscriber_nodes.
Fields
event_type: Versioned event type (book_acquired, …).schema_versions: Schema versions this guest can consume (default[1]).supports_suspend: WhetherEventResult::Suspendedis supported for this type.resource_class: Concurrency class (default"network").filter: Optional host-owned payload object filter (top-level key equality).queue: Queue this subscription consumes; empty means the domain-event bus. A plugin-owned queue matches by name only (no type, schema, or filter).max_retries: Redeliveries before dead-lettering;Noneuses the host default.dead_letter_queue: Queue that receives a message oncemax_retriesis exhausted.retry_delay_secs: Seconds a retried message waits before redelivery.message_retention_secs: Seconds a delivery may wait, due but never leased, before the host expires it (the consumer'smessage_retention_period).NoneusesEVENT_DELIVERY_DEFAULT_RETENTION_SECS.
pub fn new(event_type: impl Into<String>, schema_versions: Vec<u32>) -> Self
Build a type+schema subscription with default resource class and no filter.
pub fn queue(queue: impl Into<String>) -> Self
Build a plugin-owned queue subscription ([[queues.consumers]]).
pub fn queue_name(&self) -> &str
Queue this subscription consumes (core.events when unset).
pub fn is_queue(&self) -> bool
True for a plugin-owned queue subscription (not the domain-event bus).
pub fn max_attempts(&self) -> Option<u32>
max_attempts for deliveries created from this subscription.
Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize
pub struct EventDeliveryFence {
pub delivery_id: String,
pub owner: String,
pub generation: i64,
}
Claim fence for an event delivery (mirrors JobFence).
Fields
delivery_id: Delivery id that was claimed.owner: Worker id stored inlease_owner.generation:lease_generationassigned by the successful claim.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct EventDeliveryMetrics {
pub pending: i64,
pub running: i64,
pub suspended: i64,
pub dead_letter: i64,
pub acked: i64,
pub oldest_pending_age_secs: Option<i64>,
pub retries_total: i64,
pub suspensions_total: i64,
pub dead_letters_total: i64,
pub dispatch_latency_ms_avg: Option<i64>,
pub handler_latency_ms_avg: Option<i64>,
}
Operator-visible delivery-queue counters for GET /api/status.
Fields
pending:pendingrows with no checkpoint (not suspended).running: Currently claimed rows.suspended:pendingrows that hold a suspend checkpoint.dead_letter: Dead-lettered rows.acked: Successfully acked rows.oldest_pending_age_secs: Age in seconds of the oldestpendingrow, when any exist.retries_total: Durable retry outcomes (including reclaim-as-retry).suspensions_total: Durable suspend outcomes.dead_letters_total: Durable transitions intodead_letter.dispatch_latency_ms_avg: Average first-dispatch latency in milliseconds, when sampled.handler_latency_ms_avg: AverageonEventhandler duration in milliseconds, when sampled.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct EventDeliveryRecord {
pub id: String,
pub event_id: String,
pub plugin_id: String,
pub idempotency_key: String,
pub state: String,
pub attempt_count: i64,
pub max_attempts: i64,
pub lease_owner: Option<String>,
pub lease_expires_at: Option<DateTime<Utc>>,
pub lease_generation: i64,
pub run_after: DateTime<Utc>,
pub invocation_sequence: i64,
pub resume_pending: bool,
pub checkpoint_json: Option<String>,
pub checkpoint_schema_version: i64,
pub ordering_key: String,
pub outcome: Option<String>,
pub error_message: Option<String>,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
pub cancel_requested: bool,
pub resource_class: String,
pub wake_event_type: String,
pub wake_filter_json: String,
pub wake_grants_json: String,
pub queue_name: String,
}
Per-subscriber delivery row.
Fields
id: Delivery id ({event_id}:{plugin_id}).event_id: Parent event id.plugin_id: Subscriber plugin id.idempotency_key: Stable idempotency key.state: Lifecycle state.attempt_count: Claim count (not incremented on resume).max_attempts: Max claims before dead-letter.lease_owner: Current lease owner.lease_expires_at: Lease expiry.lease_generation: Fence generation.run_after: Earliest claim time.invocation_sequence: Resume ordinal.resume_pending: Next claim should resume rather than increment attempt.checkpoint_json: Suspend checkpoint JSON.checkpoint_schema_version: Checkpoint schema version.ordering_key: FIFO key.outcome: Terminal outcome.error_message: Operator-facing error.created_at: Insert time.updated_at: Last-modified time.cancel_requested: Cooperative cancel flag for a running delivery.resource_class: Concurrency class (networktoday).wake_event_type: Event type that can wake this suspended delivery; empty = timestamp-only.wake_filter_json: Host-owned payload object filter JSON for event-wake; empty = type only.wake_grants_json: Host-derived wake grants JSON; empty falls back to type +wake_filter_json.queue_name: Queue of the parent event, copied at dispatch.
pub fn fence(&self) -> EventDeliveryFence
Fence for heartbeat / complete / fail / suspend.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct EventStreamPage {
pub events: Vec<DomainEventRecord>,
pub last_scanned: Option<(String, String)>,
pub more: bool,
pub expired_event_ids: Vec<String>,
pub truncated: bool,
}
One page of EventStreamRead.
Fields
events: Matching events, oldest first.last_scanned: Stored(created_at, id)of the last row scanned, the next page's start;Nonewhen nothing was scanned.more: True when more events may follow (the page filled or the scan budget ran out).expired_event_ids: Ids of returned events whose delivery to one of the subscriber ids expired unleased.truncated: True when the start position is older than the retention window.
Implements: Clone, Debug, Default
pub struct EventStreamRead {
pub start: EventStreamStart,
pub subscriptions: Vec<EventCatalogSubscription>,
pub account_id: Option<String>,
pub plugin_key: String,
pub retention_days: u64,
pub settle_secs: u64,
pub limit: usize,
pub now: DateTime<Utc>,
}
One page request over the domain-event outbox (EventPublisher.read).
Fields
start: Where the read starts.subscriptions: The reader's consented subscriptions, already narrowed to the types it asked for. An event is returned when any of them matches it.account_id:Somelimits the read to one account's events;Nonereads every account, as delivery does for a host-wide invocation.plugin_key: The reader's PluginKey. Its deliveries are filed under this key and under each of its instance ids; they report which returned events it missed. Empty reports none.retention_days:[events].retention_days: nothing older is returned.settle_secs: Events stored less than this many seconds beforenoware left for a later read (crate::EVENT_STREAM_SETTLE_SECSin production), so a publication that commits behind a newer one is never skipped.limit: Most events to return (at least one).now: Current time, which fixes the retention cutoff.
Implements: Clone, Debug
pub struct EventSubscriber {
pub plugin_id: String,
pub resource_class: String,
pub max_attempts: Option<u32>,
}
Subscriber snapshot used when creating deliveries for one event.
Fields
plugin_id: Plugin id that declared a matching subscription.resource_class: Concurrency class copied onto the delivery row.max_attempts: Claims before the delivery dead-letters;Noneuses the host default (EVENT_DELIVERY_MAX_ATTEMPTS). Derived from the consumer'smax_retries + 1.
pub fn plugin(plugin_id: impl Into<String>) -> Self
Catalog match for plugin_id with the default network resource class.
pub fn max_attempts_or_default(&self) -> i64
Effective max_attempts for a new delivery row.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct EventSubscriberCatalogRecord {
pub plugin_id: String,
pub subscriptions: Vec<EventCatalogSubscription>,
pub enabled: bool,
pub updated_at: DateTime<Utc>,
}
Library-authoritative catalog row after collapsing live nodes by plugin_id.
Fields
plugin_id: Canonical PluginKey of the subscriber (not the display alias).subscriptions: Union of subscriptions from live enabled nodes.enabled: Whether any live node has this plugin enabled.updated_at: Latest heartbeat among contributing live rows.
Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize
pub struct EventSubscriberNodeRecord {
pub node_id: String,
pub plugin_id: String,
pub subscriptions: Vec<EventCatalogSubscription>,
pub enabled: bool,
pub heartbeat_at: DateTime<Utc>,
}
Live per-node catalog row (event_subscriber_nodes).
Fields
node_id: Daemon node id.plugin_id: Canonical PluginKey of the subscriber (not the display alias).subscriptions: Declared subscriptions on this node.enabled: Whether this node wants matching events forplugin_id.heartbeat_at: Last heartbeat from this node.
Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize
pub struct EventWakeGrant {
pub schema_versions: Vec<u32>,
pub filter: Option<Value>,
}
Host-derived wake grant: schema versions plus an intersected payload filter.
Fields
schema_versions: Schema versions this grant may observe.filter: Intersected payload object filter;None/ empty object matches any payload.
Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize
pub struct GlobalQueueEntry {
pub work_key: String,
pub work_id: String,
pub edition_id: Option<String>,
pub expression_id: Option<String>,
pub title: String,
pub authors: Option<String>,
pub asin: Option<String>,
pub isbn: Option<String>,
pub cover_url: Option<String>,
pub description: Option<String>,
pub subtitle: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub publisher: Option<String>,
pub length_minutes: Option<i64>,
pub published_at: Option<String>,
pub genres: Option<String>,
pub language: Option<String>,
pub store_editions: Vec<WishlistStoreEdition>,
pub purchase_hints: Vec<WishlistPurchaseHint>,
pub wish_count: i64,
pub wishers: Vec<QueueWisher>,
pub sample_uuids: Vec<String>,
pub first_requested_at: DateTime<Utc>,
pub last_requested_at: DateTime<Utc>,
}
Aggregated global request-queue entry (one work, many wishers).
Fields
work_key: Bibliographic card key of the newest wish (seeTitleRequestRecord::work_key); clients match cards on it.work_id: The work every wish of this entry is for: the queue groups by it.edition_id: The edition the newest wish naming one is for (editions.id); the entry's title, identifiers and cover describe that edition.expression_id: That edition's expression (expressions.id), when the library places it: store listings of the same expression are the same recording, so Discover prices the wish from them only.title: Display title of the work or edition.authors: Comma-separated or JSON author list from the storefront.asin: Amazon ASIN when known; otherwise null.isbn: ISBN-10/13 when known; otherwise null.cover_url: HTTPS URL for cover art when known.description: Blurb / synopsis text (may contain HTML).subtitle: Optional subtitle from bibliographic metadata.narrators: Comma-separated or JSON narrator list when present.series: Series name when the title belongs to a series.series_index: Position within the series (storefront string form).publisher: Publisher name from metadata enrichment or the storefront.length_minutes: Runtime in whole minutes when the storefront reports it.published_at: Publication date string from the storefront or enrichment.genres: Merged genre / category list for display.language: BCP-47 or storefront language code when known.store_editions: Distinct storefront editions contributing to this wishlist item.purchase_hints: Purchase URLs and prices observed per storefront.wish_count: Number of users who requested this title.wishers: Distinct people who have this title on an open wishlist.sample_uuids: Sample title-request UUIDs represented in this aggregate row.first_requested_at: Earliest request timestamp in this aggregate group.last_requested_at: Most recent request timestamp in this aggregate group.
pub fn push_wisher(&mut self, wisher: QueueWisher)
Adds wisher when they are not already present (capped at 16).
Duplicate people keep the richer picture and name fields.
wisher- Person who has this title on an open wishlist.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct JobClaimCursor {
pub priority: i64,
pub created_at: String,
pub id: String,
}
Where the next page of routed-claim candidates starts (keyset paging).
Candidates are ordered by priority DESC, created_at ASC, id ASC; the
cursor is the last row of the previous page, so rows that leave the
pending state between pages never shift the window.
Fields
priority: Priority of the last row read.created_at:created_at(RFC 3339 text) of the last row read.id: Id of the last row read.
Implements: Clone, Debug, Eq, PartialEq
pub struct JobClaimPage {
pub jobs: Vec<JobRecord>,
pub next: Option<JobClaimCursor>,
}
One page of routed-claim candidates.
Fields
jobs: Readable, not cancel-requested pending jobs, best first.next: Where the next page starts, orNonewhen no row remains.
Implements: Clone, Debug, Default
pub struct JobFence {
pub job_id: String,
pub owner: String,
pub generation: i64,
}
Lease identity a worker must present to mutate a running job.
Fields
job_id: Job id that was claimed.owner: Worker id stored inlease_owner.generation:lease_generationassigned by the successful claim.
Implements: Clone, Debug, Eq, PartialEq
pub struct JobPayload {
pub v: u32,
pub account: Option<String>,
pub title: Option<String>,
pub plugin_instance_id: Option<String>,
pub requires: Vec<String>,
pub trigger: JobTrigger,
pub integration_id: Option<String>,
pub force: bool,
pub plugin_id: Option<String>,
pub source_key: Option<String>,
pub dest_key: Option<String>,
pub checkpoint: Option<JobCheckpoint>,
pub invocation_sequence: Option<u32>,
pub resume_pending: bool,
pub pdf_only: bool,
pub paced: bool,
pub requires_unsettled_since_ms: Option<i64>,
pub cron: Option<String>,
pub scheduled_time_ms: Option<i64>,
pub subject: Option<String>,
pub node_id: Option<String>,
pub branch_request: Option<BranchRequestTarget>,
pub ingest_batch: Option<String>,
pub convert: Option<OutputCopy>,
pub notify_delivery: Option<String>,
}
JSON command envelope stored on a job row.
Fields
-
v: Envelope schema version; must equalJOB_PAYLOAD_VERSION. -
account: Optional account filter (None= all eligible accounts). -
title: Optional title filter (uuid / ASIN / ISBN / product id). -
plugin_instance_id: Pins the plugin instance that serves the job.Noneroutes to the plugin's default instance on the claiming host. -
requires: Plugin instance ids the claiming node must run, with its guest up.Recorded at admission (the pinned instance and any node-bound destination). Empty means any node may claim the job. The routed claim (
control_plane::claim_routed_job) skips a job whose instances are not deployed and observed up on the claiming node, and the unroutedcrate::LibraryStore::claim_next_jobnever claims a job that has any. -
trigger: Admission source (apiorscheduler). -
integration_id: Integration plugin id forJobKind::IntegrationScan. -
force: When true, an integration scan asks the remote to rescan, and an acquire re-downloads titles already acquired (run only by nodes that hold the library database). -
plugin_id: Destination plugin id forJobKind::PluginCopy. -
source_key: Source object key forJobKind::PluginCopy. -
dest_key: Destination object key forJobKind::PluginCopy. -
checkpoint: Bounded checkpoint restored afterbookclerk_plugin_abi::JobOutcome::Suspended. -
invocation_sequence: Resume ordinal; distinct from failureSelfattempt_count on the job row. -
resume_pending: One-shot: the next claim is a suspend-resume and must not consume a failure attempt.Cleared when that claim is taken. A leftover
Self::checkpointafter a retryable failure must not keep later claims in the resume path. -
pdf_only: For [JobKind::Acquire]: fetch only each title's companion PDF.Run only by nodes that hold the library database; a Host is never handed such a job (
control_plane::node_may_claim_job). -
paced: For [JobKind::Acquire]: the host started this acquire itself (auto-acquire, quality upgrades, acquire-all, a request from another library), so each download waits for its store account's pace (crate::pacing). An acquire a person starts by hand leaves it false: its downloads are counted but never held. -
requires_unsettled_since_ms: Unix milliseconds when the requirements sweep first found this pending job'sSelf::requiresunsettled: no node runs all of them, or one of them is no longer deployed anywhere.Cleared when they settle again. The sweep fails the job (or, when only a dropped instance is involved, rewrites it) once it has been unsettled for its grace period, so a placement move that briefly leaves no common node does not fail queued work (
control_plane::sweep_job_requirements). -
cron: For [JobKind::PluginScheduled]: the normalized[triggers] cronsschedule that fired. -
scheduled_time_ms: For [JobKind::PluginScheduled]: the fire time the handler sees asscheduledTime, in Unix milliseconds (always a whole UTC minute). -
subject: ForJobKind::DiscoverCandidatesand [JobKind::DiscoverFeed]: the Discover subject key (operator,user:<id>,portal:<id>). -
node_id: The one node that may claim this job, for work on that node's own disk (JobKind::CacheSweep,JobKind::SearchIndexRebuild,JobKind::IngestBatch).Nonelets any node that meetsSelf::requiresclaim it. The routed claim (control_plane::claim_routed_job) skips a job pinned to another node, the unroutedcrate::LibraryStore::claim_next_jobnever claims a pinned job, and the requirements sweep fails one whose node has stopped heartbeating (control_plane::sweep_job_requirements). -
branch_request: For [JobKind::BranchRequest]: the work asked for and the branch listing it was asked from. -
ingest_batch: For [JobKind::IngestBatch]: theingest_batches.idto run. -
convert: For [JobKind::Acquire]: instead of downloading, add this copy to the title's stored edition, made from the copy the library already holds (an administrator's convert). No store is asked, so the job is never paced;Self::forcemakes the copy again when it exists.Run only by nodes that hold the library database, since the copy is made from the edition's recorded files.
-
notify_delivery: For [JobKind::NotifySend]: thenotify_deliveries.idto send.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct JobRecord {
pub id: String,
pub kind: JobKind,
pub state: JobState,
pub priority: i64,
pub resource_class: JobResourceClass,
pub payload: JobPayload,
pub progress: Option<String>,
pub attempt_count: i64,
pub max_attempts: i64,
pub run_after: DateTime<Utc>,
pub lease_owner: Option<String>,
pub lease_expires_at: Option<DateTime<Utc>>,
pub dedup_key: String,
pub error_kind: Option<String>,
pub error_message: Option<String>,
pub cancel_requested: bool,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
pub started_at: Option<DateTime<Utc>>,
pub finished_at: Option<DateTime<Utc>>,
pub lease_generation: i64,
}
Durable job row returned to the daemon API and worker.
Fields
id: Stable job id (scan-{uuid}, …).kind: Job kind (scan,acquire,listen_sync).state: Lifecycle state.priority: Higher values are claimed first.resource_class: Concurrency class.payload: Kind-specific filters and trigger metadata.progress: Human-readable progress string.attempt_count: Number of times a worker has claimed this row.max_attempts: Maximum claims before a failure becomes terminal.run_after: Earliest time a pending job may be claimed.lease_owner: Worker id that currently holds the lease.lease_expires_at: Lease expiry; stale running rows are reclaimed after this.dedup_key: Idempotency key among pending/running rows.error_kind: Structured error kind when failed or cancelled.error_message: Operator-facing error text.cancel_requested: Cooperative cancel flag.created_at: When the row was inserted.updated_at: When the row was last modified.started_at: When a worker first claimed the row.finished_at: When the row reached a terminal state.lease_generation: Per-claim generation used to fence heartbeat and finalization.
pub fn fence(&self) -> Option<JobFence>
Lease identity for heartbeat and finalization, when this row is claimed.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct JobTempPath {
pub id: i64,
pub job_id: String,
pub path: String,
pub created_at: DateTime<Utc>,
pub reserved_bytes: u64,
}
Scratch path registered against a job for crash cleanup.
Fields
id: Surrogate primary key.job_id: Owning job id.path: Absolute filesystem path.created_at: When the path was registered.reserved_bytes: Bytes reserved against the job temp quota for this path.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct ListeningProgressRecord {
pub id: i64,
pub identity_id: Option<i64>,
pub provider: String,
pub external_user_id: String,
pub work_id: String,
pub edition_id: Option<String>,
pub external_item_id: String,
pub progress: Option<f64>,
pub current_time_seconds: Option<f64>,
pub duration_seconds: Option<f64>,
pub is_finished: bool,
pub last_listened_at: Option<DateTime<Utc>>,
pub updated_at: DateTime<Utc>,
}
Listening progress snapshot from an external player (e.g. AudioBookshelf).
Fields
id: Surrogate primary key assigned by the database.identity_id: Foreign key toportal_identities.id.provider: External identity or integration provider id (for example ABS).external_user_id: User id at the external provider.work_id: The work the item resolved to through its identifiers.edition_id: The edition the item's identifiers name, when exactly one does.external_item_id: Provider-native listening-progress item id.progress: Fractional progress 0.0–1.0 when the provider reports it.current_time_seconds: Current playback position within the title, in seconds.duration_seconds: Total duration in seconds when known.is_finished: Whether the listener marked the title finished (0/1 or bool).last_listened_at: RFC 3339 time of the last playback update.updated_at: RFC 3339 timestamp when the row was last modified.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct OidcClientRecord {
pub id: i64,
pub client_id: String,
pub client_secret_hash: Option<String>,
pub redirect_uris: Vec<String>,
pub name: Option<String>,
pub issue_refresh_token: bool,
pub allowed_scopes: Vec<String>,
pub enabled: bool,
pub plugin_id: Option<String>,
pub created_at: String,
}
Registered OIDC authorization-server client (Bookclerk as IdP).
Fields
id: Surrogate primary key.client_id: Public client_id used at authorize / token.client_secret_hash: Hash of the client secret;Nonefor public PKCE clients.redirect_uris: Allowed OAuth redirect URIs.name: Operator-facing display name.issue_refresh_token: When true, token responses include a refresh token.allowed_scopes: Scopes this client may be granted (openid,profile,email, …).enabled: When true, authorize and token endpoints accept this client.plugin_id: Plugin id that owns this client;Nonefor operator-created clients.created_at: RFC 3339 timestamp when the row was inserted.
pub fn has_secret(&self) -> bool
True when a client secret hash is stored (confidential client).
pub fn is_plugin_provided(&self) -> bool
True when a plugin owns this client's identity and redirect URIs.
Implements: Clone, Debug
pub struct OperatorSessionRecord {
pub id: i64,
pub expires_at: DateTime<Utc>,
pub created_at: DateTime<Utc>,
pub last_used_at: Option<DateTime<Utc>>,
pub elevated_from_user_id: Option<i64>,
pub impersonating_user_id: Option<i64>,
pub user_agent: Option<String>,
pub device_type: Option<String>,
pub client_label: Option<String>,
}
Durable operator session metadata (hashed token is never exposed).
Fields
id: Surrogate primary key assigned by the database.expires_at: RFC 3339 expiry for the ticket, session, or code.created_at: RFC 3339 timestamp when the row was inserted.last_used_at: RFC 3339 time of the last authenticated use of this session.elevated_from_user_id: User id that elevated into this operator session, if any.impersonating_user_id: User id being impersonated by this operator session, if any.user_agent: Raw User-Agent captured at session mint (optional).device_type: Best-effort device class (desktop/mobile/tablet/api).client_label: Best-effort OS / client label (Windows,Android,API, …).
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct PendingWakeProgress {
pub claimed: u32,
pub still_pending: bool,
}
How far one claimed wake tick got.
Fields
claimed: Events this tick claimed and processed one delivery page for.still_pending: True when another tick should run (saved cursor or remaining flags).
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub struct PortalIdentity {
pub id: i64,
pub provider: String,
pub external_user_id: String,
pub label: Option<String>,
pub user_id: Option<i64>,
pub created_at: DateTime<Utc>,
pub picture_url: Option<String>,
}
Portal identity bound to an external provider user (e.g. ABS).
Fields
id: Surrogate primary key assigned by the database.provider: External identity or integration provider id (for example ABS).external_user_id: User id at the external provider.label: Optional operator-facing display label.user_id: First-party user this external identity is linked to (Phase 1).created_at: RFC 3339 timestamp when the row was inserted.picture_url: Last HTTPS profile picture URL from the identity provider, when any.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct PortalSessionRecord {
pub id: i64,
pub token_hash: String,
pub created_at: String,
pub expires_at: String,
pub last_used_at: Option<String>,
pub user_agent: Option<String>,
pub device_type: Option<String>,
pub client_label: Option<String>,
pub kind: PortalSessionKind,
}
Portal session row for session lists (includes hash for current-session match).
Fields
id: Surrogate primary key assigned by the database.token_hash: SHA-256 hex of the session token (never serialized to clients).created_at: RFC 3339 created timestamp.expires_at: RFC 3339 expiry timestamp.last_used_at: RFC 3339 last-used timestamp, when known.user_agent: Raw User-Agent captured at session mint (optional).device_type: Best-effort device class.client_label: Best-effort OS / client label; for a library card, the name the clerk gave itself.kind: Where the token is presented.
Implements: Clone, Debug
pub struct PublishDomainEventSpec {
pub id: String,
pub event_type: String,
pub schema_version: i64,
pub account_id: String,
pub source: String,
pub correlation_id: String,
pub causation_id: String,
pub dedup_key: String,
pub payload: String,
pub ordering_key: String,
pub queue_name: String,
pub content_type: String,
pub delay_seconds: u32,
}
Producer-side domain event (or queue message) to persist in the outbox.
A domain event leaves queue_name empty (the bus, CORE_EVENTS_QUEUE)
and sets event_type. A queue message names its queue and leaves
event_type empty; content_type says how payload is encoded and
delay_seconds holds its deliveries back.
Fields
id: Stable event id (UUID). Generated when empty.event_type: Event type (book_acquired); empty for queue messages.schema_version: Payload schema version.account_id: Tenant / account id.source: Producer plugin id (audible, …); empty when unknown.correlation_id: Trace correlation id.causation_id: Causing event or job id.dedup_key: Unique withevent_type(duplicate publishes coalesce).payload: Bounded JSON payload (never media bytes).ordering_key: FIFO key copied onto each delivery (book uuidforbook_acquired).queue_name: Queue name; empty means the domain-event bus (CORE_EVENTS_QUEUE).content_type: Body encoding (json,text,bytes); empty meansjson.delay_seconds: Seconds before the first delivery may be claimed (queue messages).
Implements: Clone, Debug, Default, Deserialize<'de>, Serialize
pub struct QueueWisher {
pub user_id: Option<i64>,
pub identity_id: Option<i64>,
pub display_name: Option<String>,
pub login_name: Option<String>,
pub operator: bool,
pub has_avatar: bool,
pub avatar_source: Option<String>,
pub gravatar_hash: Option<String>,
pub picture_url: Option<String>,
pub picture_path: Option<String>,
}
Compact wisher shown on the global queue (avatar + label).
Fields
user_id: First-partyusers.idwhen the portal identity is linked.identity_id: Portal identity that created the wish (dedupe for unlinked identities).display_name: Display name, identity label, or"Operator".login_name: Local login name when the first-party user has one.operator: True when the wish came from the operator token (no portal user).has_avatar: True when an uploaded avatar file exists (filled by the daemon).avatar_source: Explicit picture choice when the user has set one.gravatar_hash: SHA-256 hex of the contact email for Gravatar.picture_url: HTTPS picture from the wishing identity, when any.picture_path: Same-origin 128 px copy ofpicture_urlfor the web app to show (filled by the daemon; never stored).
pub fn same_person(&self, other: &Self) -> bool
Returns true when both rows represent the same person for aggregation.
other- Candidate wisher to compare.
True for two operator wishes, the same user_id, or the same unlinked identity.
Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct SecurityAuditEvent {
pub id: i64,
pub at: DateTime<Utc>,
pub actor: String,
pub action: String,
pub detail_json: Option<String>,
}
Security audit event (elevate / impersonate / login / provision).
Fields
id: Surrogate primary key assigned by the database.at: RFC 3339 timestamp of the audit event.actor: Actor label (user id, operator, or system).action: Audit action verb (for examplelogin,rotate_token).detail_json: JSON object with structured event details (no secrets).
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct StoredPasskey {
pub id: i64,
pub credential_id: String,
pub passkey_json: String,
pub name: Option<String>,
}
Stored WebAuthn credential (passkey JSON plus the label shown in Settings).
Fields
id: Surrogate primary key.credential_id: Base64url credential id.passkey_json: Serializedwebauthn_rspasskey JSON.name: Label chosen at registration;Nonefor rows created before names existed.
Implements: Clone, Debug
pub struct TasteHolder {
pub plugin_key: String,
pub account_id: String,
pub source: String,
}
A storefront account that holds a work, as a TasteTitle lists it.
Fields
plugin_key: The account's plugin key.account_id: The account id at that plugin.source: The account's storefront id (accounts.source), lowercase.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct TasteTitle {
pub work_id: String,
pub edition_id: String,
pub plugin_key: String,
pub source: String,
pub product_id: String,
pub marketplace: String,
pub asin: Option<String>,
pub isbn: Option<String>,
pub title: String,
pub subtitle: Option<String>,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub series_store_id: Option<String>,
pub publisher: Option<String>,
pub categories: Option<String>,
pub subjects: Option<String>,
pub description: Option<String>,
pub language: Option<String>,
pub cover_url: Option<String>,
pub length_minutes: Option<i64>,
pub published_at: Option<String>,
pub is_abridged: bool,
pub is_podcast: bool,
pub purchased_at: Option<DateTime<Utc>>,
pub acquired: bool,
pub holders: Vec<TasteHolder>,
pub is_finished: bool,
pub rating_overall: Option<f32>,
pub rating_performance: Option<f32>,
pub rating_story: Option<f32>,
pub tags: Option<String>,
}
One work the library holds, as Discover reads it for taste and seeds.
Bibliographic fields come from the work (credits, series, subjects,
description) and from a representative edition and store listing: one
whose edition has files, else the most recently bought. The person's
fields (is_finished, ratings, tags) start empty and are filled from
user_title_state for whichever people the reader asks about.
Fields
work_id: The work (works.id); the title's identity.edition_id: The representative edition (editions.id).plugin_key: Plugin key of the representative listing's store.source: Storefront id of that store (an account'ssource), lowercase.product_id: The representative listing's product id at its store.marketplace: The representative listing's stored marketplace.asin: The representative edition's ASIN, when it has one.isbn: The representative edition's ISBN, when it has one.title: The work's title.subtitle: The edition's subtitle, when known.authors: Names credited on the work (authors first), comma-separated.narrators: Narrators credited on the work's expressions, comma-separated.series: The first series the work belongs to.series_index: The work's position in that series as printed ("3","2.5").series_store_id: The representative store's own id for the series, when it gave one.publisher: The edition's first credited publisher.categories: Store categories (serialized), from the listing or the work.subjects: Subject tags of the work (serialized), when enriched.description: The work's synopsis (may contain HTML).language: The expression's language, when known.cover_url: Cover art URL of the edition, else of the work.length_minutes: The edition's running time in minutes, when known.published_at: The edition's publication date as given, when known.is_abridged: Whether the expression is abridged.is_podcast: Whether the work is a podcast show or episode.purchased_at: The newest purchase date of the representative listing's holders.acquired: Whether the representative edition has files at a destination.holders: The accounts that hold any edition of the work, by plugin and id.is_finished: Whether the people asked about finished the work.rating_overall: Their mean overall rating (0 to 5), when any gave one.rating_performance: Their mean narration rating (0 to 5), when any gave one.rating_story: Their mean story rating (0 to 5), when any gave one.tags: Their tags, space-separated, each once.
Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize
pub struct TitleRequestRecord {
pub id: i64,
pub uuid: String,
pub identity_id: Option<i64>,
pub title: String,
pub authors: Option<String>,
pub asin: Option<String>,
pub isbn: Option<String>,
pub notes: Option<String>,
pub status: RequestStatus,
pub work_key: String,
pub work_id: String,
pub edition_id: Option<String>,
pub resolved_edition_id: Option<String>,
pub cover_url: Option<String>,
pub cover_path: Option<String>,
pub sources: Vec<TitleRequestSourceRecord>,
pub description: Option<String>,
pub subtitle: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub publisher: Option<String>,
pub length_minutes: Option<i64>,
pub published_at: Option<String>,
pub genres: Option<String>,
pub language: Option<String>,
pub store_editions: Vec<WishlistStoreEdition>,
pub purchase_hints: Vec<WishlistPurchaseHint>,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
Personal wishlist row (also contributes to the shared global queue while open).
Fields
id: Surrogate primary key assigned by the database.uuid: Stable UUID for this row (API / foreign-key identity).identity_id: Foreign key toportal_identities.id.title: Display title: the title of the wish's work.authors: Comma-separated authors: the work's author credits in billing order.asin: Amazon ASIN from the wish's storefront sources, when one carries it.isbn: ISBN-10/13 from the wish's storefront sources, when one carries it.notes: Free-form operator or requester notes.status: Lifecycle status for the row (user, request, …).work_key: Bibliographic card key (isbn:…/asin:…/soft:…) clients use to match a wish to a catalog card. Derived from the work's title and authors and the sources' identifiers on every read, never stored.work_id: The work the wish is for; wishes for one work are one queue entry.edition_id: The edition the wish named, when the library knows it.resolved_edition_id: Edition (editions.id) the library holds once the wishlist item is fulfilled.cover_url: HTTPS URL for cover art when known.cover_path: Same-origin path of this cover's processed images, set by the daemon whencover_urlis anhttpsURL. Append/128(thumbnail),/360(card) or/full, so a client can show covers without loadingcover_urlfrom another site.sources: Per-storefront snapshots (empty for legacy rows).description: Blurb / synopsis text (may contain HTML).subtitle: Optional subtitle from bibliographic metadata.narrators: Comma-separated or JSON narrator list when present.series: Series name when the title belongs to a series.series_index: Position within the series (storefront string form).publisher: Publisher name from metadata enrichment or the storefront.length_minutes: Runtime in whole minutes when the storefront reports it.published_at: Publication date string from the storefront or enrichment.genres: Merged genre / category list for display.language: BCP-47 or storefront language code when known.store_editions: Distinct storefront editions contributing to this wishlist item.purchase_hints: Purchase URLs and prices observed per storefront.created_at: RFC 3339 timestamp when the row was inserted.updated_at: RFC 3339 timestamp when the row was last modified.
pub fn hide_prices_and_links(&mut self)
Removes the store links and prices of every purchase hint, for a patron whose "See prices and store links" member control is off.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema
pub struct TitleRequestSourceRecord {
pub id: i64,
pub title_request_id: i64,
pub source: String,
pub product_id: String,
pub title: Option<String>,
pub subtitle: Option<String>,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub asin: Option<String>,
pub isbn: Option<String>,
pub description: Option<String>,
pub publisher: Option<String>,
pub length_minutes: Option<i64>,
pub published_at: Option<String>,
pub categories: Option<String>,
pub language: Option<String>,
pub cover_url: Option<String>,
pub url: Option<String>,
pub price_cents: Option<i64>,
pub currency: Option<String>,
pub price_label: Option<String>,
pub list_price_cents: Option<i64>,
pub list_price_label: Option<String>,
pub member_price_cents: Option<i64>,
pub member_price_label: Option<String>,
pub observed_at: Option<DateTime<Utc>>,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
Per-storefront catalog/pricing snapshot attached to a wishlist row.
Fields
id: Surrogate primary key assigned by the database.title_request_id: Foreign key totitle_requests.id.source: Content-source plugin id (audible,libro, …).product_id: Storefront product id (ASIN, ISBN, UUID, …).title: Display title of the work or edition.subtitle: Optional subtitle from bibliographic metadata.authors: Comma-separated or JSON author list from the storefront.narrators: Comma-separated or JSON narrator list when present.series: Series name when the title belongs to a series.series_index: Position within the series (storefront string form).asin: Amazon ASIN when known; otherwise null.isbn: ISBN-10/13 when known; otherwise null.description: Blurb / synopsis text (may contain HTML).publisher: Publisher name from metadata enrichment or the storefront.length_minutes: Runtime in whole minutes when the storefront reports it.published_at: Publication date string from the storefront or enrichment.categories: Storefront category / genre path list (serialized).language: BCP-47 or storefront language code when known.cover_url: HTTPS URL for cover art when known.url: Storefront product or purchase URL when known.price_cents: Observed price in minor currency units, when known.currency: ISO 4217 currency code for price fields.price_label: Storefront-formatted price string for display.list_price_cents: List/MSRP price in minor units, when known.list_price_label: Storefront-formatted list price for display.member_price_cents: Member/subscriber price in minor units, when known.member_price_label: Storefront-formatted member price for display.observed_at: RFC 3339 time when this storefront snapshot was observed.created_at: RFC 3339 timestamp when the row was inserted.updated_at: RFC 3339 timestamp when the row was last modified.
Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Serialize, ToSchema
pub struct UserIntegrationHint {
pub source: String,
pub account_id: String,
pub label: Option<String>,
}
Storefront / integration connection summary for admin user lists.
Fields
source: Content-source or integration plugin id (audible,libro, …).account_id: Store or operator account id this row belongs to.label: Optional operator-facing account label.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema
pub struct UserInviteRecord {
pub id: i64,
pub token_hash: String,
pub role: UserRole,
pub login_name: Option<String>,
pub display_name: Option<String>,
pub expires_at: DateTime<Utc>,
pub redeemed_at: Option<DateTime<Utc>>,
pub created_by: String,
pub created_at: DateTime<Utc>,
}
Invite ticket for provisioning a User (token plaintext never stored).
Fields
id: Surrogate primary key assigned by the database.token_hash: SHA-256 hex digest of the opaque token (plaintext never stored).role: First-party role (administratorormember).login_name: Local username for password login, when set.display_name: Human-readable name shown in the UI.expires_at: RFC 3339 expiry for the ticket, session, or code.redeemed_at: RFC 3339 time when the ticket/invite was redeemed, if any.created_by: Actor that created the row (user id or operator label).created_at: RFC 3339 timestamp when the row was inserted.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct UserListeningHint {
pub title: Option<String>,
pub provider: String,
pub last_listened_at: DateTime<Utc>,
}
Recent unfinished listening hint for admin user lists.
Fields
title: Title of the work being listened to, when the library knows it.provider: Integration / storefront provider id.last_listened_at: RFC 3339 time of the last playback update.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Serialize, ToSchema
pub struct UserPreferences {
pub id: i64,
pub subject_key: String,
pub identity_id: Option<i64>,
pub default_view: String,
pub disabled_shelves: Vec<String>,
pub discover_sort: String,
pub discover_sort_dir: String,
pub discover_language: Option<String>,
pub discover_excluded_sources: Vec<String>,
pub theme: String,
pub updated_at: DateTime<Utc>,
}
Per-user GUI / Discover preferences (operator or portal identity).
Fields
id: Surrogate primary key assigned by the database.subject_key: Preference subject key (operator,user:<id>, portal key).identity_id: Foreign key toportal_identities.id.default_view: Preferred library SPA view identifier (for examplegridorlist).disabled_shelves: Shelf kind ids to hide (author,chirp_deals, …). Empty = all on.discover_sort: Preferred Discover sort column (for exampletitleoradded).discover_sort_dir: Discover sort direction (asc/desc).discover_language: Preferred content language (en,__all__, …).None= browser default.discover_excluded_sources: Store ids to hide in Discover. Empty = all sources (including future).theme: Appearance preference (system,light, ordark).updated_at: RFC 3339 timestamp when the row was last modified.
pub fn defaults_for(subject_key: &str, identity_id: Option<i64>) -> Self
Defaults when no row exists yet.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct UserPresenceExtras {
pub online: bool,
pub listening: Option<UserListeningHint>,
pub integrations: Vec<UserIntegrationHint>,
pub last_active_at: Option<DateTime<Utc>>,
}
Presence + connection extras for administrator user management.
Fields
online: True when the user has a non-expired portal session.listening: Most recent unfinished listen within the listening window, if any.integrations: Linked storefront / integration accounts across portal identities.last_active_at: Most recent unexpired portal session activity (RFC 3339), when known.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct UserRecord {
pub id: i64,
pub role: UserRole,
pub status: UserStatus,
pub display_name: Option<String>,
pub login_name: Option<String>,
pub email: Option<String>,
pub has_password: bool,
pub security_version: i64,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
pub last_seen_at: Option<DateTime<Utc>>,
pub avatar_source: Option<String>,
pub totp_enabled: bool,
}
First-party Bookclerk user (security principal for portal paths).
Fields
id: Surrogate primary key assigned by the database.role: First-party role (owner,administrator, ormember).status: Lifecycle status for the row (user, request, …).display_name: Human-readable name shown in the UI.login_name: Local username for password login, when set.email: Optional contact email (notifications / magic-link invites later).has_password: Whether a local password hash is stored for this user.security_version: Incremented to invalidate existing sessions after security changes.created_at: RFC 3339 timestamp when the row was inserted.updated_at: RFC 3339 timestamp when the row was last modified.last_seen_at: Last authenticated portal activity (RFC 3339); survives session expiry.avatar_source: Explicit picture choice (monogram/gravatar/upload/sso:{id});Noneis auto.totp_enabled: True when a TOTP authenticator has been confirmed for local password login.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct UserSsoPicture {
pub identity_id: i64,
pub provider: String,
pub picture_url: String,
pub last_used_at: Option<DateTime<Utc>>,
}
IdP-supplied avatar available as a profile-picture choice.
Fields
identity_id:portal_identities.idthis picture belongs to.provider: Identity-broker id (oidc:google,oidc:github, …).picture_url: HTTPS URL to display (hotlinked from the IdP / CDN).last_used_at: Most recent portal session activity for this identity, when any.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct UserTitleState {
pub user_id: i64,
pub work_id: String,
pub is_finished: bool,
pub rating_overall: Option<f64>,
pub rating_performance: Option<f64>,
pub rating_story: Option<f64>,
pub tags: Option<String>,
pub updated_at: DateTime<Utc>,
}
One user's own state for one work (user_title_state).
Fields
user_id: The user (users.id) the state belongs to.work_id: The work (works.id) the state is about.is_finished: Whether the user finished the work.rating_overall: The user's overall rating (0 to 5), when given.rating_performance: The user's narration rating (0 to 5), when given.rating_story: The user's story rating (0 to 5), when given.tags: The user's tags, as one serialized string, when any.updated_at: When the state was last written.
Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize
pub struct WishlistPurchaseHint {
pub source: String,
pub product_id: String,
pub title: Option<String>,
pub url: Option<String>,
pub price_cents: Option<i64>,
pub currency: Option<String>,
pub price_label: Option<String>,
pub list_price_cents: Option<i64>,
pub list_price_label: Option<String>,
pub member_price_cents: Option<i64>,
pub member_price_label: Option<String>,
}
Snapshotted purchase link/price for a wishlist title.
Fields
source: Content-source plugin id (audible,libro, …).product_id: Storefront product id (ASIN, ISBN, UUID, …).title: Display title of the work or edition.url: Storefront product or purchase URL when known.price_cents: Observed price in minor currency units, when known.currency: ISO 4217 currency code for price fields.price_label: Storefront-formatted price string for display.list_price_cents: List/MSRP price in minor units, when known.list_price_label: Storefront-formatted list price for display.member_price_cents: Member/subscriber price in minor units, when known.member_price_label: Storefront-formatted member price for display.
pub fn hide_price_and_link(&mut self)
Removes the hint's store link and every price it carries, keeping the store and product id, for a patron whose "See prices and store links" member control is off.
Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Serialize, ToSchema
pub struct WishlistStoreEdition {
pub source: String,
pub product_id: String,
}
Storefront edition key for wishlist / queue payloads.
Fields
source: Content-source plugin id (audible,libro, …).product_id: Storefront product id (ASIN, ISBN, UUID, …).
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct WorkRecord {
pub id: String,
pub kind: String,
pub title: String,
pub parent_work_id: Option<String>,
pub credits: Vec<String>,
pub narrators: Vec<String>,
pub series: Vec<String>,
pub description: Option<String>,
pub subjects: Option<String>,
pub categories: Option<String>,
pub cover_url: Option<String>,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
Canonical work spanning one or more ownership rows / editions.
Fields
id: Work id (UUID).kind: Stored work kind (book,podcast_show,podcast_episode,drama).title: Display title.parent_work_id: The show a podcast episode belongs to.credits: Names credited on the work itself (authors, …), in billing order.narrators: Narrators credited on the work's expressions, each named once.series: Names of the series the work belongs to.description: Blurb / synopsis text (may contain HTML).subjects: Subject / topic tags from enrichment (serialized).categories: Store category / genre path list (serialized).cover_url: HTTPS URL for cover art when known.created_at: When the row was inserted.updated_at: When the row was last modified.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct NamedAtomicBackend<R> {
/* private fields */
}
An AtomicTxnBackend that compiles every named operation and hands the
plan to a NamedAtomicRunner.
pub fn on(db: DatabaseConnection) -> Self
The backend over db, an open and migrated library connection.
pub fn new(runner: R) -> Self
Wraps runner.
Implements: AtomicTxnBackend, Debug
pub struct SchemaWalk {
pub from: i64,
pub requested_to: i64,
pub stopped_at: i64,
pub ups: Vec<HostMigrationStep>,
pub downs: Vec<HostMigrationStep>,
pub blocked: bool,
}
Result of walking a host migration plan from one version to another.
Fields
from: Database version before the walk.requested_to: Version the caller asked to reach.stopped_at: Version the walk can actually reach (may be higher thanrequested_towhen an irreversible step blocks a downgrade).ups: Remainingupsteps in order (empty when rolling back).downs:downsteps newest-first (empty when upgrading).blocked: True when a missingdownstopped a rollback short ofrequested_to.
pub fn is_noop(&self) -> bool
True when no DDL remains to apply.
Implements: Clone, Debug, Eq, PartialEq
pub struct SessionClientInfo {
pub user_agent: Option<String>,
pub device_type: String,
pub client_label: String,
}
Parsed client presentation for a session row.
Fields
user_agent: Raw User-Agent (or syntheticAPI/ empty).device_type: High-level device class:desktop,mobile,tablet,api, orunknown.client_label: Human label such asWindows,macOS,Android,iPhone, orAPI.
Implements: Clone, Debug, Eq, PartialEq
pub struct FacetValue {
pub key: String,
pub value: String,
pub works: u64,
}
One value of a facet value list.
Fields
key: The value'sfacet_key, the list's order and cursor.value: The value as shown (one of its spellings).works: How many held works have it.
Implements: Clone, Debug, Eq, PartialEq
pub struct FacetValuesPage {
pub values: Vec<FacetValue>,
pub next: Option<String>,
}
One page of a facet value list.
Fields
values: The values, by key.next: The last key returned, where the next page starts;Noneon the last page.
Implements: Clone, Debug, Eq, PartialEq
pub struct LibraryWorkRow {
pub work_id: String,
pub kind: WorkKind,
pub title: String,
pub authors: Option<String>,
pub series: Option<String>,
pub series_position: Option<String>,
pub cover_edition_id: Option<String>,
pub media_kinds: Vec<MediaKind>,
pub acquire_status: AcquireStatus,
pub edition_count: u64,
pub holding_count: u64,
pub added_at: String,
pub length_minutes: Option<u64>,
pub purchased_at: Option<String>,
}
One row of the page index, as list views show it.
Fields
work_id: The work.kind: Book or podcast.title: Display title.authors: Authors (or hosts) joined for display.series: First series name.series_position: Position inSelf::series.cover_edition_id: The edition whose cover the list shows.media_kinds: Media kinds of the work's editions, sorted.acquire_status: The furthest acquire state any edition reached.edition_count: How many editions the work has.holding_count: How many holdings the work's listings have.added_at: RFC 3339 time of the newest holding.length_minutes: Runtime in minutes of the longest held edition, when known.purchased_at: RFC 3339 time of the newest purchase a store reported.
Implements: Clone, Debug, Eq, PartialEq
pub struct UnheldItem<'a> {
pub authors: Option<&'a str>,
pub narrators: Option<&'a str>,
pub series: Option<&'a str>,
pub genres: Option<&'a str>,
pub is_explicit: Option<bool>,
}
What a catalog item the library does not hold says about itself, read
by WorkScope::admits_unheld. People are comma- or
semicolon-separated, genres as the page index splits them.
Fields
authors: The item's authors, as one comma-separated string.narrators: The item's narrators, as one comma-separated string.series: The series name, without its position.genres: Genre labels, separated by,,;or|.is_explicit: Whether a store marks the item explicit (adult) content;Nonewhen no store said.
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub struct WorkCursor {
pub sort: WorkSort,
pub key: String,
pub title: Option<String>,
pub work_id: String,
}
Where the next page of a WorkSort order starts: the sort values of
the last row returned.
Fields
sort: The order the cursor belongs to; a cursor is refused under another.key: The last row's primary sort value (sort title, sort author, added-at stamp, series key, purchase stamp or runtime in minutes).title: The last row's sort title; set forWorkSort::AuthorandWorkSort::Series, whose ties break on title.work_id: The last row's work id, the final tie-break.
pub fn encode(&self) -> String
The opaque token a client sends back: URL-safe base64 of the JSON.
pub fn decode(token: &str) -> Result<Self>
Parses a token from Self::encode.
Returns LibraryError::Invalid when the token is not one this
library issued.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct WorkPage {
pub works: Vec<LibraryWorkRow>,
pub next: Option<WorkCursor>,
}
One page of library works.
Fields
works: The rows, in the requested order.next: Where the next page starts;Noneon the last page.
Implements: Clone, Debug, Eq, PartialEq
pub struct WorkPageQuery {
pub sort: WorkSort,
pub media_kind: Option<MediaKind>,
pub kind: Option<WorkKind>,
pub status: Option<AcquireStatus>,
pub account: Option<String>,
pub filter: Option<WorkFilter>,
pub scope: Option<WorkScope>,
pub after: Option<WorkCursor>,
pub limit: u64,
}
Filters and position of one page of library works.
Fields
sort: Order of the page.media_kind: Only works with an edition of this media kind.kind: Only works of this kind.status: Only works whose furthest acquire state is this one.account: Only works held by this store account id (any plugin).filter: Only works that pass this filter.scope: Only works inside this patron scope;Nonefor a caller who sees the whole library.after: Continue after this cursor.limit: Most rows to return; at least 1.
Implements: Clone, Debug, Default
pub struct WorkScope {
pub include: Vec<(WorkFacet, String)>,
pub exclude: Vec<(WorkFacet, String)>,
pub owner: Option<i64>,
}
The part of the library a patron may see, as the page index applies it.
A work passes when one of the patron's own store accounts holds it, or
when it matches no exclude value and, if there are include values,
matches at least one of them. Values are facet_keys of the page
index's facets.
Fields
include:(facet, key)pairs a work must match one of; empty lets every work through.exclude:(facet, key)pairs that hide a work, whateverincludesays.owner: The patron (users.id) whose linked store accounts' books always pass;Nonefor a caller with no accounts of their own.
pub fn sees_everything(&self) -> bool
True when the scope hides nothing.
pub fn admits_unheld(&self, item: &UnheldItem<'_>) -> bool
True when a catalog item the library does not hold may be shown to the patron: Discover shelves and storefront search results.
The item's own metadata stands in for the page index's facets, with the same rule: no exclude value matches and, when there are include values, one of them does. An item carries no library tag or collection, so a scope that includes only by those admits no catalog item, and excludes by them never hide one.
item- What the store listing says about the item.
pub fn key_set_id(&self) -> String
Content id of the scope's include and exclude values: lowercase hex
SHA-256 over its (effect, facet, key) rows, sorted and without
duplicates, each field length-prefixed, so two
scopes share an id exactly when they hold the same values.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct EditionDetail {
pub id: String,
pub work_id: String,
pub expression_id: String,
pub expression_kind: ExpressionKind,
pub language: Option<String>,
pub abridgement: Abridgement,
pub media_kind: MediaKind,
pub title: String,
pub subtitle: Option<String>,
pub published_at: Option<String>,
pub duration_minutes: Option<i64>,
pub cover_url: Option<String>,
pub acquire_status: AcquireStatus,
pub listings: Vec<EditionListing>,
}
One edition of a work with its expression and listings.
Fields
id: Edition id.work_id: The work the edition realises: the work itself, or one of a show's episodes.expression_id: The expression the edition carries.expression_kind: How the expression realises the work.language: The expression's language tag, when known.abridgement: Whether the expression is abridged.media_kind: Carrier of the edition.title: The edition's title.subtitle: The edition's subtitle.published_at: Publication date as the store gave it.duration_minutes: Running time in minutes, for audio.cover_url: Cover image URL from the store, when known.acquire_status: The edition's acquire state.listings: The edition's listings, by id.
Implements: Clone, Debug, PartialEq
pub struct EditionListing {
pub id: String,
pub plugin_key: String,
pub marketplace: String,
pub product_id: String,
pub url: Option<String>,
pub holdings: Vec<ListingHolding>,
}
One store listing of an edition.
Fields
id: Listing id.plugin_key: The storefront plugin that lists it.marketplace: Store marketplace (us,uk, …), empty when the store has one.product_id: The store's product id (ASIN, ISBN, product UUID, …).url: The product page, when known.holdings: The listing's holdings, by id.
Implements: Clone, Debug, Eq, PartialEq
pub struct ListingHolding {
pub id: String,
pub holder: HoldingHolder,
pub entitlement: Entitlement,
pub purchased_at: Option<String>,
pub added_at: String,
}
One holding of a listing.
Fields
id: Holding id.holder: Who holds the listing.entitlement: On what terms the holder has it.purchased_at: RFC 3339 purchase time, when the store reported one.added_at: RFC 3339 time the holding was first recorded.
Implements: Clone, Debug, Eq, PartialEq
pub struct WorkDetail {
pub id: String,
pub kind: WorkKind,
pub title: String,
pub description: Option<String>,
pub authors: Vec<String>,
pub series: Option<String>,
pub series_position: Option<String>,
pub editions: Vec<EditionDetail>,
}
A top-level work with everything its detail view shows.
Fields
id: Work id.kind: Book or podcast.title: Display title.description: Blurb or synopsis (may contain HTML).authors: Authors (hosts for a podcast), in billing order.series: First series name.series_position: Position inSelf::series.editions: Editions, by id; a show's episodes' editions included.
Implements: Clone, Debug, PartialEq
pub struct WorkSearchDoc {
pub work_id: String,
pub title: String,
pub other_titles: Vec<String>,
pub authors: Vec<String>,
pub narrators: Vec<String>,
pub series: Vec<String>,
pub identifiers: Vec<String>,
}
The searchable text of one held top-level work.
Fields
work_id: The work (a podcast's show, never an episode).title: The work's title.other_titles: Distinct edition and listing titles and subtitles other thanSelf::title(episode titles, for a show).authors: Authors (hosts, for a podcast), from the model's credits and the listings' author text.narrators: Narrators, from the listings' narrator text.series: Series names, from the model and the listings.identifiers: Product ids of the listings and identifier values (ISBN, ASIN and others) of the editions, lowercased.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct WorkTag {
pub value: String,
pub source: WorkTagSource,
}
One library tag on a work.
Fields
value: The tag as written.source: Where it came from.
Implements: Clone, ComposeSchema, Debug, Eq, PartialEq, Serialize, ToSchema
pub struct WorkTagsBody {
/* private fields */
}
PUT /api/library/works/{id}/tags body: the tags an Administrator sets.
pub fn validate(self) -> Result<WorkTagsRequest>
Checks the body (normalize_work_tags).
Returns LibraryError::Invalid for too many or too long tags.
Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema
pub struct WorkTagsRequest {
/* private fields */
}
A validated [WorkTagsBody]: at most MAX_WORK_TAGS distinct tags
(by facet_key), trimmed, each 1 to MAX_WORK_TAG_BYTES bytes, in
the order sent with the first spelling kept.
pub fn tags(&self) -> &[String]
The tags as written, trimmed and distinct.
Implements: Clone, Debug, Eq, PartialEq
pub struct CatalogListing {
pub draft: ListingDraft,
pub detail: ListingDetail,
pub offers: Vec<ListingOffer>,
}
One title a store's catalog answer reported.
Fields
draft: What the resolver sees: key, kinds, title, identifiers, credits and series. Its plugin key and marketplace must be set.detail: The store's own text for it.offers: Prices the answer quoted (often none: search hits rarely price).
Implements: Clone, Debug
pub struct CatalogListingRecord {
pub id: String,
pub plugin_key: String,
pub marketplace: String,
pub product_id: String,
pub edition_id: String,
pub work_id: Option<String>,
pub expression_id: Option<String>,
pub title: String,
pub categories: Option<String>,
pub detail: ListingDetail,
pub asin: Option<String>,
pub isbn: Option<String>,
pub offers: Vec<ListingOffer>,
pub observed_at: DateTime<Utc>,
}
A stored catalog listing, as Discover and the wishlist read it.
Fields
id:store_listings.id.plugin_key: Provenance-qualified PluginKey of the store.marketplace: Lower-cased marketplace.product_id: The store's product id.edition_id: The edition the listing sells.work_id: That edition's work, when the rows are consistent.expression_id: That edition's expression (expressions.id), when the rows are consistent. Listings of one expression are the same recording or text, so their prices compare; listings of one work in different expressions (a narration and a full-cast dramatisation) do not.title: Title as the store lists it.categories: Store category labels.detail: The store's own text.asin: ASIN of the edition, preferring one scoped to the marketplace.isbn: An ISBN of the edition.offers: Stored prices, one per audience.observed_at: When a store last reported the listing.
pub fn offer(&self, audience: OfferAudience) -> Option<&ListingOffer>
The stored offer for audience.
Implements: Clone, Debug
pub struct ListingDetail {
pub subtitle: Option<String>,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub series_product_id: Option<String>,
pub description: Option<String>,
pub publisher: Option<String>,
pub published_at: Option<String>,
pub length_minutes: Option<i64>,
pub language: Option<String>,
pub cover_url: Option<String>,
pub url: Option<String>,
pub rating_overall: Option<f64>,
pub rating_count: Option<i64>,
pub is_abridged: Option<bool>,
pub is_explicit: Option<bool>,
}
The store's own text for a listing, beyond the title the resolver sees.
Display only: credits and series here are as the store prints them, and nothing matches on them.
Fields
subtitle: Subtitle.authors: Authors, comma-separated.narrators: Narrators, comma-separated.series: Series name.series_index: Position in the series (1,2.5).series_product_id: The store's own product id for the series or podcast show (an Audible series ASIN); store-specific, so it lives on the listing.description: Synopsis, kept whole.publisher: Publisher or imprint.published_at: Publication date as the store reports it.length_minutes: Runtime in whole minutes.language: Language code (en).cover_url: Cover image URL.url: Product page URL.rating_overall: Community rating (0 to 5).rating_count: How many ratings back the rating.is_abridged: Abridged (true), unabridged (false) or unknown.is_explicit: Explicit (adult) content (true), clean (false) or unknown.
pub fn of_new_book(book: &NewBook) -> Self
The store text a scanned library title carries, for its listing.
Only the fields a scan reports are taken. A title the store marks unabridged is left unknown, since a scan record cannot tell unabridged from unreported.
pub fn of_catalog_hit(hit: &CatalogHit) -> Self
The store text of a storefront catalog record, as the store reported it.
Everything the record carries is taken, including cover, synopsis,
product page and rating; a podcast episode's show product becomes
Self::series_product_id. HTML entities are left as the record
has them.
Implements: Clone, Debug, Default, PartialEq
pub struct ListingOffer {
pub audience: OfferAudience,
pub price_cents: Option<i64>,
pub price_label: Option<String>,
pub currency: Option<String>,
pub observed_at: DateTime<Utc>,
}
One price a store quoted for one listing and audience.
Fields
audience: Who pays it.price_cents: Price in minor units ofSelf::currency, when the store gave one.price_label: The store's formatted price ($14.95), when it gave one.currency: ISO 4217 currency code.observed_at: When the store quoted it.
pub fn is_empty(&self) -> bool
True when the offer carries neither a price nor a label.
Implements: Clone, Debug, PartialEq
pub struct RecordedListings {
pub ids: Vec<Option<String>>,
pub unresolved: usize,
}
What LibraryStore::record_catalog_listings stored for one answer.
Fields
ids: One entry per input, in order: the listing id, orNonefor a title that was not stored.unresolved: How many valid titles could not be resolved this time (other writers kept changing their rows on every attempt). An answer with any is incomplete and should not be cached, so those titles are tried again.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct Chapter {
pub title: String,
pub start_ms: u64,
pub depth: u32,
}
One chapter of a checked list.
Named EditionChapter in the OpenAPI documents, apart from the player
apps' Chapter.
Fields
title: Chapter title; never empty, at most 512 bytes, no control characters.start_ms: Start, in milliseconds from the start of the edition's timeline.depth: Nesting depth; 0 for a top-level chapter, at most 7. A chapter at depth n + 1 is nested under the nearest earlier chapter at depth n.
Implements: Clone, ComposeSchema, Debug, Eq, PartialEq, Serialize, ToSchema
pub struct ChapterClaim {
pub source_kind: ChapterSourceKind,
pub source_id: String,
pub quality: ClaimQuality,
pub digest: ChapterDigest,
pub chapter_count: Option<u64>,
pub runtime_ms: Option<u64>,
pub input_digest: Option<ChapterDigest>,
pub revision: i64,
pub pinned_at: Option<String>,
pub created_by_user_id: Option<i64>,
pub updated_at: String,
}
One stored chapter claim, without its list.
Fields
source_kind: The kind of source.source_id: Which source of that kind (a PluginKey; empty for a person's edit and for Bookclerk's processing).quality: Where a machine source ranks within its kind.digest: The claimed list.chapter_count: How many chapters the list has;Nonewhile its write is unfinished.runtime_ms: Length of the timeline the list was measured on, in milliseconds.input_digest: For a processed claim, the list it was derived from.revision: The edition's claim counter when this claim last changed.pinned_at: When an Administrator pinned it (RFC 3339).created_by_user_id: The person whose edit it is.updated_at: When it last changed (RFC 3339).
Implements: Clone, Debug, Eq, PartialEq
pub struct ChapterClaimWrite {
pub source: ChapterSource,
pub list: ChapterList,
pub runtime_ms: Option<u64>,
}
A claim to record (LibraryStore::record_chapter_claim).
Fields
source: Who states it.list: The chapters.runtime_ms: Length of the timeline the chapters were measured on, in milliseconds, when known.
Implements: Clone, Debug
pub struct ChapterDigest(/* private */);
Lower-case hex SHA-256 naming one stored chapter list
(ChapterList::digest).
pub fn parse(stored: &str) -> Option<Self>
Reads a stored digest, refusing anything but 64 lower-case hex characters.
pub fn as_str(&self) -> &str
The digest as stored.
Implements: Clone, Debug, Display, Eq, Hash, Ord, PartialEq, PartialOrd
pub struct ChapterInput {
pub title: String,
pub start_ms: u64,
pub depth: u32,
}
One chapter as a source states it, before it is checked.
Fields
title: Chapter title.start_ms: Start, in milliseconds from the start of the edition's timeline.depth: Nesting depth; 0 for a top-level chapter.
Implements: Clone, Debug, Eq, PartialEq
pub struct ChapterList(/* private */);
A checked chapter list, in pre-order with starts never decreasing.
Every list satisfies: at most MAX_CHAPTERS chapters; each title
non-empty, at most MAX_CHAPTER_TITLE_BYTES bytes, free of control
characters and of leading or trailing white space; each start at most
MAX_CHAPTER_START_MS and no earlier than the one before; the first
depth 0 and each later depth at most one more than the one before and
at most MAX_CHAPTER_DEPTH.
pub fn new(input: Vec<ChapterInput>, check: ChapterCheck) -> Result<Self>
Checks input into a list.
input- The chapters in pre-order.check- Whether to refuse or repair what breaks a rule.
Returns LibraryError::Invalid naming the first chapter that
breaks a rule ChapterCheck does not repair.
pub fn chapters(&self) -> &[Chapter]
The chapters, in pre-order.
pub fn is_empty(&self) -> bool
True when the list has no chapters.
pub fn spans(&self, end_ms: Option<u64>) -> Vec<ChapterSpan>
The chapters as spans a player can seek between: in pre-order, each
ending where the next one starts, as Audiobookshelf flattens a
tree, and the last ending at end_ms.
end_ms- Where the timeline ends, in milliseconds.None, or a value before the last chapter's start, ends the last chapter at its own start.
One span per chapter, starts non-decreasing, every end at or after its start.
pub fn digest(&self) -> ChapterDigest
The list's digest: SHA-256 over each chapter's start (8 bytes, big endian), depth (4 bytes), title length (4 bytes) and title bytes, in order.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct ChapterSpan {
pub title: String,
pub start_ms: u64,
pub end_ms: u64,
pub depth: u32,
}
One chapter as a player seeks between them: where it starts and ends
on the edition's timeline (ChapterList::spans).
Fields
title: Chapter title.start_ms: Start, in milliseconds from the start of the edition's timeline.end_ms: End, in milliseconds: the next chapter's start, or the end of the timeline for the last chapter; never beforestart_ms.depth: Nesting depth; 0 for a top-level chapter. A chapter at depth n + 1 is nested under the nearest earlier chapter at depth n.
Implements: Clone, ComposeSchema, Debug, Eq, PartialEq, Serialize, ToSchema
pub struct EditionChapters {
pub list: ChapterList,
pub source_kind: ChapterSourceKind,
pub source_id: String,
pub runtime_ms: Option<u64>,
}
The chapters an edition resolved to.
Fields
list: The chapters; empty when an Administrator cleared them.source_kind: The winning claim's source kind.source_id: The winning claim's source id.runtime_ms: Length of the timeline the list was measured on, in milliseconds.
Implements: Clone, Debug, Eq, PartialEq
pub struct ChapterEditBody {
/* private fields */
}
PUT /api/library/editions/{id}/chapters body: the edition's chapters
as an Administrator sets them, in pre-order. An empty list clears them.
pub fn validate(self) -> Result<ChapterList>
Checks the chapters strictly (ChapterCheck::Strict).
Returns LibraryError::Invalid naming the first chapter that
breaks a rule.
Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema
pub struct ChapterEditEntry {
/* private fields */
}
One chapter of an edit, as JSON carries it.
Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema
pub struct ChapterPinBody {
/* private fields */
}
PUT /api/library/editions/{id}/chapters/pin body: the claim to pin.
pub fn validate(self) -> Result<ChapterPinRequest>
Checks the source id's length and characters.
Returns LibraryError::Invalid for a source id over
MAX_CHAPTER_SOURCE_ID_BYTES or with a control character.
Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema
pub struct ChapterPinRequest {
pub source_kind: ChapterSourceKind,
pub source_id: String,
}
A checked pin request.
Fields
source_kind: The claim's source kind.source_id: The claim's source id.
Implements: Clone, Debug, Eq, PartialEq
pub struct TitleQuery<'a> {
pub title: &'a str,
pub authors: Option<&'a str>,
pub asin: Option<&'a str>,
pub isbn: Option<&'a str>,
pub series: Option<&'a str>,
pub series_index: Option<&'a str>,
}
A title someone asks about (a wish, a catalog card): what the resolver needs to say which work it belongs to.
Fields
title: Display title.authors: Comma-separated authors, when known.asin: Audible ASIN, when known.isbn: ISBN, when known.series: Series name, when known.series_index: Position in the series, when known.
Implements: Clone, Debug, Default
pub struct WorkEnrichment {
pub description: Option<String>,
pub subjects: Option<String>,
pub categories: Option<String>,
pub cover_url: Option<String>,
}
Enrichment fields for LibraryStore::set_work_enrichment.
Fields
description: Blurb / synopsis text.subjects: Subject tags (serialized).categories: Category labels (serialized).cover_url: HTTPS cover URL.
pub fn of_new_book(book: &NewBook) -> Self
The fields a scanned library title offers its work: its store categories (a scan reports no synopsis, subjects or cover).
pub fn is_empty(&self) -> bool
True when no field is set.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct ListeningIdentifiers {
pub asin: Option<String>,
pub isbn: Option<String>,
}
The identifiers a listening item names its book by, as the provider reported them (any case and punctuation; normalised here).
Fields
asin: Amazon / Audible ASIN, when the provider knows it.isbn: ISBN-10 or ISBN-13, when the provider knows it.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct ListeningMatch {
pub work_id: Option<String>,
pub edition_id: Option<String>,
}
What one listening item resolved to in the library.
Fields
work_id: Work the item's identifiers resolve to, when they name exactly one.edition_id: Edition carrying the identifier that decided the work, when exactly one edition carries it.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct ListeningProgressWrite {
pub before: Option<ListeningProgressRecord>,
pub after: NewListeningProgress,
}
One stored listening row a batched write produced.
Fields
before: The stored row before this write;Nonewhen the write inserted it.after: The row as written: every report for its key merged overbeforethe wayLibraryStore::upsert_listening_progressmerges one.
Implements: Clone, Debug
pub struct ConflictCursor {
pub listing_id: String,
pub kind: String,
pub subject_ids: String,
}
Where a conflicts page stopped: the last row's key, in key order.
Fields
listing_id: The last row's listing id.kind: The last row's kind.subject_ids: The last row's stored subject ids (a JSON array).
pub fn encode(&self) -> String
The cursor as an opaque URL-safe token.
pub fn decode(token: &str) -> Result<Self>
Reads a token made by Self::encode.
Returns LibraryError::Invalid when the token is not one.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct ResolutionConflict {
pub listing_id: String,
pub kind: String,
pub subject_ids: Vec<String>,
pub plugin_key: String,
pub product_id: String,
pub title: String,
pub edition_id: String,
pub updated_at: String,
}
One conflict the resolver recorded for an Administrator.
Fields
listing_id: The listing whose resolution conflicted.kind:strong_identifiers,work_identifiers,ambiguous_workorwork_kind_mismatch.subject_ids: The edition ids (strong_identifiers) or work ids (the other kinds) involved, sorted.plugin_key: The listing's storefront PluginKey.product_id: The store's product id.title: The listing's title as the store reported it.edition_id: The edition the listing sells now.updated_at: RFC 3339 time the conflict was last seen.
Implements: Clone, Debug, Eq, PartialEq
pub struct AccountPaceState {
pub override_: PaceOverride,
pub cooldown_until: Option<DateTime<Utc>>,
pub window: DownloadWindow,
}
One account's pacing state as stored.
Fields
override_: The operator's override of the storefront's pace.cooldown_until: End of the store's cool-down, when one is set (it may be past).window: Downloads in the lastBUDGET_WINDOW, oldest first.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct DownloadId(/* private */);
One store download's ledger identity.
It is made once, when a download is kept for recording, and every write attempt of that download passes the same one, so a write that committed but whose answer was lost inserts no second row when it is tried again.
pub fn new() -> Self
A fresh identity (a random UUID) for a new download.
pub fn as_str(&self) -> &str
The identity as the ledger's id column stores it.
Implements: Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd
pub struct Bookmark {
pub id: String,
pub user_id: i64,
pub edition_id: String,
pub position: PlaybackMs,
pub title: String,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
A place one person marked in one edition.
Fields
id: Bookmark id (hyphenated UUID).user_id: The person who made it (users.id).edition_id: The edition it is in.position: The marked place.title: The person's note; may be empty.created_at: When it was made.updated_at: When it last changed.
Implements: Clone, Debug, Eq, PartialEq
pub struct NewPlaybackSession<'a> {
pub user_id: i64,
pub edition_id: &'a str,
pub serving_node_id: &'a str,
pub destination: &'a str,
pub files_digest: &'a str,
pub client_kind: PlayerKind,
pub client_name: &'a str,
}
A play session to open (LibraryStore::open_playback_session).
Fields
user_id: The listener (users.id).edition_id: The edition to play.serving_node_id: This node's id: it streams the files.destination: The destination the files will be read from.files_digest: Digest of the edition's file rows on that destination (crate::control_plane::PlaybackPlan::digest).client_kind: What kind of player asks.client_name: The player's own name; at mostMAX_PLAYER_NAME_BYTESbytes are kept.
Implements: Clone, Copy, Debug
pub struct PlaybackChange {
pub progress: PlaybackProgress,
pub became_finished: bool,
}
The result of a sync or of setting progress outright.
Fields
progress: The person's progress after the write.became_finished: True when this write is the one that reached the edition's end.
Implements: Clone, Debug, Eq, PartialEq
pub struct PlaybackEdition {
pub edition_id: String,
pub work_id: Option<String>,
pub title: String,
pub runtime: Option<PlaybackMs>,
}
What the player needs to know of an edition before it plays
(LibraryStore::playback_edition).
Fields
edition_id: The edition.work_id: The work it belongs to;Noneonly while the edition is being moved between works.title: The edition's display title.runtime: Its runtime as the catalog states it, to the minute; players report the exact one once they have loaded the audio.
Implements: Clone, Debug, Eq, PartialEq
pub struct PlaybackMs(/* private */);
A length of time on a recording's timeline, in milliseconds: a
position, a duration or time listened. At most MAX_PLAYBACK_MS.
pub const ZERO: Self = _
The start of a recording.
pub fn new(ms: u64) -> Option<Self>
ms as a timeline length.
None when ms is past MAX_PLAYBACK_MS.
pub fn get(self) -> u64
The length in milliseconds.
Implements: Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd
pub struct PlaybackProgress {
pub user_id: i64,
pub edition_id: String,
pub position: PlaybackMs,
pub duration: Option<PlaybackMs>,
pub is_finished: bool,
pub started_at: DateTime<Utc>,
pub finished_at: Option<DateTime<Utc>>,
pub updated_at: DateTime<Utc>,
}
How far one person has listened to one edition.
Fields
user_id: The listener (users.id).edition_id: The edition.position: Where they are on the edition's timeline.duration: The edition's runtime as the last player reported it.is_finished: True once they reached the end of this edition.started_at: When they first played it.finished_at: When they last reached the end.updated_at: When the row last changed.
Implements: Clone, Debug, Eq, PartialEq
pub struct PlaybackProgressEdit {
pub position: Option<PlaybackMs>,
pub duration: Option<PlaybackMs>,
pub finished: Option<bool>,
}
Progress to set outright (LibraryStore::set_playback_progress): a
seek from a page with no session, Mark finished, or Start over.
Fields
position: The position to store;Nonekeeps it.duration: The runtime to store;Nonekeeps it.finished:Some(true)marks the edition (and its work) finished,Some(false)clears the edition's flag only,Nonedecides from the position and runtime.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct PlaybackSession {
pub id: String,
pub user_id: i64,
pub edition_id: String,
pub serving_node_id: String,
pub destination: String,
pub files_digest: String,
pub client_kind: PlayerKind,
pub client_name: String,
pub start_position: PlaybackMs,
pub position: PlaybackMs,
pub listened: PlaybackMs,
pub started_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
pub closed_at: Option<DateTime<Utc>>,
}
One stretch of listening on one player.
Fields
id: Session id (hyphenated UUID).user_id: The listener (users.id).edition_id: The edition being played.serving_node_id: The node that opened the session and streams its files.destination: The destination the files are read from.files_digest: Digest of the edition's file rows when the session opened.client_kind: What kind of player opened it.client_name: The player's own name for itself.start_position: Where the session started from.position: Where it was at the last sync.listened: Time spent listening in it, as the player counted.started_at: When it opened.updated_at: When it last synced.closed_at: When the player closed it;Nonewhile open.
Implements: Clone, Debug, Eq, PartialEq
pub struct PlaybackSync {
pub position: PlaybackMs,
pub listened: PlaybackMs,
pub duration: Option<PlaybackMs>,
pub close: bool,
}
What a player reports about a playing session
(LibraryStore::sync_playback_session).
Fields
position: Where the listener is now.listened: Time listened since the last sync of this session.duration: The recording's whole runtime, when the player knows it.close: True when this is the session's last report: it closes.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct ProgressCursor {
pub updated_at: String,
pub edition_id: String,
}
A page position of [LibraryStore::list_playback_progress]: the last
row of the page before.
Fields
updated_at: That row'supdated_at, as stored.edition_id: That row's edition.
Implements: Clone, Debug, Eq, PartialEq
pub struct BookmarkEditBody {
/* private fields */
}
PUT /api/playback/bookmarks/{id} body: what to change. A field left
out keeps its stored value.
pub fn validate(self) -> Result<BookmarkEditRequest>
Checks the body.
Returns LibraryError::Invalid for a position past
MAX_PLAYBACK_MS, or a title that is too long or has a control
character.
Implements: ComposeSchema, Debug, Default, Deserialize<'de>, ToSchema
pub struct BookmarkEditRequest {
pub position: Option<PlaybackMs>,
pub title: Option<String>,
}
A checked change to a bookmark.
Fields
position: The new place;Nonekeeps it.title: The new note, trimmed;Nonekeeps it.
Implements: Clone, Debug, Eq, PartialEq
pub struct NewBookmarkBody {
/* private fields */
}
POST /api/library/editions/{id}/bookmarks body.
pub fn validate(self) -> Result<NewBookmarkRequest>
Checks the body.
Returns LibraryError::Invalid for a position past
MAX_PLAYBACK_MS, or a title that is too long or has a control
character.
Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema
pub struct NewBookmarkRequest {
pub position: PlaybackMs,
pub title: String,
}
A checked bookmark to add.
Fields
position: The place to mark.title: The note, trimmed; may be empty.
Implements: Clone, Debug, Eq, PartialEq
pub struct OpenSessionBody {
/* private fields */
}
POST /api/playback/sessions body.
pub fn validate(self) -> Result<OpenSessionRequest>
Checks the body and tidies the player's name.
Returns LibraryError::Invalid for an empty edition id or one
over MAX_EDITION_ID_BYTES.
Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema
pub struct OpenSessionRequest {
pub edition_id: String,
pub player: PlayerKind,
pub player_name: String,
}
A checked request to open a play session.
Fields
edition_id: The edition to play, as sent.player: What kind of player asks.player_name: The player's name as stored: no control characters, trimmed, at mostMAX_PLAYER_NAME_BYTESbytes.
Implements: Clone, Debug, Eq, PartialEq
pub struct PlaybackSyncBody {
/* private fields */
}
POST /api/playback/sessions/{id}/sync and .../close body: where
the listener is.
pub fn validate(self, close: bool) -> Result<PlaybackSync>
Checks the body: every length at most MAX_PLAYBACK_MS.
close- True for thecloseroute: the report ends the session.
Returns LibraryError::Invalid naming the field that is too
large.
Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema
pub struct ProgressEditBody {
/* private fields */
}
PUT /api/playback/progress/{edition_id} body: what to set. A field
left out keeps its stored value.
pub fn validate(self) -> Result<PlaybackProgressEdit>
Checks the body: every length at most MAX_PLAYBACK_MS.
Returns LibraryError::Invalid naming the field that is too
large.
Implements: ComposeSchema, Debug, Default, Deserialize<'de>, ToSchema
pub struct TrackPath {
pub session_id: String,
pub index: usize,
}
The file a stream request names (parse_track_path).
Fields
session_id: The play session's id: a hyphenated lowercase UUID.index: The track's index in the session's list, belowMAX_PLAYBACK_TRACKS.
Implements: Clone, Debug, Eq, PartialEq
pub struct NewPlayerCard<'a> {
pub identity_id: i64,
pub session_hash: &'a str,
pub password_id: Option<&'a str>,
pub label: &'a str,
pub user_agent: Option<&'a str>,
pub device_type: &'a str,
pub tokens: PlayerCardTokens<'a>,
}
A new player card (LibraryStore::mint_player_card).
Fields
identity_id: The portal identity the card signs in as.session_hash: SHA-256 hex of random bytes nobody is given: the session row's own token hash, unique per card.password_id: The player password it was made with, when it was.label: The app's name, shown in the session list.user_agent: The app'sUser-Agent, when it sent one.device_type: Best-effort device class (mobile,tablet,desktop,api).tokens: The card's first tokens.
Implements: Clone, Copy, Debug
pub struct PlayerCard {
pub session_id: i64,
pub identity: PortalIdentity,
}
A live player card, as an access token resolves to it.
Fields
session_id: The card'sportal_sessions.id.identity: The identity it signs in as.
Implements: Clone, Debug
pub struct PlayerCardTokens<'a> {
pub access_hash: &'a str,
pub refresh_hash: &'a str,
}
What signing a card in or refreshing it hands out, as digests: the caller holds the tokens themselves.
Fields
access_hash: SHA-256 hex of the new access token.refresh_hash: SHA-256 hex of the new refresh token.
Implements: Clone, Copy, Debug
pub struct PlayerPassword {
pub id: String,
pub user_id: i64,
pub label: String,
pub created_at: DateTime<Utc>,
pub last_used_at: Option<DateTime<Utc>>,
}
A player password as its owner sees it in Account settings.
Fields
id: Password id.user_id: The patron it signs in as.label: The name the patron gave it.created_at: When it was made.last_used_at: When it last signed an app in.
Implements: Clone, Debug, Eq, PartialEq
pub struct PlayerFacet {
pub key: String,
pub value: String,
}
One value of the page index on an item: its key and how it is written.
Fields
key: The value's key (crate::facet_key), what a filter matches.value: The value as shown.
Implements: Clone, Debug, Eq, PartialEq
pub struct PlayerItem {
pub edition_id: String,
pub work_id: String,
pub title: String,
pub subtitle: Option<String>,
pub description: Option<String>,
pub published_at: Option<String>,
pub runtime_minutes: Option<u64>,
pub language: Option<String>,
pub abridged: bool,
pub authors: Vec<PlayerFacet>,
pub narrators: Vec<PlayerFacet>,
pub series: Vec<PlayerFacet>,
pub series_position: Option<String>,
pub genres: Vec<String>,
pub publishers: Vec<String>,
pub isbn: Option<String>,
pub asin: Option<String>,
pub added_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
What the player API shows of one item (LibraryStore::player_items).
Fields
edition_id: The edition: the item id.work_id: Its work.title: The edition's title.subtitle: Its subtitle.description: The work's description (may hold markup).published_at: The publication date as the store gave it.runtime_minutes: The runtime the catalog states, in whole minutes.language: The expression's language tag.abridged: True when the expression is abridged.authors: Authors, in the order the work's row lists them.narrators: Narrators.series: Series, the work's first series first.series_position: The work's place in its first series, as written.genres: Genres.publishers: Publishers.isbn: The edition's ISBN, when known.asin: The edition's ASIN, when known.added_at: When the library acquired it.updated_at: When its record last changed.
Implements: Clone, Debug, PartialEq
pub struct PluginDatabaseRecord {
pub plugin_id: String,
pub binding: String,
pub adapter_plugin_key: String,
pub backend_kind: String,
pub unit_ref: String,
pub created_at: String,
}
One provisioned plugin database binding registry row.
Fields
plugin_id: Owning plugin PluginKey (canonical text).binding: Binding name fromplugin.tomlcapabilities.bindings.databases.adapter_plugin_key: Adapter PluginKey that provisioned the physical unit.backend_kind: Diagnostic adapter family (sqlite,postgres,d1, or custom).unit_ref: Backend-native unit: file path, schema name, or D1 database name.created_at: RFC 3339 provisioning time.
Implements: Clone, Debug, Eq, PartialEq
pub struct KvEntry {
pub key: String,
pub value: Vec<u8>,
pub metadata: String,
pub expires_at: Option<DateTime<Utc>>,
}
One live key/value row.
Fields
key: Key within the namespace.value: Value bytes.metadata: Opaque JSON metadata text; empty when none.expires_at: Absolute expiry, when set.
Implements: Clone, Debug, Eq, PartialEq
pub struct KvListPage {
pub keys: Vec<KvEntry>,
pub list_complete: bool,
pub cursor: String,
}
One page of LibraryStore::kv_list.
Fields
keys: Keys in lexical order (values are not loaded).list_complete: True when no further page exists.cursor: Opaque cursor for the next page; empty when complete.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct KvWriteSpec {
pub value: Vec<u8>,
pub metadata: String,
pub expires_at: Option<DateTime<Utc>>,
pub max_value_bytes: u32,
pub max_keys: u32,
}
A write plus the namespace limits it must satisfy.
Fields
value: Value bytes.metadata: Opaque JSON metadata text; empty when none.expires_at: Absolute expiry;Nonenever expires.max_value_bytes: Largest value this namespace accepts.max_keys: Most live keys this namespace holds.
Implements: Clone, Debug, Eq, PartialEq
pub struct PassStart {
pub cursor: String,
pub sync_token: String,
pub resumed: bool,
pub pass_id: String,
}
How the next pass of one account starts.
Fields
cursor: Cursor of the first page to ask for; empty starts at the beginning.sync_token: Sync token to send; empty asks for a full pass.resumed: True when the pass resumes one that stopped part way.pass_id: Id of the pass, stamped on every holding a page lists (holdings.seen_pass); a resumed pass keeps the id its earlier pages stamped.
Implements: Clone, Debug, Eq, PartialEq
pub struct QualityCheckState {
pub cursor: String,
pub checked_at: Option<DateTime<Utc>>,
}
Where the quality-upgrade check of one account stands.
Fields
cursor: Holding id the next check continues after; empty to start from the account's first holding.checked_at: When the check last ran;Nonebefore it first ran.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct ScanState {
pub sync_token: String,
pub resume_cursor: String,
pub resume_token: String,
pub last_complete_at: Option<DateTime<Utc>>,
pub pass_id: String,
pub updated_at: DateTime<Utc>,
}
Where one account's scan stands.
Fields
sync_token: Opaque token from the end of the last pass; empty for none.resume_cursor: Cursor of a stopped pass's next page; empty when none.resume_token: Token the stopped pass started with.last_complete_at: When the last complete pass ended.pass_id: Id of the pass in progress or last run; empty before the first.updated_at: When the row was last written.
Implements: Clone, Debug, Eq, From<Model>, PartialEq
pub struct UserStateEdit {
pub is_finished: Option<bool>,
pub rating_overall: FieldEdit<f64>,
pub rating_performance: FieldEdit<f64>,
pub rating_story: FieldEdit<f64>,
pub tags: FieldEdit<String>,
}
A change to one user's state for one work, applied by
LibraryStore::edit_user_title_state.
Fields
is_finished: The finished flag to store;Nonekeeps it (a new row starts unfinished).rating_overall: Overall rating, 0 to 5.rating_performance: Narration rating, 0 to 5.rating_story: Story rating, 0 to 5.tags: Tags, whitespace-separated.
Implements: Clone, Debug, Default, PartialEq
pub struct WorkSplitBody {
/* private fields */
}
POST /api/library/works/{id}/split body: the expressions to move.
pub fn validate(self) -> Result<WorkSplitRequest>
Checks the body: every id 1 to MAX_SPLIT_EXPRESSION_ID_BYTES
bytes, and 1 to MAX_SPLIT_EXPRESSIONS distinct ids (a repeated
id counts once).
Returns LibraryError::Invalid for an empty or overlong id, or a
count outside the bounds.
Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema
pub struct WorkSplitRequest {
/* private fields */
}
A validated [WorkSplitBody]: 1 to MAX_SPLIT_EXPRESSIONS distinct
expression ids, each 1 to MAX_SPLIT_EXPRESSION_ID_BYTES bytes,
sorted.
pub fn expression_ids(&self) -> &[String]
The expressions to move, sorted and distinct.
Implements: Clone, Debug, Eq, PartialEq
pub struct AcquireTitle {
pub holding_id: String,
pub edition_id: String,
pub listing_id: String,
pub plugin_key: String,
pub source: String,
pub account_id: String,
pub marketplace: String,
pub product_id: String,
pub asin: Option<String>,
pub isbn: Option<String>,
pub title: String,
pub subtitle: Option<String>,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub series_product_id: Option<String>,
pub publisher: Option<String>,
pub categories: Option<String>,
pub length_minutes: Option<i64>,
pub language: Option<String>,
pub is_abridged: bool,
pub content_kind: &'static str,
pub purchased_at: Option<DateTime<Utc>>,
pub added_at: Option<DateTime<Utc>>,
pub published_at: Option<DateTime<Utc>>,
pub status: AcquireStatus,
pub storage_key: Option<String>,
pub acquired_by: Option<String>,
pub pdf_status: AcquireStatus,
pub pdf_storage_key: Option<String>,
pub pdf_acquired_by: Option<String>,
}
One title an account holds, as acquire reads it from the library model.
Fields
holding_id:holdings.idof the account's holding.edition_id: The edition the listing sells: the key the title's files and acquire state belong to.listing_id:store_listings.id.plugin_key: Provenance-qualified PluginKey of the store.source: Display alias of the store's plugin (audible,libro, …), as the account records it.account_id: The holding account's id at that store.marketplace: Lower-cased marketplace (empty for a store with one).product_id: The store's own product id: what its download and fetch APIs take.asin: The edition's ASIN, preferring one scoped to the marketplace.isbn: The edition's lowest ISBN, when it has one.title: Title as the store lists it.subtitle: Subtitle as the store lists it, else the edition's.authors: Authors as the store prints them, comma-separated.narrators: Narrators as the store prints them, comma-separated.series: Series name as the store lists it.series_index: Position in that series as the store writes it.series_product_id: The store's product id for the series or podcast show.publisher: Publisher as the store lists it.categories: Store category labels (serialized as the scan stored them).length_minutes: Running time in whole minutes, from the store or the edition.language: Language as the store lists it.is_abridged: True when the store or the expression marks it abridged.content_kind: What the title is, in the scan'scontent_kindlabels:episodefor a podcast episode,podcastfor a show,bookotherwise.purchased_at: When the account bought the title, when the store reported it.added_at: When this library first recorded the account's holding of the title; the added date when the store reports no purchase time.published_at: Publication time as the store reported it, else the edition's.status: The edition's acquire state; not acquired when no title of it was ever queued.storage_key: Primary destination key of the edition's audio once acquired.acquired_by: The account holding (holdings.id) whose title's write set the edition's audio state;Nonewhen no title of it was ever queued, or when that holding no longer exists (its account was revoked or its title relinked), so no title owns the state any more.pdf_status: The edition's companion PDF state.pdf_storage_key: Destination key of the companion PDF once acquired.pdf_acquired_by: The account holding (holdings.id) whose title's write set the PDF state;Noneas forSelf::acquired_by.
pub fn acquired_here(&self) -> bool
True when this title's holding set the edition's audio state: the one whose writes change it once acquired.
pub fn pdf_acquired_here(&self) -> bool
True when this title's holding set the edition's companion PDF state.
pub fn asin_or_isbn(&self) -> &str
Naming and display fallback: ASIN, else ISBN, else the store's product id.
Implements: Clone, Debug, PartialEq
pub struct AcquireTitlePage {
pub titles: Vec<AcquireTitle>,
pub next: Option<String>,
}
One page of LibraryStore::acquire_titles_page.
Fields
titles: The page's titles, in holding order.next: The cursor of the next page;Noneonce the walk is done.
Implements: Clone, Debug, PartialEq
pub struct AcquiredTitleKey {
pub holding_id: String,
pub edition_id: String,
pub source: String,
pub plugin_key: String,
pub account_id: String,
pub marketplace: String,
pub product_id: String,
pub updated_at: DateTime<Utc>,
}
One account's title of an edition acquired with a stored file, without its metadata.
Fields
holding_id: The account holding (holdings.id): the id the full view is read by.edition_id: The acquired edition (editions.id).source: Display alias of the store plugin (audible,libro, ...), from the account; empty when the account row is gone.plugin_key: Provenance-qualified plugin key of the store.account_id: Store account that holds the title.marketplace: Store marketplace of the listing, as stored.product_id: Store product id of the listing.updated_at: Last change of the title: the latest of its holding, its listing and its edition's acquire state. An unparsable stored value counts as the time of the read.
Implements: Clone, Debug, Eq, PartialEq
pub struct AcquiredTitleKeyPage {
pub keys: Vec<AcquiredTitleKey>,
pub next: Option<String>,
}
One page of AcquiredTitleKeys.
Fields
keys: Every account title of the page's editions, by edition then holding id.next: The cursor of the next page (an edition id), orNoneafter the last.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct AudioStream {
pub codec: Option<AudioCodec>,
pub format: AudioFormat,
pub duration_ms: Option<u64>,
}
What a probe found about the audio stream of one file, besides its
[FileProbe]: the encoding, channels, sample rate and the running time
a player sees.
Each value is None when the file's headers do not state it; nothing
is decoded to find them.
Fields
codec: The audio encoding.format: Channels, sample rate and, for AAC, the profile.duration_ms: The playable running time in milliseconds, as the container states it after edit lists and encoder priming; never zero (Self::is_well_formed).
pub fn is_well_formed(&self) -> bool
True when every stated value is in range: channels and a sample
rate above zero and within the tag reader's limits, an AAC profile
only on AAC, and a running time above zero that a database integer
holds and bookclerk_tags::MAX_DURATION_MS allows.
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub struct CandidateRef {
pub listing_id: String,
pub origin: String,
pub seed_title: Option<String>,
pub seed_categories: Option<String>,
pub starter_genre: Option<String>,
}
One title a store returned for a subject, as written: the shared listing it is, plus why the subject got it.
Fields
listing_id: Thestore_listingsrow.origin: How the store found it (related to …,deals).seed_title: The subject's title that seeded it, when a seed did.seed_categories: That seed's categories.starter_genre: Starter genre it was browsed from, for a thin taste.
Implements: Clone, Debug, Eq, PartialEq
pub struct ChangedObject {
pub key: String,
pub changed_seq: i64,
pub removed: bool,
pub size: u64,
}
One object whose row changed after a reader's last sequence.
Fields
key: The object's key at the destination.changed_seq: The change sequence that changed the row.removed: True when the object is gone.size: Size in bytes when last seen.
Implements: Clone, Debug, Eq, PartialEq
pub struct DestinationFeed {
pub destination: String,
pub seq: i64,
pub feed_state: FeedState,
pub feed_cursor: Option<String>,
pub feed_error: Option<String>,
pub feed_checked_at: Option<DateTime<Utc>>,
pub listing_seq: Option<i64>,
pub listing_cursor: Option<String>,
pub listing_started_at: Option<DateTime<Utc>>,
pub listed_at: Option<DateTime<Utc>>,
pub next_listing_at: Option<DateTime<Utc>>,
pub listing_error: Option<String>,
pub objects: u64,
pub checked_seq: i64,
pub listing_base: Option<u64>,
pub revision: i64,
}
How one destination's outside changes are followed.
Fields
destination: The destination's plugin instance id.seq: The last change sequence number handed out.feed_state: The change feed's state.feed_cursor: The feed cursor to read from next;Nonebefore the first read.feed_error: The last feed failure.feed_checked_at: When the feed was last read.listing_seq: Sequence of the listing in progress;Nonebetween listings.listing_cursor: Cursor of the next page of the listing in progress.listing_started_at: When the listing in progress, or the last one, started.listed_at: When the last listing finished.next_listing_at: When the next scheduled listing is due.listing_error: Why the last listing failed or its removals were not applied.objects: Objects the destination held after the last listing or feed page.checked_seq: The last sequence the copy check read changes up to.listing_base: Objects known when the listing in progress started, which its removal guard is judged against;Nonebetween listings.revision: The row revision this value was read at (0 before the first save);LibraryStore::save_destination_feedrefuses a save from an older one.
pub fn new(destination: &str) -> Self
A destination never followed before: no feed read, no listing.
pub fn next_seq(&mut self) -> i64
Takes the next change sequence number.
pub fn listing_due(&self, now: DateTime<Utc>) -> bool
Whether a listing should run at now: one is in progress, none has
finished yet, the feed is not healthy while a feed is in use, or the
scheduled one is due.
Implements: Clone, Debug, Eq, PartialEq
pub struct EditionAcquisition {
pub edition_id: String,
pub status: AcquireStatus,
pub storage_key: Option<String>,
pub error_message: Option<String>,
pub holding_id: String,
pub updated_at: String,
pub pdf_status: AcquireStatus,
pub pdf_storage_key: Option<String>,
pub pdf_holding_id: Option<String>,
}
An edition's acquire state (edition_acquisitions).
Fields
edition_id: The edition id.status: Where the edition's acquire stands; a status this build does not know reads asAcquireStatus::NotAcquired.storage_key: Primary destination key of the edition's audio once acquired.error_message: Last acquire failure message.holding_id: The account holding (holdings.id) whose title's write set the state.updated_at: RFC 3339 time of that write.pdf_status: Where the edition's companion PDF acquire stands; a status this build does not know reads asAcquireStatus::NotAcquired.pdf_storage_key: Destination key of the companion PDF once acquired.pdf_holding_id: The account holding (holdings.id) whose title's write set the PDF state;Noneuntil a PDF write happens.
Implements: Clone, Debug, Eq, From<Model>, PartialEq
pub struct EditionAsin {
pub value: String,
pub marketplace: String,
}
An ASIN a catalog match found for an edition.
Fields
value: The ASIN as the catalog printed it (normalised when stored).marketplace: The marketplace the ASIN is sold in (such asus).
Implements: Clone, Debug, Eq, PartialEq
pub struct EditionCopy {
pub edition_id: String,
pub destination: String,
pub state: CopyState,
pub storage_key: Option<String>,
pub attempts: u32,
pub next_attempt_at: Option<DateTime<Utc>>,
pub last_error: Option<String>,
}
One edition's copy at one destination.
Fields
edition_id: The edition (editions.id).destination: The destination's plugin instance id.state: Where the copy stands.storage_key: The edition's primary audio key on the destination, once a write there was stored.attempts: Failed writes since the copy was last stored.next_attempt_at: When the next background attempt is due;Noneunless pending.last_error: The last write failure;Noneonce stored.
pub fn wants_attempt(&self, now: DateTime<Utc>) -> bool
Whether an acquire at now should write this copy: a pending copy
whose delay has passed. A stored copy needs nothing, a failed or
missing one waits for an acquire of its title, and a pending one
waits out its delay.
Implements: Clone, Debug, Eq, PartialEq
pub struct EditionEnrichment {
pub asin: Option<EditionAsin>,
pub description: Option<String>,
pub subjects: Option<String>,
pub categories: Option<String>,
pub cover_url: Option<String>,
pub language: Option<String>,
pub source: String,
pub confidence: f64,
}
What an enricher fills on one edition; None fields are left alone.
Fields
asin: An ASIN to record as the edition's identifier. An ASIN another edition already holds stays there.description: Description for the work, when it has none.subjects: Subjects for the work, when it has none.categories: Category labels for the work, when it has none.cover_url: Cover for the edition (and the work), when it has none.language: Language for the expression, when it has none.source: Who filled it, recorded aseditions.enrich_source.confidence: How sure the enricher was, from 0.0 to 1.0.
Implements: Clone, Debug, Default, PartialEq
pub struct EditionFile {
pub owner: FileOwner,
pub writer: String,
pub role: FileRole,
pub sha256: Option<String>,
}
Who holds a recorded file key, and what the file is.
Fields
owner: The edition (or branch title) the file belongs to.writer: The host upload id that claimed the key last, orACQUIRE_WRITER.role: What the file is.sha256: Lowercase hex SHA-256 of the content, when known (host uploads).
Implements: Clone, Debug, Eq, PartialEq
pub struct EnrichCandidate {
pub edition_id: String,
pub work_id: Option<String>,
pub title: String,
pub subtitle: Option<String>,
pub authors: Option<String>,
pub narrators: Option<String>,
pub duration_minutes: Option<i64>,
pub marketplace: String,
pub isbn: Option<String>,
pub asin: Option<String>,
pub description: Option<String>,
pub subjects: Option<String>,
pub cover_url: Option<String>,
pub language: Option<String>,
pub enrich_source: Option<String>,
}
One held edition, with what an enricher needs to look it up and the fields it may fill.
Fields
edition_id:editions.id.work_id: The edition's work (works.id), when its expression still names one.title: The edition's display title.subtitle: The edition's subtitle, else a listing's.authors: The credited authors as the first listing of the edition prints them, when it does.narrators: The credited narrators as the first listing of the edition prints them, when it does.duration_minutes: The edition's running time in whole minutes, else a listing's.marketplace: The marketplace of the edition's first listing (lower case, such asus), which scopes an ASIN found for it.isbn: The edition's ISBN (the smallest when it has several).asin: The edition's ASIN (the smallest when it has several), which a store listing or an earlier catalog match recorded.description: The work's description, else a listing's.subjects: The work's subjects.cover_url: The edition's cover, else a listing's.language: The expression's language, else a listing's.enrich_source: Who already filled the edition (editions.enrich_source).
Implements: Clone, Debug, PartialEq
pub struct EnrichCandidatePage {
pub candidates: Vec<EnrichCandidate>,
pub next: Option<String>,
}
One page of LibraryStore::enrich_candidates_page.
Fields
candidates: The page's held editions, in edition id order.next: The cursor of the next page;Noneonce the walk is done.
Implements: Clone, Debug, PartialEq
pub struct FileProbe {
pub content_type: String,
pub bitrate_kbps: Option<u32>,
pub lossless: bool,
pub source_store: Option<String>,
}
What a probe found in one stored audio file, and where the copy came
from (edition_files).
The same values decide which of two copies of one edition is kept
(FileProbe::is_better_than), wherever the comparison runs.
Fields
content_type: Media type of the file (audio/mp4,audio/mpeg,audio/flac).bitrate_kbps: Average audio bitrate in kilobits per second;Nonewhen the file states no running time to divide its size by.lossless: True for a lossless encoding (FLAC, ALAC).source_store: Plain id of the storefront the copy was downloaded from, when known.
pub const MAX_CONTENT_TYPE_BYTES: usize = 64
Longest media type a probe may carry, in bytes.
pub const MAX_BITRATE_KBPS: u32 = 20_000
Highest bitrate a probe may carry, in kilobits per second: above any audiobook encoding, so a forged value cannot win by size alone.
pub fn is_better_than(&self, other: &Self) -> bool
True when a copy with this probe should replace one with other
(library data model ADR, section 3): a lossless copy beats a lossy
one, and within the same kind the higher bitrate wins. A copy whose
bitrate is unknown never replaces one whose bitrate is known, and
equal copies do not replace each other.
pub fn is_well_formed(&self) -> bool
True when the values are ones an honest probe can produce: a short
media type of visible ASCII, a bitrate within
Self::MAX_BITRATE_KBPS, and a storefront that is a store's plain
id (lowercase letters, digits, _, - and ., as node frames name
stores).
Implements: Clone, Debug, Eq, PartialEq
pub struct HeldIdentifiers {
pub asins: BTreeSet<String>,
pub isbns: BTreeSet<String>,
pub product_ids: BTreeSet<String>,
}
Which of a set of store identifiers belong to titles the library holds.
Fields
asins: Upper-cased ASINs of held editions.isbns: ISBNs of held editions, as stored (canonical ISBN-13).product_ids: Store product ids of held listings.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct LibraryStore {
/* private fields */
}
Handle to the Bookclerk library database.
Async API over a SeaORM DatabaseConnection. DatabaseConnection is
cheaply cloneable (shared connection), so LibraryStore is Clone.
pub fn scope(
&self,
plugin_key: impl Into<String>,
source_id: impl Into<String>,
) -> SourceScope
Plugin-scoped view — first-party and third-party sources use this.
plugin_key isolates rows; source_id is the display alias written
to the source column.
pub async fn acquire_title(
&self,
plugin_key: &str,
account_id: &str,
marketplace: &str,
product_id: &str,
) -> Result<Option<AcquireTitle>>
The title account_id holds at a store, as acquire reads it.
plugin_key- The store's PluginKey.account_id- The account at that store.marketplace- The store's marketplace (any case; blank for one).product_id- The store's product id.
None when the store's listing is not resolved yet or the account
does not hold it.
Returns LibraryError::Orm when a read fails.
pub async fn acquire_titles_named(
&self,
account_id: Option<&str>,
id: &str,
) -> Result<Vec<AcquireTitle>>
The titles accounts hold that id names, as acquire reads them, in
holding order: what an acquire job given one title visits.
id matches, ignoring ASCII case, a listing's store product id, an
ASIN or ISBN of the listing's edition (every listing of that
edition), or a holding id.
account_id- Only the titles of the accounts this id or label names (ignoring ASCII case), when set.id- The product id, ASIN, ISBN, or holding id.
Every matching account holding's title; empty when nothing matches.
Returns LibraryError::Orm when a read fails.
pub async fn acquire_titles_of_listings(
&self,
listing_ids: &[String],
) -> Result<Vec<AcquireTitle>>
The titles accounts hold of the store listings listing_ids, as
acquire reads them, in holding order: every account's copy of those
listings.
listing_ids-store_listings.idvalues.
One title per account holding of a listing; empty when none is held.
Returns LibraryError::Orm when a read fails.
pub async fn held_titles_of_edition(&self, edition_id: &str) -> Result<Vec<AcquireTitle>>
The held titles of edition edition_id: one per account holding of
any of its listings, in holding id order.
Returns LibraryError::Orm when a read fails.
pub async fn acquire_title_of_holding(
&self,
holding_id: &str,
) -> Result<Option<AcquireTitle>>
The title of one account holding (holdings.id), as acquire reads
it.
None when no account holding has that id (a node holding, a
holding withdrawn, or an id this library never had) or its listing
is gone.
Returns LibraryError::Orm when a read fails.
pub async fn accounts_holding_titles(
&self,
account_id: Option<&str>,
plugin_key: Option<&str>,
) -> Result<BTreeSet<(String, String)>>
The accounts that hold at least one title, as (plugin_key, account_id): what an acquire of every title in its scope touches.
account_id- Only the accounts this id or label names (ignoring ASCII case), when set.plugin_key- Only accounts on this plugin, when set.
Returns LibraryError::Orm when a read fails.
pub async fn acquire_titles_page(
&self,
account_id: Option<&str>,
after: Option<&str>,
limit: u64,
) -> Result<AcquireTitlePage>
One page of the titles accounts hold, as acquire reads them, in holding order: what reconcile and storage matching walk.
account_id- Only the titles of the accounts this id or label names (ignoring ASCII case), when set.after- The previous page'sAcquireTitlePage::next;Nonefor the first page.limit- Most holdings the page reads (1 to 64, and at most the database'smaxResultRows).
The page's titles and the cursor of the next page. A holding whose
listing is gone has no title, so a page can be short or empty while
more follow: walk until next is None.
Returns LibraryError::Orm when a read fails.
pub async fn all_acquire_titles(
&self,
account_id: Option<&str>,
) -> Result<Vec<AcquireTitle>>
Every account title, in holding order: Self::acquire_titles_page
walked to its end.
account_id- Only the titles of the accounts this id or label names (ignoring ASCII case), when set.
Returns LibraryError::Orm when a read fails.
pub async fn acquired_title_keys_page(
&self,
after: Option<&str>,
limit: u64,
) -> Result<AcquiredTitleKeyPage>
One keyset page of the account titles whose edition is acquired with a stored audio file, identity columns only.
A page of editions whose result would exceed the database's result limits is halved and read again.
after- The previous page'sAcquiredTitleKeyPage::next, orNonefor the first page.limit- Editions wanted, clamped to 1..=ACQUIRED_KEYS_MAX_PAGEand to the database's row limit.
Every account holding of up to limit acquired editions, in edition
then holding order. An acquired edition no account holds yields no
key; walk until next is None.
Returns LibraryError::Orm when a read fails.
pub async fn record_catalog_listings(
&self,
listings: &[CatalogListing],
) -> Result<RecordedListings>
Stores what a store's catalog answer reported and returns each title's listing id.
A title whose listing a store reported within
CATALOG_LISTING_REFRESH keeps its resolution and text, and only
its offers are written. Any other title is resolved into the book
model as a catalog listing ([Self::record_catalog_listing]: work,
expression, edition and listing row, no holding), then its store
text is filled. Text and offers go to the database plugin as atomic
host batches sized from its limits.
listings- The titles, in the store's order.
The listing ids, one per input in order. A title that does not form
a valid listing (a blank title or key, or a field over the listing
limits) gets None; so does one whose rows other writers kept
changing on every attempt, which is also counted in
RecordedListings::unresolved and does not stop the rest of the
answer. A stored title that was not placed stays stale, so the next
answer resolves it again.
Returns LibraryError when a read or write of the answer's rows
fails, including the resolver's own reads and writes; titles before
the failure may already be stored.
pub async fn record_listing_offers(&self, offers: &[(String, ListingOffer)]) -> Result<()>
Stores prices a store quoted for listings already in the pool.
offers-(listing id, offer)pairs. An offer older than the stored one for the same audience is ignored; one for a listing no longer stored fails its foreign key and is dropped with its batch, while the other batches are still written.
Returns the first batch's database error, after every batch was tried.
pub async fn record_store_text(
&self,
texts: &[(ListingKey, ListingDetail)],
) -> Result<usize>
Fills the store text of stored listings named by their store key, as a store's answer for titles the library already lists would.
Each listing keeps a stored value its text leaves out, and a cover in the text also becomes the cover of the edition the listing sells when that edition has none.
texts-(store key, store text)pairs; a key with no stored listing is skipped.
A held work whose edition gained a cover has its page index row refreshed, so the row can name that edition as its cover edition.
How many of texts named a stored listing.
Returns the database error of the listing read, of the first write batch that failed (after every batch was tried), or of the row refresh.
pub async fn catalog_listings(&self, ids: &[String]) -> Result<Vec<CatalogListingRecord>>
Reads stored listings by id, with their work, identifiers and offers.
Rows are read in chunks bounded by the backend's bind limit; a chunk
whose result would pass the database plugin's maxResultBytes
(long synopses) is split and read again.
ids-store_listingsids; duplicates are read once.
The listings found, in the order of ids (first occurrence); ids no
longer stored are left out.
Returns the database error.
pub async fn listing_expressions(
&self,
products: &[(String, String)],
) -> Result<HashMap<(String, String), BTreeSet<String>>>
The expressions (recordings) the shared listing pool placed each store product in, in any marketplace.
A store's product id names one edition per marketplace, so a product usually has one expression; a product listed in two marketplaces under different editions has each of their expressions. A product the pool never listed is left out.
products-(plugin_key, product_id)pairs, as stores report them (the product id is compared in its stored spelling).
Each pooled product's expression ids, keyed by the pair as given.
Returns the database error.
pub async fn prune_catalog_listings(&self, cutoff: DateTime<Utc>) -> Result<u64>
Deletes catalog listings nothing refers to any more.
A listing is deleted when no store reported it since cutoff and
nobody holds it, no Discover subject has it as a candidate, no
cached storefront call lists it, no wish names it and no resolution
override names it. Its offers go with it. The edition, expression and work it
made stay, since other rows (a wish, a later scan) may use them.
How many listings were deleted.
Returns the database error.
pub async fn record_chapter_claim(
&self,
edition_id: &str,
write: &ChapterClaimWrite,
) -> Result<ChaptersOutcome>
Records one source's chapters for an edition and resolves the edition's chapters again.
The list is stored first when it is new. The claim then replaces the source's earlier one; a claim that states the same list and runtime as before changes nothing, so recording the same chapters on every acquire costs one read.
edition_id- The edition (editions.id).write- The claim.
Whether the edition's chapters changed.
Returns LibraryError::NotFound for an unknown edition, or the
database error.
pub async fn remove_chapter_edit(&self, edition_id: &str) -> Result<ChaptersOutcome>
Removes an Administrator's edit of an edition's chapters, so they resolve from the other sources again.
Whether the edition's chapters changed; ChaptersOutcome::Unchanged
when there was no edit.
Returns LibraryError::NotFound for an unknown edition, or the
database error.
pub async fn pin_chapter_claim(
&self,
edition_id: &str,
target: Option<(ChapterSourceKind, &str)>,
user_id: Option<i64>,
) -> Result<ChaptersOutcome>
Pins one of an edition's chapter claims, so it wins over every other source, or removes the pin.
At most one claim is pinned: pinning one unpins the rest in the same batch. A claim that is pinned or unpinned moves to the edition's next revision.
edition_id- The edition.target- The claim to pin, by source kind and source id;Noneremoves the pin.user_id- The Administrator;Nonefor the operator.
Returns LibraryError::NotFound for an unknown edition or a
claim it does not have, or the database error.
pub async fn chapter_claims(&self, edition_id: &str) -> Result<Vec<ChapterClaim>>
An edition's chapter claims, newest first, each with its list's chapter count.
Returns the read error.
pub async fn edition_chapters(&self, edition_id: &str) -> Result<Option<EditionChapters>>
The chapters an edition resolved to; None when it has none.
Returns the read error, or LibraryError::Other when the stored
list is missing or no longer passes its own checks.
pub async fn chapter_list(&self, digest: &ChapterDigest) -> Result<Option<ChapterList>>
A stored chapter list; None when no complete list has this
digest.
Returns the read error, or LibraryError::Other when the entries
do not match the list's row or its digest.
pub async fn resolve_edition_chapters(&self, edition_id: &str) -> Result<ChaptersOutcome>
Resolves an edition's chapters from its claims and writes the
result, publishing edition_updated when the list changed.
The write is guarded on the highest claim revision the resolution read; when a newer claim landed in between, the resolution is computed again.
Returns the database error, or LibraryError::Conflict when
claims kept changing for every attempt.
pub async fn destination_feed(&self, destination: &str) -> Result<Option<DestinationFeed>>
How destination's outside changes are followed; None before its
first sync pass (or for a stored state this build does not know).
Returns an error when the read fails.
pub async fn destination_feeds(&self) -> Result<Vec<DestinationFeed>>
Every destination's feed row, ordered by destination.
Returns an error when the read fails.
pub async fn save_destination_feed(&self, feed: &mut DestinationFeed) -> Result<()>
Writes feed, replacing the destination's row, and moves
feed.revision to the revision written.
The write is a compare-and-swap on the revision feed was read at:
a first save inserts the row, and a later one updates it only while
nobody else saved since. A sync pass whose lease another node took
therefore fails at its next save instead of overwriting the new
holder's progress.
Returns LibraryError::Conflict when the row changed since
feed was read, or the error of a failed write.
pub async fn record_seen_objects(
&self,
destination: &str,
seq: i64,
objects: &[SeenObject],
now: DateTime<Utc>,
) -> Result<u64>
Records that destination holds objects, as a listing page or a
feed page numbered seq reported them.
Each object is marked seen at seq. One that is new, was removed,
or whose size or signature differs from its row is recorded as
changed at seq; an unchanged one keeps its changed_seq. A row a
later page or listing already wrote is left as it is.
How many objects changed.
Returns an error when a read or a write fails.
pub async fn remove_seen_objects(
&self,
destination: &str,
seq: i64,
keys: &[String],
now: DateTime<Utc>,
) -> Result<u64>
Records that the objects at keys are gone from destination, as
a feed page numbered seq reported. A key with no row, already
removed, or written by a later page or listing is left alone.
How many objects were marked removed.
Returns an error when a write fails.
pub async fn unlisted_object_count(
&self,
destination: &str,
listing_seq: i64,
) -> Result<u64>
Objects destination is known to hold that the listing numbered
listing_seq has not seen: the ones Self::finish_listing would
mark removed.
Returns an error when the read fails.
pub async fn known_object_count(&self, destination: &str) -> Result<u64>
Objects destination is known to hold now.
Returns an error when the read fails.
pub async fn finish_listing(
&self,
destination: &str,
listing_seq: i64,
now: DateTime<Utc>,
) -> Result<u64>
Ends the listing numbered listing_seq of destination: every
object it did not see is marked removed at listing_seq.
How many objects were marked removed.
Returns an error when the write fails.
pub async fn keep_unlisted_objects(
&self,
destination: &str,
listing_seq: i64,
) -> Result<()>
Marks every object destination holds as seen by the listing
numbered listing_seq, without recording a change: used when a
listing's removals are held back, so the next listing compares
against the same set.
Returns an error when the write fails.
pub async fn changed_objects(
&self,
destination: &str,
after: (i64, Option<&str>),
limit: u64,
) -> Result<Vec<ChangedObject>>
Up to limit objects of destination whose rows changed after
after: a change sequence, or a sequence and the last key read in
it to continue a page. Ordered by sequence, then key.
Returns an error when the read fails.
pub async fn prune_object_tombstones(&self, before: DateTime<Utc>) -> Result<u64>
Deletes tombstones of objects removed before before.
How many tombstones were deleted.
Returns an error when the delete fails.
pub async fn lose_copies(
&self,
destination: &str,
keys: &[String],
action: MissingFileAction,
now: DateTime<Utc>,
) -> Result<LostCopies>
Records that the files at keys are gone from destination.
Every stored copy whose primary audio key is one of them is looked
at. When another audio file of its edition is recorded at the
destination (edition_files) and the destination still holds it
(the file was moved or renamed), the copy now names that key.
Otherwise action decides:
- [
MissingFileAction::Restore]: the copy turns pending, due atnow, so the next copy retry writes it again. - [
MissingFileAction::MarkMissing]: the copy turns missing and is left alone. When no destination holds a stored copy of the edition any more, the edition is no longer acquired (its title's acquire status turns not acquired), so a member can ask for it again.
Returns an error when a read or a write fails.
pub async fn release_missing_editions(&self, destination: &str) -> Result<u64>
Releases every edition with a missing copy at destination that is
still acquired although no destination holds a stored copy of it:
the state a failed release in Self::lose_copies leaves behind,
since the copy is already missing and no later loss names it.
How many editions turned not acquired.
Returns an error when a read or a write fails.
pub async fn unlisted_copy_keys(&self, destination: &str) -> Result<(Vec<String>, u64)>
The primary audio keys of destination's stored copies that have no
present object row there: files a finished listing did not see
(including ones that were gone before the destination was first
listed, which leave no tombstone), in key order.
The missing keys, and how many distinct keys the destination's stored copies name.
Returns an error when a read fails.
pub async fn replace_discover_candidates(
&self,
subject: &DiscoverSubject,
source: &str,
scope: SeedScope,
rows: &[CandidateRef],
) -> Result<()>
Replaces every candidate one store returned for one subject.
Each row is upserted with this call's fetch time, then the store's rows for the subject that this call did not write are deleted. Other stores' rows for the subject are untouched.
The writes go to the database plugin as canonical host batches, each
one atomic request (one transaction) holding as many rows as the
plugin's maxStatements and maxRequestBytes allow, so a few hundred
candidates cost a handful of round trips instead of one per row. No
interactive transaction is used: the external database adapters only
take single statements and atomic batches, so begin is refused
there. The delete rides in the last batch. A reader between two
batches can see part of the new set next to old rows that are not
deleted yet.
subject- Whose candidates these are.source- Storefront plugin id that returned them.scope- Seeds that produced them.rows- The candidates, as listing references; a listing named twice keeps the last.
Returns the database error, including when a single row is larger than one request may carry. Batches written before it stay; the old rows are only deleted once every new row is stored.
pub async fn list_discover_candidates(
&self,
subject: &DiscoverSubject,
) -> Result<Vec<StoredCandidate>>
Lists every stored candidate of one subject, oldest store fetch first, each joined with its listing from the shared pool.
Candidate rows are read in id pages, then their listings in chunks
that stay under the database plugin's result limit
(LibraryStore::catalog_listings), then the rows are ordered by
fetch time (ties keep id order). Rows whose scope text is unknown
(written by a newer release), or whose listing is gone, are skipped.
Returns the database error.
pub async fn discover_subject_exists(&self, subject: &DiscoverSubject) -> Result<bool>
Reports whether a Discover subject still exists.
The operator always exists; a user or portal subject exists while
its users or portal_identities row does. Jobs check this so a
fetch or ranking queued before the subject was deleted does not
write its rows back.
Returns the database error.
pub async fn forget_discover_subject(&self, subject: &DiscoverSubject) -> Result<()>
Deletes every stored Discover row of one subject (candidates, feed, taste and fetch marker).
Returns the database error.
pub async fn put_discover_taste(
&self,
subject: &DiscoverSubject,
taste_json: &str,
scope: SeedScope,
) -> Result<()>
Stores one subject's taste, replacing the previous one.
subject- Whose taste it is.taste_json- The taste, as the Discover crate encodes it.scope- Seeds it comes from.
Returns the database error.
pub async fn get_discover_taste(
&self,
subject: &DiscoverSubject,
) -> Result<Option<StoredDiscoverTaste>>
Returns one subject's stored taste, when it has one.
Returns the database error.
pub async fn mark_discover_fetch(
&self,
subject: &DiscoverSubject,
at: DateTime<Utc>,
) -> Result<()>
Records that one subject's candidate fetch finished at at.
Recorded separately from the candidate rows, so a fetch that found nothing new still counts as fresh for a day.
Returns the database error.
pub async fn newest_discover_candidate_fetch(
&self,
subject: &DiscoverSubject,
) -> Result<Option<DateTime<Utc>>>
Returns when one subject's last candidate fetch finished.
None when no fetch has finished for the subject yet.
Returns the database error.
pub async fn get_discover_store_call(
&self,
call_key: &str,
max_age: Duration,
) -> Result<Option<Vec<StoreCallHit>>>
Returns a cached storefront answer no older than max_age.
call_key- Key the caller derived from the store, call kind and query.max_age- Oldest answer still worth reusing.
The listings the call answered, in the store's order, or None
when absent or too old.
Returns the database error.
pub async fn get_discover_store_calls(
&self,
call_keys: &[String],
max_age: Duration,
) -> Result<HashMap<String, Vec<StoreCallHit>>>
Self::get_discover_store_call for many calls at once, in a few
chunked reads instead of two per call.
A discover fetch asks one store dozens of calls (deals, each seed, each starter genre); reading their cached answers up front saves two database round trips per call. Like the single read, a call row is read first and its hits after, so an answer being rewritten reads as expired, never as part of its hits.
call_keys- Keys the caller derived; duplicates are read once.max_age- Oldest answer still worth reusing.
Each key with a fresh answer, mapped to its listings in the store's order (at most 500 per key). Absent or expired keys are left out.
Returns the database error.
pub async fn put_discover_store_call(
&self,
call_key: &str,
source: &str,
hits: &[StoreCallHit],
) -> Result<()>
Stores (or refreshes) one cached storefront answer: the call row and the listings it answered, replacing the previous answer's hits.
The writes go as atomic host batches sized from the database plugin's limits. The first batch marks the call as fetched long ago and deletes the old hits; the new fetch time is written last, in the final batch. A reader between batches, or after a batch fails, sees an expired answer and asks the store again, never a fresh answer with only part of its hits. Each write claims the call row with its own random token, and its hits and fetch time apply only while the row still carries that token, so two concurrent answers to one call are never mixed: the later claim wins, and the earlier write adds nothing after it.
call_key- The call's key.source- Storefront plugin id that answered.hits- The listings, in the store's order.
Returns the database error.
pub async fn prune_discover_store_calls(&self, cutoff: DateTime<Utc>) -> Result<u64>
Deletes cached storefront answers fetched before cutoff.
How many answers were deleted.
Returns the database error.
pub async fn put_discover_feed(
&self,
subject: &DiscoverSubject,
feed_json: &str,
scope: SeedScope,
candidates_fetched_at: Option<DateTime<Utc>>,
) -> Result<()>
Stores (or replaces) one subject's ranked feed.
One upsert writes the row without reading the old one first, so a stored feed too large to read back cannot block its replacement.
subject- Whose feed it is.feed_json- The feed, before hidden shelves are filtered out.scope- Seeds it was ranked from.candidates_fetched_at- Newest candidate fetch it used, when any.
Returns the database error.
pub async fn get_discover_feed(
&self,
subject: &DiscoverSubject,
) -> Result<Option<StoredFeed>>
Returns one subject's stored feed, when it has one.
Returns the database error.
pub async fn list_discover_feed_subjects(&self) -> Result<Vec<DiscoverSubject>>
Lists every subject that has a stored feed, so a shared change (the request queue) can re-rank them all.
Keys that do not parse as a DiscoverSubject are skipped.
Returns the database error.
pub async fn set_copy_stored(
&self,
edition_id: &str,
destination: &str,
storage_key: &str,
) -> Result<()>
Records that destination holds the complete files of edition_id,
with its primary audio at storage_key there. Clears any pending
retry.
Returns an error when the write fails.
pub async fn set_copy_pending(
&self,
edition_id: &str,
destination: &str,
error: &str,
now: DateTime<Utc>,
) -> Result<CopyState>
Records that writing edition_id to destination failed with
error at now. The copy turns pending with its next attempt due
after copy_retry_delay, or failed once it has failed
MAX_COPY_ATTEMPTS times. A key an earlier stored copy recorded is
kept.
The attempt count is read, then written: the acquire job that writes an edition holds the node's work lock, so two writes of one copy do not race.
The copy's state after the failure.
Returns an error when the read or the write fails.
pub async fn record_copies_from_files(&self, edition_id: &str) -> Result<usize>
Records a stored copy of edition_id on each destination where its
primary audio file is recorded (edition_files, role audio) and
no copy row exists yet.
An edition acquired before copies were recorded has files but no copy rows; its audio rows say where the acquire wrote it. Call this only for an acquired edition: an acquire records each key just before writing it, so a row alone does not prove the write finished. Existing copy rows are never changed.
How many copies were recorded.
Returns an error when the read or a write fails.
pub async fn copies_of_editions(&self, edition_ids: &[String]) -> Result<Vec<EditionCopy>>
Every recorded copy of the editions in edition_ids, ordered by
edition then destination. Rows in a state this build does not know
are left out.
Returns an error when the read fails.
pub async fn due_copy_editions(
&self,
now: DateTime<Utc>,
destinations: &[String],
limit: u64,
) -> Result<Vec<String>>
Up to limit editions with a pending copy on one of destinations
whose next attempt is due at now, soonest due first, each named
once. A copy on a destination not in destinations (one no longer
deployed) is not due anywhere.
Returns an error when the read fails.
pub async fn defer_copy_retries(
&self,
edition_id: &str,
destinations: &[String],
now: DateTime<Utc>,
) -> Result<()>
Moves the due retries of edition_id's pending copies on
destinations to their next delay from now, without counting an
attempt: called once an acquire for them is queued, so the next
pass does not queue another while that one waits. The acquire's own
outcome then records the copy as usual.
Returns an error when the read or a write fails.
pub async fn enrich_candidates_page(
&self,
after: Option<&str>,
limit: u64,
) -> Result<EnrichCandidatePage>
One page of the held editions an enricher walks, in edition id order.
after- The previous page'sEnrichCandidatePage::next;Nonefor the first page.limit- Most editions the page reads (1 to 200, and at most the database'smaxResultRows).
The page's editions that a holding still holds, and the cursor of
the next page. An edition nobody holds is left out, so a page can be
short or empty while more follow: walk until next is None.
Returns LibraryError::Orm when a read fails.
pub async fn enrich_edition(
&self,
edition_id: &str,
fill: &EditionEnrichment,
) -> Result<()>
Fills what edition edition_id lacks from fill and records who
filled it.
The work takes the description, subjects and cover it lacks (a work another edition already described keeps its own values), the expression the language it lacks, and the edition the cover it lacks. The edition's provenance is written last, so a write that fails before it leaves the edition unmarked and the next run tries again.
edition_id- The edition filled.fill- The values offered and who offers them.
Returns LibraryError::NotFound when the edition is gone, or
LibraryError::Orm when a read or write fails.
pub async fn edition_acquisition(
&self,
edition_id: &str,
) -> Result<Option<EditionAcquisition>>
An edition's acquire state; None when no title of it was ever
queued or acquired.
Returns an error when the read fails.
pub async fn edition_of_holding(&self, holding_id: &str) -> Result<Option<String>>
The edition holding holding_id (holdings.id) holds: the one its
listing sells; None when the holding or its listing is gone.
Returns an error when a read fails.
pub async fn file_owner_of_holding(&self, holding_id: &str) -> Result<Option<FileOwner>>
The file owner of a node holding (holdings.id, a title a branch
shares here): the edition its listing sells.
Returns an error when a read fails.
pub async fn record_edition_file(
&self,
destination: &str,
key: &str,
owner: &FileOwner,
role: FileRole,
) -> Result<bool>
Records that owner writes key on destination (an acquire run
on this node, just before the write).
The record is taken when the key is unrecorded, already owner's,
or held by an owner no longer live (a removed edition, or a title a
branch shares here, whose keys an acquire on this node takes over).
Another live edition's key is refused, changing nothing: two
editions whose short ids collide can plan one chapter or sidecar
name the audio-name check does not see, and the write must not
replace that edition's file. Each record is one conditional write,
so of two acquires racing for one key only one wins.
true when the key is now owner's; false when another live
edition holds it.
Returns an error when a write fails.
pub async fn record_edition_copy_file(
&self,
destination: &str,
key: &str,
owner: &FileOwner,
role: FileRole,
copy: Option<&OutputCopy>,
) -> Result<bool>
Self::record_edition_file for a file of one library copy
(output.copies): the row also names the copy's format and quality,
or none when copy is None.
true when the key is now owner's; false when another live
edition holds it.
Returns an error when a write fails.
pub async fn claim_edition_file(
&self,
destination: &str,
key: &str,
owner: &FileOwner,
writer: &str,
role: FileRole,
sha256: Option<&str>,
expected: Option<&EditionFile>,
title: &str,
catalog: bool,
) -> Result<bool>
Claims key on destination for owner, with writer (a host
upload id) as its latest writer.
The claim succeeds when the key is unrecorded, already the owner's (any account's row of the same edition), or recorded for an owner that holds no key against this claim; answers false, changing nothing, when another edition holds it. An edition holds its keys against every claim while it exists. Each claim is one conditional write, so of two uploads of different editions racing for one key only one wins.
expected is the record the caller read before
(Self::edition_file; None when unrecorded), which a refused
claim's release restores: the claim also answers false, changing
nothing, when the record is no longer that one (an acquire recorded
the key in between), so a release never removes a record the claim
did not replace.
destination,key- The file's place.owner- Who claims it.writer- The host upload id.role,sha256- What the file is and its declared digest.expected- The record read before the claim.title- What the upload writes for: the account holding (holdings.id) of a job upload, or the node holding (holdings.id) of a catalog upload. A key its edition already holds is taken over only when this upload or an earlier upload for the same title (or, for a catalog upload, an earlier catalog upload of the same branch) wrote it, never one an acquire or another account's upload wrote: the edition's files are shared, so one node cannot replace them. A job upload may also take over a key a branch's catalog upload wrote (catalogfalse), as an acquire on this node would replace a delivered copy with its own.catalog- True for a catalog upload's claim.
Returns an error when a write fails.
pub async fn release_edition_file(
&self,
destination: &str,
key: &str,
writer: &str,
prior: Option<&EditionFile>,
) -> Result<()>
Gives back a claim writer made on key on destination: the
record returns to prior (who held it before the claim), or is
removed when prior is None (the claim created it). Changes
nothing once someone else has written the key since (its writer is
no longer writer), so a release never takes a key from a later
claim or acquire.
Returns an error when the write fails.
pub async fn count_edition_files_by(&self, writer: &str) -> Result<u64>
How many keys writer (a host upload id) holds, on every
destination together. An upload id is unique and claims keys for one
owner only, so this is how many keys that upload's title still holds
through it.
Returns an error when the read fails.
pub async fn edition_file(
&self,
destination: &str,
key: &str,
) -> Result<Option<EditionFile>>
Who holds key on destination; None when it is unrecorded.
A row naming an owner kind this build does not know reads as held by an edition no claim matches, so it is never taken over.
Returns an error when the read fails.
pub async fn set_edition_file_probe(
&self,
destination: &str,
key: &str,
owner: &FileOwner,
probe: &FileProbe,
) -> Result<bool>
Stores what a probe found in owner's file at key on
destination, stamped with the time of the write.
The row is changed only while owner still holds the key, so a
probe that finishes after another edition took the key over
describes nothing.
true when the row was owner's and now carries probe.
Returns an error when probe is not well formed
(FileProbe::is_well_formed) or the write fails.
pub async fn set_uploaded_file_probe(
&self,
destination: &str,
key: &str,
writer: &str,
probe: &FileProbe,
) -> Result<bool>
Stores what a probe found in the file the upload writer wrote at
key on destination, as Self::set_edition_file_probe does for
an owner.
The row is changed only while writer is still the upload that
claimed the key last, so a committed upload never describes a file
a later write replaced.
true when the row was writer's and now carries probe.
Returns an error when probe is not well formed or the write fails.
pub async fn set_edition_file_stream(
&self,
destination: &str,
key: &str,
owner: &FileOwner,
stream: &AudioStream,
) -> Result<bool>
Stores what a probe found about the audio stream of owner's file
at key on destination (AudioStream), beside the probe
Self::set_edition_file_probe stores.
The row is changed only while owner still holds the key, as for
the probe.
true when the row was owner's and now carries stream.
Returns an error when stream is not well formed
(AudioStream::is_well_formed) or the write fails.
pub async fn edition_audio_files(&self, edition_id: &str) -> Result<Vec<ProbedAudioFile>>
Every audio file (primary audio, parts and chapters) recorded for
edition edition_id, on every destination, with what the last probe
of each found (ProbedAudioFile), in destination then key order.
Returns an error when the read fails.
pub async fn edition_file_probe(
&self,
destination: &str,
key: &str,
) -> Result<Option<FileProbe>>
What the last probe found in the file at key on destination;
None when the key is unrecorded or was never probed.
Returns an error when the read fails.
pub async fn edition_file_copy(
&self,
destination: &str,
key: &str,
) -> Result<Option<OutputCopy>>
The library copy (output.copies) the file at key on
destination belongs to; None when the key is unrecorded, belongs
to no one copy, or names a copy this build cannot read.
Returns an error when the read fails.
pub async fn audio_keys_of(
&self,
destination: &str,
owner: &FileOwner,
) -> Result<Vec<String>>
The audio keys (primary audio, parts and chapters) recorded for
owner on destination, in key order: every file a copy of the
edition's recording there needs.
Returns an error when the read fails.
pub async fn name_held_by_another_owner(
&self,
stem: &str,
owner: &FileOwner,
) -> Result<bool>
True when another live edition's file is recorded, on any
destination, at the name stem (a planned key without its
extension): the key stem itself, stem with an extension in the
same folder (stem.cue), or one of its part files
(stem — Part 1.m4b). Another edition's files already live under
that name, so an acquire of owner is refused rather than overwrite
them. A longer name that only starts with stem (stem Peaks.m4b)
is not the same name. A branch title's file, or a file of an edition
no longer in the library, does not count: an acquire takes those
keys over, as LibraryStore::claim_edition_file does.
Returns an error when the read fails.
pub async fn publish_domain_event(
&self,
spec: PublishDomainEventSpec,
) -> Result<PublishDomainEventOutcome>
Persist a domain event. Duplicate (account_id, source, event_type, dedup_key)
coalesces. Wake processing is left to Self::process_pending_wakes.
Returns LibraryError::Orm when the write fails, or
LibraryError::Other when the payload exceeds 64 KiB.
pub async fn dispatch_event_deliveries(
&self,
event_id: &str,
subscribers: &[EventSubscriber],
operation_id: &str,
) -> Result<u32>
Snapshot matching subscribers and create one delivery row per plugin.
Idempotent under replay: existing (event_id, plugin_id) rows are kept.
Marks the outbox row dispatched in the same transaction.
Returns LibraryError::Orm when the write fails.
pub async fn next_undispatched_event(&self) -> Result<Option<DomainEventRecord>>
Next undispatched outbox row (oldest first).
Returns LibraryError::Orm when the read fails.
pub async fn process_pending_wakes(
&self,
limit: u64,
_owner: &str,
lease_secs: u64,
) -> Result<PendingWakeProgress>
Claim up to limit wake_pending events and process one delivery page each.
Each claimed event is leased with a unique UUID token so two processors
cannot own the same slice (process node_id is not the fence — it is ABA
across restarts). Cursor release and finish require that token.
Returns LibraryError::Orm when the read or wake write fails.
pub async fn lease_next_event_delivery(
&self,
owner: &str,
lease_secs: u64,
operation_id: &str,
plugin_ids: &[String],
max_in_flight: u32,
node_id: &str,
) -> Result<Option<EventDeliveryRecord>>
Lease the next ready delivery with a fenced pending → running mutation.
A delivery is one subscriber's own copy of an event, so a lease never
takes work from another subscriber: it only picks which node runs this
copy. Jobs, by contrast, are claimed (see docs/internals/jobs.md).
When node_id is non-empty, this node’s own catalog must match the parent
event’s type, schema version, and filter. The host loads the catalog and
filters candidates in Rust, then CAS-updates one row (portable slot +
UPDATE … WHERE id = ? AND state = pending). An empty node_id keeps
plugin-id-only filtering (tests).
Returns LibraryError::Orm when the claim write fails.
pub async fn lease_next_event_delivery_due_by(
&self,
owner: &str,
lease_secs: u64,
operation_id: &str,
plugin_ids: &[String],
max_in_flight: u32,
node_id: &str,
due_by: DateTime<Utc>,
) -> Result<Option<EventDeliveryRecord>>
Self::lease_next_event_delivery restricted to deliveries due at
or before due_by (run_after <= due_by).
A host that is not the best placed to run a plugin passes a cutoff in the past, so it only picks up deliveries the better hosts left waiting that long.
Returns LibraryError::Orm when the claim write fails.
pub async fn release_unexecuted_event_delivery(
&self,
fence: &EventDeliveryFence,
restore_resume: bool,
) -> Result<bool>
Return a claimed delivery to pending without consuming an attempt.
Used when this worker cannot execute the subscriber (plugin not loaded).
Returns LibraryError::Orm when the update fails.
pub async fn heartbeat_event_delivery(
&self,
fence: &EventDeliveryFence,
lease_secs: u64,
) -> Result<bool>
Refresh the lease when fence still owns the running generation.
Returns LibraryError::Orm when the update fails.
pub async fn ack_event_delivery(&self, fence: &EventDeliveryFence) -> Result<bool>
Mark a fenced delivery acked.
Returns LibraryError::Orm when the update fails.
pub async fn reject_event_delivery(
&self,
fence: &EventDeliveryFence,
reason: &str,
) -> Result<bool>
Mark a fenced delivery permanently rejected.
Returns LibraryError::Orm when the update fails.
pub async fn dead_letter_event_delivery(
&self,
fence: &EventDeliveryFence,
reason: &str,
) -> Result<bool>
Mark a fenced delivery dead_letter.
Returns LibraryError::Orm when the update fails.
pub async fn retry_event_delivery(
&self,
fence: &EventDeliveryFence,
run_after: DateTime<Utc>,
reason: &str,
) -> Result<bool>
Return a fenced delivery to pending with backoff (retryable handler).
When attempt_count has already reached max_attempts, the delivery is
dead-lettered instead of looping forever on a guest that keeps returning
retry.
Returns LibraryError::Orm when the update fails.
pub async fn suspend_event_delivery(
&self,
fence: &EventDeliveryFence,
checkpoint_json: &str,
checkpoint_schema_version: i64,
wake_at: DateTime<Utc>,
wake_event_type: &str,
wake_filter_json: &str,
wake_grants_json: &str,
) -> Result<bool>
Suspend a fenced delivery (checkpoint + wake) without burning an attempt.
Returns LibraryError::Orm when the update fails.
pub async fn fail_event_delivery(
&self,
fence: &EventDeliveryFence,
reason: &str,
) -> Result<bool>
Fail a running delivery: retry with backoff or dead-letter at max attempts.
Returns LibraryError::Orm when the update fails.
pub async fn reclaim_expired_event_deliveries(&self) -> Result<u32>
Reclaim expired running deliveries back to pending.
Rows with cancel_requested become rejected instead of pending so an
operator cancel survives a worker crash. A stored checkpoint restores
resume_pending so a crash during resume does not consume an attempt.
Returns LibraryError::Orm when the update fails.
pub async fn get_domain_event(&self, id: &str) -> Result<Option<DomainEventRecord>>
Load one event envelope.
Returns LibraryError::Orm when the read fails.
pub async fn get_event_delivery(&self, id: &str) -> Result<Option<EventDeliveryRecord>>
Load one delivery.
Returns LibraryError::Orm when the read fails.
pub async fn list_domain_events(&self, limit: u64) -> Result<Vec<DomainEventRecord>>
Recent outbox events, newest first.
Returns LibraryError::Orm when the read fails.
pub async fn list_domain_events_for_queue(
&self,
queue_name: &str,
limit: u64,
) -> Result<Vec<DomainEventRecord>>
Recent outbox rows on one queue, newest first.
Returns LibraryError::Orm when the read fails.
pub async fn list_queue_names(&self) -> Result<Vec<String>>
Distinct queue names that hold at least one outbox row, sorted.
Returns LibraryError::Orm when the read fails.
pub async fn count_queue_deliveries(&self, queue_name: &str, state: &str) -> Result<i64>
Delivery rows on one queue in state.
Returns LibraryError::Orm when the read fails.
pub async fn list_event_deliveries_for_queue(
&self,
queue_name: &str,
state: Option<&str>,
limit: u64,
) -> Result<Vec<EventDeliveryRecord>>
Deliveries filtered by optional state and queue, newest first.
Returns LibraryError::Orm when the read fails.
pub async fn list_event_deliveries(
&self,
state: Option<&str>,
limit: u64,
) -> Result<Vec<EventDeliveryRecord>>
Deliveries filtered by optional state, newest first.
Returns LibraryError::Orm when the read fails.
pub async fn retry_dead_letter_delivery(&self, id: &str) -> Result<bool>
Re-queue a dead-lettered delivery for operator retry.
Returns LibraryError::Orm when the update fails.
pub async fn acknowledge_dead_letter_delivery(&self, id: &str) -> Result<bool>
Operator acknowledge: mark a dead-letter as rejected (no further retry).
Returns LibraryError::Orm when the update fails.
pub async fn count_event_deliveries(&self, state: &str) -> Result<i64>
Count deliveries in state.
A peer writer on the same SQLite file can make this read return
SQLITE_BUSY. The read is repeated until the lock clears or the
attempt budget is spent. state is unchanged.
Returns LibraryError::Orm when the read fails for a reason other
than file-lock contention, and LibraryError::Unavailable when the
lock is still held after the retries.
pub async fn event_delivery_metrics(&self) -> Result<EventDeliveryMetrics>
Operator-visible delivery-queue counters (pending vs suspended split).
Each read waits out a peer SQLite file lock the same way
Self::count_event_deliveries does.
Returns LibraryError::Orm when a read fails for a reason other than
file-lock contention, and LibraryError::Unavailable when a lock is
still held after the retries.
pub async fn record_event_handler_latency(&self, duration_ms: i64) -> Result<()>
Record one onEvent duration sample.
Returns LibraryError::Orm when the write fails.
pub async fn list_domain_events_by_dispatch_state(
&self,
dispatch_state: &str,
limit: u64,
) -> Result<Vec<DomainEventRecord>>
Outbox envelopes in dispatch_state, oldest first.
Returns LibraryError::Orm when the read fails.
pub async fn list_dispatched_events_page(
&self,
created_after: &str,
after: Option<(&str, &str)>,
limit: u64,
) -> Result<Vec<DomainEventRecord>>
Dispatched events newer than created_after, after optional (created_at, id) cursor.
Returns LibraryError::Orm when the read fails.
pub async fn upsert_event_subscriber(
&self,
node_id: &str,
plugin_id: &str,
subscriptions: &[EventCatalogSubscription],
enabled: bool,
) -> Result<()>
Heartbeat one node's plugin registration (does not delete other nodes).
Returns LibraryError::Orm when the write fails.
pub async fn upsert_event_subscriber_at(
&self,
node_id: &str,
plugin_id: &str,
subscriptions: &[EventCatalogSubscription],
enabled: bool,
heartbeat_at: DateTime<Utc>,
) -> Result<()>
Heartbeat one node's plugin registration at an explicit timestamp.
Returns LibraryError::Orm when the write fails.
pub async fn list_live_event_subscribers(
&self,
) -> Result<Vec<EventSubscriberCatalogRecord>>
Live catalog collapsed by plugin_id using the default heartbeat TTL.
Returns LibraryError::Orm when the read fails.
pub async fn list_live_event_subscribers_with_ttl(
&self,
ttl_secs: i64,
) -> Result<Vec<EventSubscriberCatalogRecord>>
Live catalog collapsed by plugin_id for a custom heartbeat TTL.
Returns LibraryError::Orm when the read fails.
pub async fn list_live_event_subscriber_nodes(
&self,
ttl_secs: i64,
) -> Result<Vec<EventSubscriberNodeRecord>>
Live per-node rows whose heartbeat is within ttl_secs.
Read in pages of the adapter's maxResultRows, keyed by
(plugin_id, node_id), so a catalog larger than one result still
reads on an adapter that does not paginate for the host.
Returns LibraryError::Orm when the read fails.
pub async fn dispatch_catalog_matches(
&self,
event: &DomainEventRecord,
operation_id: &str,
) -> Result<u32>
Create deliveries from the live catalog for one event.
Returns LibraryError::Orm when the write fails.
pub async fn reconcile_catalog_deliveries(
&self,
created_after: DateTime<Utc>,
) -> Result<u32>
Late-join catalog deliveries for missing (event_id, plugin_id) pairs.
Pages an anti-join of dispatched events in the retention window that
lack a delivery for each live plugin. Unchanged catalogs with no missing
pairs issue bounded empty SELECTs and zero dispatch writes.
Returns LibraryError::Orm when a read or write fails.
pub async fn request_event_delivery_cancel(
&self,
id: &str,
) -> Result<Option<EventDeliveryRecord>>
Cancel a pending delivery or flag a running one for cooperative stop.
Pending (including suspended) rows become rejected. Running rows set
cancel_requested so the heartbeat loop aborts onEvent.
Returns LibraryError::Orm when the update fails.
pub async fn event_delivery_cancel_requested(&self, id: &str) -> Result<bool>
True when a running delivery worker should abort after the current step.
Returns LibraryError::Orm when the read fails.
pub async fn resume_event_delivery(&self, id: &str) -> Result<bool>
Wake a suspended delivery: run_after = now and resume_pending = 1.
Returns LibraryError::Orm when the update fails.
pub async fn expire_unleased_event_deliveries(
&self,
retention_days: u64,
now: DateTime<Utc>,
) -> Result<u64>
Expire deliveries that waited, due but never leased, past their consumer's retention period.
This is the Cloudflare Queues message retention period applied per
subscriber: a plugin instance that is deployed but not running stops
accumulating work, and catches up from the event stream once it runs.
A delivery is a candidate while it is pending, has never been
leased (attempt_count = 0), and is not suspended or resuming. It
expires once both its insert time and its run_after are older than
the retention of the matching subscription in the live catalog
(message_retention_secs, else
EVENT_DELIVERY_DEFAULT_RETENTION_SECS), capped at
retention_days; a subscriber with no live catalog row waits the
full retention_days. The matching subscription is the first one of the
subscriber that matches the parent event in full (queue, type, schema
version and filter), as at dispatch. Host consumers (host: and node
consumers) never expire and are left out of the scan. Expired rows stay
until EventPruneStep::TerminalDeliveries removes them, so they
record which events a subscriber missed. About 10 000
candidates are examined per call (the budget is checked after each
page, so the last page can go past it); the next call resumes where this one
stopped and wraps around once it reaches the newest candidate.
retention_days- The events retention window, which caps every delivery retention.now- The time the retention periods are measured back from.
The number of deliveries moved to expired.
Returns LibraryError::Orm when a read or the update fails.
pub async fn read_event_stream(&self, read: &EventStreamRead) -> Result<EventStreamPage>
Reads one page of past domain events for EventPublisher.read.
Scans the outbox in (created_at, id) order from read.start, never
before read.retention_days, and returns the events any of
read.subscriptions matches (type, schema version and filter, as
delivery does), limited to read.account_id when set. Queue messages
are never returned. One call examines at most
EVENT_STREAM_SCAN_FACTOR times read.limit rows, in pages that fit
the adapter's bind and result-row limits; when the budget runs out
first the page says more and its last_scanned resumes the scan.
Returns LibraryError::Orm when a read fails.
pub async fn prune_event_deliveries(
&self,
retention_days: u64,
dead_letter_retention_days: u64,
) -> Result<u64>
Delete terminal deliveries past their retention windows, then empty events.
Acked, rejected and expired rows use retention_days. Dead letters use
dead_letter_retention_days. Dispatched parent events with no remaining
deliveries are removed only after the same retention_days cutoff.
Expired per-node catalog heartbeats are swept here too. Runs every
EventPruneStep in order; a caller that must recheck a lease between
deletes runs Self::prune_event_step itself.
Returns LibraryError::Orm when the delete fails.
pub async fn prune_event_step(
&self,
step: EventPruneStep,
retention_days: u64,
dead_letter_retention_days: u64,
) -> Result<u64>
Runs one delete of Self::prune_event_deliveries.
step- Which rows to expire or delete.retention_days- Window for acked, rejected and expired deliveries and empty dispatched events, and the cap on every delivery retention period.dead_letter_retention_days- Window for dead letters.
The number of rows expired or removed.
Returns LibraryError::Orm when the delete fails.
pub async fn mark_holdings_seen(
&self,
plugin_key: &str,
account_id: &str,
pass_id: &str,
product_ids: &[String],
) -> Result<()>
Stamps scan pass pass_id on the account's holdings of product_ids.
A holding is stamped whether or not its listing resolved on this page, so a title the library model could not settle is never taken for one that left the account.
plugin_key- The account's plugin (and the listings').account_id- The scanned account.pass_id- The pass in progress (account_scan_state.pass_id).product_ids- The product ids the page listed.
Returns an error when a batch fails.
pub async fn remove_account_holdings(
&self,
plugin_key: &str,
account_id: &str,
selection: HoldingSelection<'_>,
) -> Result<usize>
Removes the account's holdings that selection names, publishing
holding_removed for each in the batch that deletes it.
plugin_key- The account's plugin.account_id- The account.selection- Which of its holdings go.
How many holdings were selected for removal (a concurrent writer may have kept or removed some of them first).
Returns an error when a read or a batch fails; holdings removed by earlier batches stay removed.
pub async fn remove_node_holdings(
&self,
node_id: &str,
selection: NodeHoldingSelection<'_>,
) -> Result<usize>
Removes the holdings of branch node_id that selection names,
publishing holding_removed for each in the batch that deletes it.
Files already delivered for them stay with their editions.
How many holdings were selected for removal.
Returns an error when a read or a batch fails; holdings removed by earlier batches stay removed.
pub async fn refresh_library_works(&self, work_ids: &[String]) -> Result<u64>
Refreshes the page index rows of work_ids (an episode refreshes its
show): writes each work's row (an unheld work's with a holding count
of 0, which pages skip) and deletes the row of a work that is gone.
work_ids- Works whose editions, listings or holdings changed.
How many rows were written or deleted (a write skipped because a later refresh already wrote the row is not counted).
Returns LibraryError::Orm or a batch error when a read or write
fails.
pub async fn rebuild_library_index_page(
&self,
after: Option<&str>,
) -> Result<Option<String>>
Refreshes one page of the rebuild: the works with an id after
after, in id order, as LibraryStore::refresh_library_works
does.
after- The last work id of the previous page;Noneto start.
The last work id of this page, or None when the walk is done.
Returns LibraryError::Orm or a batch error when a read or write
fails.
pub async fn top_level_work_ids_page(
&self,
after: Option<&str>,
limit: u64,
) -> Result<Vec<String>>
One page of top-level work ids (podcast shows, not their episodes) in id order, for a walk over every work.
after- The last id of the previous page;Noneto start.limit- Most ids to return, further capped at the database's result-row limit.
Returns LibraryError::Orm when the read fails.
pub async fn library_index_built(&self) -> Result<bool>
True when the page index has a finished build of
LIBRARY_INDEX_LAYOUT.
Returns LibraryError::Orm when the read fails.
pub async fn drop_library_index_build(&self) -> Result<()>
Drops the finished build of LIBRARY_INDEX_LAYOUT, so the next
heartbeat queues a rebuild of every row: for a change, such as the
library's collections, that the rows' derivation reads but no
work's events carry.
Returns a batch error when the write fails.
pub async fn finish_library_index_build(&self) -> Result<()>
Records a finished build of LIBRARY_INDEX_LAYOUT.
Returns a batch error when the write fails.
pub async fn work_of_edition(&self, edition_id: &str) -> Result<Option<String>>
The works an edition belongs to (one, unless it was just moved).
Returns LibraryError::Orm when the read fails.
pub async fn work_of_listing(&self, listing_id: &str) -> Result<Option<String>>
The work a listing's edition belongs to.
Returns LibraryError::Orm when the read fails.
pub async fn library_works_by_ids(
&self,
ids: &[String],
query: &WorkPageQuery,
) -> Result<Vec<LibraryWorkRow>>
The rows of ids that pass query's filters, in the order of
ids (a search's relevance order); query's order, cursor and
limit are not used. Unheld works and ids with no row are left out.
ids- Top-level work ids.query- The filters to apply.
Returns LibraryError::Orm when a read fails.
pub async fn work_in_scope(&self, work_id: &str, scope: &WorkScope) -> Result<bool>
Whether a work is inside a patron scope: its top-level work (the
show, for an episode) is a held work of the page index that passes
scope.
Returns LibraryError::Orm when a read fails.
pub async fn edition_in_scope(
&self,
edition_id: &str,
scope: Option<&WorkScope>,
) -> Result<bool>
Whether an edition is inside a patron scope: no scope admits every
edition, and a scope admits one whose work passes
Self::work_in_scope. An edition that belongs to no work is
outside every scope, so a scoped patron never learns of it.
edition_id- The edition (editions.id).scope- The patron's filter,Nonewhen nothing is hidden.
Returns LibraryError::Orm when a read fails; callers fail closed.
pub async fn library_facet_values(
&self,
of: FacetValuesOf,
after: Option<&str>,
limit: u64,
scope: Option<&WorkScope>,
) -> Result<FacetValuesPage>
One page of the values a facet has across the held works, by key.
of- The facet, or the user whose tags to list.after- Thenextkey of the previous page;Noneto start.limit- Most values to return; at least 1, further capped at the database's result-row limit.scope- Count only the works inside this patron scope;Nonefor a caller who sees the whole library.
Returns LibraryError::Orm when the read fails.
pub async fn library_works_page(&self, query: &WorkPageQuery) -> Result<WorkPage>
One page of the library's works from the page index.
query- Order, filters, cursor and page size.
Returns LibraryError::Invalid when the cursor belongs to another
order, or LibraryError::Orm when the read fails.
pub async fn library_works_at(
&self,
query: &WorkPageQuery,
offset: u64,
limit: u64,
reversed: bool,
) -> Result<(Vec<LibraryWorkRow>, u64)>
One page of the library's works by position: limit rows from
offset in query's order (reversed when reversed), and how
many rows the query matches in all. query.after and
query.limit are not read.
For callers that page by number, such as player apps; the library's
own pages use Self::library_works_page, whose cursors hold
still while rows are added.
query- Order and filters.offset- Rows to skip.limit- Most rows to return.reversed- True to read the order backwards.
Returns LibraryError::Orm when a read fails.
pub async fn owned_work_for(&self, query: &TitleQuery<'_>) -> Result<Option<String>>
The work in the library that query belongs to, when the library
holds one.
The query is resolved exactly as a scanned listing would be (shared identifiers first, then the work's identifiers, then the work-level title-and-author match), but nothing is written. A query that would make a new work, or whose work nothing in the library holds, is not owned: Dune Messiah is its own work beside Dune. A query that cannot form a valid listing (a blank title, or a field over the listing limits) matches no work, so it is not owned either.
Returns LibraryError when a read fails.
pub async fn work_for(&self, query: &TitleQuery<'_>) -> Result<Option<String>>
The existing work query belongs to, held by a library title or
not, when the resolver finds one; None when it would make a new
work. Nothing is written. A wish stores this id when it is created,
so the queue and the shelves compare works, not words.
Returns LibraryError when a read fails. A query that cannot form
a valid listing (a blank title, or a field over the listing limits)
names no work.
pub async fn existing_edition_work(&self, listing: &Listing) -> Result<Option<String>>
The work of the stored edition listing would join, without
writing anything: Some only when the resolver places it on an
edition this library already has (through a shared identifier), so
no new work, expression or edition, and no title match, is involved.
Returns LibraryError when a read fails.
pub async fn work_for_wish(
&self,
query: &TitleQuery<'_>,
) -> Result<(String, Option<String>)>
The work a wish for query is for, made when the library has none.
The query is resolved exactly as Self::work_for resolves it. When
that names an existing work (held by a library title or not), that is
the work. Otherwise a catalog work is written as one atomic batch:
the work, an expression and an edition carrying the wish's ASIN and
ISBN (a non-acquirable catalog edition, as the data model ADR keeps
catalog results), then their credits and series. No store listing or
holding is written, so the library does not hold it. A later wish
with the same identifiers joins that edition, and a later scan of the
book finds the work through the work matcher (same title, authors
and kind), so wishes and the scanned title share the work.
Every id is derived (the work's from its match key, the edition's
from the query, the expression's from both) and every row is
inserted with INSERT OR IGNORE, so two wishes for one new book made
at once (on one node or two) name the same rows.
query- The wished title, authors, identifiers and series.
The work, and the existing edition the query's identifiers reached
(None when they reached none).
Returns LibraryError::Invalid when the query cannot form a valid
listing (a blank title, or a field over the listing limits), and
LibraryError when a read or write fails.
pub async fn record_listing(
&self,
listing: &Listing,
holding: &HoldingDraft,
) -> Result<Plan>
Resolves listing into the library and records holding of it.
listing- The validated listing a storefront reported.holding- Who holds it, and how.
The plan that was written (a no-op plan when nothing changed).
Returns LibraryError when a read or write fails, when the stored
rows are inconsistent, or when other writers kept changing the rows
for three attempts.
pub async fn record_catalog_listing(&self, listing: &Listing) -> Result<Plan>
Resolves a catalog listing (a title a store sells that nobody in
the library holds) into the library: its work, expression, edition
and store_listings row, with no holding.
A later scan of the same product finds the same listing row and adds only its holding, so a catalog listing and a held one never diverge.
The plan that was written (a no-op plan when nothing changed).
pub async fn works_by_ids(&self, ids: &[String]) -> Result<BTreeMap<String, WorkRecord>>
Loads many works by id, with their work-level credits, narrators and series, in chunked bulk reads.
ids- Work ids; unknown ids are left out of the result.
The works found, keyed by id.
Returns LibraryError::Orm when a read fails.
pub async fn get_work(&self, id: &str) -> Result<Option<WorkRecord>>
Loads a work by id, with its work-level credits and series.
Returns LibraryError::Orm when a read fails.
pub async fn list_works_page(
&self,
after_id: Option<&str>,
limit: u64,
) -> Result<Vec<WorkRecord>>
Lists up to limit works with ids after after_id, in id order, with
their work-level credits and series.
A keyset page: pass the last id of one page as after_id of the
next, and stop at a short page. Unlike Self::list_works it never
reads the whole table at once.
after_id- Exclusive lower bound onworks.id;Nonestarts at the first work.limit- Page size, clamped to 1..=500.
Returns LibraryError::Orm when a read fails.
pub async fn embedding_text_hashes(
&self,
target_kind: &str,
model: &str,
target_ids: &[String],
) -> Result<HashMap<String, String>>
Stored text hashes of the model embeddings of target_kind targets
among target_ids, keyed by target id. Targets with no embedding are
absent.
Reads in chunks sized from the adapter's bind limit, so one call replaces a lookup per target.
Returns LibraryError::Orm when a read fails.
pub async fn prune_orphan_work_embeddings(&self) -> Result<u64>
Deletes work embeddings (every model) whose work no longer exists, and answers how many it removed.
Returns LibraryError::Orm when the delete fails.
pub async fn list_works(&self) -> Result<Vec<WorkRecord>>
Lists every work by title, with its work-level credits and series.
Returns LibraryError::Orm when a read fails.
pub async fn work_of_holding(&self, holding_id: &str) -> Result<Option<String>>
The work holding holding_id (holdings.id) reaches through its
listing's edition; None when the holding or its listing is gone.
Returns LibraryError::Orm when a read fails.
pub async fn works_of_editions(
&self,
edition_ids: BTreeSet<String>,
) -> Result<BTreeMap<String, String>>
Each edition's work, through its expression, read in chunks that fit the database's limits.
Edition id to work id; an edition that no longer exists, or whose expression row is missing, is left out.
Returns LibraryError::Orm when a read fails.
pub async fn set_work_enrichment(
&self,
work_id: &str,
enrichment: &WorkEnrichment,
) -> Result<()>
Fills a work's enrichment fields; None keeps the stored value.
work_id- The work.enrichment- Description, subjects and cover found by enrichment.
Returns LibraryError::NotFound when the work is gone, or
LibraryError::Orm when the write fails.
pub async fn add_work_identifier(
&self,
work_id: &str,
scheme: IdentifierScheme,
raw: &str,
) -> Result<()>
Attaches a work-level identifier enrichment found (an OpenLibrary work id); a value another work already holds is left there.
Returns LibraryError::Orm when the write fails.
pub async fn match_listening_items(
&self,
items: &[ListeningIdentifiers],
) -> Result<Vec<ListeningMatch>>
Resolves many listening items to works in a few bulk lookups.
The item's ASIN is tried first, then its ISBN; the first one that
names a work decides it. For that identifier, the work comes from the
editions whose edition_identifiers carry it (an ASIN in any
marketplace), used only when those editions agree on one work; the
edition is kept when exactly one carries it. Titles are never
compared.
items- Each item's identifiers.
One match per item, in the same order; an item no identifier resolves has neither a work nor an edition.
Returns LibraryError::Orm when a read fails.
pub async fn portal_identity_ids(
&self,
provider: &str,
external_user_ids: &BTreeSet<String>,
) -> Result<BTreeMap<String, i64>>
Portal identity ids of many external users of one provider.
provider- Identity provider / integration id.external_user_ids- User ids at that provider.
portal_identities.id keyed by external user id; users with no
identity are absent.
Returns LibraryError::Orm when a read fails.
pub async fn upsert_listening_progress_batch(
&self,
rows: &[NewListeningProgress],
) -> Result<Vec<ListeningProgressWrite>>
Stores many listening rows in a few chunked reads and atomic batches.
Reports for one (provider, external_user_id, external_item_id) are
merged in order over the stored row, exactly as successive calls to
Self::upsert_listening_progress would merge them: optional text
and the identity keep their stored value when a report leaves them
out, progress fields take the report's. Each row is written once.
The writes are split into atomic batches under the database plugin's
maxStatements and maxRequestBytes; a row's two statements always
share a batch. No interactive transaction is used, so a reader
between two batches can see part of the sync.
rows- Reports to store, in the order the provider sent them.
One write per distinct row key, in the order the keys first appear.
Returns the database error. Batches sent before a failing one stay written.
pub async fn route_notification(
&self,
new: &NewNotification,
limits: NotifyQueueLimits,
) -> Result<Routed>
Accepts a notification: stores it, writes one delivery-log row per
destination the routing rules pick and, for a patron, the inbox row,
in one batch; then enqueues one notify_send job per delivery.
new- The notification, already rendered.limits- The queue limits the send jobs are admitted under.
The stored id and the deliveries made.
LibraryError::Invalid when the notification breaks a message
rule; LibraryError::NotFound when its patron does not exist;
LibraryError::Conflict when route replacements kept landing while
it was routed; an error when a read or the batch fails. A failed
enqueue is not an error: the delivery waits for the sweep.
pub async fn route_notification_to(
&self,
new: &NewNotification,
destination_id: &str,
limits: NotifyQueueLimits,
) -> Result<Routed>
Stores new with one delivery to destination destination_id
alone, whatever the routes say: an administrator's test of a
destination.
LibraryError::Invalid when the notification breaks a message
rule; LibraryError::NotFound when the destination does not
exist; an error when a read or the batch fails.
pub async fn user_holds_account(
&self,
user_id: i64,
plugin_key: &str,
account_id: &str,
) -> Result<bool>
Whether user user_id holds store account (plugin_key,
account_id) through one of their linked identities: the check a
plugin's patron raise must pass inside its invocation's account
scope.
An error when a read fails.
pub async fn enqueue_notify_send(
&self,
delivery: &PendingDelivery,
limits: NotifyQueueLimits,
) -> Result<Option<String>>
Enqueues the notify_send job of one delivery and records its id.
The job id, or None when the queue is full (the sweep tries again).
An error when the enqueue or the write fails.
pub async fn unscheduled_notify_deliveries(
&self,
limit: u64,
) -> Result<Vec<PendingDelivery>>
Pending deliveries no send job was recorded for, oldest first: the ones whose enqueue failed or found the queue full.
An error when the read fails.
pub async fn drop_orphaned_notify_deliveries(&self) -> Result<u64>
Drops pending deliveries whose send job ended without recording a result (an operator cancelled it, or it failed on a host error), so the sweep does not send them again behind the operator's back and the delivery log says what happened.
How many deliveries were dropped.
An error when the batch fails.
pub async fn stalled_notify_sends(
&self,
ready_before: DateTime<Utc>,
after: Option<&str>,
limit: u64,
) -> Result<(Vec<StalledSend>, Option<String>)>
One page of send jobs still pending although they have been ready
to run since before ready_before, with the pending delivery and
notifier instance of each when it still has one. Whether a job is
stalled or only waiting behind other work depends on whether its
notifier runs anywhere, which the caller decides.
Pending send jobs are walked by id, after the last id of the
previous page (None for the first), at most limit rows a page;
the second value is the cursor of the next page, None after the
last. Only the id, readiness, lease generation and dedup key columns
are read, so a page stays narrow under the database's result-size
cap, and a page the database still refuses for its size is read
again at half the rows. Readiness is compared here rather than in
SQL because stored timestamps carry a varying number of fractional
digits, so they do not order as text.
The delivery comes from the job's dedup key (it names the delivery
the job was enqueued for), not from the delivery's job_id, so a
job whose link write failed is still matched with its delivery.
An error when a read fails.
pub async fn fail_stalled_notify_send(
&self,
stalled: &StalledSend,
reason: &str,
) -> Result<StallOutcome>
Cancels one stalled send job and fails its pending delivery in a single atomic write, so a claim racing the sweep either wins (and nothing changes) or loses (and the failure is counted toward the destination's pause), and the cancel never lands without the count. A delivery whose destination is already paused is dropped instead, with no attempt or failure counted, as a send would drop it. Only call this for a job whose notifier runs nowhere; a job that is only waiting for a worker is not a notifier failure.
What happened; StallOutcome::NotStalled when the job was
claimed, retried or ended since it was read.
An error when the batch fails.
pub async fn drop_notify_delivery_if_job_ended(&self, delivery_id: &str) -> Result<bool>
Drops a pending delivery no send job is linked to when a send job for it already ended: its enqueue succeeded but the link write did not, and the job was then cancelled or failed. Without this the sweep would queue a second send behind the operator's back, since the ended job no longer blocks a new one with the same dedup key.
Whether the delivery was dropped (and must not be enqueued again).
An error when the read or the batch fails.
pub async fn notify_send_work(&self, delivery_id: &str) -> Result<Option<SendWork>>
Everything the send job of delivery_id needs; None when the row
is gone (pruned, or its notification or destination removed).
An error when a read fails or a stored value is malformed.
pub async fn record_notify_delivered(
&self,
delivery_id: &str,
provider_id: Option<&str>,
fence: Option<&JobFence>,
) -> Result<bool>
Records a delivered send: the delivery is done and its destination's failure count is cleared.
false when the delivery was no longer pending (a replayed job).
fence- The send job's claim; the write is skipped (and answers as if the delivery were no longer pending) once that claim has lost the job.
An error when the batch fails.
pub async fn record_notify_retry(
&self,
delivery_id: &str,
reason: &str,
fence: Option<&JobFence>,
) -> Result<Option<i64>>
Records a send attempt the notifier asked to retry.
The attempts made, this one included; None when the delivery was
no longer pending.
fence- The send job's claim; the write is skipped (and answers as if the delivery were no longer pending) once that claim has lost the job.
An error when the batch or the read fails.
pub async fn record_notify_failed(
&self,
delivery_id: &str,
reason: &str,
attempt: FailedAttempt,
fence: Option<&JobFence>,
) -> Result<Option<FailureEffect>>
Records a send the notifier refused for good (or that ran out of
attempts): the delivery fails and its destination's failure count
rises, pausing it at PAUSE_AFTER_FAILURES.
Whether this failure paused the destination; None when the
delivery was no longer pending.
fence- The send job's claim; the write is skipped (and answers as if the delivery were no longer pending) once that claim has lost the job.attempt- Whether this answer spends an attempt of its own.
An error when the batch or the read fails.
pub async fn record_notify_dropped(
&self,
delivery_id: &str,
reason: &str,
fence: Option<&JobFence>,
) -> Result<bool>
Records a delivery that was not sent (its destination is paused or gone, or its notifier instance is gone). The destination's failure count is untouched.
false when the delivery was no longer pending.
fence- The send job's claim; the write is skipped (and answers as if the delivery were no longer pending) once that claim has lost the job.
An error when the batch fails.
pub async fn create_notify_destination(&self, new: &NewDestination) -> Result<Destination>
Creates a destination.
LibraryError::Invalid for a bad label, a channel with an owner or
an address, a personal destination without an owner, or one past
the owner's MAX_ROUTES_PER_TYPE addresses;
LibraryError::NotFound when the owner does not exist; an error
when the batch fails.
pub async fn notify_destination(&self, id: &str) -> Result<Option<Destination>>
One destination by id.
An error when the read fails or the row is malformed.
pub async fn notify_channels(&self) -> Result<Vec<Destination>>
Every library channel, oldest first.
An error when the read fails.
pub async fn personal_destinations(&self, user_id: i64) -> Result<Vec<Destination>>
One patron's personal destinations, oldest first.
An error when the read fails.
pub async fn rename_notify_destination(&self, id: &str, label: &str) -> Result<()>
Renames a destination.
LibraryError::Invalid for a bad label;
LibraryError::NotFound when the destination does not exist.
pub async fn resume_notify_destination(&self, id: &str) -> Result<()>
Resumes a paused destination and clears its failure count.
LibraryError::NotFound when the destination does not exist.
pub async fn delete_notify_destination(&self, id: &str) -> Result<()>
Deletes a destination with its routes, patron targets and delivery log rows.
LibraryError::NotFound when the destination does not exist.
pub async fn notify_routes(&self) -> Result<BTreeMap<String, Vec<Route>>>
Every operational route, by type; an "In app" route comes first in
its type's list under IN_APP_DESTINATION.
An error when the read fails or a stored severity is malformed.
pub async fn set_notify_routes(
&self,
notification_type: &str,
routes: &[Route],
) -> Result<()>
Replaces the routes of one operational type. A route to
IN_APP_DESTINATION is the staff inbox, not a stored destination.
LibraryError::Invalid for too many routes, a repeated destination
or one that is not a channel; LibraryError::NotFound when a
destination does not exist.
pub async fn patron_offers(&self) -> Result<BTreeMap<String, Vec<PatronOffer>>>
Every patron offer, by type.
An error when the read fails.
pub async fn set_patron_offers(
&self,
notification_type: &str,
offers: &[PatronOffer],
) -> Result<()>
Replaces the instances offered to patrons for one patron type.
LibraryError::Invalid for too many offers or a repeated instance.
pub async fn patron_choices(&self, user_id: i64) -> Result<Vec<PatronChoice>>
One patron's choices, by type.
An error when a read fails.
pub async fn set_patron_choice(&self, user_id: i64, choice: &PatronChoice) -> Result<()>
Stores one patron's choice for one patron type, replacing the last.
LibraryError::Invalid for too many or repeated destinations, or,
when the choice is enabled, one on a notifier not offered for the
type;
LibraryError::NotFound when a destination does not exist.
pub async fn clear_patron_choice(
&self,
user_id: i64,
notification_type: &str,
) -> Result<()>
Drops one patron's choice for a type, so the defaults apply again.
An error when the batch fails.
pub async fn notify_deliveries(
&self,
destination_id: Option<&str>,
before: Option<&NotifyCursor>,
limit: u64,
) -> Result<NotifyPage<DeliveryRecord>>
One page of the delivery log, newest first.
destination_id- Only this destination's rows, when set.before- Where the page starts (the previous page's last row).limit- Page size, clamped to1..=MAX_NOTIFY_PAGE.
An error when a read fails or a stored value is malformed.
pub async fn inbox(
&self,
user_id: i64,
before: Option<&NotifyCursor>,
limit: u64,
) -> Result<NotifyPage<InboxEntry>>
One page of a patron's inbox, newest first.
user_id- The patron.before- Where the page starts (the previous page's last entry; its id is the notification id).limit- Page size, clamped to1..=MAX_NOTIFY_PAGE.
An error when a read fails or a stored value is malformed.
pub async fn inbox_unread(&self, user_id: i64) -> Result<u64>
How many entries in a patron's inbox are unread.
An error when the read fails.
pub async fn mark_inbox_read(
&self,
user_id: i64,
notification_id: Option<&str>,
) -> Result<u64>
Marks one inbox entry read, or every unread one when
notification_id is None.
How many entries changed.
LibraryError::NotFound when the named entry is not in this
patron's inbox; an error when the batch fails.
pub async fn prune_notifications(&self, now: DateTime<Utc>) -> Result<u64>
Deletes notifications older than NOTIFICATION_RETENTION_DAYS as
of now, with their inbox entries and delivery-log rows.
How many notifications were deleted.
An error when the batch fails; nothing is deleted then.
pub async fn pin_listing(
&self,
listing_id: &str,
edition_id: &str,
user_id: Option<i64>,
) -> Result<PinOutcome>
Pins listing_id to edition_id: records the Administrator's
decision and moves the listing there, as one atomic batch.
Every statement requires both the listing and the edition to exist,
so an unknown id writes nothing. The listing's recorded conflicts are
dropped (the pin settles them). When the listing moves, the batch
publishes edition_linked for edition_id and edition_updated for
the edition it left; both are published only while this batch's pin
is the stored one.
listing_id- The listing (store_listings.id).edition_id- The edition it sells (editions.id).user_id- The Administrator (users.id);Nonefor the operator.
What the pin did.
Returns the database error of a failed read or write.
pub async fn unpin_listing(&self, listing_id: &str) -> Result<bool>
Removes the pin on listing_id, if any.
The listing keeps selling the edition it was pinned to: the resolver keeps a stored listing's edition, so a pin only ever moves a listing when it is made.
Whether a pin was removed.
Returns the database error of a failed read or write.
pub async fn listing_pin(&self, listing_id: &str) -> Result<Option<String>>
The edition listing_id is pinned to, or None when it has no pin.
Returns LibraryError::Orm when the read fails.
pub async fn list_resolution_conflicts(
&self,
after: Option<&ConflictCursor>,
limit: u64,
) -> Result<(Vec<ResolutionConflict>, Option<ConflictCursor>)>
One page of the conflicts the resolver recorded, in key order (listing, kind, subjects), with each listing's store and title.
after- Where the previous page stopped;Nonestarts at the first conflict.limit- Page size, clamped to 1..=MAX_CONFLICT_PAGEand to the database plugin's result-row cap.
The page, and the cursor of the next page when this one is full.
Returns LibraryError::Orm when a read fails, or
LibraryError::Invalid when a stored subject list is not a JSON
array of strings.
pub async fn record_resolution_conflict_for_test(
&self,
listing_id: &str,
kind: &str,
subject_ids: &[&str],
)
Records a resolver conflict for listing_id, as a scan that could
not decide would. Test support only.
When the write fails.
pub async fn account_pace_state(
&self,
plugin_key: &str,
account_id: &str,
now: DateTime<Utc>,
) -> Result<AccountPaceState>
Reads one account's pacing state at now.
plugin_key- The account's plugin.account_id- The account.now- The current time (the window ends here).
Returns LibraryError::Orm when a read fails.
pub async fn set_account_pace_override(
&self,
plugin_key: &str,
account_id: &str,
override_: &PaceOverride,
) -> Result<()>
Stores the operator's override of an account's pace (the cool-down
is kept), and wakes parked paced acquires that may download on it so
they look at the new pace (Self::wake_paced_acquires).
Returns LibraryError::Other when the override is out of range
(PaceOverride::validate), or an error when the batch fails.
pub async fn extend_account_cooldown(
&self,
plugin_key: &str,
account_id: &str,
until: DateTime<Utc>,
) -> Result<()>
Records the store's cool-down for an account, unless one that ends later is already recorded.
Returns an error when the batch fails.
pub async fn clear_account_cooldown(
&self,
plugin_key: &str,
account_id: &str,
) -> Result<()>
Clears an account's cool-down (the operator knows better), and wakes
parked paced acquires that may download on it
(Self::wake_paced_acquires).
Returns an error when the batch fails.
pub async fn record_account_download(
&self,
id: &DownloadId,
plugin_key: &str,
account_id: &str,
started_at: DateTime<Utc>,
job_id: Option<&str>,
starter: DownloadStarter,
) -> Result<()>
Records a download that reached the store, and prunes the account's
ledger rows older than LEDGER_RETENTION, in one batch.
Writing the same id again adds no second row, so a write whose
answer was lost may be retried.
id- The download's identity, the same for every write attempt.plugin_key- The account's plugin.account_id- The account.started_at- When the download started.job_id- The acquire job that ran it, if any.starter- Whether the host or a person started it.
Returns an error when the batch fails.
pub async fn playback_edition(&self, edition_id: &str) -> Result<Option<PlaybackEdition>>
The edition a player asks about, with its work and catalog runtime.
None for an unknown edition.
Returns the read error.
pub async fn playback_progress(
&self,
user_id: i64,
edition_id: &str,
) -> Result<Option<PlaybackProgress>>
One person's progress in one edition.
Returns the read error.
pub async fn list_playback_progress(
&self,
user_id: i64,
include_finished: bool,
after: Option<&ProgressCursor>,
limit: u64,
) -> Result<(Vec<PlaybackProgress>, Option<ProgressCursor>)>
A page of one person's progress rows, most recently played first.
user_id- The listener.include_finished- False lists only editions not yet finished (Continue listening).after- The last row of the page before;Nonefor the first.limit- Most rows to return.
The rows, and the cursor of the next page when there may be one.
Returns the read error.
pub async fn set_playback_progress(
&self,
user_id: i64,
edition_id: &str,
work_id: Option<&str>,
edit: &PlaybackProgressEdit,
) -> Result<PlaybackChange>
Sets one person's progress in one edition outright, with no session: a seek from the book's page, Mark finished or Start over.
The row is created when the person has none. Finishing also sets
the work's finished flag when work_id is given. One atomic batch;
nothing is written for an unknown edition on an engine that checks
foreign keys, which is then the returned error.
user_id- The listener.edition_id- The edition.work_id- The edition's work, for the finished flag.edit- What to store.
Returns the database error.
pub async fn delete_playback_progress(
&self,
user_id: i64,
edition_id: &str,
) -> Result<bool>
Forgets one person's progress in one edition. The work's finished flag is left as it is.
True when a row was removed.
Returns the database error.
pub async fn open_playback_session(
&self,
new: NewPlaybackSession<'_>,
) -> Result<PlaybackSession>
Opens a play session and answers it.
The session starts where the person's progress is, or at the start when they have none or had finished the edition (playing a finished edition again starts it over and clears the edition's finished flag; the work stays finished). One atomic batch.
Returns the database error, for example for an unknown edition on an engine that checks foreign keys.
pub async fn playback_session(&self, id: &str) -> Result<Option<PlaybackSession>>
One play session by id.
Returns the read error.
pub async fn sync_playback_session(
&self,
session: &PlaybackSession,
work_id: Option<&str>,
sync: &PlaybackSync,
) -> Result<Option<PlaybackChange>>
Records a player's report for an open session: the position, the
time listened since the last report and, with close, its end.
The person's progress moves with it. When the position reaches the
recording's end (reaches_end) the edition is marked finished,
and so is its work when work_id is given. One atomic batch, in
which the progress only moves if the session was still open.
session- The session, as read just before.work_id- The edition's work, for the finished flag.sync- The player's report.
None when the session had already closed; nothing is written
then.
Returns the database error.
pub async fn publish_playback_event(
&self,
event: PlaybackEvent,
progress: &PlaybackProgress,
work_id: Option<&str>,
session_id: Option<&str>,
)
Publishes a playback host event, after the write it describes.
Best effort: the listening state is already committed, so a failed publish is logged rather than undoing it.
Payload: userId, editionId, workId (or null), sessionId (or
null when progress was set outright), positionMs and durationMs
(or null while no player has reported the runtime).
event- Which event.progress- The listener's progress after the write.work_id- The edition's work.session_id- The play session, when the write came from one.
pub async fn list_bookmarks(
&self,
user_id: i64,
edition_id: &str,
) -> Result<Vec<Bookmark>>
One person's bookmarks in one edition, in timeline order.
Returns the read error.
pub async fn bookmark(&self, id: &str) -> Result<Option<Bookmark>>
One bookmark by id.
Returns the read error.
pub async fn add_bookmark(
&self,
user_id: i64,
edition_id: &str,
position: PlaybackMs,
title: &str,
) -> Result<Option<Bookmark>>
Adds a bookmark for one person in one edition.
user_id- The person.edition_id- The edition.position- The place to mark.title- Their note; at mostMAX_BOOKMARK_TITLE_BYTESbytes are kept.
The bookmark, or None when the person already keeps
MAX_BOOKMARKS_PER_EDITION in the edition.
Returns the database error.
pub async fn edit_bookmark(
&self,
user_id: i64,
id: &str,
position: Option<PlaybackMs>,
title: Option<&str>,
) -> Result<Option<Bookmark>>
Changes one of a person's bookmarks.
user_id- The person; another person's bookmark is not found.id- The bookmark.position- The new place;Nonekeeps it.title- The new note;Nonekeeps it.
The bookmark after the change, or None when the person has no
such bookmark.
Returns the database error.
pub async fn delete_bookmark(&self, user_id: i64, id: &str) -> Result<bool>
Removes one of a person's bookmarks.
True when a bookmark of theirs was removed.
Returns the database error.
pub async fn insert_player_password(
&self,
user_id: i64,
label: &str,
password_hash: &str,
) -> Result<Option<PlayerPassword>>
Stores a new player password for user_id.
user_id- The patron.label- Its name; trimmed, and at mostMAX_PLAYER_PASSWORD_LABEL_BYTESbytes are kept.password_hash- SHA-256 hex of the generated password.
The password, or None when the patron already keeps
MAX_PLAYER_PASSWORDS.
Returns the database error.
pub async fn list_player_passwords(&self, user_id: i64) -> Result<Vec<PlayerPassword>>
A patron's player passwords, newest first.
Returns the read error.
pub async fn delete_player_password(&self, user_id: i64, id: &str) -> Result<bool>
Removes one of a patron's player passwords and ends every card it signed in.
True when a password of theirs was removed.
Returns the database error.
pub async fn use_player_password(
&self,
password_hash: &str,
) -> Result<Option<PlayerPassword>>
The player password a sign-in presents, by digest, and its patron; marks it used.
The password, or None for no such password.
Returns the database error.
pub async fn mint_player_card(&self, card: NewPlayerCard<'_>) -> Result<Option<i64>>
Makes a player card: its session row, its card row and its first access and refresh tokens, in one batch.
The card's session id, or None when the player password it names
was removed meanwhile.
Returns the database error.
pub async fn player_card_by_access(&self, access_hash: &str) -> Result<Option<PlayerCard>>
Resolves a player card's access token to its card and identity, touching the session at most once a minute as a browser session is.
access_hash- SHA-256 hex of the access token.
None for an unknown or expired token or an ended card.
Returns the database error.
pub async fn refresh_player_card(
&self,
refresh_hash: &str,
tokens: PlayerCardTokens<'_>,
) -> Result<Option<PlayerCard>>
Trades a refresh token for a new access and refresh token, in one
batch. The presented token and every other refresh token of the
card keep working for PLAYER_REFRESH_GRACE_SECS more, so two
refreshes racing with one token both succeed; the card's thirty
days start again.
refresh_hash- SHA-256 hex of the presented refresh token.tokens- Digests of the new pair.
The card, or None when the token does not refresh: unknown,
expired, or its card ended.
Returns the database error.
pub async fn end_player_card(&self, token_hash: &str) -> Result<bool>
Ends the card a token (access or refresh) belongs to: the app signed out.
True when a live card was ended.
Returns the database error.
pub async fn player_editions_of_works(
&self,
work_ids: &[String],
) -> Result<HashMap<String, String>>
The edition each work is listed by in the player API: of its audio editions this library acquired, the one acquired last. A work with none is left out.
work_ids- Works (top-level works of the page index).
Returns LibraryError::Orm when a read fails.
pub async fn player_items(&self, edition_ids: &[String]) -> Result<Vec<PlayerItem>>
The items of edition_ids, in the same order: audio editions this
library acquired. An unknown, unacquired or non-audio edition is
left out.
Returns LibraryError::Orm when a read fails.
pub async fn player_items_page(
&self,
query: &WorkPageQuery,
offset: u64,
limit: u64,
reversed: bool,
) -> Result<(Vec<PlayerItem>, u64)>
The items of one page of works (Self::library_works_at), each
work by the edition Self::player_editions_of_works picks, and
how many works the query matches in all. A work with no acquired
audio edition is left out of the page.
query- Order and filters of the page index.offset- Works to skip.limit- Most works to read.reversed- True to read the order backwards.
Returns LibraryError::Orm when a read fails.
pub async fn list_playback_sessions(
&self,
user_id: i64,
offset: u64,
limit: u64,
) -> Result<(Vec<PlaybackSession>, u64)>
One person's play sessions, newest first: limit from offset,
and how many they have in all.
Returns LibraryError::Orm when a read fails.
pub async fn list_user_bookmarks(&self, user_id: i64, cap: u64) -> Result<Vec<Bookmark>>
Every bookmark one person made, at most cap, oldest first.
Returns LibraryError::Orm when a read fails.
pub async fn record_plugin_database(
&self,
plugin_id: &str,
binding: &str,
adapter_plugin_key: &str,
backend_kind: &str,
unit_ref: &str,
) -> Result<PluginDatabaseRecord>
Records one provisioned binding unit, keeping any existing row.
Returns the authoritative row (an earlier registration wins so a re-open never silently re-targets a binding at a different unit).
Returns an error when the insert or lookup fails.
pub async fn get_plugin_database(
&self,
plugin_id: &str,
binding: &str,
) -> Result<Option<PluginDatabaseRecord>>
The registry row for (plugin_id, binding), if provisioned.
Returns an error when the query fails.
pub async fn list_plugin_databases(
&self,
plugin_id: Option<&str>,
) -> Result<Vec<PluginDatabaseRecord>>
All registry rows, optionally filtered to one owner PluginKey.
Returns an error when the query fails.
pub async fn remove_plugin_databases(
&self,
plugin_id: &str,
binding: Option<&str>,
) -> Result<u64>
Deletes registry rows for a plugin (one binding, or all of them).
Removes only the registry entry; dropping the underlying unit is the caller's responsibility (operator CLI / uninstall flow).
Returns an error when the delete fails.
pub async fn rebind_plugin_database(
&self,
plugin_id: &str,
binding: &str,
adapter_plugin_key: &str,
backend_kind: &str,
unit_ref: &str,
) -> Result<PluginDatabaseRecord>
Inserts or updates placement for one (plugin_id, binding) on restore.
Logical identity is portable; adapter_plugin_key / backend_kind /
unit_ref are the target adapter's physical placement, never the
source's.
Returns when the upsert fails.
pub async fn kv_get(
&self,
plugin_key: &str,
namespace: &str,
key: &str,
) -> Result<Option<KvEntry>>
Reads one key; None when absent or expired.
Returns an error when the query fails.
pub async fn kv_put(
&self,
plugin_key: &str,
namespace: &str,
key: &str,
spec: KvWriteSpec,
) -> Result<KvPutOutcome>
Writes one key, replacing any previous value, metadata, and expiry.
Enforces spec.max_value_bytes and spec.max_keys (expired rows do
not count and are reclaimed to make room).
Returns an error when the write fails.
pub async fn kv_delete(
&self,
plugin_key: &str,
namespace: &str,
key: &str,
) -> Result<bool>
Deletes one key. Returns whether a live value existed.
Returns an error when the delete fails.
pub async fn kv_list(
&self,
plugin_key: &str,
namespace: &str,
prefix: &str,
cursor: &str,
limit: u32,
) -> Result<KvListPage>
Lists live keys in lexical order, limit per page (0 means
KV_LIST_DEFAULT_LIMIT). cursor is the opaque value a previous
page returned; empty starts from the beginning.
Returns an error when the query fails or the cursor is malformed.
pub async fn kv_count(&self, plugin_key: &str, namespace: &str) -> Result<u64>
Live keys in one namespace.
Returns an error when the query fails.
pub async fn kv_prune_expired_in(&self, plugin_key: &str, namespace: &str) -> Result<u64>
Removes expired rows of one namespace. Returns the rows removed.
Returns an error when the delete fails.
pub async fn kv_prune_expired(&self) -> Result<u64>
Removes every expired row across all plugins and namespaces.
Returns an error when the delete fails.
pub async fn kv_delete_plugin(&self, plugin_key: &str) -> Result<u64>
Removes every row of one plugin (retire / uninstall).
Returns an error when the delete fails.
pub async fn replace_request_queue_ranks(&self, ranks: &[QueueRank]) -> Result<()>
Replaces the stored queue ranking with ranks.
Each row is upserted with this pass's time, then every row this pass did not write (an entry whose wishes were all closed) is deleted. The writes go to the database plugin as canonical atomic batches sized from its advertised limits, never an interactive transaction; the delete rides in the last batch. A reader between two batches can see part of the new ranking next to old rows, which only shifts order.
ranks- One ranking per queue entry; a repeatedwork_idkeeps the last.
Returns the database error. Batches written before it stay; old rows are deleted only once every new row is stored.
pub async fn list_request_queue_ranks(&self) -> Result<Vec<StoredQueueRank>>
Lists every stored queue ranking row.
Rows are read in work id pages of a bounded size; a page whose result
would exceed the plugin's maxResultBytes is halved and read again.
A row whose reasons do not parse keeps its score with no reasons.
Returns the database error.
pub async fn prune_record_step(
&self,
step: RecordPruneStep,
now: DateTime<Utc>,
) -> Result<u64>
Runs one retention delete as of now and answers how many rows
(for RecordPruneStep::StorageScans, generations) it removed.
step- Which table and rule to apply.now- The instant the windows are measured back from; the maintenance duty passes the current time, tests a fixed one.
Returns LibraryError::Orm when a read or delete fails; rows the
step had not reached yet are left for the next pass.
pub async fn quality_check_state(
&self,
plugin_key: &str,
account_id: &str,
) -> Result<Option<QualityCheckState>>
Reads where an account's quality-upgrade check stands.
None when the account has no scan state yet (it was never
scanned, so it holds nothing to check).
Returns an error when the read fails.
pub async fn save_quality_check(
&self,
plugin_key: &str,
account_id: &str,
cursor: &str,
at: DateTime<Utc>,
) -> Result<()>
Records that a quality-upgrade check of an account ran at at and
continues after holding cursor next time (empty starts over).
Writes only an existing row of an account that is not revoked; the scan creates the row.
Returns an error when the batch fails.
pub async fn scan_state(
&self,
plugin_key: &str,
account_id: &str,
) -> Result<Option<ScanState>>
Reads where an account's scan stands.
Returns an error when the read fails.
pub async fn save_scan_checkpoint(
&self,
plugin_key: &str,
account_id: &str,
cursor: &str,
pass_token: &str,
pass_id: &str,
) -> Result<()>
Records that a pass wrote a page and continues at cursor.
plugin_key- The account's plugin.account_id- The account.cursor- The next page's cursor.pass_token- The sync token the pass started with.pass_id- The pass's id (PassStart::pass_id), kept so a resumed pass stamps the same one.
Returns an error when the batch fails.
pub async fn finish_scan_pass(
&self,
plugin_key: &str,
account_id: &str,
sync_token: &str,
complete: bool,
) -> Result<()>
Records the end of a pass: stores the plugin's next sync token, drops
the resume cursor, and stamps last_complete_at for a complete pass.
Returns an error when the batch fails.
pub async fn reset_scan_state(&self, plugin_key: &str, account_id: &str) -> Result<()>
Forgets an account's sync token and resume cursor (the plugin called one invalid), so its next pass is full and starts at the beginning.
Returns an error when the batch fails.
pub async fn storage_scan_put_object(
&self,
scan_id: &str,
key: &str,
size: u64,
media_rank: u8,
is_audio: bool,
) -> Result<()>
Inserts an object row. A repeat of the same key is a no-op.
Returns LibraryError::Orm when the write fails.
pub async fn storage_scan_put_identity(
&self,
scan_id: &str,
identity: &str,
key: &str,
size: u64,
media_rank: u8,
) -> Result<()>
Inserts an identity → key row. Repeats are no-ops.
Returns LibraryError::Orm when the write fails.
pub async fn storage_scan_identity_page(
&self,
scan_id: &str,
identity: &str,
after: Option<(i64, &str)>,
limit: u64,
) -> Result<Vec<(String, i64)>>
One page of identity candidates, ordered by (media_rank, object_key).
after is the last key already considered. The page is bounded by
limit (clamped to 1..=64). Callers try each key and request the next
page; this does not load every match.
Returns LibraryError::Orm when the read fails.
pub async fn storage_scan_object_page(
&self,
scan_id: &str,
prefix: &str,
after_key: Option<&str>,
limit: u64,
) -> Result<Vec<String>>
One page of object keys at or above prefix, in object_key order.
The upper bound is the byte-wise successor of prefix, not a SQL LIKE
pattern, so wildcard characters in a storage key stay literal.
Returns LibraryError::Orm when the read fails.
pub async fn storage_scan_claim(&self, scan_id: &str, key: &str) -> Result<()>
Marks an object claimed so unmatched-audio counts stay in the database.
Returns LibraryError::Orm when the update fails.
pub async fn storage_scan_unclaimed_audio(&self, scan_id: &str) -> Result<u64>
Audio objects in the scan that no library row claimed.
Returns LibraryError::Orm when the count fails.
pub async fn storage_scan_delete(&self, scan_id: &str) -> Result<()>
Deletes inventory rows and the generation ownership row for scan_id.
Both deletes go to the database plugin as one atomic batch, so a failure leaves the generation and its rows in place and an apply checkpoint cannot adopt an empty inventory.
Returns the batch error when the delete fails.
pub async fn storage_scan_register(
&self,
scan_id: &str,
instance_id: &str,
job_id: Option<&str>,
) -> Result<()>
Binds scan_id to instance_id and an optional job.
A second register for the same id and instance refreshes the heartbeat. A different instance fails closed so a reused id cannot adopt another scan.
Returns LibraryError::Orm when the write fails, or
LibraryError::Other when instance_id does not match the existing row.
pub async fn storage_scan_mark_complete(&self, scan_id: &str) -> Result<()>
Marks a generation's inventory complete so a later checkpoint can adopt it.
Returns LibraryError::Orm when the update fails.
pub async fn storage_scan_adoption(&self, scan_id: &str) -> Result<Option<(String, bool)>>
Returns (instance_id, completed) when the generation row still exists.
Returns LibraryError::Orm when the read fails.
pub async fn storage_scan_touch(&self, scan_id: &str) -> Result<()>
Refreshes the generation heartbeat after a page is stored.
Returns LibraryError::Orm when the update fails.
pub async fn storage_scan_generation_count(&self) -> Result<u64>
How many generation rows exist. Tests use this to bound retained scans.
Returns LibraryError::Orm when the count fails.
pub async fn storage_scan_reclaim_abandoned(&self, stale_before: &str) -> Result<u64>
Deletes generations that are not live resumable work.
A generation with an active job is kept even when updated_at is older
than stale_before. A jobless generation is kept only while its
heartbeat is at least stale_before. Terminal, missing, and stale
jobless generations are removed with their inventory rows.
Returns LibraryError::Orm when a read or delete fails.
pub async fn storage_scan_reclaim_if_terminal(&self, job_id: &str) -> Result<u64>
Deletes this job's inventories when the job is terminal or already gone.
Pending and running jobs, including a retry after one failed attempt, are left untouched.
Returns LibraryError::Orm when a read or delete fails.
pub async fn storage_scan_reclaim_terminal_page(
&self,
after_scan_id: Option<&str>,
limit: u64,
) -> Result<(u64, Option<String>)>
Deletes up to limit generations whose job is terminal or missing.
Pending, running, and jobless generations are kept. after_scan_id
walks past a page of still-active rows so one sweep cannot stall on
them. Pass the returned cursor back; None means the walk wrapped.
Returns LibraryError::Orm when a read or delete fails. A delete
error leaves that generation for a later retry.
pub async fn taste_titles(&self) -> Result<Vec<TasteTitle>>
Every work the library holds, one TasteTitle each, in work id
order, with no person's state applied.
A work is held when an account or a branch holds a listing of one
of its editions. TasteTitle::holders lists the accounts that
hold it (a branch-held work has none).
Returns LibraryError::Orm when a read fails.
pub async fn user_title_states_for_works(
&self,
work_ids: &[String],
) -> Result<Vec<UserTitleState>>
The stored state of every user for the given works, read in chunks.
work_ids- Works whose state to read.
The stored rows, ordered by work then user.
Returns LibraryError::Orm when a read fails.
pub async fn held_works(&self, work_ids: &[String]) -> Result<BTreeSet<String>>
The works among work_ids the library holds: an account or a branch
holds a listing of one of their editions.
work_ids- Works to check.
The held ones.
Returns LibraryError::Orm when a read fails.
pub async fn held_identifiers(
&self,
asins: &[String],
isbns: &[String],
product_ids: &[String],
) -> Result<HeldIdentifiers>
Which of asins, isbns and product_ids belong to a title the
library holds, so a ranking can drop candidates the library already
has without reading the whole library.
An ASIN or ISBN is held when it identifies an edition one of whose listings an account or a branch holds; a product id is held when a held listing carries it, on any store.
asins- ASINs to check, in any case.isbns- ISBNs to check, as stored (canonical ISBN-13).product_ids- Store product ids to check.
The held ones; ASINs upper-cased.
Returns LibraryError::Orm when a read fails.
pub async fn set_user_title_state(
&self,
user_id: i64,
work_id: &str,
fields: &UserBookFields,
) -> Result<()>
Records fields as user_id's state for work_id.
Fields left None keep their stored value (a new row starts
unfinished, unrated and untagged). New tags also replace the work's
user_work_tags rows, which the library page filters by. The write
is one atomic batch.
user_id- The user (users.id).work_id- The work (works.id).fields- The fields to set.
Returns the database error, for example when the user or the work does not exist on an engine that checks foreign keys.
pub async fn edit_user_title_state(
&self,
user_id: i64,
work_id: &str,
edit: &UserStateEdit,
) -> Result<Option<UserTitleState>>
Applies edit to user_id's state for work_id and returns the
state as stored afterwards.
Unlike LibraryStore::set_user_title_state, a field can be
cleared as well as kept or set. New tags also replace the work's
user_work_tags rows. The write is one atomic batch, and every
statement in it requires the work to exist, so an unknown work
writes nothing.
user_id- The user (users.id).work_id- The work (works.id).edit- What to change.
The stored state, or None when no such work exists.
Returns the database error.
pub async fn user_title_states(&self, user_ids: &[i64]) -> Result<Vec<UserTitleState>>
Every work state of the given users, read in chunks.
user_ids- Users whose state to read.
The stored rows, ordered by user then work.
Returns LibraryError::Orm when a read fails.
pub async fn user_title_states_of_works(
&self,
user_id: i64,
work_ids: &[String],
) -> Result<Vec<UserTitleState>>
One user's stored state for each of work_ids, read in chunks
that fit the database's limits.
user_id- The user (users.id).work_ids- Works whose state to read; duplicates are read once.
The stored rows, one per work the user has state for, ordered by work.
Returns LibraryError::Orm when a read fails.
pub async fn users_linked_to_account(
&self,
plugin_key: &str,
account_id: &str,
) -> Result<Vec<i64>>
The users linked to a storefront account: the users of the portal identities whose account links name it.
plugin_key- The account's plugin.account_id- The account id at that plugin.
Distinct user ids, ascending; empty when no linked identity has a user.
Returns LibraryError::Orm when a read fails.
pub async fn library_work_detail(&self, work_id: &str) -> Result<Option<WorkDetail>>
One top-level work with its editions, listings and holdings.
work_id- The work. A podcast episode's id reads as missing: its show is the work the library lists.
None when there is no such top-level work.
Returns LibraryError::Orm when a read fails.
pub async fn edition_cover_urls(
&self,
edition_ids: &[String],
) -> Result<HashMap<String, String>>
The cover URLs of edition_ids, for a page of index rows (each
names its cover edition), chosen as edition_cover says: the
edition's own, else a listing's, else its work's (or show's).
Edition id to cover URL; editions with no cover are left out.
Returns LibraryError::Orm when a read fails.
pub async fn user_title_state(
&self,
user_id: i64,
work_id: &str,
) -> Result<Option<UserTitleState>>
One user's own state for one work.
user_id- The user (users.id).work_id- The work (works.id).
None when the user recorded nothing for the work.
Returns LibraryError::Orm when the read fails.
pub async fn work_search_document(
&self,
work_id: &str,
) -> Result<(String, Option<WorkSearchDoc>)>
The search document of work_id's top-level work.
work_id- A work; an episode stands for its show.
The top-level work's id and its document, or None for the document
when the work is gone or no longer held (its document is then
removed from the index).
Returns crate::LibraryError::Orm when a read fails.
pub async fn work_search_documents(
&self,
work_ids: &[String],
) -> Result<Vec<(String, Option<WorkSearchDoc>)>>
The search documents of the top-level works of work_ids, read
together in a few chunked lookups.
work_ids- Works; an episode stands for its show.
One entry per distinct top-level work, in id order: its id and its
document, or None for the document when the work is gone or no
longer held (its document is then removed from the index).
Returns crate::LibraryError::Orm when a read fails.
pub async fn split_work(
&self,
work_id: &str,
expression_ids: &[String],
user_id: Option<i64>,
) -> Result<SplitOutcome>
Moves expression_ids out of work_id into a new work, as one
atomic batch.
Every write requires the new work, and the new work is inserted only
while every named expression still belongs to work_id and another
stays behind, so a concurrent change writes nothing rather than half
a split.
work_id- The work to split (works.id).expression_ids- The expressions to move, 1 toMAX_SPLIT_EXPRESSIONS; duplicates count once.user_id- The Administrator (users.id);Nonefor the operator.
What the split did. SplitOutcome::Split is returned only when
the expressions were moved.
Returns the database error of a failed read or write, or
LibraryError::Conflict when the work changed between the read
and the write.
pub async fn work_tags(&self, work_id: &str) -> Result<Vec<WorkTag>>
A work's library tags, every source, in key order (a key two sources share is listed once per source).
Returns LibraryError::NotFound for a missing work or an episode,
or the read error.
pub async fn set_work_tags(
&self,
work_id: &str,
values: &[String],
) -> Result<Vec<WorkTag>>
Replaces the tags an Administrator set on a work (sidecar tags stay) and refreshes the work's page index row, so the Library filter and patron scopes see the change at once.
The replacement is one atomic batch. The caller checks who may set tags.
work_id- A top-level work (works.id).values- The tags; blanks and repeats (ignoring case) are dropped.
The work's tags afterwards, every source.
Returns LibraryError::NotFound for a missing work or an episode,
LibraryError::Invalid for too many or too long tags, or the
read or write error.
pub async fn enqueue_job(&self, spec: EnqueueJobSpec) -> Result<EnqueueOutcome>
Admit a job in one transaction, coalescing onto an active dedup key.
spec- Kind, payload, priority, attempt cap, and pending cap.
EnqueueOutcome::Created, EnqueueOutcome::Duplicate, or
EnqueueOutcome::QueueFull.
Returns LibraryError::Orm when the database write fails.
pub async fn claim_next_job(
&self,
resource_class: JobResourceClass,
owner: &str,
lease_secs: u64,
operation_id: &str,
) -> Result<Option<JobRecord>>
Claim the next ready job with a conditional pending → running mutation.
operation_id is the atomic / local-txn idempotency key: retrying a
lost response with the same id must not claim a different row.
Returns LibraryError::Orm when the claim write fails.
pub async fn list_job_claim_candidates(
&self,
resource_class: JobResourceClass,
after: Option<&JobClaimCursor>,
limit: u64,
) -> Result<JobClaimPage>
One page of ready pending jobs of resource_class, best first, for a
routed claim.
Pages are keyset-ordered by priority DESC, created_at ASC, id ASC:
pass None for the first page and the previous page's
JobClaimPage::next for the following one, until it is None. A
caller that skips every job of a page (for example jobs another node
must run) can therefore still reach the runnable rows behind them.
Each returned row is readable and not cancel-requested. On the way,
pending rows with an unknown class or an unreadable command become
invalid_job, and cancel-requested pending rows become cancelled,
exactly as Self::claim_next_job does. Every write is a CAS on
state = 'pending', so a concurrent claimer is never overwritten.
Returns LibraryError::Orm when a read or write fails.
pub async fn claim_job_by_id(
&self,
job_id: &str,
expected_generation: i64,
owner: &str,
lease_secs: u64,
) -> Result<Option<JobRecord>>
Claims the pending job job_id for owner with a single CAS, but
only while its lease generation is still expected_generation.
The update matches state = 'pending' and expected_generation, the
lease generation of the record the caller routed on, so of several
concurrent claimers on any number of connections exactly one moves the
row to running (and bumps the generation that fences every later
write). A successful claim therefore always runs at
expected_generation + 1, which lets the caller name the claim's
generation (in its permit holders, say) before claiming. A row whose
payload was rewritten after the caller read it
(Self::rewrite_pending_job_payload bumps the generation) is not
claimed, so a job never runs on requirements its claimer did not
check. No transaction is needed: a pending → running move does not
change the admission count.
job_id- The job to claim.expected_generation-lease_generationof the record the caller evaluated; a successful claim runs atexpected_generation + 1.owner- Worker lease owner written on the row.lease_secs- Lease length.
The claimed record, or None when the row is missing, not pending,
not yet due, cancel-requested, unreadable, moved past
expected_generation, or another claimer won.
Returns LibraryError::Orm when a read or write fails.
pub async fn list_pending_jobs_page(
&self,
after_id: Option<&str>,
limit: u64,
) -> Result<(Vec<JobRecord>, Option<String>)>
One page of pending jobs in id order, for maintenance passes.
Pass None for the first page and the returned cursor for the next,
until it is None. Unlike the claim pages this ignores run_after
and the resource class; unreadable rows are skipped (the claim paths
mark them invalid_job).
Returns LibraryError::Orm when the read fails.
pub async fn wake_paced_acquires(&self, account_id: &str) -> Result<u32>
Makes parked paced acquires that may download on an account ready to run now, after its pace was relaxed or its pause cleared.
A paced acquire parked by the pace (Self::defer_job) waits until
the moment its account was due to download again. When a person or
the operator loosens the limit, the job must look again rather than
sleep out the old deadline. Every pending paced acquire that names
account_id, or names no account, and whose run_after is later
than now is moved to now; on its next claim it checks the pace and
parks again if it still has to wait. Each write is a compare-and-swap
on state = 'pending' and the generation it read, which it bumps, so
a job claimed meanwhile is left alone.
How many jobs were woken.
Returns LibraryError::Orm when a read or write fails.
pub async fn rewrite_pending_job_payload(
&self,
job_id: &str,
lease_generation: i64,
payload: &JobPayload,
) -> Result<bool>
Replaces the payload of a pending job read at lease_generation.
A compare-and-swap on state = 'pending' and the generation, which it
also bumps: a claimer that read the row before this write loses its
own CAS (and re-reads), so a concurrent claim is never overwritten and
never runs on the replaced payload.
true when this write won; false when the row moved on.
Returns LibraryError::Orm when the write fails, or
LibraryError::Other when the payload cannot be serialized.
pub async fn fail_pending_job(
&self,
job_id: &str,
lease_generation: i64,
error_kind: &str,
error_message: &str,
) -> Result<bool>
Fails a pending job read at lease_generation, terminally.
A compare-and-swap on state = 'pending' and the generation, so a job
a worker claimed meanwhile is left alone. The row leaves the pending
count and frees its dedup key.
true when this write won; false when the row moved on.
Returns LibraryError::Orm when the write fails.
pub async fn release_job_claim(&self, fence: &JobFence, resumed: bool) -> Result<bool>
Returns a job claimed under fence to pending without spending an
attempt, as if the claim had not happened.
Used when the claim is refused at handoff (the node is no longer
trusted with the job). resumed says the claim resumed a suspended
job: its attempt count was not raised, and the one-shot resume flag
is set again. Otherwise the count the claim added is taken back. The
lease generation stays bumped, so the refused claimer's fence can
never write to the row again.
true when the row was released; false when fence no longer owns
the running generation.
Returns LibraryError::Orm when a read or write fails, or
LibraryError::Other when the stored payload is not valid JSON.
pub async fn heartbeat_job(
&self,
fence: &JobFence,
lease_secs: u64,
progress: Option<&str>,
) -> Result<bool>
Refresh the lease when fence still owns the running generation.
Returns LibraryError::Orm when the update fails.
pub async fn set_job_progress(&self, fence: &JobFence, progress: &str) -> Result<bool>
Persist progress when fence still owns the running generation.
Returns LibraryError::Orm when the update fails.
pub async fn complete_job(&self, fence: &JobFence, progress: Option<&str>) -> Result<bool>
Mark a running job succeeded when fence still owns the generation.
Returns LibraryError::Orm when the update fails.
pub async fn suspend_job(
&self,
fence: &JobFence,
checkpoint: &JobCheckpoint,
wake_at: DateTime<Utc>,
) -> Result<bool>
Park a running job as pending with a checkpoint, to be claimed again after wake_at.
The CAS matches [Self::complete_job]: state=running and the caller's fence. On success the
lease is cleared so another replica can claim the next attempt. payload.checkpoint is
replaced with checkpoint (other payload fields are preserved).
Returns LibraryError::Orm when the read or update fails, or LibraryError::Other
when the stored payload is not valid JSON.
pub async fn defer_job(
&self,
fence: &JobFence,
wake_at: DateTime<Utc>,
progress: &str,
) -> Result<bool>
Parks a running job as pending until wake_at without spending an
attempt, with progress saying why it waits.
For a job that cannot go on yet and has nothing to resume from, such
as an acquire waiting for its store account's download pace
(crate::pacing). Unlike Self::suspend_job it drops any stored
checkpoint, so the next claim starts fresh. The CAS matches
[Self::complete_job]: state=running and the caller's fence.
true when the row was parked; false when fence no longer owns
the running generation.
Returns LibraryError::Orm when the read or update fails, or
LibraryError::Other when the stored payload is not valid JSON.
pub async fn checkpoint_running_job(
&self,
fence: &JobFence,
checkpoint: &JobCheckpoint,
) -> Result<bool>
Replaces payload.checkpoint while fence still owns the running job.
Unlike Self::suspend_job, the row stays running and resume_pending
is left unchanged. A stale fence updates zero rows. Reclaim keeps the
payload, so the next claim observes the checkpoint.
Returns LibraryError::Orm on database failure, or LibraryError::Other
when the checkpoint exceeds bookclerk_plugin_abi::MAX_CHECKPOINT_BYTES.
pub async fn fail_job(
&self,
fence: &JobFence,
error_kind: &str,
error_message: &str,
) -> Result<bool>
Fail a running job when fence still owns the generation.
Returns LibraryError::Orm when the update fails.
pub async fn fail_job_without_retry(
&self,
fence: &JobFence,
error_kind: &str,
error_message: &str,
) -> Result<bool>
Fail a running job for good when fence still owns the generation:
like Self::fail_job, but the job does not go back to pending
whatever attempts it has left. For an outcome another try cannot
change (an interlibrary request its branch no longer lists).
Returns LibraryError::Orm when the update fails.
pub async fn request_job_cancel(&self, id: &str) -> Result<Option<JobRecord>>
Cancel a pending job immediately, or flag a running job for cooperative stop.
Pending and running are handled atomically against claim: a CAS miss
(the worker claimed, or the job left running) retries until the row
is terminal, cancelled, or flagged cancel_requested.
The updated record, or None when the id is unknown.
Returns LibraryError::Orm when the update fails.
pub async fn job_cancel_requested(&self, id: &str) -> Result<bool>
True when a running worker should abort after the current step.
Returns LibraryError::Orm when the read fails.
pub async fn reclaim_expired_leases(&self) -> Result<u32>
Reclaim expired running leases with a conditional running update.
Number of rows moved out of running.
Returns LibraryError::Orm when the update fails.
pub async fn get_job(&self, id: &str) -> Result<Option<JobRecord>>
Load one job by id, rejecting unreadable rows as invalid_job.
Returns LibraryError::Orm when the read fails.
pub async fn list_jobs(&self, limit: u64) -> Result<Vec<JobRecord>>
List recent jobs, newest first, capped at limit (minimum 1).
A peer writer on the same SQLite file (TRUNCATE journal) can make this
read return SQLITE_BUSY. The read is repeated until the lock clears
or the attempt budget is spent. limit is unchanged.
Returns LibraryError::Orm when the read fails for a reason other
than file-lock contention, and LibraryError::Unavailable when the
lock is still held after the retries.
pub async fn prune_terminal_jobs(&self, retention_days: u64) -> Result<u64>
Delete terminal jobs older than retention_days.
Returns LibraryError::Orm when the delete fails.
pub async fn reserve_job_temp_path(
&self,
job_id: &str,
path: &str,
reserved_bytes: u64,
quota_bytes: u64,
) -> Result<()>
Reserve reserved_bytes against the job temp quota and register path.
Returns LibraryError::Orm when the write fails, or
LibraryError::Other when the quota would be exceeded.
pub async fn register_job_temp_path(&self, job_id: &str, path: &str) -> Result<()>
Register a scratch path with a zero-byte reservation (legacy helper).
Returns LibraryError::Orm when the insert fails.
pub async fn list_job_temp_paths(&self, job_id: &str) -> Result<Vec<JobTempPath>>
List scratch paths registered for job_id.
Returns LibraryError::Orm when the read fails.
pub async fn list_all_job_temp_paths(&self) -> Result<Vec<JobTempPath>>
List every registered scratch path (used by the startup sweeper).
Returns LibraryError::Orm when the read fails.
pub async fn unregister_job_temp_path(&self, job_id: &str, path: &str) -> Result<()>
Drop one scratch-path row after that path is gone from disk.
Returns LibraryError::Orm when the delete fails.
pub async fn reserved_temp_bytes(&self) -> Result<u64>
Sum of reserved scratch bytes across all jobs.
Returns LibraryError::Orm when the read fails.
pub async fn has_running_acquire_job(&self) -> Result<bool>
True when any acquire job is currently running.
Returns LibraryError::Orm when the read fails.
pub async fn reconcile_orphaned_acquire_rows(&self) -> Result<u32>
Mark orphaned queued / downloading edition acquire states as
error after a crash.
The state is written as the holding that queued it, with its event; a state whose holding is gone (its account was revoked since) is written on its own, with no title for an event to name.
Number of edition states updated.
Returns LibraryError::Orm when a status write fails.
pub async fn count_active_jobs(&self) -> Result<i64>
Count pending + running jobs (admission cap).
Returns LibraryError::Orm when the read fails.
pub async fn job_admitted_since(
&self,
dedup_key: &str,
since: DateTime<Utc>,
) -> Result<bool>
True when a job with dedup_key was admitted at or after since
and is waiting, running or has succeeded.
Such a job started after since, so it read whatever had changed by
then. A retrying event consumer uses this to skip work an earlier
attempt already queued instead of admitting it again.
dedup_key- TheJobKind::dedup_keyof the job.since- The moment the job must have been admitted after.
Returns LibraryError::Orm when the read fails.
pub async fn job_is_active(&self, dedup_key: &str) -> Result<bool>
True when a job with dedup_key is waiting or running.
A Discover page read uses this to say its shelves are being rebuilt while an event-queued fetch or ranking has not finished.
dedup_key- TheJobKind::dedup_keyof the job.
Returns LibraryError::Orm when the read fails.
pub fn from_connection(db: DatabaseConnection) -> Self
Wrap an already-opened (and migrated) SeaORM connection.
Prefer the database plugin host (open_library_store) or, in tests,
bookclerk_plugin_database_sqlite::open_memory — this crate does not
open engine-specific connections.
pub fn with_atomic_txn(self, backend: Arc<dyn AtomicTxnBackend>) -> Self
Attach a guest atomic backend for named security operations.
Hosts attach this for every database plugin. Tests that open a local
connection leave it unset and run the same commands through
crate::execute_db_atomic.
pub fn with_typed_exec(self, backend: Arc<dyn TypedAtomicExec>) -> Self
Attach a guest executeAtomic backend for granted job SQL.
Hosts attach this for every database plugin so job sessions do not use the SeaORM proxy. Tests that open a local connection leave it unset.
pub fn with_max_binds(self, max_binds: u32) -> Self
Records the guest's negotiated bind cap for wake IN (…) chunking.
pub fn with_plan_limits(
self,
max_statements: u32,
max_result_rows: u32,
max_payload_bytes: u32,
) -> Self
Records negotiated statement / result / payload caps from connect.
pub fn with_db_capabilities(self, caps: DbCapabilities) -> Self
Records the full negotiated bookclerk_plugin_abi::DbCapabilities.
pub fn db_capabilities(&self) -> &DbCapabilities
Negotiated capability advertisement used for plan validation.
pub async fn execute_guest_atomic(
&self,
req: ExecuteRequest,
policy: &GuestSqlPolicy,
) -> Result<ExecuteReply, PluginError>
Runs guest-authored SQL after grammar, table-scope, and cap checks.
Hosts inject this into JobRunner.job as the granted
bookclerk_plugin_abi::GuestDatabase::execute path.
Job sessions pass a host-issued GuestSqlPolicy
(books by default).
Returns bookclerk_plugin_abi::PluginError::invalid_params when the
SQL is outside the guest grammar or allowlist, and an engine/transport
error when the batch fails.
pub fn dispatch_chunk_size(&self) -> usize
Subscribers packed into one dispatch plan (receipt overhead and the live counter bump are ~13 statements).
pub fn wake_page(&self) -> u64
Wake delivery page size derived from negotiated maxBinds.
pub fn connection(&self) -> &DatabaseConnection
Borrow the underlying SeaORM connection (e.g. for crate::secrets).
pub fn db(&self) -> &DatabaseConnection
Alias for Self::connection — convenience name used by credential modules.
pub async fn delete_elevated_operator_sessions_for_user(
&self,
user_id: i64,
) -> Result<u64>
Revoke Operator sessions minted by this user's elevate-to-operator flow.
Returns an error when the operation fails.
pub async fn upsert_account(
&self,
plugin_key: &str,
account_id: &str,
marketplace: &str,
label: Option<&str>,
scan_enabled: bool,
source: &str,
) -> Result<AccountRecord>
Upsert an account (updates scan_enabled on conflict).
Accounts are keyed by (plugin_key, account_id): the same store id may
exist under two plugins. source is the owning plugin's display alias.
Content sources should prefer crate::SourceScope::upsert_account,
which forces both.
Returns an error when the operation fails.
pub async fn ensure_account(
&self,
plugin_key: &str,
account_id: &str,
marketplace: &str,
label: Option<&str>,
source: &str,
) -> Result<AccountRecord>
Ensure an account row exists without overwriting scan_enabled.
Content sources should prefer crate::SourceScope::ensure_account.
Returns an error when the operation fails.
pub async fn remap_account_id(&self, plugin_key: &str, from: &str, to: &str) -> Result<()>
Remap from → to account ids within one plugin (books, holdings
and the account row).
Used when classic Libation stored an email AccountId and a later
login/scan discovers Audible customer_id. Holdings move to to
with holding_removed / holding_added events before the old
account row, whose foreign key would otherwise drop them, is deleted.
Returns an error when the operation fails.
pub async fn reconcile_account_id(
&self,
plugin_key: &str,
canonical_id: &str,
aliases: &[&str],
marketplace: &str,
label: Option<&str>,
scan_enabled: bool,
source: &str,
) -> Result<AccountRecord>
Remap any existing alias account ids onto canonical_id, then upsert.
Returns an error when the operation fails.
pub async fn get_account(
&self,
plugin_key: &str,
account_id: &str,
) -> Result<Option<AccountRecord>>
Loads one account by (plugin_key, account_id), if present.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn find_accounts_by_id(&self, account_id: &str) -> Result<Vec<AccountRecord>>
Every account row with this store id, across plugins.
Returns a crate error when the database operation fails.
pub async fn get_account_unique(&self, account_id: &str) -> Result<Option<AccountRecord>>
Resolves one account by store id, failing closed when two plugins own that id.
Returns LibraryError::Conflict when the id is ambiguous.
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 list_accounts_for_plugin(
&self,
plugin_key: &str,
) -> Result<Vec<AccountRecord>>
List the accounts of one storefront plugin, ordered by account id.
The filter runs in the query, so the read is bounded by that plugin's accounts rather than the whole library's.
plugin_key- Canonical plugin key whose accounts to read.
Returns the read error.
pub async fn count_identities(&self) -> Result<i64>
Count library identity rows (SQL COUNT, not a full fetch).
Same cardinality as Self::count_accounts. Prefer this when the caller
only needs a number for an operator-facing summary.
A peer writer on the same SQLite file (TRUNCATE journal) can make this
read return SQLITE_BUSY. The read is repeated until the lock clears
or the attempt budget is spent.
Returns LibraryError::Orm when the read fails for a reason other
than file-lock contention, and LibraryError::Unavailable when the
lock is still held after the retries.
pub async fn count_accounts(&self) -> Result<i64>
Count account rows (SQL COUNT, not a full fetch).
Uses Self::count_identities, including its wait for a peer SQLite lock.
Returns LibraryError::Orm when the read fails for a reason other
than file-lock contention, and LibraryError::Unavailable when the
lock is still held after the retries.
pub async fn find_accounts(&self, identifier: &str) -> Result<Vec<AccountRecord>>
Every account whose id or nickname (label) matches, case-insensitive.
Returns an error when the operation fails.
pub async fn find_account(
&self,
identifier: &str,
plugin_key: Option<&str>,
) -> Result<Option<AccountRecord>>
Resolve one account by id or nickname (label), case-insensitive.
plugin_key narrows the match to one plugin. Without it, a needle that
matches accounts of two plugins fails closed.
Returns LibraryError::Conflict when the needle is ambiguous.
pub async fn set_scan_enabled(
&self,
plugin_key: &str,
account_id: &str,
scan_enabled: bool,
) -> Result<()>
Toggle whether an account is included in automatic library scans.
Returns an error when the operation fails.
pub async fn mark_connection_active(
&self,
plugin_key: &str,
account_id: &str,
) -> Result<()>
Mark bookstore credentials active again (after reconnect).
Returns an error when the operation fails.
pub async fn delete_account_secrets(
&self,
plugin_key: &str,
account_id: &str,
) -> Result<()>
Delete all encrypted_secrets rows for an account (source auth + Widevine CDM).
Returns an error when the operation fails.
pub async fn revoke_credentials(&self, plugin_key: &str, account_id: &str) -> Result<()>
Mark bookstore credentials revoked, remove the account's holdings
(with holding_removed for each) and forget its sync token, without
deleting the account, its flat library rows or acquired files.
The account no longer reaches the store, so the library no longer holds its titles through it. A later reconnect starts a full scan pass (no sync token), which adds the holdings back.
Returns an error when the operation fails.
pub async fn upsert_portal_identity(
&self,
provider: &str,
external_user_id: &str,
label: Option<&str>,
) -> Result<PortalIdentity>
Create or fetch a portal identity for (provider, external_user_id).
Ensures a first-party UserRecord (role member) is linked via
portal_identities.user_id.
Returns an error when the operation fails.
pub async fn create_user(
&self,
role: UserRole,
display_name: Option<&str>,
password_hash: Option<&str>,
) -> Result<UserRecord>
Create a first-party user.
Returns an error when the operation fails.
pub async fn create_user_with_login(
&self,
role: UserRole,
display_name: Option<&str>,
login_name: Option<&str>,
password_hash: Option<&str>,
) -> Result<UserRecord>
Create a first-party user with optional local login_name and email.
Returns an error when the operation fails.
pub async fn create_user_with_profile(
&self,
role: UserRole,
display_name: Option<&str>,
login_name: Option<&str>,
email: Option<&str>,
password_hash: Option<&str>,
) -> Result<UserRecord>
Create a first-party user with login, email, and optional password hash.
Returns an error when the operation fails.
pub async fn get_user(&self, id: i64) -> Result<Option<UserRecord>>
Look up a first-party user by id.
Returns an error when the operation fails.
pub async fn get_user_by_login_name(&self, login_name: &str) -> Result<Option<UserRecord>>
Look up by local login_name (case-insensitive).
Returns an error when the operation fails.
pub async fn get_user_by_email(&self, email: &str) -> Result<Option<UserRecord>>
Look up by email (case-insensitive).
Returns an error when the operation fails.
pub async fn get_user_password_hash(&self, id: i64) -> Result<Option<String>>
Raw password hash for verification (never expose via API).
Returns an error when the operation fails.
pub async fn list_users(&self) -> Result<Vec<UserRecord>>
List all first-party users (admin tooling).
Returns an error when the operation fails.
pub async fn list_user_presence_extras(
&self,
listening_within: Duration,
) -> Result<HashMap<i64, UserPresenceExtras>>
Presence, listening, and storefront links for administrator user lists.
online means any non-expired portal session. listening is the newest
unfinished progress row with last_listened_at within
listening_within (typical UI window: ~30 minutes). Used by
GET /api/users. Session activity (last_active_at) comes from
unexpired portal_sessions.last_used_at. Durable last-seen lives on
users.last_seen_at (survives logout) and is refreshed with session
use at most once per minute.
Returns an error when the operation fails.
pub async fn delete_user(&self, id: i64) -> Result<()>
Delete a first-party user and personal data.
Removes portal identities, account links, wishlist rows, claim tickets,
sessions, and prefs for the user. Acquired library books are retained.
Refuses to delete the last active owner. Publishes wishlist_changed
(status deleted) for each open wish removed with the user, so
Discover stops counting it for everyone else.
Returns an error when the operation fails.
pub async fn set_user_status(&self, id: i64, status: UserStatus) -> Result<UserRecord>
Set user status (active / disabled).
Refuses to disable the last active owner.
Returns an error when the operation fails.
pub async fn set_user_display_name(
&self,
id: i64,
display_name: Option<&str>,
) -> Result<UserRecord>
Set display name (does not bump security_version).
Returns an error when the operation fails.
pub async fn set_user_password_hash(
&self,
id: i64,
password_hash: Option<&str>,
) -> Result<UserRecord>
Set or clear Argon2id password hash; bumps security_version.
Returns an error when the operation fails.
pub async fn set_user_login_name(
&self,
id: i64,
login_name: Option<&str>,
) -> Result<UserRecord>
Set login_name (unique); does not bump security_version.
Returns an error when the operation fails.
pub async fn set_user_email(&self, id: i64, email: Option<&str>) -> Result<UserRecord>
Set contact email (unique when set); does not bump security_version.
Returns an error when the operation fails.
pub async fn set_user_avatar_source(
&self,
id: i64,
source: Option<&str>,
) -> Result<UserRecord>
Set the user's picture source (monogram / gravatar / upload / sso:{id} / auto).
None or empty stores auto-resolve (upload, then last-used SSO, then Gravatar).
Returns an error when the user is missing or the write fails.
pub async fn set_portal_identity_picture(
&self,
provider: &str,
external_user_id: &str,
picture_url: Option<&str>,
) -> Result<()>
Store or clear the HTTPS picture URL on a portal identity.
Missing identities are ignored so callers can run this after a failed lookup without an extra round-trip.
Returns an error when the write fails.
pub async fn list_user_sso_pictures(&self, user_id: i64) -> Result<Vec<UserSsoPicture>>
IdP pictures linked to user_id, with last portal-session activity.
Identities without a picture_url are omitted. last_used_at is the
latest session last_used_at or created_at for that identity.
Returns an error when the query fails.
pub async fn delete_portal_sessions_for_user(&self, user_id: i64) -> Result<u64>
Delete all portal sessions for identities linked to user_id.
Returns an error when the operation fails.
pub async fn insert_user_invite(
&self,
token_hash: &str,
role: UserRole,
login_name: Option<&str>,
display_name: Option<&str>,
expires_at: DateTime<Utc>,
created_by: &str,
) -> Result<UserInviteRecord>
Insert a user invite (store hash only).
Returns an error when the operation fails.
pub async fn redeem_user_invite(&self, token_hash: &str) -> Result<UserInviteRecord>
Atomically redeem a user invite.
Returns an error when the operation fails.
pub async fn set_user_role(&self, id: i64, role: UserRole) -> Result<UserRecord>
Set user role (owner / administrator / member).
Refuses to demote the last active owner.
Returns an error when the operation fails.
pub async fn count_administrators(&self) -> Result<u64>
Count administrators (includes disabled).
Returns an error when the operation fails.
pub async fn count_active_administrators(&self) -> Result<u64>
Count administrators with status active.
Returns an error when the operation fails.
pub async fn count_owners(&self) -> Result<u64>
Count owners (includes disabled) — bootstrap / inventory.
Returns an error when the operation fails.
pub async fn count_active_owners(&self) -> Result<u64>
Count owners with status active (last-owner demote/disable/delete guard).
Returns an error when the operation fails.
pub async fn ensure_users_bridged(&self) -> Result<usize>
Backfill portal_identities.user_id and remap prefs portal:{id} → user:{id}.
Safe to call repeatedly after migrations. Does not link CLI-created store
accounts that have no account_links (avoids widening access).
Returns an error when the operation fails.
pub async fn ensure_local_portal_identity(
&self,
user_id: i64,
label: Option<&str>,
) -> Result<PortalIdentity>
Ensure a local portal identity exists for a first-party user.
Returns an error when the operation fails.
pub async fn get_portal_identity(
&self,
provider: &str,
external_user_id: &str,
) -> Result<Option<PortalIdentity>>
Loads a portal identity by primary key, if present.
provider- External provider id.external_user_id- User id at the external provider.
Result<Option<crate::models::PortalIdentity>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn get_portal_identity_by_id(&self, id: i64) -> Result<Option<PortalIdentity>>
Look up portal identity by row id.
Returns an error when the operation fails.
pub async fn insert_claim_ticket(
&self,
token_hash: &str,
identity_id: Option<i64>,
expires_at: DateTime<Utc>,
created_by: &str,
) -> Result<ClaimTicketRecord>
Insert a claim ticket (store only the hash).
Returns an error when the operation fails.
pub async fn get_claim_ticket_by_hash(
&self,
token_hash: &str,
) -> Result<Option<ClaimTicketRecord>>
Loads a claim ticket row by its token hash, if present.
token_hash- SHA-256 hex digest of the opaque token.
Result<Option<crate::models::ClaimTicketRecord>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn list_open_claim_tickets(&self) -> Result<Vec<ClaimTicketRecord>>
List unredeemed, unexpired claim tickets (newest first).
Returns an error when the operation fails.
pub async fn redeem_claim_ticket(&self, token_hash: &str) -> Result<ClaimTicketRecord>
Atomically mark a claim ticket redeemed.
Uses a single UPDATE … WHERE redeemed_at IS NULL AND expires_at > now so
concurrent redeemers cannot both succeed.
Returns an error when the operation fails.
pub async fn redeem_claim_ticket_to_session(
&self,
token_hash: &str,
session_hash: &str,
expires_at: DateTime<Utc>,
client: Option<&SessionClientInfo>,
new_password_hash: Option<&str>,
password_fingerprint: Option<&str>,
) -> Result<PortalIdentity>
Consume a claim ticket, optionally set an unset local password, and mint a portal session in one transaction.
new_password_hash is assigned only while the ticket-bound local user
still has no password. A failed consume rolls back password and session
writes. Missing password for an unset local user aborts without consuming
the ticket.
token_hash- SHA-256 hex digest of the claim ticket.session_hash- SHA-256 hex digest of the new portal session token.expires_at- RFC 3339 expiry for the minted session.client- Optional client metadata stored on the session row.new_password_hash- Argon2id hash to set when the local user has none.password_fingerprint- Stable HMAC of the plaintext password for atomic-execute idempotency; ignored by the mutation SQL.
The portal identity bound to the consumed ticket.
Returns a crate error when the ticket is invalid/consumed, a required invite password is missing, or the database operation fails.
pub async fn insert_portal_session(
&self,
token_hash: &str,
identity_id: i64,
expires_at: DateTime<Utc>,
) -> Result<()>
Create a portal session (hash only).
Returns an error when the operation fails.
pub async fn insert_portal_session_with_client(
&self,
token_hash: &str,
identity_id: i64,
expires_at: DateTime<Utc>,
client: Option<&SessionClientInfo>,
) -> Result<()>
Create a portal session with optional client metadata.
Returns an error when the operation fails.
pub async fn insert_clerk_session(
&self,
token_hash: &str,
identity_id: i64,
expires_at: DateTime<Utc>,
label: &str,
) -> Result<i64>
Creates a clerk sign-in session: a token a clerk presents
as Authorization: Bookclerk-Clerk, never as a cookie.
token_hash- SHA-256 hex of the token (the token is never stored).identity_id- The user's portal identity.expires_at- First expiry; each use moves it forward (Self::get_clerk_session_identity).label- The name the clerk gave itself, shown in the user's session list.
The new session's row id.
Returns an error when the insert fails.
pub async fn delete_clerk_session(&self, token_hash: &str) -> Result<bool>
Deletes a clerk sign-in session by token hash (the clerk signing itself out). A browser session with that hash is left alone.
Returns an error when the delete fails.
pub async fn delete_portal_session(&self, token_hash: &str) -> Result<bool>
Delete a portal session by token hash (logout / revoke).
Returns an error when the operation fails.
pub async fn list_portal_sessions_for_identity(
&self,
identity_id: i64,
) -> Result<Vec<(i64, String, String)>>
List portal sessions for an identity (id, created_at, expires_at).
Returns an error when the operation fails.
pub async fn list_portal_session_records_for_identity(
&self,
identity_id: i64,
) -> Result<Vec<PortalSessionRecord>>
List portal sessions with client metadata for session management UIs.
Returns an error when the operation fails.
pub async fn delete_portal_session_by_id_for_identity(
&self,
id: i64,
identity_id: i64,
) -> Result<bool>
Delete a portal session by id only if it belongs to identity_id.
Returns an error when the operation fails.
pub async fn count_account_links_for_account(
&self,
plugin_key: &str,
account_id: &str,
) -> Result<u64>
Count account_links referencing account_id.
Returns an error when the operation fails.
pub async fn get_portal_session_identity(
&self,
token_hash: &str,
) -> Result<Option<PortalIdentity>>
Resolve a valid browser (cookie) session to its identity.
Refreshes portal_sessions.last_used_at and users.last_seen_at at most
once per minute so administrator presence can tell active from idle
without a write on every request. last_seen_at is kept after logout.
A library card is not a browser session and resolves to
nothing here.
Returns an error when the operation fails.
pub async fn get_clerk_session_identity(
&self,
token_hash: &str,
idle: Duration,
) -> Result<Option<PortalIdentity>>
Resolve a valid clerk sign-in session to its identity.
Like Self::get_portal_session_identity, but only for a client
session, and each touch (at most once a minute) also moves its expiry
to idle from now, so a client in use stays signed in and one left
unused for idle is signed out.
Returns an error when the operation fails.
pub async fn clerk_session_person(&self, token_hash: &str) -> Result<Option<i64>>
The person a library card is signed in as right now, read without
touching the session: a clerk session with that token hash that
has not expired, whose identity names a user who exists and is not
disabled.
A copy download asks this on every request
(crate::control_plane::authorize_copy); it does not keep the
card signed in, which only the card's own use does
(Self::get_clerk_session_identity).
token_hash- SHA-256 hex of the card's token.
Returns an error when a read fails.
pub async fn insert_operator_session(
&self,
token_hash: &str,
expires_at: DateTime<Utc>,
) -> Result<()>
Create a durable operator session (hash only).
Returns an error when the operation fails.
pub async fn insert_operator_session_with_client(
&self,
token_hash: &str,
expires_at: DateTime<Utc>,
client: Option<&SessionClientInfo>,
) -> Result<()>
Create a durable operator session with optional client metadata.
Returns an error when the operation fails.
pub async fn insert_elevated_operator_session(
&self,
token_hash: &str,
expires_at: DateTime<Utc>,
elevated_from_user_id: i64,
) -> Result<()>
Create an elevated operator session (Administrator reauth → short TTL).
Returns an error when the operation fails.
pub async fn insert_elevated_operator_session_with_client(
&self,
token_hash: &str,
expires_at: DateTime<Utc>,
elevated_from_user_id: i64,
client: Option<&SessionClientInfo>,
) -> Result<()>
Create an elevated operator session with optional client metadata.
Returns an error when the operation fails.
pub async fn get_operator_session(
&self,
token_hash: &str,
) -> Result<Option<OperatorSessionRecord>>
Look up a valid operator session (touches last_used_at).
Returns an error when the operation fails.
pub async fn operator_session_valid(&self, token_hash: &str) -> Result<bool>
Return whether a hashed operator session is still valid (and touch last_used).
Returns an error when the operation fails.
pub async fn set_operator_session_impersonating(
&self,
token_hash: &str,
user_id: Option<i64>,
) -> Result<OperatorSessionRecord>
Set or clear impersonation on an operator session.
Returns an error when the operation fails.
pub async fn delete_operator_session(&self, token_hash: &str) -> Result<bool>
Delete an operator session by token hash (logout / revoke).
Returns an error when the operation fails.
pub async fn delete_operator_session_by_id(&self, id: i64) -> Result<bool>
Delete an operator session by row id.
Returns an error when the operation fails.
pub async fn prune_expired_operator_sessions(&self) -> Result<u64>
Delete expired operator sessions (bounded cleanup).
Returns an error when the operation fails.
pub async fn list_operator_sessions(&self) -> Result<Vec<OperatorSessionRecord>>
List active operator sessions (newest first) for remote sign-out UI.
Returns an error when the operation fails.
pub async fn first_portal_identity_for_user(
&self,
user_id: i64,
) -> Result<Option<PortalIdentity>>
First portal identity linked to a first-party user (for impersonation scoping).
Returns an error when the operation fails.
pub async fn list_portal_identities_for_user(
&self,
user_id: i64,
) -> Result<Vec<PortalIdentity>>
All portal identities linked to a first-party user.
Returns an error when the operation fails.
pub async fn link_portal_identity_to_user(
&self,
provider: &str,
external_user_id: &str,
user_id: i64,
label: Option<&str>,
) -> Result<PortalIdentity>
Link (provider, external_user_id) to an existing user (SSO / invite_only).
Creates the identity row when missing. Refuses to steal an identity already bound to a different user.
Returns an error when the operation fails.
pub async fn insert_oidc_rp_state(
&self,
state_hash: &str,
provider_id: &str,
pkce_verifier: &str,
nonce: &str,
purpose: &str,
user_id: Option<i64>,
expires_at: DateTime<Utc>,
) -> Result<()>
Insert a short-lived OIDC RP authorize state row.
Returns an error when the operation fails.
pub async fn take_oidc_rp_state(
&self,
state_hash: &str,
) -> Result<Option<(String, String, String, String, Option<i64>)>>
Consume (delete) an OIDC RP state by hash if it has not expired.
Find + delete run in one transaction so concurrent callbacks cannot both observe the same unused state.
Returns an error when the operation fails.
pub async fn insert_webauthn_credential(
&self,
user_id: i64,
credential_id: &str,
passkey_json: &str,
name: Option<&str>,
) -> Result<()>
Store a WebAuthn credential for a user.
user_id- First-party user who owns the passkey.credential_id- Base64url credential id.passkey_json- Serializedwebauthn_rspasskey.name- Label shown in Settings; empty becomesNone.
Returns an error when the insert fails (including unique credential id).
pub async fn list_webauthn_credentials(&self, user_id: i64) -> Result<Vec<StoredPasskey>>
Passkeys registered to a user.
Returns an error when the operation fails.
pub async fn count_webauthn_credentials(&self, user_id: i64) -> Result<u64>
Count passkeys for a user.
Returns an error when the operation fails.
pub async fn get_webauthn_credential_by_cred_id(
&self,
credential_id: &str,
) -> Result<Option<(i64, i64, String)>>
Look up a passkey by credential id.
Returns an error when the operation fails.
pub async fn update_webauthn_credential(&self, id: i64, passkey_json: &str) -> Result<()>
Replace passkey JSON after a successful assertion (counter update).
Returns an error when the operation fails.
pub async fn delete_webauthn_credential(&self, user_id: i64, id: i64) -> Result<bool>
Delete a passkey owned by user_id.
Returns an error when the operation fails.
pub async fn set_user_totp_enabled(&self, user_id: i64, enabled: bool) -> Result<()>
Set whether this user has a confirmed TOTP authenticator.
user_id- First-party user id.enabled-trueafter a successful enroll confirm;falseon disable.
Returns LibraryError::NotFound when the user does not exist.
pub async fn confirm_totp_enrollment(&self, user_id: i64, secret_b32: &str) -> Result<()>
Promote a pending TOTP secret to primary and set totp_enabled in one transaction.
Returns LibraryError::NotFound when the user does not exist.
pub async fn disable_user_totp(&self, user_id: i64) -> Result<()>
Delete TOTP secrets and clear totp_enabled in one transaction.
Returns LibraryError::NotFound when the user does not exist.
pub async fn insert_webauthn_challenge(
&self,
challenge_id: &str,
user_id: Option<i64>,
kind: &str,
state_json: &str,
expires_at: DateTime<Utc>,
) -> Result<()>
Insert a WebAuthn ceremony state.
Returns an error when the operation fails.
pub async fn take_webauthn_challenge(
&self,
challenge_id: &str,
kind: &str,
) -> Result<Option<(Option<i64>, String)>>
Consume a WebAuthn ceremony by id (transactional delete-and-return).
Returns an error when the operation fails.
pub async fn prune_expired_oidc_rp_states(&self) -> Result<u64>
Drop expired OIDC RP states (bounded cleanup).
Returns an error when the operation fails.
pub async fn prune_expired_webauthn_challenges(&self) -> Result<u64>
Drop expired WebAuthn challenges (bounded cleanup).
Returns an error when the operation fails.
pub async fn count_oidc_rp_states(&self) -> Result<u64>
Count pending OIDC RP states (for public-begin caps).
Returns an error when the operation fails.
pub async fn count_webauthn_challenges(&self) -> Result<u64>
Count pending WebAuthn challenges (for public-begin caps).
Returns an error when the operation fails.
pub async fn portal_session_created_at(
&self,
token_hash: &str,
) -> Result<Option<DateTime<Utc>>>
Created-at of a still-valid portal session (recent-auth checks).
Returns an error when the operation fails.
pub async fn set_portal_session_created_at(
&self,
token_hash: &str,
created_at: DateTime<Utc>,
) -> Result<bool>
Overwrite created_at for a portal session (tests / recent-auth fixtures).
Returns an error when the operation fails.
pub async fn insert_security_audit_event(
&self,
actor: &str,
action: &str,
detail_json: Option<&str>,
) -> Result<SecurityAuditEvent>
Appends one security audit event row.
actor- Actor label.action- Audit action verb.detail_json-detail_jsonargument for this call.
Result<crate::models::SecurityAuditEvent> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn insert_oidc_client(
&self,
client_id: &str,
client_secret_hash: Option<&str>,
redirect_uris: &[String],
name: Option<&str>,
issue_refresh_token: bool,
allowed_scopes: &[String],
enabled: bool,
plugin_id: Option<&str>,
) -> Result<OidcClientRecord>
Insert a new OIDC client (public clients may omit secret hash).
Custom (operator) clients pass plugin_id = None and typically
enabled = true. Plugin-owned templates pass the plugin id and start
disabled.
Returns an error when the operation fails.
pub async fn upsert_plugin_oidc_client(
&self,
client_id: &str,
plugin_id: &str,
name: &str,
redirect_uris: &[String],
issue_refresh_token: bool,
allowed_scopes: &[String],
) -> Result<OidcClientRecord>
Insert a plugin-owned OIDC client when missing; refresh redirect URIs when present.
New rows start disabled. Existing rows owned by the same plugin keep
enabled, name, scopes, and secret. Collisions with custom (operator) clients
or a different plugin's client_id are hard errors — this never mutates
an unowned row. Alias-era rows (plugin_id = "audiobookshelf") are rewritten
to the provenance-qualified PluginKey (…#audiobookshelf) on the next
heartbeat from that guest; a different PluginKey with the same alias
cannot take the client over.
Returns LibraryError::Conflict when client_id is already owned by a
custom client or another plugin.
pub async fn update_oidc_client(
&self,
client_id: &str,
redirect_uris: &[String],
name: Option<&str>,
issue_refresh_token: bool,
allowed_scopes: &[String],
enabled: bool,
secret_hash: Option<Option<String>>,
) -> Result<Option<OidcClientRecord>>
Update an existing OIDC client without changing the secret unless secret_hash is Some.
Pass Some(None) as secret_hash to clear the secret (public PKCE). Pass None to keep.
Returns an error when the operation fails.
pub async fn set_oidc_client_secret(
&self,
client_id: &str,
client_secret_hash: Option<&str>,
) -> Result<Option<OidcClientRecord>>
Replace the stored client-secret hash (or clear it).
Returns an error when the operation fails.
pub async fn delete_oidc_client(&self, client_id: &str) -> Result<bool>
Delete a registered OIDC client by client_id.
Returns an error when the operation fails.
pub async fn list_oidc_clients(&self) -> Result<Vec<OidcClientRecord>>
List registered OIDC clients, oldest first.
Returns an error when the operation fails.
pub async fn get_oidc_client(&self, client_id: &str) -> Result<Option<OidcClientRecord>>
Loads a registered OIDC client by client_id, if present.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn insert_oidc_auth_code(
&self,
code_hash: &str,
client_id: &str,
user_id: i64,
redirect_uri: &str,
code_challenge: &str,
code_challenge_method: &str,
scope: &str,
expires_at: DateTime<Utc>,
) -> Result<()>
Persists a hashed OIDC authorization code with PKCE metadata.
code_hash- SHA-256 hex digest of the authorization code.client_id- OIDC client_id.user_id- First-party user id.redirect_uri- OAuth redirect URI.code_challenge- PKCE code_challenge.code_challenge_method- PKCE method (S256orplain).scope- OAuth scope string.expires_at- Expiry timestamp.
Result<()> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn peek_oidc_auth_code(
&self,
code_hash: &str,
) -> Result<Option<(String, i64, String, String, String, String)>>
Reads an unconsumed, unexpired auth code without consuming it; returns (client_id, user_id, redirect_uri, challenge, method, scope). For a caller that records what the code grants before it consumes the code, so a failed write leaves the code usable for a retry.
Returns an error when the read fails.
pub async fn consume_oidc_auth_code(
&self,
code_hash: &str,
) -> Result<Option<(String, i64, String, String, String, String)>>
Atomically consume an auth code; returns (client_id, user_id, redirect_uri, challenge, method, scope).
Returns an error when the operation fails.
pub async fn insert_oidc_refresh_token(
&self,
token_hash: &str,
client_id: &str,
user_id: i64,
scope: &str,
expires_at: DateTime<Utc>,
) -> Result<()>
Persists a hashed OIDC refresh token.
token_hash- SHA-256 hex digest of the opaque token.client_id- OIDC client_id.user_id- First-party user id.scope- OAuth scope string.expires_at- Expiry timestamp.
Result<()> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn get_oidc_refresh_token(
&self,
token_hash: &str,
) -> Result<Option<(String, i64, String)>>
Loads a refresh token row by hash, if present.
token_hash- SHA-256 hex digest of the opaque token.
Result<Option<(String, i64, String)>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn revoke_oidc_refresh_token(&self, token_hash: &str) -> Result<bool>
Marks a refresh token revoked; returns whether a row was updated.
token_hash- SHA-256 hex digest of the opaque token.
Result<bool> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn list_security_audit_events(
&self,
limit: u64,
) -> Result<Vec<SecurityAuditEvent>>
List recent security audit events (newest first).
Returns an error when the operation fails.
pub async fn link_account(
&self,
identity_id: i64,
plugin_key: &str,
account_id: &str,
source: &str,
) -> Result<AccountLinkRecord>
Link a bookstore account to a portal identity.
Account links are exclusive: one (plugin_key, account_id) may belong
to only one identity (idx_account_links_account_exclusive).
Returns an error when the operation fails.
pub async fn list_account_links(&self, identity_id: i64) -> Result<Vec<AccountLinkRecord>>
Lists store accounts linked to a portal identity.
identity_id- Portal identity id.
Result<Vec<crate::models::AccountLinkRecord>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn unlink_account(
&self,
identity_id: i64,
plugin_key: &str,
account_id: &str,
) -> Result<()>
Remove an account link row (does not delete the account).
Returns an error when the operation fails.
pub async fn upsert_book(&self, book: &NewBook) -> Result<AcquireTitle>
Records a title an account holds, as a library sync lists it: the listing it describes, resolved into works, expressions and editions, the account's holding of it, the listing's store text and the fields it offers its work.
The listing is derived from book (listing_from_book); a scan
that has the plugin's structured record uses
Self::upsert_scanned_title instead.
The account's title, as acquire reads it.
Returns LibraryError::Invalid when book has no plugin key or
fails listing validation, LibraryError::NotFound when the
holding was removed again before it could be read back, or the
database error.
pub async fn update_book_metadata(&self, book: &NewBook) -> Result<()>
Updates a title's store text and the fields it offers its work, without asserting that its account holds it.
For metadata from elsewhere (enrichment), which must not bring back a holding a scan or a revoke removed: the listing is linked as a catalog listing when it is not stored yet.
Returns LibraryError::Invalid when book has no plugin key or
fails listing validation, or the database error.
pub async fn upsert_scanned_title(&self, title: &ScannedTitle) -> Result<AcquireTitle>
Records a scanned title: the listing its plugin's structured record
describes (or, without one, the listing title.book describes), the
account's holding of it, its store text and the fields it offers
its work.
The listing is filed under the book's plugin, whatever plugin key it carries.
The account's title, as acquire reads it.
pub async fn upsert_scanned_titles(&self, titles: &[ScannedTitle]) -> Result<usize>
Records a page of scanned titles as Self::upsert_scanned_title
records each one, with every title's listing resolved as one page
(record_listing_page_with_details), so titles the library already
holds as the store describes them cost no reads of their own.
A title that fails listing validation or cannot be resolved is logged and skipped, so one bad title does not stop the rest of a scan; the next scan tries it again.
How many of titles were recorded.
Returns LibraryError::Invalid when a title has no plugin key;
nothing is written then.
pub async fn held_title(
&self,
title_id: &str,
account_id: &str,
) -> Result<Option<AcquireTitle>>
The title account_id holds that title_id names: its holding id,
the store's product id, or an ASIN or ISBN of its edition.
Prefers a holding id match, then a product id, then an ASIN, then
an ISBN. When two plugins hold the same account id and both match
at the same priority, the lookup fails closed; pass the plugin key
through Self::held_title_in instead.
Returns LibraryError::Conflict when the match is ambiguous, or
the database error.
pub async fn held_title_in(
&self,
plugin_key: Option<&str>,
title_id: &str,
account_id: &str,
) -> Result<Option<AcquireTitle>>
Self::held_title narrowed to one plugin key when plugin_key is
set.
Returns LibraryError::Conflict when the match is ambiguous, or
the database error.
pub async fn has_held_titles(&self) -> Result<bool>
True when any account holds a title (SQL EXISTS-style read, not a
full fetch).
A peer writer on the same SQLite file (TRUNCATE journal) can make this
read return SQLITE_BUSY. The read is repeated until the lock clears
or the attempt budget is spent.
Returns LibraryError::Orm when the read fails for a reason other
than file-lock contention, and LibraryError::Unavailable when the
lock is still held after the retries.
pub async fn update_user_fields(
&self,
title_id: &str,
account_id: &str,
fields: &UserBookFields,
) -> Result<()>
Records user-defined fields (tags, ratings, finished) for every person linked to the account that holds the title, on the title's work, without touching scan metadata.
Each person keeps their own state, so members sharing the account do not overwrite one another's; an account no person is linked to records nothing.
Returns LibraryError::NotFound when the account holds no title
title_id names, LibraryError::Conflict when the name is
ambiguous, or the database error.
pub async fn set_pdf_status(
&self,
title_id: &str,
account_id: &str,
status: AcquireStatus,
pdf_storage_key: Option<&str>,
) -> Result<()>
Records the companion PDF state of the title account_id holds
that title_id names (see Self::held_title), as
Self::set_holding_pdf_status records it for that holding.
title_id- Holding id, product id, ASIN or ISBN of the title.account_id- Store account id.status- The new PDF state.pdf_storage_key- Object-storage key for the companion PDF.
Returns LibraryError::NotFound when the account holds no such
title, LibraryError::Conflict when the name is ambiguous, or the
database error.
pub async fn set_holding_pdf_status(
&self,
holding_id: &str,
status: AcquireStatus,
pdf_storage_key: Option<&str>,
) -> Result<()>
Records the companion PDF state account holding holding_id
(holdings.id) wrote for the edition its listing sells.
Once the PDF is acquired, only the holding that acquired it changes it while that holding exists.
holding_id- The account holding that wrote the state.status- The new PDF state.pdf_storage_key- Object-storage key for the companion PDF.
Returns LibraryError::NotFound when no account holding has that
id, or the database error.
pub async fn is_ignored(&self, title_id: &str, account_id: &str) -> Result<bool>
Returns whether (title_id, account_id) is on the ignore list.
title_id- Product id / ASIN / ISBN used as the title key.account_id- Store account id.
Result<bool> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn set_ignored(
&self,
title_id: &str,
account_id: &str,
ignored: bool,
reason: Option<&str>,
) -> Result<()>
Adds or removes a title from the per-account ignore list.
title_id- Product id / ASIN / ISBN used as the title key.account_id- Store account id.ignored- When true, add to the ignore list; when false, remove.reason- Optional operator note for why the title is ignored.
Result<()> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn set_acquire_status(
&self,
title_id: &str,
account_id: &str,
status: AcquireStatus,
storage_key: Option<&str>,
error_message: Option<&str>,
) -> Result<()>
Records the acquire state of the title account_id holds that
title_id names (see Self::held_title), as
Self::set_holding_acquire_status records it for that holding.
title_id- Holding id, product id, ASIN or ISBN of the title.account_id- Store account id.status- Acquire or request status value.storage_key- Object-storage key for the primary audio artifact.error_message- Optional failure message to persist.
Returns LibraryError::NotFound when the account holds no such
title (or it stops holding the edition before the write),
LibraryError::Conflict when the name is ambiguous, or the
database error.
pub async fn set_holding_acquire_status(
&self,
holding_id: &str,
status: AcquireStatus,
storage_key: Option<&str>,
error_message: Option<&str>,
) -> Result<()>
Records the acquire state account holding holding_id
(holdings.id) wrote for the edition its listing sells.
The edition's edition_acquisitions row (read with
Self::edition_acquisition) and the state's event, which names
the holding, are written in one batch; an edition another holding
acquired keeps its state while that holding exists.
holding_id- The account holding that wrote the state.status- The new acquire state.storage_key- Object-storage key for the primary audio artifact.error_message- Optional failure message to persist.
Returns LibraryError::NotFound when no account holding has that
id or it no longer holds the edition, or the database error.
pub async fn bulk_set_acquire_status(
&self,
account: Option<&str>,
asins: &[String],
status: AcquireStatus,
) -> Result<u32>
Bulk-update acquire status (classic set-status --force).
Walks every account holding (only account's when set) and writes
status for each title, keeping its edition's storage key. When
asins is non-empty, only titles whose holding id, product id, ISBN
or ASIN one of them names (ignoring ASCII case) are written.
How many titles were written.
Returns the first read or write error; titles written before it stay written.
pub async fn list_saved_filters(&self) -> Result<Vec<SavedFilterRecord>>
List saved quick-filter expressions.
Returns an error when the operation fails.
pub async fn upsert_saved_filter(
&self,
name: &str,
query: &str,
) -> Result<SavedFilterRecord>
Inserts or replaces a named saved library filter query.
name- Logical name (filter, secret, …).query- Saved filter query string.
Result<SavedFilterRecord> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn get_saved_filter(&self, name: &str) -> Result<Option<SavedFilterRecord>>
Loads a saved filter by name, if present.
name- Logical name (filter, secret, …).
Result<Option<SavedFilterRecord>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn delete_saved_filter(&self, name: &str) -> Result<()>
Deletes a saved filter by name.
name- Logical name (filter, secret, …).
Result<()> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn count_works_by_status(&self) -> Result<AcquireStatusCounts>
Counts the library's held works per acquire status in one grouped
read of the page index (library_work_rows), where each work has the
furthest state any of its editions reached.
The count for each AcquireStatus and the total. A row with a
status this build does not know is counted in the total only.
Returns LibraryError::Orm when the read fails for a reason other
than file-lock contention, and LibraryError::Unavailable when the
lock is still held after the retries.
pub async fn upsert_listening_progress(
&self,
row: &NewListeningProgress,
) -> Result<ListeningProgressRecord>
Inserts or updates listening progress for a title.
row-rowargument for this call.
Result<ListeningProgressRecord> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn get_listening_progress(
&self,
provider: &str,
external_user_id: &str,
external_item_id: &str,
) -> Result<Option<ListeningProgressRecord>>
Loads listening progress for one identity and book.
provider- External provider id.external_user_id- User id at the external provider.external_item_id-external_item_idargument for this call.
Result<Option<ListeningProgressRecord>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn list_listening_progress(
&self,
external_user_id: Option<&str>,
) -> Result<Vec<ListeningProgressRecord>>
Lists listening progress rows for an identity.
external_user_id- User id at the external provider.
Result<Vec<ListeningProgressRecord>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn create_title_request(
&self,
req: &NewTitleRequest,
) -> Result<TitleRequestRecord>
Creates a wishlist / title-request row.
req- Insert / update request payload.
Result<TitleRequestRecord> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn create_title_request_for(
&self,
req: &NewTitleRequest,
work: Option<&WishWork>,
) -> Result<TitleRequestRecord>
Creates a wishlist / title-request row for a known work.
A wish that names a store edition the server looked up is for that
listing's work: its resolution in the shared pool, with no holding.
Without one, the wish's text and identifiers find or make the work
(Self::work_for_wish).
req- Insert / update request payload.work- The work (and edition) of a pooled listing the wish names, orNoneto resolve it fromreq.
The new wish, or the caller's open wish for the same work.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn upsert_title_request_sources(
&self,
title_request_id: i64,
sources: &[NewTitleRequestSource],
) -> Result<TitleRequestRecord>
Upsert per-storefront snapshots for a wishlist row, then return the merged record.
Returns an error when the operation fails.
pub async fn list_title_request_sources(
&self,
title_request_id: i64,
) -> Result<Vec<TitleRequestSourceRecord>>
Lists per-storefront snapshots for a title request.
title_request_id-title_request_idargument for this call.
Result<Vec<TitleRequestSourceRecord>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn find_open_wishlist(
&self,
identity_id: Option<i64>,
work_id: &str,
) -> Result<Option<TitleRequestRecord>>
Open wish of this identity for work_id, if any.
identity_id- The wisher's portal identity;Nonefor the operator.work_id- The work wished for.
Returns LibraryError::Orm when a read fails.
pub async fn list_wishlist(
&self,
identity_id: Option<i64>,
) -> Result<Vec<TitleRequestRecord>>
Personal open wishlist for a portal identity, or operator (identity_id null).
Returns an error when the operation fails.
pub async fn list_global_request_queue(&self) -> Result<Vec<GlobalQueueEntry>>
Global request queue: open wishes grouped by their work.
Sorted by wish count as a simple default; Discover re-ranks with local taste plus a heavy per-wisher boost for the Wishlist sidebar.
Returns an error when the operation fails.
pub async fn get_title_request_by_uuid(
&self,
uuid: &str,
) -> Result<Option<TitleRequestRecord>>
Loads a wishlist title-request row by UUID, if present.
uuid- Book UUID.
Result<Option<TitleRequestRecord>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn list_title_requests(
&self,
status: Option<RequestStatus>,
) -> Result<Vec<TitleRequestRecord>>
Lists wishlist / title-request rows.
status- Acquire or request status value.
Result<Vec<TitleRequestRecord>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn update_title_request_status(
&self,
uuid: &str,
status: RequestStatus,
resolved_edition_id: Option<&str>,
) -> Result<()>
Updates the lifecycle status of a title request.
uuid- Book UUID.status- Acquire or request status value.resolved_edition_id- Edition that fulfilled the request, when it is now held.
Result<()> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn upsert_embedding(
&self,
target_kind: &str,
target_id: &str,
model: &str,
dims: i64,
vector: &[u8],
text_hash: &str,
) -> Result<()>
Inserts or replaces an embedding vector for a target.
target_kind- Embedding target kind.target_id- Embedding target id.model- Embedding model id.dims- Vector dimensionality.vector- Raw embedding bytes.text_hash- Hash of the embedded text.
Result<()> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn get_embedding_vector(
&self,
target_kind: &str,
target_id: &str,
model: &str,
) -> Result<Option<(String, Vec<u8>)>>
Loads the raw embedding bytes for a target, if present.
target_kind- Embedding target kind.target_id- Embedding target id.model- Embedding model id.
Result<Option<(String, Vec<u8>)>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn list_embeddings(
&self,
target_kind: &str,
model: &str,
) -> Result<Vec<(String, Vec<u8>)>>
Lists embedding metadata rows (optionally filtered).
target_kind- Embedding target kind.model- Embedding model id.
Result<Vec<(String, Vec<u8>)>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn embedding_text_hash(
&self,
target_kind: &str,
target_id: &str,
model: &str,
) -> Result<Option<String>>
Returns the stored text hash for an embedding target, if any.
target_kind- Embedding target kind.target_id- Embedding target id.model- Embedding model id.
Result<Option<String>> — Ok on success.
Returns a crate error when the database operation fails or inputs are invalid.
pub async fn get_user_preferences(
&self,
subject_key: &str,
) -> Result<Option<UserPreferences>>
Load per-user GUI / Discover preferences by subject key.
Returns an error when the operation fails.
pub async fn get_user_preferences_or_default(
&self,
subject_key: &str,
identity_id: Option<i64>,
) -> Result<UserPreferences>
Preferences for subject_key, or in-memory defaults when no row exists.
Returns an error when the operation fails.
pub async fn upsert_user_preferences(
&self,
subject_key: &str,
identity_id: Option<i64>,
default_view: &str,
disabled_shelves: &[String],
discover_sort: &str,
discover_sort_dir: &str,
discover_language: Option<&str>,
discover_excluded_sources: &[String],
theme: &str,
) -> Result<UserPreferences>
Insert or replace preferences for a subject (operator or portal identity).
Returns an error when the operation fails.
Implements: Clone, Debug
pub struct LostCopies {
pub restoring: u64,
pub missing: u64,
pub not_acquired: u64,
}
What LibraryStore::lose_copies did with the stored copies whose file
is gone.
Fields
restoring: Copies that turned pending for the copy retry to write again (output.missing_files = restore).missing: Copies marked missing (output.missing_files = mark_missing).not_acquired: Editions that turned not acquired because no destination holds a stored copy of them any more.
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub struct NewBook {
pub product_id: String,
pub plugin_key: String,
pub source: String,
pub account_id: String,
pub asin: Option<String>,
pub isbn: Option<String>,
pub marketplace: String,
pub title: String,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub series_asin: Option<String>,
pub purchased_at: Option<DateTime<Utc>>,
pub publisher: Option<String>,
pub length_minutes: Option<i64>,
pub is_abridged: bool,
pub content_kind: String,
pub categories: Option<String>,
pub subtitle: Option<String>,
pub published_at: Option<DateTime<Utc>>,
}
One title as a library sync (or an import) reports it: the account that holds it, the store listing it describes and the store's text.
Fields
product_id: Storefront product id (ASIN, ISBN, UUID, …).plugin_key: Provenance-qualified PluginKey that owns the account. Forced by the scope on write.source: Display alias of the owning plugin (audible,libro, …).account_id: Store or operator account id this row belongs to.asin: Amazon ASIN when known; otherwise null.isbn: ISBN-10/13 when known; otherwise null.marketplace: Store marketplace / locale code (for exampleus,uk).title: Display title of the work or edition.authors: Comma-separated or JSON author list from the storefront.narrators: Comma-separated or JSON narrator list when present.series: Series name when the title belongs to a series.series_index: Position within the series (storefront string form).series_asin: Amazon series ASIN when the storefront exposes one.purchased_at: RFC 3339 purchase time from the storefront, when known.publisher: Publisher name from metadata enrichment or the storefront.length_minutes: Runtime in whole minutes when the storefront reports it.is_abridged: Whether the edition is abridged (0/1 or bool).content_kind: Title kind:book,episode,podcast, ….categories: Storefront category / genre path list (serialized).subtitle: Optional subtitle from bibliographic metadata.published_at: Publication date string from the storefront or enrichment.
pub fn needs_html_entity_decode(&self) -> bool
True when any human-readable field may contain an HTML entity.
pub fn decode_html_entities(&mut self)
Decode HTML entities in human-readable metadata fields (titles, etc.).
pub fn minimal(
product_id: impl Into<String>,
account_id: impl Into<String>,
marketplace: impl Into<String>,
title: impl Into<String>,
) -> Self
Minimal Audible book row with scan metadata defaults.
Sets product_id from the first argument, asin = Some(product_id),
isbn = None, uuid = None (auto), and plugin_key = source = "audible" (a [crate::SourceScope] replaces both on write).
Implements: Clone, Debug, From<NewBook>
pub struct NewListeningProgress {
pub identity_id: Option<i64>,
pub provider: String,
pub external_user_id: String,
pub work_id: String,
pub edition_id: Option<String>,
pub external_item_id: String,
pub progress: Option<f64>,
pub current_time_seconds: Option<f64>,
pub duration_seconds: Option<f64>,
pub is_finished: bool,
pub last_listened_at: Option<DateTime<Utc>>,
}
Input for upserting listening progress.
Fields
identity_id: Foreign key toportal_identities.id.provider: External identity or integration provider id (for example ABS).external_user_id: User id at the external provider.work_id: The work the item resolved to through its identifiers.edition_id: The edition the item's identifiers name, when exactly one does.external_item_id: Provider-native listening-progress item id.progress: Fractional progress 0.0–1.0 when the provider reports it.current_time_seconds: Current playback position within the title, in seconds.duration_seconds: Total duration in seconds when known.is_finished: Whether the listener marked the title finished (0/1 or bool).last_listened_at: RFC 3339 time of the last playback update.
Implements: Clone, Debug
pub struct NewTitleRequest {
pub uuid: Option<String>,
pub identity_id: Option<i64>,
pub title: String,
pub authors: Option<String>,
pub asin: Option<String>,
pub isbn: Option<String>,
pub notes: Option<String>,
pub status: RequestStatus,
pub resolved_edition_id: Option<String>,
pub cover_url: Option<String>,
}
Input for creating a title request / wishlist row.
Fields
uuid: Stable UUID for this row (API / foreign-key identity).identity_id: Foreign key toportal_identities.id.title: Title the wisher asked for. It only finds (or makes) the wish's work and is not stored on the wish.authors: Comma-separated authors the wisher gave, used liketitle.asin: Amazon ASIN the wisher gave, used liketitle.isbn: ISBN-10/13 the wisher gave, used liketitle.notes: Free-form operator or requester notes.status: Lifecycle status for the row (user, request, …).resolved_edition_id: Edition (editions.id) the library holds once the wishlist item is fulfilled.cover_url: HTTPS URL for cover art when known.
pub fn needs_html_entity_decode(&self) -> bool
Returns true when the string still contains HTML character entities.
pub fn decode_html_entities(&mut self)
Decode HTML entities in human-readable fields.
Implements: Clone, Debug
pub struct NewTitleRequestSource {
pub source: String,
pub product_id: String,
pub title: Option<String>,
pub subtitle: Option<String>,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub asin: Option<String>,
pub isbn: Option<String>,
pub description: Option<String>,
pub publisher: Option<String>,
pub length_minutes: Option<i64>,
pub published_at: Option<String>,
pub categories: Option<String>,
pub language: Option<String>,
pub cover_url: Option<String>,
pub url: Option<String>,
pub price_cents: Option<i64>,
pub currency: Option<String>,
pub price_label: Option<String>,
pub list_price_cents: Option<i64>,
pub list_price_label: Option<String>,
pub member_price_cents: Option<i64>,
pub member_price_label: Option<String>,
pub listing_id: Option<String>,
}
Input for upserting a per-storefront wishlist snapshot.
Fields
source: Content-source plugin id (audible,libro, …).product_id: Storefront product id (ASIN, ISBN, UUID, …).title: Display title of the work or edition.subtitle: Optional subtitle from bibliographic metadata.authors: Comma-separated or JSON author list from the storefront.narrators: Comma-separated or JSON narrator list when present.series: Series name when the title belongs to a series.series_index: Position within the series (storefront string form).asin: Amazon ASIN when known; otherwise null.isbn: ISBN-10/13 when known; otherwise null.description: Blurb / synopsis text (may contain HTML).publisher: Publisher name from metadata enrichment or the storefront.length_minutes: Runtime in whole minutes when the storefront reports it.published_at: Publication date string from the storefront or enrichment.categories: Storefront category / genre path list (serialized).language: BCP-47 or storefront language code when known.cover_url: HTTPS URL for cover art when known.url: Storefront product or purchase URL when known.price_cents: Observed price in minor currency units, when known.currency: ISO 4217 currency code for price fields.price_label: Storefront-formatted price string for display.list_price_cents: List/MSRP price in minor units, when known.list_price_label: Storefront-formatted list price for display.member_price_cents: Member/subscriber price in minor units, when known.member_price_label: Storefront-formatted member price for display.listing_id: The shared pool's listing for this store edition, when the server looked it up at the store (crate::CatalogListing);Nonekeeps what the row already names.
pub fn needs_html_entity_decode(&self) -> bool
Returns true when the string still contains HTML character entities.
pub fn decode_html_entities(&mut self)
Decode HTML entities in human-readable metadata fields.
Implements: Clone, Debug, Default
pub struct ProbedAudioFile {
pub destination: String,
pub storage_key: String,
pub role: FileRole,
pub copy: Option<OutputCopy>,
pub probe: Option<FileProbe>,
pub stream: AudioStream,
}
One audio file of an edition as LibraryStore::edition_audio_files
reads it back.
Fields
destination: Output destination id (local,s3).storage_key: Storage key on that destination.role: Primary audio, a part or a chapter file.copy: The library copy (output.copies) the file belongs to;Nonefor an upload or a copy this build cannot read.probe: What the last probe found;Noneuntil the file has been probed.stream: What the last probe found about the stream; allNoneuntil the file has been probed, or for a probe from before streams were stored.
Implements: Clone, Debug, Eq, PartialEq
pub struct QueueRank {
pub work_id: String,
pub owned: bool,
pub taste_score: f64,
pub reasons: Vec<String>,
}
The taste ranking of one queue entry, as the ranking job computed it.
Fields
work_id: The work (works.id) the entry's wishes are for, which identifies the entry.owned: True when the library already holds the entry's work.taste_score: Household taste score before the wish-count boost. A non-finite value is stored as 0.reasons: Taste reasons; at mostMAX_QUEUE_REASONSare stored.
Implements: Clone, Debug, PartialEq
pub struct SavedFilterRecord {
pub id: i64,
pub name: String,
pub query: String,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
Saved Lucene-style quick filter.
Fields
id: Surrogate primary key assigned by the database.name: Human-readable or logical name for this row.query: Saved library filter expression (UI search DSL).created_at: RFC 3339 timestamp when the row was inserted.updated_at: RFC 3339 timestamp when the row was last modified.
Implements: Clone, Debug
pub struct ScannedTitle {
pub book: NewBook,
pub listing: Option<Listing>,
pub is_explicit: Option<bool>,
}
One title a storefront scan reported.
Fields
book: The scan's record of the title: the account, the store text and, withoutSelf::listing, the listing it describes.listing: The listing the plugin's structured record describes;Nonewhen onlybookis known.is_explicit: Whether the store marks the edition explicit (adult) content:Some(true)explicit,Some(false)clean,Noneunknown. Kept on the listing (store_listings.is_explicit).
Implements: Clone, Debug, From<NewBook>
pub struct SeenObject {
pub key: String,
pub size: u64,
pub signature: Option<String>,
pub modified_at_ms: Option<u64>,
}
One object as a listing or a change feed reports it.
Fields
key: The object's key at the destination.size: Object size in bytes.signature: The backend's opaque change signature, else its entity tag;Nonewhen it gave neither, and then a change of size alone counts as a change.modified_at_ms: Last modification time in UTC unix milliseconds, when known.
Implements: Clone, Debug, Eq, PartialEq
pub struct StoreCallHit {
pub listing_id: String,
pub origin: String,
pub rank_hint: Option<u32>,
}
One listing a cached storefront call answered.
Fields
listing_id: Thestore_listingsrow the hit resolved to.origin: How the store found it for this call.rank_hint: The store's own 1-based rank for the hit, when it gave one.
Implements: Clone, Debug, Eq, PartialEq
pub struct StoredCandidate {
pub source: String,
pub listing: CatalogListingRecord,
pub seed_scope: SeedScope,
pub origin: String,
pub seed_title: Option<String>,
pub seed_categories: Option<String>,
pub starter_genre: Option<String>,
pub fetched_at: DateTime<Utc>,
}
One stored storefront candidate of a subject: the shared listing joined with what is personal to the subject.
Fields
source: Storefront plugin id that returned the title (audible).listing: The listing, read from the shared pool.seed_scope: Seeds that produced the row.origin: How the store found it.seed_title: The subject's title that seeded it, when a seed did.seed_categories: That seed's categories.starter_genre: Starter genre it was browsed from, for a thin taste.fetched_at: When the store fetch that produced the row ran.
Implements: Clone, Debug
pub struct StoredDiscoverTaste {
pub taste_json: String,
pub seed_scope: SeedScope,
pub computed_at: DateTime<Utc>,
}
One subject's stored Discover taste.
Fields
taste_json: The taste as JSON (bookclerk_discover::StoredTaste).seed_scope: Seeds the taste comes from.computed_at: When the taste was computed.
Implements: Clone, Debug, Eq, PartialEq
pub struct StoredFeed {
pub feed_json: String,
pub seed_scope: SeedScope,
pub candidates_fetched_at: Option<DateTime<Utc>>,
pub computed_at: DateTime<Utc>,
}
One subject's stored, ranked Discover feed.
Fields
feed_json: The feed as JSON, before hidden shelves are filtered out.seed_scope: Seeds the feed was ranked from.candidates_fetched_at: Newest candidate fetch the feed used, when it used any.computed_at: When the feed was ranked.
Implements: Clone, Debug
pub struct StoredQueueRank {
pub rank: QueueRank,
pub ranked_at: DateTime<Utc>,
}
One stored queue ranking row.
Fields
rank: The ranking.ranked_at: When the ranking pass that wrote the row ran.
Implements: Clone, Debug, PartialEq
pub struct TitleHolding {
pub edition_id: String,
pub holding_id: String,
}
The edition a library title sells and the account holding it is held by: the key its acquire writes are recorded under.
Fields
edition_id: The edition the title's listing sells.holding_id: The account's holding of that listing (holdings.id).
Implements: Clone, Debug, Eq, PartialEq
pub struct UserBookFields {
pub tags: Option<String>,
pub rating_overall: Option<f32>,
pub rating_performance: Option<f32>,
pub rating_story: Option<f32>,
pub is_finished: Option<bool>,
}
Partial update for user-defined book fields.
Fields
tags: Operator or storefront tags (serialized string).rating_overall: Overall user rating from the storefront, if any.rating_performance: Narration/performance rating from the storefront, if any.rating_story: Story rating from the storefront, if any.is_finished: Whether the listener marked the title finished (0/1 or bool).
Implements: Clone, Debug, Default
pub struct WishWork {
pub work_id: String,
pub edition_id: Option<String>,
}
The work a wish is for, read from a store listing in the shared pool.
Fields
work_id:works.idof the listing's resolution.edition_id:editions.idthe listing is an edition of.
Implements: Clone, Debug, Eq, PartialEq
pub struct NotifyCursor {
pub created_at: String,
pub id: String,
}
Where a page of the delivery log or an inbox starts: the last row of the previous page (newest first).
Fields
created_at: RFC 3339 creation time of the last row read.id: Id of the last row read (the notification id for an inbox).
pub fn encode(&self) -> String
The opaque token a page answer carries.
pub fn decode(token: &str) -> Result<Self>
Reads a token made by Self::encode.
LibraryError::Invalid when the token is not one: not base64url,
not the JSON shape, or a field over 128 bytes.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct NotifyPage<T> {
pub items: Vec<T>,
pub more: bool,
}
One page of a newest-first listing.
Fields
items: The page's rows, at most the page size asked for.more: Whether at least one row follows the last one: only then does the listing hand out a cursor, so a full final page ends the walk.
Implements: Clone, Debug, Eq, PartialEq
pub struct NotifyQueueLimits {
pub max_pending: i64,
pub max_attempts: i64,
}
Queue limits a notify_send admission uses (the daemon's [jobs]).
Fields
max_pending: Global cap on pending and running jobs.max_attempts: Claims before a failing send job stops.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum DbAtomicParams {
DeleteUser { user_id: i64 },
SetUserStatus { user_id: i64, status: String },
SetUserPasswordHash { user_id: i64, password_hash: Option<String> },
SetUserRole { user_id: i64, role: String },
RedeemClaimTicket { token_hash: String, session_hash: String, expires_at: String, user_agent: Option<String>, device_type: Option<String>, client_label: Option<String>, new_password_hash: Option<String>, password_fingerprint: Option<String> },
TakeOidcRpState { state_hash: String },
TakeWebauthnChallenge { challenge_id: String, kind: String },
EnqueueJob { kind: String, payload_json: String, priority: i64, max_attempts: i64, max_pending: i64, run_after: Option<String> },
ClaimNextJob { resource_class: String, owner: String, lease_secs: i64 },
ReserveJobTemp { job_id: String, path: String, reserved_bytes: i64, quota_bytes: i64 },
ConfirmTotpEnrollment { user_id: i64, format: String, ciphertext: String, cipher_algorithm: Option<String>, cipher_nonce: Option<String>, kdf_algorithm: Option<String>, kdf_salt: Option<String>, kdf_m_cost: Option<i64>, kdf_t_cost: Option<i64>, kdf_p_cost: Option<i64>, created_at: String },
DisableUserTotp { user_id: i64 },
PublishDomainEvent { id: String, event_type: String, schema_version: i64, account_id: String, source: String, correlation_id: String, causation_id: String, dedup_key: String, payload: String, ordering_key: String, queue_name: String, content_type: String, deliver_after: String },
SetAcquireStatus { holding_id: String, edition_id: String, status: String, storage_key: Option<String>, error_message: Option<String>, event_id: String, event_type: String, schema_version: i64, event_account_id: String, source: String, correlation_id: String, causation_id: String, dedup_key: String, payload: String, ordering_key: String },
DispatchEventDeliveries { event_id: String, subscribers_json: String, mark_dispatched: bool },
ClaimNextEventDelivery { owner: String, lease_secs: i64, plugin_ids_json: String, max_in_flight: i64 },
LinkListing(Box<ListingLinkParams>),
WriteCredits(Box<CreditBatchParams>),
}
Named atomic library operation compiled by the host into a generic plan.
Variants
-
DeleteUser: Delete a first-party user and personal data (last-owner guarded).user_id:users.idto delete.
-
SetUserStatus: Setusers.status(active/disabled; last-owner guarded).user_id:users.idto update.status: Canonical status string (activeordisabled).
-
SetUserPasswordHash: Set or clear the Argon2id password hash and bumpsecurity_version.user_id:users.idto update.password_hash: New hash, ornullto clear.
-
SetUserRole: Setusers.role(last-owner guarded on demotion).user_id:users.idto update.role: Canonical role string (owner/administrator/member).
-
RedeemClaimTicket: Consume a claim ticket, optionally set a first password, mint a session.token_hash: SHA-256 hex digest of the claim ticket.session_hash: SHA-256 hex digest of the new portal session token.expires_at: RFC 3339 expiry for the minted session.user_agent: Raw User-Agent captured at session mint.device_type: Best-effort device class.client_label: Best-effort OS / client label.new_password_hash: Argon2id hash to set when the local user has none.password_fingerprint: Domain-separated HMAC of the invite password for idempotency.
-
TakeOidcRpState: Consume a one-time OIDC RP state (DELETE+ expiry check).state_hash: SHA-256 hex digest of the OAuthstateparameter.
-
TakeWebauthnChallenge: Consume a one-time WebAuthn challenge (DELETE+ expiry check).challenge_id: Public ceremony id returned to the browser.kind:register,login, orelevate.
-
EnqueueJob: Admit a durable job (dedup + pending cap + insert).kind: Job kind wire string (scan,acquire,listen_sync,integration_scan).payload_json: Versioned command envelope JSON.priority: Higher values are claimed first.max_attempts: Maximum claims before a failure is terminal.max_pending: Global cap on pending+running rows.run_after: Optional RFC 3339 delay before the job becomes claimable.
-
ClaimNextJob: Claim the next ready job inresource_classforowner.resource_class: Resource class wire string (network, …).owner: Worker id stored aslease_owner.lease_secs: Lease length in seconds.
-
ReserveJobTemp: Reserve scratch-quota bytes for one job path.job_id: Owning job id.path: Absolute filesystem path.reserved_bytes: Bytes to reserve for this path.quota_bytes: Global reserved-bytes cap.
-
ConfirmTotpEnrollment: Promote a sealed TOTP secret toprimaryand setusers.totp_enabled.user_id:users.idto enroll.format: Payload format (sealed-v1).ciphertext: Sealed TOTP secret bytes (b64:…).cipher_algorithm: Cipher algorithm identifier, if any.cipher_nonce: AEAD nonce (b64:…), if any.kdf_algorithm: Legacy KDF algorithm, if any.kdf_salt: Legacy KDF salt (b64:…), if any.kdf_m_cost: Legacy Argon2 memory cost in KiB, if any.kdf_t_cost: Legacy Argon2 time cost, if any.kdf_p_cost: Legacy Argon2 parallelism, if any.created_at: RFC 3339 timestamp to store ascreated_aton the primary row.
-
DisableUserTotp: Delete TOTP secrets and clearusers.totp_enabled.user_id:users.idto disable.
-
PublishDomainEvent: Persist a domain event in the outbox (dedup on eventType+dedupKey).id: Stable event id (UUID).event_type: Event type (book_acquired).schema_version: Payload schema version.account_id: Tenant / account id.source: Producer plugin id; empty when unknown.correlation_id: Trace correlation id.causation_id: Causing event or job id.dedup_key: Unique witheventType.payload: Bounded JSON payload.ordering_key: FIFO key copied onto deliveries.queue_name: Queue name; empty means the domain-event bus (core.events).content_type: Body encoding (json,text,bytes); empty meansjson.deliver_after: RFC 3339 earliest delivery time; empty means now.
-
SetAcquireStatus: Write an edition's acquire state for the account holding that made the write, and publish its event in the same batch.holding_id: The account holding (holdings.id) that wrote the state; every statement is gated on it still holdingedition_id.edition_id: The edition whoseedition_acquisitionsrow is written.status: Acquire status string (acquired,downloading, …).storage_key: Object-storage key for the primary audio artifact.error_message: Optional failure message.event_id: Event id when publishing; empty skips the outbox insert.event_type: Event type when publishing (book_acquired).schema_version: Payload schema version.event_account_id: Tenant / account id on the event.source: Producer plugin id; empty when unknown.correlation_id: Trace correlation id.causation_id: Causing event or job id.dedup_key: Unique witheventType.payload: Bounded JSON payload.ordering_key: FIFO key copied onto deliveries.
-
DispatchEventDeliveries: Create per-subscriber deliveries and mark the event dispatched.event_id: Parent event id.subscribers_json: JSON array of{ "pluginId": "…" }subscriber snapshots.mark_dispatched: When true, this page is the last snapshot and may mark the parent dispatched.
-
ClaimNextEventDelivery: Claim the next ready event delivery forowner.owner: Worker id stored aslease_owner.lease_secs: Lease length in seconds.plugin_ids_json: JSON array of plugin ids this worker can execute ([]claims nothing).max_in_flight: Library-wide maxrunningdeliveries per(plugin_id, resource_class).
-
LinkListing: Write one resolved store listing: new work, expression and edition, identifiers, the listing, its holding, conflicts and events.Answers
retrywhen another writer stored the listing or claimed a strong identifier first. -
WriteCredits: Write contributors, credits, series and series entries (idempotent).
Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize
pub enum CanonicalObject {
Schema { sql_contract_version: u32, statements: Vec<String> },
TableChunk { table: String, columns: Vec<String>, rows: Vec<Vec<DbValue>> },
Identity { entries: BTreeMap<String, IdentityHighWater> },
}
One immutable canonical object (hashed before compression).
Variants
Schema: AdmittedCREATE TABLE/CREATE INDEXin restore order.sql_contract_version: Bookclerk SQL grammar/ABI contract.statements: Canonical statements (tables in FK-safe order, then indexes).
TableChunk: Bounded table rows in canonical order.table: Folded table name.columns: Column names in CREATE declaration order.rows: Row-majorDbValuecells.
Identity: Identity high-water for generated columns.entries: Folded table name → high-water.
Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize
pub enum BackupReason {
Manual,
PreMigrate,
}
Why a backup was written.
Variants
Manual: Operator-created (bookclerk db backup create). Never pruned automatically.PreMigrate: Written immediately before a frozen schema walk.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum BackupResolve {
Id(String),
Archive(PathBuf),
}
How resolve_backup_spec located a recovery point.
Variants
Id: Catalog id underbackups/manifests/.Archive:.tar.gzarchive of one recovery point.
Implements: Clone, Debug
pub enum CanonicalRestoreKind {
Library,
PluginBinding,
}
How restore applies DDL companions.
Variants
Library: Host library: Postgres identity companions only (no plugin catalog).PluginBinding: Plugin binding: catalog + Postgres identity companions.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum DatabaseUnitKind {
Library,
PluginBinding,
}
Logical kind of one database unit in a recovery point.
Variants
Library: Host library database.PluginBinding: Plugin-owned binding (plugin_id+binding).
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum EntityKind {
Account,
Book,
Work,
Edition,
Listing,
TitleRequest,
User,
PortalIdentity,
OperatorSession,
Passkey,
OidcState,
WebauthnChallenge,
Node,
EnrollmentLink,
PendingJoin,
LibraryIdentity,
LibraryLink,
LibraryNodeKeys,
ClerkLink,
ClerkCard,
Configuration,
PluginInstance,
PluginDeployment,
Placement,
PluginVersion,
VersionPointer,
SettingsSchema,
RemoteConsent,
BranchRequest,
DomainEvent,
EventDelivery,
Job,
SavedFilter,
ClaimTicket,
NotifyDestination,
Notification,
MetadataClaim,
}
The kind of thing a LibraryError::NotFound could not find.
Each variant displays as the lower-case phrase an error message uses,
such as enrollment link.
Variants
Account: A store account, keyed by plugin and account id.Book: A library title: an account's holding of a store listing.Work: A work of the library data model.Edition: An edition of the library data model.Listing: A store listing of the library data model (store_listings).TitleRequest: A title request (wishlist entry).User: A user.PortalIdentity: A portal identity linked to a user.OperatorSession: An operator session.Passkey: A registered passkey.OidcState: An OpenID Connect relying-party sign-in state.WebauthnChallenge: A WebAuthn ceremony challenge.Node: A library node.EnrollmentLink: A node enrollment link.PendingJoin: A pending join of this host to another library.LibraryIdentity: This library's identity.LibraryLink: A link to another library.LibraryNodeKeys: The node keys a linked library published.ClerkLink: A library this install holds a library card for, as a clerk.ClerkCard: The sealed library card of a clerk link.Configuration: A configuration document, by namespace.PluginInstance: A plugin instance.PluginDeployment: A plugin deployment.Placement: A plugin instance's scheduler placement.PluginVersion: An installed plugin version.VersionPointer: A plugin's active version pointer.SettingsSchema: A plugin's pinned settings schema.RemoteConsent: A remote plugin consent.BranchRequest: A request from a linked library.DomainEvent: A domain event on the outbox.EventDelivery: An event delivery.Job: A job.SavedFilter: A saved library filter.ClaimTicket: A claim ticket.NotifyDestination: A notification destination.Notification: A notification (in an inbox or the delivery log).MetadataClaim: One source's metadata claim about a library subject.
pub const ALL: [Self; 37] = _
Every kind, in declaration order.
pub const fn as_str(self) -> &'static str
The phrase an error message names this kind with.
Implements: Clone, Copy, Debug, Display, Eq, Hash, PartialEq
pub enum LibraryError {
Schema(String),
Orm(DbErr),
Config(ConfigError),
Io(Error),
NotFound(Missing),
LastAdministrator,
LastOwner,
InvalidEmail,
Unavailable(String),
Conflict(String),
Forbidden(String),
Invalid(String),
LimitExceeded(LimitExceeded),
Other(Error),
}
Failures from library store, schema apply, secrets, or config.
Variants
-
Schema: Schema versioning, backup, or canonical SQL failure. -
Orm: SeaORM / database-plugin failure (DbErr). -
Config: Configuration load or validation failure. -
Io: Filesystem or other I/O failure. -
NotFound: A requested row was not found; the payload names what and which. -
LastAdministrator: Demoting or disabling the last active administrator is refused. -
LastOwner: Demoting, disabling, or deleting the last active owner is refused. -
InvalidEmail: Contact email failed library-backed syntax validation. -
Unavailable: Backend temporarily unreachable or an atomic RPC response was lost.Callers that still hold the original consume-once / session token should retry the same atomic operation id rather than minting a new one.
-
Conflict: Identity or ownership conflict (for example a taken OIDCclient_id). -
Forbidden: The caller may not perform this write (for example a configuration write without operator authority). -
Invalid: The request or stored document failed validation. -
LimitExceeded: A request or its result exceeded a negotiated SQL-v1 cap (maxResultBytes,maxResultRows,maxRequestBytes, ...).Not retryable as is: the caller narrows the request (fewer rows, fewer statements) or switches to a transport that fits.
-
Other: Catch-all for otherwise unclassified failures.
pub fn not_found(entity: EntityKind, id: impl Display) -> Self
A Self::NotFound for entity with the id id.
entity- The kind of row that is missing.id- The id that was asked for, as the caller names it.
pub const fn missing(entity: EntityKind) -> Self
A Self::NotFound for entity without an id (a singleton, or a
lookup by something other than an id).
pub fn from_db_err(err: DbErr) -> Self
Maps a SeaORM / adapter sea_orm::DbErr onto a typed library error.
Busy, deadlock, and lost-commit tokens become Self::Unavailable.
Unique/duplicate-object tokens become Self::Conflict. Foreign-key,
CHECK, and NOT NULL stay Self::Orm. Everything else stays Self::Orm.
pub fn from_abi_err(err: PluginError) -> Self
Maps an ABI bookclerk_plugin_abi::PluginError from an adapter or
admission check onto a typed library error.
A limit_exceeded error becomes Self::LimitExceeded; everything
else is Self::Other with the same message.
pub fn limit(&self) -> Option<LimitExceeded>
The exceeded cap when this error is (or wraps the message of) a SQL-v1 limit error.
Matches Self::LimitExceeded directly and parses the canonical
limit exceeded: <name> is <cap>; used <n> text out of
Self::Orm, Self::Unavailable and Self::Other, so a limit
error survives a string hop through the adapter boundary.
pub fn is_schema_apply_retryable(&self) -> bool
True when host schema apply may retry after re-reading durable state.
Implements: Debug, Display, Error, From<ConfigError>, From<DbErr>, From<Error>, From<LibraryError>
pub enum AcquireStatus {
NotAcquired,
Queued,
Downloading,
Acquired,
Error,
}
Acquire / download state for a title.
Variants
NotAcquired: Title has not been queued or downloaded yet.Queued: Title is waiting in the acquire queue.Downloading: Acquire pipeline is actively downloading this title.Acquired: Primary audio artifact is stored and library status is liberated.Error: Last acquire attempt failed; see the edition'serror_message.
pub const ALL: [Self; 5] = _
Every status, in pipeline order (the edition_acquisitions.status
CHECK lists the same strings).
pub fn as_str(self) -> &'static str
Returns the canonical snake_case / lowercase wire string.
pub fn parse(s: &str) -> Option<Self>
Parses the canonical wire string; returns None when unknown.
pub fn to_classic(self) -> i32
Classic EF LiberatedStatus integer.
pub fn from_classic(status: i64) -> Self
Parse classic EF LiberatedStatus integer.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum EnqueueOutcome {
Created { id: String },
Duplicate { existing_id: String },
QueueFull,
}
Result of admitting a job into the durable queue.
Variants
Created: A new row was inserted.id: New job id.
Duplicate: An equivalent pending/running job already exists.existing_id: Existing job id that satisfies the dedup key.
QueueFull:pending + runningalready equalsmax_pending.
Implements: Clone, Debug, Eq, PartialEq
pub enum EventStreamStart {
Oldest,
Since(DateTime<Utc>),
After { created_at: String, id: String },
}
Where one event stream read starts.
Variants
Oldest: The oldest retained event.Since: The first event stored at or after this time.After: The first event after this stored(created_at, id)position.created_at: Storedcreated_attext of the last row already read.id: Event id of the last row already read.
Implements: Clone, Debug, Eq, PartialEq
pub enum JobKind {
Scan,
Acquire,
ListenSync,
IntegrationScan,
PluginCopy,
PluginScheduled,
DiscoverCandidates,
DiscoverFeed,
DiscoverRequestQueue,
CacheSweep,
SearchIndexRebuild,
LibraryIndexRebuild,
BranchRequest,
IngestBatch,
NotifySend,
Invalid,
}
Kind of durable daemon work stored in the jobs table.
Variants
Scan: Library scan for one account or every scan-enabled account.Acquire: Acquire pending titles (optional title / account filter).ListenSync: Sync listening progress from capable integrations.IntegrationScan: Remote integration library scan (Audiobookshelf, …).PluginCopy: ABIJobRunnerstream-copy vertical slice (plugin_copy).PluginScheduled: One fire of a plugin's[triggers] cronsschedule (plugin_scheduled), delivered to itsscheduled(controller)handler on a node that runs the instance.DiscoverCandidates: Fetch storefront candidates from one Discover subject's own seeds (discover_candidates), store by store.DiscoverFeed: Rank one Discover subject's stored candidates into shelves (discover_feed); no network.DiscoverRequestQueue: Rank the shared request queue against household taste and store the ranking (discover_request_queue); no network. One job serves everyone, since the queue is not personalized.CacheSweep: Sweep one node's image caches and its orphaned job scratch (cache_sweep); only the node named byJobPayload::node_idclaims it.SearchIndexRebuild: Rebuild one node's full-text search index from the library (search_index_rebuild); only the node named byJobPayload::node_idclaims it.LibraryIndexRebuild: Rebuild the library's page index (library_work_rows) from the library model (library_index_rebuild); one for the whole library, any node claims it.BranchRequest: An interlibrary request (branch_request): send this library a book one of its branches listed. Pinned byJobPayload::node_idto that branch, which claims it over the node socket (requests.claim) and never through the plugin job path; no node of this library runs it.IngestBatch: Identify and store one ingest batch (ingest_batch): uploaded files or storage references, held by the batch's patron. Pinned byJobPayload::node_idto the node whose disk holds the staged bytes, and run only by a node that holds the library database.NotifySend: Send one notification to one destination (notify_send): the delivery-log rowJobPayload::notify_deliverynames, through its notifier instance (JobPayload::plugin_instance_id, also inJobPayload::requires), so only a node running that instance claims it.Invalid: Terminal placeholder after an unreadable persisted command is rejected.
pub const ALL: [Self; 16] = _
Every kind, in declaration order; the SQL plans derive their kind lists from it so a new kind cannot be left unclaimable.
pub fn as_str(self) -> &'static str
Returns the canonical snake_case wire string.
pub fn parse(s: &str) -> Option<Self>
Parses the canonical wire string; returns None when unknown.
pub fn resource_class(self) -> JobResourceClass
Resource class used for admission and worker concurrency.
pub fn dedup_key(self, payload: &JobPayload) -> String
Idempotency key unique among pending/running jobs of the same work.
Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum JobResourceClass {
Network,
Media,
Transcription,
Indexing,
}
Concurrency class that bounds how many jobs of this type run at once.
Variants
Network: Store HTTP / scan / acquire / listening-sync work.Media: Codec / remux work (reserved; media pool remains separate).Transcription: Speech-to-text / derived transcript work (reserved for #121).Indexing: Search-index / embedding work (reserved).
pub fn as_str(self) -> &'static str
Returns the canonical snake_case wire string.
pub fn parse(s: &str) -> Option<Self>
Parses the canonical wire string; returns None when unknown.
pub const ALL: &'static [&'static str] = _
Canonical wire strings for every known class.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum JobState {
Pending,
Running,
Succeeded,
Failed,
Cancelled,
}
Lifecycle state of a durable job row.
Variants
Pending: Admitted and waiting to be claimed.Running: Claimed by a worker that holds a live lease.Succeeded: Finished successfully.Failed: Exhausted retries or failed without retry.Cancelled: Cancelled by an operator before or during execution.
pub fn as_str(self) -> &'static str
Returns the canonical snake_case wire string.
pub fn parse(s: &str) -> Option<Self>
Parses the canonical wire string; returns None when unknown.
pub fn is_active(self) -> bool
True when the job may still be claimed or is executing.
pub fn is_terminal(self) -> bool
True when the job will not run again.
Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum JobTrigger {
Api,
Scheduler,
}
Who admitted the job (API vs periodic scheduler).
Variants
Api: Enqueued from the HTTP control plane, tray, or CLI daemon commands.Scheduler: Enqueued by the daemon interval scheduler.
pub fn as_str(self) -> &'static str
Returns the canonical snake_case wire string.
pub fn parse(s: &str) -> Option<Self>
Parses the canonical wire string; returns None when unknown.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum PortalSessionKind {
Browser,
Clerk,
Player,
}
Where a user's session token is presented.
A token works only in its own place: a browser token only as the session
cookie, a library card only as Authorization: Bookclerk-Clerk, and a
player card's tokens only on the /player API.
Variants
Browser: A browser's session cookie.Clerk: A library card: a clerk that shows the user's books from this library without joining it as a node.Player: A player library card: an audiobook player app signed in to the/playerAPI. Its tokens live inplayer_card_tokens; the row's own token hash is never handed out.
pub fn as_str(self) -> &'static str
Returns the column value.
pub fn parse(s: &str) -> Option<Self>
Parses the column value; returns None when unknown.
Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum PublishDomainEventOutcome {
Created { id: String },
Duplicate { existing_id: String },
}
Result of crate::LibraryStore::publish_domain_event.
Variants
Created: A new outbox row was inserted.id: Event id.
Duplicate: An equivalent(event_type, dedup_key)row already exists.existing_id: Existing event id.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum RequestStatus {
Open,
Cancelled,
}
Wishlist row status (open while wishlisted; cancelled after un-wishlist).
Variants
Open: Wishlist item is still open (not fulfilled/cancelled).Cancelled: Request cancelled by the requester or operator.
pub fn as_str(self) -> &'static str
Returns the canonical snake_case / lowercase wire string.
pub fn parse(s: &str) -> Option<Self>
Parses the canonical wire string; returns None when unknown.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum UserRole {
Owner,
Administrator,
Member,
}
First-party user role (owner | administrator | member).
Variants
Owner: Library super-user: may elevate to Operator after password re-auth.Administrator: Library / user administration without Operator elevation.Member: Library member with scoped portal access (no operator token).
pub fn as_str(self) -> &'static str
Returns the canonical snake_case / lowercase wire string.
pub fn parse(s: &str) -> Option<Self>
Parses the canonical wire string; returns None when unknown.
pub fn is_privileged(self) -> bool
Whether this role may provision users and manage the host library.
pub fn can_elevate(self) -> bool
Whether this role may elevate to a short-lived Operator session.
pub fn can_administer_owned_nodes(self) -> bool
Whether this role reaches the node administration routes even while the user owns no node (Administrator, Owner). A Member reaches them once they own a node: owning a node does not require a role.
Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Display, Eq, PartialEq, Serialize, ToSchema
pub enum UserStatus {
Active,
Disabled,
}
First-party user status.
Variants
Active: Account may sign in and use the portal.Disabled: Account is blocked from new sessions.
pub fn as_str(self) -> &'static str
Returns the canonical snake_case / lowercase wire string.
pub fn parse(s: &str) -> Option<Self>
Parses the canonical wire string; returns None when unknown.
Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum SchemaState {
Uninitialized,
Unreleased { base_version: i64, checksum: String },
Frozen { version: i64, checksum: String },
}
Durable Bookclerk library schema state.
Variants
Uninitialized: No Bookclerk bookkeeping and no host tables.Unreleased: Development pack applied on top of a frozen base (or pre-v1).base_version: Highest frozen plan version this unreleased pack sits on (0= none).checksum: SHA-256 hex ofcrate::migrations::unreleased_ops.
Frozen: A frozencrate::migrations::HostMigrationStepis applied.version: Frozen plan version (>= 1).checksum: SHA-256 hex recorded for that frozen step.
pub fn display(&self) -> String
CLI / JSON display: uninitialized, unreleased@base<n>+<checksum>,
frozen@<version>+<checksum>.
pub fn frozen_version(&self) -> Option<i64>
Frozen revision when this state is Self::Frozen; otherwise None.
Never use 0 as a stand-in for uninitialized or unreleased.
pub fn unreleased_base_version(&self) -> Option<i64>
Frozen base recorded on an unreleased database (0 = pre-v1).
pub fn checksum(&self) -> Option<&str>
Checksum when the database has applied Bookclerk schema.
Implements: Clone, Debug, Display, Eq, PartialEq
pub enum FacetValuesOf {
Facet(WorkFacet),
Tags(i64),
}
Whose values a facet value list reads.
Variants
Facet: A facet of the page index.Tags: One user's tags (users.id).
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum WorkFacet {
Author,
Narrator,
Series,
Genre,
Publisher,
Source,
Tag,
Collection,
Explicit,
}
A filter value list of the page index (library_work_facets).
Variants
Author: Authors (hosts, for a podcast).Narrator: Narrators.Series: Series names.Genre: Genres (store categories).Publisher: Publishers.Source: Storefront plugins the work is held through.Tag: Library tags (work_tags): set by an Administrator or read from a sidecar, the same for everyone.Collection: Collections (core.collections) one of the work's files is in.Explicit: Whether a store marks one of the work's listings explicit (adult) content: the single valueexplicit, which a patron scope that hides explicit books excludes. Not offered as a Library filter.
pub const ALL: [Self; 9] = _
Every facet, in the order a work's values are written.
pub fn as_str(self) -> &'static str
The stored facet value.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Hash, PartialEq, Serialize
pub enum WorkFilter {
Facet { facet: WorkFacet, value: String },
Tag { user_id: Option<i64>, tag: String },
Finished { user_id: Option<i64>, finished: bool },
}
One filter on a page of library works.
Variants
Facet: Works with this value under a facet (matched byfacet_key). An empty series value matches works in no series.facet: The facet.value: The value.
Tag: Works the user tagged with this tag (matched byfacet_key). With no user (an operator token), nothing matches.user_id: The user (users.id) whose tags count.tag: The tag.
Finished: Works the user marked finished, or did not. With no user, no work is finished.user_id: The user (users.id) whose state counts.finished:truefor finished works,falsefor the rest.
Implements: Clone, Debug, Eq, PartialEq
pub enum WorkSort {
Title,
Author,
Added,
Series,
Purchased,
Length,
}
How a page of library works is ordered.
Variants
Title: By title sort key, A to Z.Author: By the first author's sort name, then title.Added: Newest holding first ("recently added").Series: By first series name and position, then title; works in no series last.Purchased: Newest purchase first; works no store reported a purchase time for last.Length: Longest runtime first; works with no known runtime last.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum HoldingHolder {
Account { plugin_key: String, account_id: String },
Node { node_id: String },
Patron { user_id: i64 },
}
Who holds a listing.
Variants
Account: A store account, by plugin and account id.plugin_key: The account's plugin.account_id: The account id at that plugin.
Node: A branch library's node, by node id.node_id: The node id.
Patron: A patron who uploaded the book, by user id.user_id: The person'susers.id.
Implements: Clone, Debug, Eq, PartialEq
pub enum WorkTagSource {
Admin,
Sidecar,
}
Where a library tag came from (work_tags.source).
Variants
Admin: Set in Bookclerk by an Owner, an Administrator or the operator.Sidecar: Read from a metadata file beside the book.
pub fn as_str(self) -> &'static str
The stored value.
Implements: Clone, ComposeSchema, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, ToSchema
pub enum OfferAudience {
NonMember,
Member,
}
Who a ListingOffer price is for.
Variants
NonMember: Someone without an account at the store: the price Discover shows unless the person has an account there.Member: A member or subscriber of the store.
pub fn as_str(self) -> &'static str
The stored listing_offers.audience text.
pub fn parse(text: &str) -> Option<Self>
Parses stored audience text; None for text a newer release wrote.
Implements: Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd
pub enum ChapterCheck {
Strict,
Lenient,
}
How strictly ChapterList::new reads its input.
Variants
Strict: A person's edit: anything outside the rules is refused, so what is stored is exactly what they sent.Lenient: A machine source: control characters are dropped, titles trimmed and cut toMAX_CHAPTER_TITLE_BYTES, an empty title becomes "Chapter n", and a depth that skips a level or passesMAX_CHAPTER_DEPTHis lifted. Starts out of order and too many chapters are still refused, because no repair keeps their meaning.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum ChapterSource {
Person { user_id: Option<i64> },
Processed { input: Option<ChapterDigest> },
Provider { plugin: String, quality: ProviderQuality },
Listing { plugin: String, kind: MarkerKind },
PartNames { plugin: String },
}
Who states a chapter claim, as a writer names it.
Variants
Person: An Administrator's edit. One per edition: a newer edit replaces it.user_id: The Administrator (users.id);Nonefor the operator.
Processed: Bookclerk's chapters aligned to the audio during acquire.input: The claim whose titles and starts were aligned.
Provider: A metadata provider's layout.plugin: The provider's PluginKey.quality: How it found the edition and whether its offsets are exact.
Listing: A store's markers.plugin: The storefront's PluginKey.kind: What the store says the markers are.
PartNames: The titles of a store's parts.plugin: The storefront's PluginKey.
Implements: Clone, Debug, Eq, PartialEq
pub enum ChapterSourceKind {
Person,
OutsideEdit,
Processed,
Provider,
Listing,
File,
PartNames,
}
The kind of source a chapter claim came from (source_kind).
Variants
Person: An Administrator's edit in Bookclerk.OutsideEdit: A change found outside Bookclerk: a file it did not write, or an edit in an integrated tool. Nothing records these yet.Processed: Bookclerk's own chapters, aligned to the audio during acquire.Provider: A metadata provider's chapter layout.Listing: The markers a store returned with the audio.File: Chapters read from a file as first imported. Nothing records these yet.PartNames: The titles of the parts a store delivered, one chapter per part.
pub const ALL: [Self; 7] = _
Every kind, in the order the stored values are documented.
pub fn as_str(self) -> &'static str
The stored spelling.
pub fn parse(stored: &str) -> Option<Self>
Reads a stored spelling.
Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Display, Eq, Hash, PartialEq, Serialize, ToSchema
pub enum ChaptersOutcome {
Changed,
Unchanged,
}
What a chapter write changed.
Variants
Changed: The edition's chapters now come from another list.Unchanged: The claims changed but the edition plays the same list.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum ClaimQuality {
None,
StrongAccurate,
StrongEstimated,
Weak,
Chapters,
Tracks,
Unknown,
}
Where a machine source ranks within its kind (quality).
Variants
None: Not ranked within its kind: a person's edit, an outside edit, Bookclerk's own processing, a file, part names.StrongAccurate: A provider found the edition by a strong identifier and marks the offsets exact.StrongEstimated: A provider found the edition by a strong identifier; the offsets are estimates.Weak: A provider found the edition by a weak identifier or a search.Chapters: A store's markers that it says are chapters.Tracks: A store's markers that it says are track or part boundaries.Unknown: A store's markers it says nothing about.
pub const ALL: [Self; 7] = _
Every quality, in the order the stored values are documented.
pub fn as_str(self) -> &'static str
The stored spelling; empty for Self::None.
pub fn parse(stored: &str) -> Option<Self>
Reads a stored spelling.
Implements: Clone, ComposeSchema, Copy, Debug, Eq, Hash, PartialEq, Serialize, ToSchema
pub enum MarkerKind {
Chapters,
Tracks,
Unknown,
}
What a store says its markers are.
Variants
Chapters: Literary chapters.Tracks: Track or part boundaries.Unknown: The store did not say.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum ProviderQuality {
StrongAccurate,
StrongEstimated,
Weak,
}
How a provider found the edition, and how exact its offsets are.
Variants
StrongAccurate: Found by a strong identifier; offsets marked exact.StrongEstimated: Found by a strong identifier; offsets estimated.Weak: Found by a weak identifier or a search.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum EventPruneStep {
ExpireUnleased,
TerminalDeliveries,
DeadLetters,
StaleSubscriberNodes,
EmptyEvents,
}
One delete of LibraryStore::prune_event_deliveries, in run order.
Variants
ExpireUnleased: Pending deliveries never leased within their retention period becomeexpired(seeLibraryStore::expire_unleased_event_deliveries).TerminalDeliveries: Acked, rejected and expired deliveries pastretention_days.DeadLetters: Dead letters pastdead_letter_retention_days.StaleSubscriberNodes: Per-node subscriber heartbeats past their TTL.EmptyEvents: Dispatched events pastretention_dayswith no deliveries left.
pub const ALL: [Self; 5] = _
Every step, in the order the deletes must run (deliveries before the events they belong to).
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum PinOutcome {
Moved { from: String },
Unchanged,
UnknownListing,
UnknownEdition,
}
What LibraryStore::pin_listing did.
Variants
Moved: The listing now sells the pinned edition; it soldfrombefore.from: The edition the listing left.
Unchanged: The listing already sold the pinned edition; the pin is recorded (or renewed) and nothing moved.UnknownListing: No listing has this id.UnknownEdition: No edition has this id.
Implements: Clone, Debug, Eq, PartialEq
pub enum DownloadStarter {
Host,
Person,
}
Who started a download, for the ledger.
Variants
Host: The host started it (auto-acquire, upgrades, acquire-all, requests from other libraries): held for the pace.Person: A person started it by hand: counted, never held.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum PlaybackEvent {
Started,
Progress,
Finished,
}
A host event about someone's listening, published after the write it
describes (LibraryStore::publish_playback_event).
Variants
Started: A play session opened (playback_started).Progress: A play session closed, or progress was set outright (playback_progress). The position syncs of a playing session publish nothing.Finished: The listener reached the end of an edition (playback_finished).
pub const ALL: [Self; 3] = _
Every event, in the order of a listen.
pub fn as_str(self) -> &'static str
The event type plugins subscribe to.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum PlayerKind {
Web,
Desktop,
App,
}
What kind of player opened a play session.
Variants
Web: The web app in a browser.Desktop: The desktop window's native engine.App: An outside player app, through the player API.
pub const ALL: [Self; 3] = _
Every kind, in stored order (the playback_sessions.client_kind
CHECK list).
pub fn as_str(self) -> &'static str
The stored spelling.
pub fn parse(stored: &str) -> Self
The kind a stored spelling names; Self::App for an unknown one.
Implements: Clone, Copy, Debug, Eq, From<PlayerKindParam>, Hash, Ord, PartialEq, PartialOrd
pub enum PlayerKindParam {
Web,
Desktop,
}
The kind of first-party player that opens a session. Outside player apps open theirs through the player API.
Variants
Web: The web app in a browser.Desktop: The desktop window.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, From<PlayerKindParam>, PartialEq, ToSchema
pub enum KvPutOutcome {
Written,
ValueTooLarge { len: usize, max: u32 },
KeyLimitReached { max: u32 },
}
Why a write was refused, so the binding can map it onto a wire code.
Variants
Written: The row was written.ValueTooLarge:valueexceedsmax_value_bytes.len: Bytes offered.max: Namespace cap.
KeyLimitReached: The namespace already holdsmax_keysother live keys.max: Namespace cap.
Implements: Clone, Debug, Eq, PartialEq
pub enum RecordPruneStep {
OidcAuthCodes,
OidcRefreshTokens,
PortalSessions,
ClaimTickets,
UserInvites,
EnrollmentLinks,
UploadSessions,
CopyGrants,
StorageScans,
SecurityAudit,
ConfigurationAudit,
ConfigurationChanges,
Notifications,
}
One delete of LibraryStore::prune_record_step, in run order.
Variants
OidcAuthCodes: OIDC authorization codes past their expiry (they are single-use and minutes long; consumed codes are refused byconsumed_atuntil then).OidcRefreshTokens: OIDC refresh tokens that expired or were revoked; neither is ever accepted again.PortalSessions: User portal sessions past their expiry.ClaimTickets: Claim tickets expired more thanTOKEN_HISTORY_DAYSago.UserInvites: User invites expired more thanTOKEN_HISTORY_DAYSago.EnrollmentLinks: Node enrollment links expired more thanTOKEN_HISTORY_DAYSago.UploadSessions: Committed or aborted uploads expired more thanUPLOAD_HISTORY_DAYSago.CopyGrants: Copy grants past their expiry; no download accepts one after it.StorageScans: Storage-scan generations whose job is terminal or gone, and jobless ones silent forSTORAGE_SCAN_STALE_DAYS, with their rows.SecurityAudit: Security audit events older thanAUDIT_RETENTION_DAYS.ConfigurationAudit: Configuration audit rows older thanAUDIT_RETENTION_DAYS.ConfigurationChanges: Configuration change notices older thanCONFIGURATION_CHANGE_RETENTION_DAYS.Notifications: Notifications older thancrate::notifications::NOTIFICATION_RETENTION_DAYS, with their inbox entries and delivery-log rows.
pub const ALL: [Self; 13] = _
Every step, in the order a maintenance pass runs them.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum FieldEdit<T> {
Keep,
Clear,
Set(T),
}
One field of a UserStateEdit.
Variants
Keep: Leave the stored value as it is.Clear: Remove the stored value.Set: Store this value.
Implements: Clone, Debug, Default, PartialEq
pub enum SplitOutcome {
Split { work_id: String },
UnknownWork,
BadCount,
NotOfWork(Vec<String>),
WouldEmpty,
}
What LibraryStore::split_work did.
Variants
Split: The expressions now belong towork_id, a new work.work_id: The new work.
UnknownWork: No work has this id.BadCount: No expression was named, or more thanMAX_SPLIT_EXPRESSIONS.NotOfWork: These named expressions are not the work's.WouldEmpty: The split would leave the work with no expression.
Implements: Clone, Debug, Eq, PartialEq
pub enum CopyState {
Stored,
Pending,
Failed,
Missing,
}
Where an edition's copy at one destination stands.
Variants
Stored: The destination holds the complete files.Pending: A write failed or the destination was unavailable; the copy is retried once its delay has passed.Failed: The copy failedMAX_COPY_ATTEMPTStimes in a row and is no longer retried on its own.Missing: The destination's file disappeared outside Bookclerk andoutput.missing_filesismark_missing: the copy is left alone until an acquire of the title writes it again.
pub const ALL: [Self; 4] = _
Every state, in stored order (the edition_copies.state CHECK list).
pub fn as_str(self) -> &'static str
The stored spelling.
pub fn parse(stored: &str) -> Option<Self>
The state a stored spelling names; None for one this build does
not know.
Implements: Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd
pub enum DiscoverSubject {
Operator,
User(i64),
Portal(i64),
}
Whose Discover shelves a stored row belongs to.
The same key as user_preferences.subject_key: the operator, a
first-party user, or a portal identity with no user.
Variants
Operator: The operator (token, session, or auth disabled); seeded from the household.User: A first-party user, byusers.id.Portal: A portal identity that has no first-party user, byportal_identities.id.
pub fn parse(key: &str) -> Option<Self>
Parses a stored subject key (operator, user:<id>, portal:<id>).
None for any other text, including a non-numeric or negative id.
pub fn key(&self) -> String
The subject's stored key, the inverse of Self::parse.
Implements: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd
pub enum FeedState {
Off,
Healthy,
Gap,
Failing,
}
The state of a destination's change feed.
Variants
Off: The destination's plugin has no change feed (or it is not turned on); scheduled listings alone notice outside changes.Healthy: The feed answered and said it missed nothing; listings run rarely.Gap: The feed said it may have missed changes; a listing runs at once.Failing: Reading the feed failed; a listing runs at once and the feed is tried again on the next pass.
pub const ALL: [Self; 4] = _
Every state, in stored order (the destination_feeds.feed_state
CHECK list).
pub fn as_str(self) -> &'static str
The stored spelling.
pub fn parse(stored: &str) -> Option<Self>
The state a stored spelling names; None for one this build does
not know.
Implements: Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd
pub enum FileOwner {
Edition(String),
}
Who a recorded file key belongs to.
Variants
Edition: An edition (editions.id): every holding of it shares the file.
pub fn kind(&self) -> &'static str
The stored owner_kind.
pub fn id(&self) -> &str
The stored owner_id.
Implements: Clone, Debug, Eq, Ord, PartialEq, PartialOrd
pub enum FileRole {
Audio,
Part,
Chapter,
Pdf,
Cover,
Sidecar,
Transcript,
Epub,
}
What a recorded file is.
Variants
Audio: The edition's primary audio file.Part: Another audio file of the edition: a part or a chapter file.Chapter: A chapter file of a title split by chapter.Pdf: The companion PDF.Cover: Cover art.Sidecar: Any other file beside the audio (.cue, chapter JSON, metadata).Transcript: A transcript or lyrics file.Epub: An EPUB.
pub const ALL: [Self; 8] = _
Every role, in stored order (the edition_files.role CHECK list).
pub fn as_str(self) -> &'static str
The stored spelling.
pub fn parse(stored: &str) -> Self
The role a stored spelling names; Self::Sidecar for an unknown
one, the role that gates nothing.
pub fn for_key(key: &str, primary: Option<&str>) -> Self
The role of the file at key, from its extension.
key- The storage key.primary- The edition's primary audio key, when known: another audio file is then aSelf::Part. Without it every audio file isSelf::Audio.
Implements: Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd
pub enum HoldingSelection<'a> {
Products(&'a [String]),
UnseenBy(&'a str),
All,
}
Which holdings of one account a removal takes.
Variants
Products: The account's holdings of these products of its plugin (a scan page'sremovedids).UnseenBy: The account's holdings that the scan passpass_iddid not list.All: Every holding of the account (it was revoked).
Implements: Clone, Debug, Eq, PartialEq
pub enum NodeHoldingSelection<'a> {
UnseenBy { pass: &'a str, fence: i64 },
All,
AllUnderFence(i64),
Replaced { ids: &'a [String], fence: i64 },
UnsharedBefore(&'a str),
}
Which holdings of one branch (node) a removal takes.
Variants
UnseenBy: The node's holdings its catalog passpass(the node'scatalog_pass_started_at) did not name, while that pass is still the node's andfencestill its catalog fence: a connection that resumes the pass keeps what it links, and ends the pass itself.pass: The catalog pass id.fence: The catalog fence of the batch that ended the pass.
All: Every holding of the node (it left or was revoked).AllUnderFence: Every holding of the node whilefenceis still the node's catalog fence (it stopped sharing under that fence): a newer connection that shares again keeps what it links.Replaced: These holdings of the node, by id (ones a title's newer holding replaced), whilefenceis still the node's catalog fence: a newer connection may have taken them up again.ids: The holdings' ids.fence: The catalog fence the replacing batch was written under.
UnsharedBefore: The node's holdings created before this stamp that still carry no share state: ones a catalog batch linked before finding its fence gone. A holding a live batch has given its share state since stays, and one newer than the stamp may belong to a batch still in flight.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum SeedScope {
Own,
Household,
}
Which seeds a subject's candidates and feed were built from.
Variants
Own: The subject's own books, listening, ratings and wishlist.Household: The whole household library, used while the subject has no taste of their own (and always for the operator).
pub fn as_str(self) -> &'static str
Wire and column text (own, household).
pub fn parse(text: &str) -> Option<Self>
Parses Self::as_str text; anything else is None.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub async fn migrate_library_backend(
source: &LibraryStore,
dest: &LibraryStore,
opts: &BackendMigrateOptions,
) -> Result<BackendMigrateSummary>
Copy the whole library from source into dest.
The destination should be empty unless BackendMigrateOptions::force is set.
Plugin artifacts are written first through the destination's own chunked
writer (they are content-addressed, so a second run rewrites nothing);
every other row is then copied in a single transaction on the
destination.
source- Existing library backend to read from.dest- Target backend to write into (must already be migrated).opts- Dry-run / force behavior.
Per-table row counts copied (or that would be copied when dry_run).
Returns LibraryError when the destination is non-empty without force,
or when any read/write fails.
pub async fn restore_backup_unit(
db: &DatabaseConnection,
repo: &BackupRepository,
unit: &BackupUnit,
kind: CanonicalRestoreKind,
opts: &CanonicalRestoreOpts,
preserve_plugin_registry: bool,
) -> Result<()>
Destructively replaces one logical database with unit. Never merges.
Verifies every referenced object before the first DROP. Plugin restore
rebuilds catalog companions from admitted SQL. It does not run plugin-owned
migrations. When preserve_plugin_registry is true, library restore does
not drop or replay plugin_databases (environment-local placement).
Row inserts are parameterized canonical Bookclerk SQL (? + typed
DbValue binds); adapters lower placeholders at the execute edge.
SQLite restore defers foreign keys on the restore transaction and runs
PRAGMA foreign_key_check before commit. It never toggles
PRAGMA foreign_keys on the pool connection.
Returns when validation fails, the adapter cannot provide complete unit replacement, a bind/payload/request budget is exceeded, or DDL/DML cannot be applied.
pub fn library_ddl_for_schema_state(state: &SchemaState) -> Result<String>
Library DDL that matches state, not necessarily this binary's latest pack.
Returns when the database is uninitialized, checksums do not match, or a frozen version is unknown to this binary.
pub fn sort_tables_by_foreign_keys(
tables: Vec<CanonicalTableSchema>,
) -> Result<Vec<CanonicalTableSchema>>
FK-safe table order (parents before children). Cycles fail closed.
Column-level REFERENCES and table-level FOREIGN KEY both count.
Self-references are ignored. References to tables outside this schema
are ignored. Ready nodes keep original declaration order so a child named
a_child that references z_parent still waits for the parent.
Returns when the FK graph contains a cycle.
pub fn verify_recovery_point(repo: &BackupRepository, id: &str) -> Result<ValidatedBackup>
Parses the manifest, rejects unsupported formats, and verifies every referenced object before the caller starts a destructive restore.
Returns when the manifest is malformed, an object is missing/corrupt, schema is not fully admitted, or typed cells violate the contract.
pub fn admit_canonical_schema(
sql_contract_version: u32,
sql: &str,
) -> Result<CanonicalDatabaseSchema>
Parses and fully admits a diagnostic/imported canonical SQL script.
Production capture, checksum, apply, and restore paths use already-separated
statement lists (admit_canonical_statements). This helper exists for
tests and imported scripts that still arrive as one packable string.
Returns when the packer rejects sql or any statement is not admitted.
pub fn admit_canonical_statements(
sql_contract_version: u32,
statements: &[&str],
) -> Result<CanonicalDatabaseSchema>
Admits already-separated canonical CREATE TABLE / CREATE INDEX statements.
Returns when any statement is not admitted Bookclerk SQL.
pub async fn apply_admitted_sql(
db: &DatabaseConnection,
statements: &[&str],
kind: CanonicalRestoreKind,
) -> Result<()>
Applies admitted canonical DDL plus binding companions (tests / bootstrap).
Returns when a statement fails.
pub fn archive_backup(files_dir: &Path, id: &str, dest: &Path) -> Result<()>
Packages one recovery point (manifest + referenced objects) as .tar.gz.
Returns when the destination cannot be written or objects are missing.
pub async fn backup_library(
db: &DatabaseConnection,
req: &BackupRequest,
) -> Result<Option<BackupOutcome>>
Writes a crash-safe recovery point under files_dir/backups/.
Skips only SchemaState::Uninitialized. The manifest is published only
after every referenced object exists. Pre-migrate backups prune older
automatic recovery points and garbage-collect unreferenced objects.
Manual backups are never auto-pruned.
Returns when the files dir cannot be written, capture fails, or a requested
plugin binding is missing from BackupRequest::plugin_units.
pub fn extract_backup_archive(archive: &Path, dest: &Path) -> Result<()>
Extracts a .tar.gz recovery-point archive into dest (a backups root).
Expansion is bounded by entry count, per-entry size, total expanded bytes, and gzip-decoded tar stream size so a small archive cannot fill the disk.
Returns when the archive is missing, malformed, a path escapes dest, or
an extract budget would be exceeded.
pub fn filter_library_pack_ddl(sql: &str) -> Result<String>
Library migration packs may include seed INSERTs. Those are table data
(captured from rows), not schema objects. This keeps admitted
CREATE TABLE / CREATE INDEX and skips seed DML. Any other statement
fails closed.
Returns when a non-empty statement is neither admitted DDL nor seed DML.
pub fn library_canonical_schema() -> Result<CanonicalDatabaseSchema>
Admitted library schema for this binary's current pack (frozen ups + unreleased).
Returns when current canonical SQL is not fully admitted.
pub fn library_canonical_schema_for_state(
state: &SchemaState,
) -> Result<CanonicalDatabaseSchema>
Admitted library schema for state.
Returns when DDL cannot be resolved or is not fully admitted.
pub fn list_backups(files_dir: &Path) -> Result<Vec<BackupListEntry>>
Lists published recovery points oldest-first.
Returns when the repository cannot be opened.
pub async fn plugin_canonical_schema_from_ddl_catalog(
db: &DatabaseConnection,
) -> Result<CanonicalDatabaseSchema>
Rebuilds plugin schema from durable bookclerk_sql_ddl on an open connection.
Returns when the DDL catalog is missing, incomplete, or malformed.
pub fn prune_automatic_backups(files_dir: &Path) -> Result<usize>
Deletes oldest automatic pre-migrate recovery points. Never deletes manual.
Returns when a manifest cannot be unlinked.
pub fn resolve_backup_spec(files_dir: &Path, spec: &str) -> Result<BackupResolve>
Resolves a recovery-point id, timestamp prefix, or archive path.
Returns when no complete backup matches or the spec is ambiguous.
pub async fn restore_backup(
db: &DatabaseConnection,
files_dir: &Path,
id: &str,
opts: &CanonicalRestoreOpts,
) -> Result<RestorePlan>
Restores the library unit after verifying all objects and units.
Plugin units are returned for the host/CLI to restore onto the target adapter. Restore replaces Bookclerk-visible schema for the library unit and does not merge or auto-migrate. Plugin-owned migrations are not run.
The library plugin_databases registry is preserved when the recovery
point carries no plugin units (including --include-plugin-databases with
an empty registry at capture). When plugin units are present, library
restore clears the registry so leftover bindings cannot outlive the
captured set; the host/CLI rebinds while restoring those units.
Returns when the backup is unsupported, an object is missing/corrupt, or library replace fails. Destructive SQL starts only after complete preflight.
pub async fn restore_backup_in_repo(
db: &DatabaseConnection,
repo: &BackupRepository,
id: &str,
opts: &CanonicalRestoreOpts,
) -> Result<RestorePlan>
Restores from an already-open repository (extracted archives).
Target crate::SchemaState is read from the canonical
bookclerk_schema_migrations rows. This function never infers a
versioning contract from sea_orm::DbBackend.
Same as restore_backup.
pub async fn apply_binding_bootstrap(db: &DatabaseConnection) -> Result<()>
Applies host-owned binding bootstrap when the binding is uninitialized.
Matching SchemaState::Unreleased is a no-op. Restore that rewrites
bookclerk_schema_migrations as ordinary rows will take this no-op path and will not
re-run plugin-owned DDL.
Returns when schema apply or the binding state machine fails closed.
pub fn binding_bootstrap_plan(state: &SchemaState) -> Result<Option<Vec<String>>>
Statements to apply for state, or None when the binding already matches.
Returns when state is a checksum/base mismatch or an unexpected frozen
binding (this binary has no frozen binding plan).
pub fn db_atomic_operation_id(op: &DbAtomicParams) -> String
Caller-owned idempotency key for an atomic attempt.
Consume-once keys are derived from the operation so an HTTP/RPC retry
resumes the same receipt. Claim redeem includes the session hash; callers
must derive that session from the ticket plus browser nonce (see
crate::derive_claim_session_token) so a new HTTP request after a lost
reply reuses this id. Other ops mint a UUID for this attempt.
pub fn db_atomic_request_hash(op: &DbAtomicParams) -> Result<String>
SHA-256 hex digest of the idempotency-relevant fields of op.
Claim redeem omits expires_at, client metadata, and the randomized Argon2
new_password_hash. Idempotency uses password_fingerprint (HMAC of the
plaintext password) so a retry with a fresh Argon2 salt still matches.
Returns an error when the operation fails.
pub async fn execute_db_atomic(
db: &DatabaseConnection,
compiled: CompiledAtomic,
) -> Result<DbAtomicResult>
Runs a compiled named atomic as one native SQL transaction.
Returns LibraryError for engine failures. Application outcomes
(lastOwner, empty, …) are returned as DbAtomicResult, not errors.
pub async fn execute_named_atomic(
db: &DatabaseConnection,
operation_id: &str,
params: &DbAtomicParams,
) -> Result<DbAtomicResult>
Compiles params and runs the plan as one native SQL transaction.
Returns LibraryError for engine failures or invalid named operations.
pub async fn apply_host_schema(db: &DatabaseConnection) -> Result<()>
Applies pending host-authored DDL from the canonical migration plan.
In-process adapters (sqlite tests, native postgres tests) infer the engine
from the opened connection. Production plugin-host uses
apply_host_schema_with_batch_opts so adapters lower canonical DDL after
RPC.
Returns LibraryError when a version read or DDL statement fails, the
database is newer than this binary, or a frozen checksum does not match.
pub async fn apply_host_schema_with_batch<F, Fut>(
db: &DatabaseConnection,
run_batch: F,
) -> Result<()>
where
F: FnMut(Vec<String>) -> Fut,
Fut: Future<Output = Result<()>>,
Applies schema using run_batch (typed executeAtomic) for each version.
Returns LibraryError when a version read, DDL statement, or batch fails.
pub async fn apply_host_schema_with_batch_opts<F, Fut>(
db: &DatabaseConnection,
opts: SchemaApplyOptions,
run_batch: F,
) -> Result<()>
where
F: FnMut(Vec<String>) -> Fut,
Fut: Future<Output = Result<()>>,
Applies schema with backups using run_batch for each version.
Returns LibraryError when a version read, backup, DDL, or batch fails.
pub async fn apply_host_schema_with_options(
db: &DatabaseConnection,
opts: SchemaApplyOptions,
) -> Result<()>
Applies pending host schema with optional in-place backups.
Returns LibraryError when a version read, backup, or DDL statement fails.
pub async fn current_schema_state(db: &DatabaseConnection) -> Result<SchemaState>
Reads explicit SchemaState in the Bookclerk host/bootstrap namespace.
An empty bookclerk_schema_migrations table is uninitialized; leftover SQLite
PRAGMA user_version is ignored.
Returns LibraryError::Schema on malformed, partial, or contradictory markers.
pub async fn current_schema_state_in(
db: &DatabaseConnection,
namespace: &str,
) -> Result<SchemaState>
Reads explicit SchemaState for one ledger namespace.
Host library and binding bootstrap use BOOKCLERK_SCHEMA_NAMESPACE.
Frozen checksums are verified against host_migration_plan only for
the Bookclerk namespace. Plugin-owned history uses bookclerk_plugin_migrations,
not this ledger.
Returns LibraryError::Schema on malformed, partial, or contradictory markers.
pub async fn current_schema_version(db: &DatabaseConnection) -> Result<i64>
Frozen revision when the database is SchemaState::Frozen; otherwise 0.
This is not a discriminator for uninitialized vs unreleased. Prefer
current_schema_state. 0 means “no frozen revision,” never “applied
development schema.”
Returns when the state query fails or the marker is malformed.
pub async fn ensure_restore_target_is_replaceable(db: &DatabaseConnection) -> Result<()>
Fails closed when this binary cannot interpret the target database's schema history well enough to drop every unknown table before restore.
Uninitialized targets are replaceable. Frozen history newer than this binary, unreleased checksums this binary does not know, and unreadable markers are not.
Returns LibraryError::Schema when the target is newer or uninterpretable.
pub async fn migrate_host_schema_to(
db: &DatabaseConnection,
target: i64,
opts: SchemaApplyOptions,
) -> Result<SchemaWalk>
Migrates toward target, including reversible downs for CLI rollback.
Returns LibraryError when the walk cannot start, a backup fails, or DDL fails.
A blocked downgrade still applies every reversible step and returns the walk
(the caller treats blocked / stopped_at != target as failure).
pub async fn migrate_host_schema_to_with_batch<F, Fut>(
db: &DatabaseConnection,
target: i64,
opts: SchemaApplyOptions,
run_batch: F,
) -> Result<SchemaWalk>
where
F: FnMut(Vec<String>) -> Fut,
Fut: Future<Output = Result<()>>,
Migrates toward target using run_batch (typed executeAtomic) per version.
A walk that writes anything (backup or DDL) runs under the
MIGRATION_LEASE library lease, like a start that migrates: it waits
up to MIGRATION_LEASE_WAIT for another migrator, renews the lease
while it works, and checks it before every DDL batch. A no-op walk only
checks the database and takes no lease.
Returns LibraryError when the walk cannot start, a backup fails, a
batch fails, another migrator holds the lease past the wait, or the lease
is lost mid-walk.
pub fn require_schema_migrations(caps: &DbCapabilities) -> Result<()>
Requires the schemaMigrations versioning contract from typed
bookclerk_plugin_abi::DbCapabilities.
The host always records versions in canonical bookclerk_schema_migrations
rows; canonical Bookclerk SQL is crate::migrations::current_canonical_schema
and adapters lower it for the live connection backend at execution. Plugin
identity and diagnostic engine names are not consulted.
Returns LibraryError::Other when schemaMigrations is missing.
pub fn schema_state_compatible(state: &SchemaState) -> bool
True when state is exactly the schema this binary applies: a start
against it neither migrates nor fails closed.
pub async fn apply_plugin_migrations(
db: &DatabaseConnection,
registered: &PluginMigrationSequence,
) -> Result<PluginMigrationHistory>
Applies the pending registered suffix. Idempotent when history already matches.
Outer loop walks durable history (exact-prefix). Each pending migration is
one short atomic unit: serialization-slot mutation + plugin operations +
journal append, with a bounded inner retry loop that does not consume
later migration capacity. There is no lock held across those independent
transactions. Concurrent hosts re-read durable history before applying;
uniqueness / conflict / an ambiguous reply causes another journal read.
Matching (id, checksum) at the expected ordinal is success.
Contradictory history fails closed.
Returns when prefix verification fails, apply exhausts retries, or the journal is contradictory.
pub fn history_from_execute_reply(reply: &ExecuteReply) -> Result<PluginMigrationHistory>
Parses journal rows from a typed select reply.
Returns when row shape or ordinals are invalid.
pub async fn load_plugin_migration_history(
db: &DatabaseConnection,
) -> Result<PluginMigrationHistory>
Reads the host-private plugin migration journal.
Returns when the journal cannot be read or ordinals are not contiguous.
pub fn next_pending_plugin_migration<'a>(
history: &PluginMigrationHistory,
registered: &'a PluginMigrationSequence,
) -> Result<Option<(usize, &'a ProvenPluginMigration)>>
Next registered migration after a verified durable prefix, if any.
Uses require_history_prefix then indexes registered[history.len()]
rather than rebuilding the pending suffix vector.
Returns require_history_prefix errors.
pub fn plugin_apply_statements(
ordinal: i64,
migration: &ProvenPluginMigration,
) -> Vec<String>
One atomic apply unit: serialization slot, registered ops, host journal append.
pub fn plugin_binding_type_env(
registered: &PluginMigrationSequence,
applied: usize,
) -> SqlTypeEnv
Binding catalog after host bootstrap plus schema ops from the first applied
registered migrations.
Plugin apply stamps journal DML and suffix data ops against this evolving
environment. applied is the durable prefix length (host-private ordinal
count), not a plugin version.
pub fn plugin_history_session_matches(
expected_digest: &str,
observed: &PluginMigrationHistory,
) -> Result<()>
True when a binding session's captured history digest still matches durable history.
Returns when the digest differs (peer advanced or rewritten history).
pub fn plugin_journal_has_entry(
history: &PluginMigrationHistory,
ordinal: i64,
id: &str,
checksum: &str,
) -> bool
True when history already contains this (ordinal, id, checksum) row.
pub fn plugin_journal_select_request(
operation_id: impl Into<String>,
deadline_unix_ms: u64,
) -> ExecuteRequest
Typed SELECT used by RPC hosts to read the plugin migration journal.
pub fn prove_plugin_migration_sequence(
migrations: Vec<PluginMigration>,
) -> Result<PluginMigrationSequence>
Proves a complete registration with one evolving SqlTypeEnv.
Schema operations update the environment. Data operations typecheck against the current environment. The environment is not reset between migrations.
Returns when resource limits are exceeded, an id is invalid, ids repeat,
an operation is empty/malformed, or BookclerkSQL proof fails.
Transport/resource validation is
bookclerk_plugin_abi::require_plugin_migration_registration;
this function is the authoritative semantic proof afterward.
pub fn require_history_prefix(
history: &PluginMigrationHistory,
registered: &PluginMigrationSequence,
) -> Result<()>
Fail closed unless durable history is an exact prefix of registered.
Returns when an applied id/checksum/order does not match, or durable history is longer than the current registration (older/incompatible plugin).
pub fn sql_string_literal(value: &str) -> String
SQL string literal with ' doubled.
pub fn branch_request_dedup_key(node_id: &str, work_id: &str) -> String
Dedup key of a [JobKind::BranchRequest]: one active request per
(branch node, work).
pub fn catalog_subscribers_for_event(
catalog: &[EventSubscriberCatalogRecord],
event: &DomainEventRecord,
) -> Vec<EventSubscriber>
Enabled catalog rows that match event type, schema version, and filter.
pub fn collapse_live_subscriber_nodes(
rows: &[EventSubscriberNodeRecord],
) -> Vec<EventSubscriberCatalogRecord>
Collapse live per-node rows into one catalog record per plugin_id.
enabled is true when any live row is enabled. Subscriptions are the union
of enabled live rows (disabled nodes do not contribute filters).
pub fn content_kind_from_classic(content_type: i64) -> String
Map classic EF ContentType to bookclerk content_kind.
pub fn content_kind_to_classic(content_kind: &str) -> i32
Classic EF ContentType enum value.
pub fn event_filter_matches(filter: Option<&Value>, payload_json: &str) -> bool
True when filter is absent/empty or every filter key equals the payload object value.
pub fn event_matches_wake_grants(
grants_json: &str,
legacy_filter_json: &str,
schema_version: i64,
payload: &str,
) -> bool
True when an event matches persisted wake grants, or legacy type+filter rows.
pub fn intersect_event_filters(
declared: Option<&Value>,
requested: Option<&Value>,
) -> Option<Value>
Merge declared and requested payload filters; None on a same-key conflict.
pub fn is_downloadable(content_kind: &str) -> bool
True when the title can be downloaded (classic WithoutParents).
pub fn is_valid_queue_name(name: &str) -> bool
True when name is [a-z0-9][a-z0-9._-]* and at most MAX_QUEUE_NAME_LEN chars.
Host-reserved names (core.events, node.<id>) satisfy this grammar; the
manifest validator, not the outbox, keeps plugins off those prefixes.
pub fn job_backoff_run_after(attempt_count: i64, now: DateTime<Utc>) -> DateTime<Utc>
Next run_after after a failed attempt, exponential from a 5s base (capped).
pub fn normalize_theme(raw: &str) -> String
Canonical appearance preference; unknown values become system.
pub fn plugin_scheduled_dedup_key(plugin_instance_id: &str, cron: &str) -> String
Dedup key of a JobKind::PluginScheduled fire: one active fire per
(instance, cron).
pub fn portal_prefs_key(identity_id: i64) -> String
Subject key for a portal identity (legacy; prefer user_prefs_key).
pub fn push_queue_wisher(wishers: &mut Vec<QueueWisher>, wisher: QueueWisher)
Adds wisher when they are not already present (capped at MAX_QUEUE_WISHERS).
Duplicate people keep the richer picture and name fields.
wishers- Accumulated people for this work.wisher- Person who has this title on an open wishlist.
pub fn queue_name_or_bus(name: &str) -> &str
Resolves an optional queue name: empty means CORE_EVENTS_QUEUE.
pub fn subscription_matches_event(
sub: &EventCatalogSubscription,
event: &DomainEventRecord,
) -> bool
True when one catalog subscription matches event type, schema, class, and filter.
pub fn user_prefs_key(user_id: i64) -> String
Subject key for a first-party user.
pub fn wake_grants_from_subscriptions(
subs: &[EventCatalogSubscription],
wake_type: &str,
requested_filter_json: &str,
) -> Result<Vec<EventWakeGrant>, &'static str>
Build wake grants from declared subscriptions for wake_type.
Empty wake_type yields no grants (timestamp-only). A type with no matching
subscription returns "wake event type not subscribed". When every matching
subscription conflicts with the requested filter, returns
"wake filter not within subscription".
Returns a static reason when the type is undeclared or the requested filter cannot intersect any declared filter.
pub fn plan_schema_walk(
plan: &[HostMigrationStep],
from: i64,
to: i64,
) -> Result<SchemaWalk>
Plans ups or downs from from toward to using plan.
Downgrades walk newest-first and stop at the last reversible version when
the next step has down: None. Versions newer than the compiled plan
cannot be reversed by this binary. Versions older than the first frozen
step in plan (except empty from == 0) cannot be upgraded by this
binary. An empty plan means no frozen schema versions exist.
Returns LibraryError::Schema when to is below zero, from is ahead
of every compiled step (unknown newer schema), or from is below the
plan's first retained frozen version.
pub fn plan_schema_walk_from_state(
plan: &[HostMigrationStep],
state: &SchemaState,
to: i64,
) -> Result<SchemaWalk>
Plans a frozen walk from an explicit SchemaState.
SchemaState::Unreleased is never treated as empty from == 0. A future
freeze must not apply version-1 ups on top of an unreleased development
database — recreate (cargo reset --yes) unless a later explicit promote
path is added.
Returns LibraryError::Schema when an unreleased database is asked to
become a frozen revision, or when plan_schema_walk fails.
pub fn classify_session_client(
user_agent: Option<&str>,
is_api: bool,
) -> SessionClientInfo
Classify a User-Agent (or missing UA for API/bearer clients).
user_agent- OptionalUser-Agentheader value.is_api- When true (no browser UA / bearer-style client), label as API.
Panics when an internal invariant does not hold.
pub fn compile_claim_event_delivery(
operation_id: &str,
delivery_id: &str,
owner: &str,
lease_secs: i64,
plugin_id: &str,
resource_class: &str,
max_in_flight: i64,
now: &str,
) -> Result<CompiledAtomic, DbErr>
Compiles a host-side CAS claim for one pending event_deliveries row.
Returns DbErr::Custom when wrapping the plan fails.
pub fn compile_named_request(
operation_id: &str,
params: &DbAtomicParams,
now: &str,
) -> Result<CompiledAtomic, DbErr>
Compiles a named atomic request into canonical Bookclerk SQL.
Adapters lower placeholders and functions at execute time.
Returns DbErr::Custom when the named operation is missing or invalid.
pub fn interpret_typed_exec(
compiled: &CompiledAtomic,
reply: &ExecuteReply,
expected_hash: &str,
) -> DbAtomicResult
Maps a typed ExecuteReply onto a host DbAtomicResult.
pub fn validate_execute_reply(
req: &ExecuteRequest,
reply: &ExecuteReply,
caps: &DbCapabilities,
) -> Result<()>
Rejects a guest ExecuteReply that does not echo the sent request or
exceeds negotiated caps.
A mismatch after the guest reports success is treated as
LibraryError::Unavailable so callers retry the same operationId
rather than interpreting a truncated or mismatched envelope.
Returns LibraryError::Unavailable when the echo, statement count or
result selection shape does not match the request, and
LibraryError::LimitExceeded when a statement result or the whole
reply exceeds a negotiated cap (maxResultRows, maxCellBytes,
maxResultBytes, maxAtomicResultBytes). A reply read as a stream is
validated with validate_streamed_execute_reply instead.
pub fn validate_streamed_execute_reply(
req: &ExecuteRequest,
reply: &ExecuteReply,
caps: &DbCapabilities,
) -> Result<()>
validate_execute_reply for a reply reassembled from
executeStreamed frames.
caps are the streamed caps (DbCapabilities::streamed), so the
byte budgets are the streamed budget and an exceeded one is reported
as maxStreamedResultBytes whatever its size, which keeps a caller
from retrying the same read in inline pieces.
pub fn facet_key(value: &str) -> String
The key a facet value or tag is stored and matched under: trimmed and lower-cased, so "Fantasy" and "fantasy " are one value.
value- A value as shown or as a client sent it.
pub fn sort_title(title: &str) -> String
The sort key of a title: lower case, with one leading English article dropped, so "The Hobbit" sorts under h.
title- The display title.
pub fn normalize_work_tags(values: &[String]) -> Result<Vec<(String, String)>>
Trims, drops empties and duplicates (by facet_key, first spelling
kept) and checks the bounds.
Returns LibraryError::Invalid for more than MAX_WORK_TAGS tags or
a tag longer than MAX_WORK_TAG_BYTES.
pub fn parse_work_tags_request(body: &[u8]) -> Result<WorkTagsRequest>
Parses and validates a PUT /api/library/works/{id}/tags body from its
raw bytes, sans IO, the way the route reads it: JSON into
WorkTagsBody, then WorkTagsBody::validate.
Returns LibraryError::Invalid for bytes that are not the body's JSON
shape (unknown or repeated fields, wrong types, a missing field, an
array instead of an object) or tags outside the bounds.
pub fn apply_user_states(
titles: &mut [TasteTitle],
states: &[UserTitleState],
users: &[i64],
)
Applies the state of users to titles, merged per work.
A work is finished when any of the users finished it; each rating is
the mean of the users who gave one; tags are the users' tags joined,
each tag once. A title without state from any of users keeps the
unfinished, unrated, untagged default. users empty means every user
whose state is in states (the household).
titles- Titles to fill, asLibraryStore::taste_titlesreturns them.states- Stored state rows for the titles' works.users- Whose state counts; empty for everyone's.
pub fn resolve_chapters(claims: &[ChapterClaim]) -> Option<&ChapterClaim>
Picks the claim an edition's chapters resolve to.
In order: the claim an Administrator pinned; the newest edit made in
Bookclerk; the newest outside edit; then the best machine source by
the chapters machine ranking (docs/adr/edition-chapters.md, decision
2), ties broken by source id. A claim whose list write is
unfinished is never picked, and an empty list is picked only from a
person, who cleared the chapters on purpose. The answer depends only on
the claims, never on the order they are given in.
pub fn parse_chapter_edit_request(body: &[u8]) -> Result<ChapterList>
Parses and checks a chapter edit body from its raw bytes, sans IO, the way the route reads it.
Returns LibraryError::Invalid for a body over
MAX_CHAPTER_EDIT_BYTES, bytes that are not the body's JSON shape, or
chapters that break a rule: more than MAX_CHAPTERS, a title that is
empty, padded, over MAX_CHAPTER_TITLE_BYTES or holds a control
character, a start past MAX_CHAPTER_START_MS or before the one
above, or a depth that skips a level or passes MAX_CHAPTER_DEPTH.
pub fn parse_chapter_pin_request(body: &[u8]) -> Result<ChapterPinRequest>
Parses and checks a pin body from its raw bytes, sans IO.
Returns LibraryError::Invalid for a body over
MAX_CHAPTER_PIN_BYTES, bytes that are not the body's JSON shape, an
unknown source kind, or a source id ChapterPinBody::validate
refuses.
pub fn copy_retry_delay(attempts: u32) -> Duration
The delay before the next background attempt of a copy that has now
failed attempts times (1 for the first failure):
COPY_RETRY_BASE_DELAY doubled per earlier failure, capped at
COPY_RETRY_MAX_DELAY.
pub fn deliver_after_for(spec: &PublishDomainEventSpec, now: &str) -> String
RFC 3339 earliest delivery time for spec; empty when it may deliver now.
pub fn prepare_publish_domain_event(
spec: PublishDomainEventSpec,
) -> Result<PublishDomainEventSpec>
Mint an event id when empty and reject oversized or blank publish fields.
Returns LibraryError::Other when the payload exceeds 64 KiB, when
dedup_key is blank, when a domain event (bus row) has no event_type
or a queue message has one, when the queue name or content type is not
recognised, or when source is not empty and fails the source grammar.
pub fn fallback_work_key(
title: &str,
authors: Option<&str>,
asin: Option<&str>,
isbn: Option<&str>,
) -> String
Local fallback when callers do not supply a discover work_map_key.
Converts ISBN-10 → ISBN-13 when possible so 10/13 variants share a key. Soft keys here are a simple lowercase fallback — Discover re-merges with richer identity matching when ranking the global queue.
pub fn inject_dispatch_page_failures(n: u32)
Fail after the next n successful dispatch pages (tests only).
pub fn call_number(edition_id: &str) -> Option<String>
The <call number> of edition edition_id: its first 40 bits as 8
lower-case Crockford base32 characters (no i, l, o or u). An id
that is not a UUID falls back to its first 8 ASCII letters and digits.
Returns None when that leaves nothing.
pub fn edition_id_for_listing(key: &ListingKey) -> String
The id of an edition first seen through the store listing key: a
version 5 UUID over its plugin key, marketplace and product id. Two
nodes (or one library rebuilt from a fresh scan) that resolve the same
listing first give its edition the same id, and so the same
<call number> in file names.
pub fn holding_from_book(book: &NewBook) -> HoldingDraft
The holding a flat library row describes.
pub fn listing_from_book(book: &NewBook) -> Result<Listing, ListingError>
The structured listing a flat library row describes, for paths that
only have a NewBook (imports, seeds, tests).
Scans that carry a plugin's structured record use that instead.
Returns resolve::ListingError when the row fails listing validation.
pub fn reaches_end(position: PlaybackMs, duration: PlaybackMs) -> bool
True when position in a recording duration long counts as having
reached its end: within the last one percent, or within the last
thirty seconds of a recording longer than a minute.
position- Where the listener is.duration- The recording's whole runtime; a zero duration is unknown and never finished.
pub fn parse_bookmark_edit_request(body: &[u8]) -> Result<BookmarkEditRequest>
Parses and validates a PUT /api/playback/bookmarks/{id} body from
its raw bytes, sans IO.
Returns LibraryError::Invalid for a body over
MAX_PLAYBACK_BODY_BYTES, bytes that are not the body's JSON shape,
a position past MAX_PLAYBACK_MS or a refused title.
pub fn parse_new_bookmark_request(body: &[u8]) -> Result<NewBookmarkRequest>
Parses and validates a POST /api/library/editions/{id}/bookmarks
body from its raw bytes, sans IO.
Returns LibraryError::Invalid for a body over
MAX_PLAYBACK_BODY_BYTES, bytes that are not the body's JSON shape,
a position past MAX_PLAYBACK_MS or a refused title.
pub fn parse_open_session_request(body: &[u8]) -> Result<OpenSessionRequest>
Parses and validates a POST /api/playback/sessions body from its raw
bytes, sans IO: JSON into OpenSessionBody, then
OpenSessionBody::validate.
Returns LibraryError::Invalid for a body over
MAX_PLAYBACK_BODY_BYTES, bytes that are not the body's JSON shape
(unknown or repeated fields, wrong types, a missing edition_id, an
unknown player, an array instead of an object) or an edition id that
is empty or too long.
pub fn parse_playback_sync_request(body: &[u8], close: bool) -> Result<PlaybackSync>
Parses and validates a sync or close body from its raw bytes, sans IO,
the way the routes read it: JSON into PlaybackSyncBody, then
PlaybackSyncBody::validate.
body- The request body.close- True for thecloseroute.
Returns LibraryError::Invalid for a body over
MAX_PLAYBACK_SYNC_BYTES, bytes that are not the body's JSON shape
(unknown or repeated fields, wrong types, a missing position_ms, an
array instead of an object) or a length past MAX_PLAYBACK_MS.
pub fn parse_progress_cursor(token: &str) -> Option<ProgressCursor>
Parses the cursor of GET /api/playback/progress, sans IO.
token- The query value as sent.
None unless token is at most MAX_PROGRESS_CURSOR_BYTES of
canonical unpadded URL-safe Base64 that decodes to UTF-8 text of a
change time (see progress_cursor_token), a | and an edition id
of 1 to MAX_EDITION_ID_BYTES bytes. An accepted token is exactly
what progress_cursor_token writes for the cursor it yields.
pub fn parse_progress_edit_request(body: &[u8]) -> Result<PlaybackProgressEdit>
Parses and validates a PUT /api/playback/progress/{edition_id} body
from its raw bytes, sans IO.
Returns LibraryError::Invalid for a body over
MAX_PLAYBACK_BODY_BYTES, bytes that are not the body's JSON shape
or a length past MAX_PLAYBACK_MS.
pub fn parse_track_path(session_id: &str, index: &str) -> Option<TrackPath>
Parses the two path parts of
GET /api/playback/sessions/{id}/tracks/{n}, sans IO.
session_id- The{id}part as sent.index- The{n}part as sent.
None unless session_id is a UUID in its canonical spelling (36
bytes, lowercase, hyphenated) and index is a decimal number below
MAX_PLAYBACK_TRACKS written with ASCII digits only and no leading
zero. Anything else names no session or track, and the route answers
404 without reading the library.
pub fn progress_cursor_token(cursor: &ProgressCursor) -> String
The opaque token of a progress cursor: unpadded URL-safe Base64 of
the row's change time, a |, and its edition id.
pub fn plan_pass(state: Option<&ScanState>, now: DateTime<Utc>) -> PassStart
Decides how the next pass of an account starts.
A stopped pass whose cursor is younger than RESUME_CURSOR_TTL resumes
with the token and pass id it started with (a row without a pass id
starts over, since its earlier pages stamped no holdings). Otherwise a pass starts from the
beginning, as a delta from the stored token unless no complete pass ended
within FULL_PASS_INTERVAL, in which case it is full.
state- The stored row,Nonebefore the account's first pass.now- The current time.
pub fn set_dispatch_chunk_for_test(chunk: Option<usize>)
Override subscribers-per-plan for dispatch paging tests.
pub fn parse_work_split_request(body: &[u8]) -> Result<WorkSplitRequest>
Parses and validates a POST /api/library/works/{id}/split body from
its raw bytes, sans IO, the way the route reads it: JSON into
WorkSplitBody, then WorkSplitBody::validate.
Returns LibraryError::Invalid for bytes that are not the body's JSON
shape (unknown or repeated fields, wrong types, a missing field, an
array instead of an object) or ids outside the bounds.
pub fn derive_claim_password_fingerprint(
dek: &MasterKey,
nonce: &str,
password: &str,
) -> String
Stable, non-secret fingerprint of an invite/reset password for idempotency.
Argon2id storage hashes use a fresh salt on every POST, so they cannot be
the atomic request hash. This value is
HMAC-SHA256(subkey, nonce || 0x00 || password) where
subkey = HMAC-SHA256(DEK, "bookclerk-claim-password-subkey-v1").
The randomized Argon2id hash is still what gets stored on the user row.
pub fn derive_claim_session_token(
dek: &MasterKey,
raw_ticket: &str,
nonce: &str,
) -> String
Derive the portal session token for a claim ticket plus browser nonce.
The raw session is
HMAC-SHA256(DEK, "bookclerk-claim-session-v1:" || ticket || 0x00 || nonce)
hex-encoded (64 characters). The same ticket, nonce, and process DEK always
yield the same session, so a browser retry after a lost atomic reply
reuses redeemClaimTicket:{token}:{session}. A different nonce (another
browser, or the magic link alone) cannot replay that receipt. The plaintext
bearer is never written to a receipt; only hash_token of this value is
stored.
dek- Process data-encryption key fromcrate::require_master_key.raw_ticket- Plaintext claim ticket from the SPA / share URL.nonce- Validated 64-hex redeem nonce fromparse_claim_redeem_nonce.
pub fn hash_token(raw: &str) -> String
SHA-256 hex digest of a raw ticket/session token for durable storage.
raw- Opaque plaintext token; callers must not persist this value.
Lowercase hex SHA-256 digest (64 characters).
pub fn parse_claim_redeem_nonce(raw: &str) -> Result<&str>
Accept a browser-generated claim-redeem nonce.
The SPA persists a 32-byte random value as 64 hex characters across HTTP
retries (sessionStorage). Possession of the used magic-link URL without
this nonce cannot recover the committed session.
Returns an error when the value is missing, the wrong length, or not hex.
pub fn apply_merged_sources(row: &mut TitleRequestRecord)
Apply merged bib / editions / hints onto a wishlist row from its source snapshots.
Updates row in place from row.sources, clearing merged fields when no
sources remain.
row- Wishlist title-request record whosesourcessnapshots are merged.
pub fn pick_better_description(a: Option<&str>, b: Option<&str>) -> Option<String>
Prefer HTML blurbs over plain text; otherwise the longer string wins.
a- First candidate description (may be HTML or plain).b- Second candidate description.
The richer non-empty description, or None when both are empty.
pub type Result<T> = Result<T, LibraryError>;
Result alias for LibraryError.
pub type InProcessSqliteAtomic = NamedAtomicBackend<InProcessSqlite>;
The crate::AtomicTxnBackend over a local SQLite connection.
pub const LEFT_BEHIND_TABLES: &[(&str, &str)] = _;
Tables the copy leaves behind on purpose, each with the reason.
Every other table of the library schema is copied; a test checks that the two lists together cover the schema.
pub const CHUNK_TARGET_UNCOMPRESSED_BYTES: usize = _;
Target uncompressed JSON size for one table-data chunk.
256 KiB sits in a 128–512 KiB band: large enough to avoid pathological
per-object overhead on typical catalog rows, small enough for a small-VPS
working set and for maxResultBytes paging. A single row larger than the
target still occupies its own chunk.
pub const BACKUPS_DIR: &str = "backups";
Subdirectory of $BOOKCLERK_FILES_DIR holding the backup repository.
pub const BACKUP_FORMAT_VERSION: u32 = 1;
Manifest format written by this binary.
pub const BACKUP_RETENTION: usize = 5;
Automatic pre-migrate recovery points retained after prune.
pub const LIBRARY_SKIP_TABLES: &[&str] = _;
Library registry rows are environment-local (unit_ref is not portable).
pub const MIGRATION_LEASE_TTL: Duration = _;
How long a schema migration lease lasts without renewal. The migrator renews it every third of this while it works.
pub const MIGRATION_LEASE_WAIT: Duration = _;
How long a starter waits for another starter's migration before it fails
closed. Longer than MIGRATION_LEASE_TTL, so a migrator that died is
replaced by a waiter rather than failing every waiter.
pub const BOOKCLERK_SCHEMA_NAMESPACE: &str = "bookclerk";
Ledger namespace for host library schema and Bookclerk-owned binding bootstrap.
pub const MAX_PLUGIN_MIGRATION_APPLY_ATTEMPTS: usize = 8;
Bounded retries for one expected plugin migration apply unit.
Independent of how many migrations are registered. A fresh binding may
apply the complete registration; this only caps retries of a single
expected (ordinal, id, checksum) while durable history is unchanged.
pub const CORE_EVENTS_QUEUE: &str = "core.events";
Queue that carries the domain-event bus ([events] producers and consumers).
pub const EDITION_ACQUIRE_CHANGED: &str = "edition_acquire_changed";
Host event type published with an edition's acquire state change other
than becoming acquired (payload editionId, titleId, status).
pub const EVENT_DELIVERY_DEFAULT_RETENTION_SECS: u32 = 86_400;
How long a delivery may wait, due but never leased, before the host
expires it when its consumer declares no message_retention_period: one
day. A consumer that is deployed but not running stops accumulating work
after this, and catches up through the event stream instead.
pub const EVENT_DELIVERY_MAX_ATTEMPTS: i64 = 8;
Default max delivery attempts before dead-letter.
pub const EVENT_RESOURCE_CLASS_NETWORK: &str = "network";
Default delivery resource class (network).
pub const EVENT_SUBSCRIBER_HEARTBEAT_TTL_SECS: i64 = 60;
Live catalog rows quieter than this many seconds are ignored at dispatch.
pub const HOST_CONSUMER_PREFIX: &str = "host:";
Prefix of subscriber ids the daemon itself consumes under (host:discover,
host:search-index:<node>). Their deliveries never expire.
pub const INGEST_BATCH_FINISHED: &str = "ingest_batch_finished";
Host event type published when an ingest batch (an upload or a storage
intake) reaches a final state (payload batchId, state, source,
intakeInstance, detail).
pub const JOB_PAYLOAD_VERSION: u32 = 1;
Current job command envelope version stored in JobPayload::v.
pub const LISTENING_SYNCED: &str = "listening_synced";
Host event published when a listening sync changed what Discover reads from a stored row: its owner, matched book or work, authors, or how far they got (started, quarter, finished).
Payload: provider (the integration that synced) and identityIds (the
portal identities whose rows changed, before or after; rows not tied to
an identity are not listed).
pub const MAX_QUEUE_NAME_LEN: usize = 63;
Longest queue name.
pub const MAX_QUEUE_WISHERS: usize = 16;
Maximum distinct people serialized on a global-queue or Discover card.
pub const NODE_QUEUE_PREFIX: &str = "node.";
Prefix of the per-node queues (node.<node_id>) node subsystems consume.
pub const OPERATOR_PREFS_KEY: &str = "operator";
Subject key for the shared operator account.
pub const QUEUE_CONTENT_TYPE_BYTES: &str = "bytes";
Queue message body is raw bytes stored as base64 text.
pub const QUEUE_CONTENT_TYPE_JSON: &str = "json";
Queue message body is UTF-8 JSON text.
pub const QUEUE_CONTENT_TYPE_TEXT: &str = "text";
Queue message body is plain UTF-8 text.
pub const WISHLIST_CHANGED: &str = "wishlist_changed";
Host event published when a wishlist entry is added or changes status, or an open entry is deleted with its user.
Payload: requestId (the entry's uuid), identityId (the portal identity
that wished for it, or null) and status after the write (open,
cancelled, or deleted).
pub const SCHEMA_STATE_FROZEN: &str = "frozen";
On-disk bookclerk_schema_migrations.state for a frozen plan version.
pub const SCHEMA_STATE_UNRELEASED: &str = "unreleased";
On-disk bookclerk_schema_migrations.state for an unreleased development pack.
pub const EVENT_STREAM_SCAN_FACTOR: usize = 8;
Rows one LibraryStore::read_event_stream call may examine per event
it may return.
pub const EVENT_STREAM_SETTLE_SECS: u64 = 30;
Seconds an outbox row must age before LibraryStore::read_event_stream
returns it. created_at is stamped before the insert commits, so a
publication can commit after a newer one; a read that stops short of the
last few seconds never moves its cursor past a row that has yet to
appear. Newer events still reach subscribers through delivery.
pub const LIBRARY_INDEX_LAYOUT: i64 = 2;
Layout of library_work_rows this binary writes. A library with no
finished build of this layout is rebuilt; bump it when a change to how
rows are derived needs every row rewritten.
- 2: every work with an edition names a cover edition, whose cover may come from a store listing or the work, so libraries indexed under 1 (no cover edition unless the edition row had a cover) are rebuilt.
pub const MAX_WORK_TAGS: usize = 32;
Most tags an Administrator may set on one work. With the delete this fits one batch of the smallest statement count a database plugin may advertise (40).
pub const MAX_WORK_TAG_BYTES: usize = 256;
Longest tag, in UTF-8 bytes after trimming: the longest value the page index keeps under a facet, and the longest value a scope rule matches.
pub const CATALOG_LISTING_REFRESH: Duration = _;
How long a catalog listing counts as current: a store answer for a listing seen more recently than this refreshes only its prices, not its resolution or text, so overlapping tastes cost one resolve a day.
pub const MAX_CHAPTERS: usize = 2000;
Most chapters one list holds, the same cap as a metadata file's
(maxMetadataFileChapters in plugin.capnp).
pub const MAX_CHAPTER_DEPTH: u32 = 7;
Deepest nesting stored; 0 is a top-level chapter. A machine source's deeper chapter is lifted to this depth; an edit's is refused.
pub const MAX_CHAPTER_START_MS: u64 = crate::store::playback::MAX_PLAYBACK_MS;
Latest chapter start stored, in milliseconds: sixty days, the playback
core's longest position (crate::MAX_PLAYBACK_MS).
pub const MAX_CHAPTER_TITLE_BYTES: usize = 512;
Longest chapter title stored, in UTF-8 bytes. A machine source's longer title is cut at a character boundary; an edit's is refused.
pub const MAX_CHAPTER_EDIT_BYTES: usize = _;
Largest chapter edit body the route reads, in bytes: room for
MAX_CHAPTERS chapters with titles at MAX_CHAPTER_TITLE_BYTES,
some of them escaped.
pub const MAX_CHAPTER_PIN_BYTES: usize = 1024;
Largest pin body the route reads, in bytes.
pub const MAX_CHAPTER_SOURCE_ID_BYTES: usize = 256;
Longest source_id a pin names, in bytes; a PluginKey is far shorter.
pub const MAX_CONFLICT_PAGE: u64 = 200;
Largest conflicts page LibraryStore::list_resolution_conflicts reads.
pub const MAX_BOOKMARKS_PER_EDITION: u64 = 200;
Most bookmarks one person keeps in one edition.
pub const MAX_BOOKMARK_TITLE_BYTES: usize = 200;
Longest bookmark title, in bytes (well inside the minimum database profile's cell size).
pub const MAX_PLAYBACK_MS: u64 = _;
The longest position or duration the player stores: sixty days, far past any recording, and small enough that sums of two stay exact in every database profile's integer.
pub const MAX_PLAYER_NAME_BYTES: usize = 64;
Longest player name a session stores, in bytes.
pub const MAX_EDITION_ID_BYTES: usize = 128;
Longest edition id a session is opened for, in bytes; a real one is a 36-byte UUID.
pub const MAX_PLAYBACK_BODY_BYTES: usize = 4096;
Largest body the other playback parsers read, in bytes: room for an escaped bookmark title or a long player name.
pub const MAX_PLAYBACK_SYNC_BYTES: usize = 1024;
Largest sync body the routes read, in bytes; a real one is under 100.
pub const MAX_PLAYBACK_TRACKS: usize = 512;
Most tracks a play session lists: a stream path's index is below it.
pub const MAX_PROGRESS_CURSOR_BYTES: usize = 256;
Longest progress cursor token the route reads, in bytes; a real one is about 100.
pub const MAX_PLAYER_PASSWORDS: u64 = 20;
Most player passwords one patron keeps.
pub const MAX_PLAYER_PASSWORD_LABEL_BYTES: usize = 64;
Longest player password label, in bytes.
pub const PLAYER_ACCESS_TTL_SECS: i64 = _;
Lifetime of a player card's access token.
pub const PLAYER_REFRESH_GRACE_SECS: i64 = _;
How long the other refresh tokens of a card keep working after one of them is used: long enough for two refreshes that raced with the same token to both succeed, and for a phone whose refresh answer was lost while it slept to try again (the apps expect ten minutes).
pub const PLAYER_REFRESH_TTL_DAYS: i64 = 30;
Lifetime of a player card's refresh token; each refresh starts it again.
pub const KV_LIST_DEFAULT_LIMIT: u32 = 100;
Default page size for LibraryStore::kv_list when the caller passes 0.
pub const AUDIT_RETENTION_DAYS: i64 = 365;
Days security_audit_events and configuration_audit rows are kept.
pub const CONFIGURATION_CHANGE_RETENTION_DAYS: i64 = 30;
Days configuration_changes notices are kept. They only signal that a
document changed; the document and its audit row hold the content.
pub const STORAGE_SCAN_STALE_DAYS: i64 = 1;
Days without a heartbeat after which a jobless storage-scan generation (a CLI scan) is treated as abandoned.
pub const TOKEN_HISTORY_DAYS: i64 = 30;
Days an expired claim ticket, user invite, or node enrollment link stays listed (as expired or redeemed) before it is deleted.
pub const UPLOAD_HISTORY_DAYS: i64 = 1;
Days a committed or aborted host upload is kept past its token's expiry.
No request can use it after expiry; the day only spares a commit replay racing the expiry a confusing "unknown upload". Open uploads are never deleted here: an abort still needs the row to tell the receiving node which copies to delete.
pub const FULL_PASS_INTERVAL: Duration = _;
Longest time since the last complete pass before the host asks for a full pass again, so a store whose deltas miss edits or removals is corrected.
pub const RESUME_CURSOR_TTL: Duration = _;
Longest time a stopped pass's cursor is resumed; an older one restarts the pass (store cursors expire).
pub const MAX_SPLIT_EXPRESSIONS: usize = 12;
Most expressions one split moves: the batch's widest statement binds each id twice, and the minimum database profile allows 32 binds.
pub const MAX_SPLIT_EXPRESSION_ID_BYTES: usize = 64;
Longest expression id a split body may name, in bytes; ids are UUIDs.
pub const ACQUIRED_KEYS_MAX_PAGE: u64 = 256;
Upper clamp for the editions one LibraryStore::acquired_title_keys_page
read covers.
An acquisition row is a few short columns (well under 1 KiB on the wire), so this many stay far below the 256 KiB inline result cap of an adapter that does not stream.
pub const ACQUIRE_WRITER: &str = "acquire";
The writer of a key an acquire run on this node wrote.
pub const COPY_RETRY_BASE_DELAY: Duration = _;
Delay before the first background retry of a failed copy; each later
failure doubles it, up to COPY_RETRY_MAX_DELAY.
pub const COPY_RETRY_MAX_DELAY: Duration = _;
The longest delay between two background retries of one copy.
pub const HOLDING_REMOVED: &str = "holding_removed";
Event type published when a holding is removed.
pub const MAX_COPY_ATTEMPTS: u32 = 8;
Failed attempts after which a pending copy turns CopyState::Failed
and is no longer retried in the background.
pub const MAX_QUEUE_REASONS: usize = 6;
Most taste reasons one stored row keeps, so a row stays small whatever the ranking explains.
pub const OBJECT_TOMBSTONE_DAYS: i64 = 30;
Days a removed object's tombstone is kept for readers that page changes.
pub const MAX_NOTIFY_PAGE: u64 = 200;
Most rows one page of the delivery log or the inbox returns.
pub const CLAIM_REDEEM_NONCE_HEX_LEN: usize = 64;
Hex length of a browser-generated claim-redeem nonce (32 bytes).
Generated from crates/bookclerk-library at main · View as Markdown