bookclerk_library

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

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).

Re-exports

Modules

  • 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 in crate::migrations.
  • library_link: Named-atomic parameters for writing a resolved listing.
  • master_key: Data-encryption key (DEK) for encrypted_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 in encrypted_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 from bookclerk_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 for encrypted_secrets.account_type.
  • secret_kind: Well-known kind values for the encrypted_secrets table.

Traits

AtomicTxnBackend

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.

AtomicTxnBackend::delete_user

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).

AtomicTxnBackend::set_user_status

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).

AtomicTxnBackend::set_user_password_hash

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.

AtomicTxnBackend::set_user_role

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).

AtomicTxnBackend::redeem_claim_ticket_to_session

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.

AtomicTxnBackend::take_oidc_rp_state

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).

AtomicTxnBackend::take_webauthn_challenge

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).

AtomicTxnBackend::enqueue_job

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.

AtomicTxnBackend::claim_next_job

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.

AtomicTxnBackend::reserve_job_temp_path

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.

AtomicTxnBackend::confirm_totp_enrollment

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.

AtomicTxnBackend::disable_user_totp

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.

AtomicTxnBackend::publish_domain_event

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.

AtomicTxnBackend::set_acquire_status

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.

Errors

Returns crate::LibraryError::NotFound when the holding no longer holds the edition, or the database error.

AtomicTxnBackend::dispatch_event_deliveries

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.

AtomicTxnBackend::write_credits

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.

AtomicTxnBackend::claim_event_delivery

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>

TypedAtomicExec

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.

TypedAtomicExec::execute_typed

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.

Errors

Returns a plugin ABI error when validation, transport, or the engine rejects the batch.

Implemented by: ProfileExec

NamedAtomicRunner

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.

NamedAtomicRunner::run_compiled

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.

Errors

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

Structs

DbAtomicResult

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 when status is ok, or the existing record a duplicate folded into (enqueueJob, publishDomainEvent).
  • operation_id: Echo of the request operationId.
  • 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.

DbAtomicResult::ok

pub fn ok(payload: JsonValue) -> Self

Successful operation with a JSON payload.

DbAtomicResult::ok_unit

pub fn ok_unit() -> Self

Successful operation with no payload (deleteUser).

DbAtomicResult::with_status

pub fn with_status(status: &str) -> Self

Application failure or empty consume-once result (no payload).

Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize

BackendMigrateOptions

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

BackendMigrateSummary

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_artifacts counts archives; their chunks are not counted.
  • dry_run: When true, counts rows without writing to the destination.

BackendMigrateSummary::total_rows

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

BackupRepository

pub struct BackupRepository {
    /* private fields */
}

On-disk backup repository rooted at files_dir/backups.

BackupRepository::open

pub fn open(files_dir: &Path) -> Result<Self>

Opens (creating) the repository under files_dir/backups.

Errors

Returns when the backups directory cannot be created.

BackupRepository::open_root

pub fn open_root(root: &Path) -> Result<Self>

Opens root as a backups repository (manifests/ + objects/).

Errors

Returns when the directories cannot be created.

BackupRepository::root

pub fn root(&self) -> &Path

Repository root (…/backups).

BackupRepository::lock_exclusive

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.

Errors

Returns when the lock file cannot be created or flocked.

BackupRepository::put_object

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.

Errors

Returns when encoding, compression, or the filesystem write fails.

BackupRepository::get_object

pub fn get_object(&self, digest: &str) -> Result<CanonicalObject>

Loads and verifies one object by uncompressed digest.

Errors

Returns when the object is missing, corrupt, or the digest mismatches.

BackupRepository::object_exists

pub fn object_exists(&self, digest: &str) -> bool

True when an object file exists (does not imply the bytes are valid).

BackupRepository::publish_manifest

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.

Errors

Returns when a referenced object is missing or corrupt, or the filesystem write fails.

BackupRepository::read_manifest

pub fn read_manifest(&self, id: &str) -> Result<BackupManifest>

Reads and integrity-checks a published manifest.

Errors

Returns when the file is missing, JSON is malformed, the sidecar hash mismatches, or the embedded id does not match the filename.

BackupRepository::list_manifests

pub fn list_manifests(&self) -> Vec<BackupManifest>

Lists published recovery-point manifests oldest-first. Staging files and unreadable manifests are skipped.

BackupRepository::list_manifests_strict

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.

Errors

Returns when the manifests directory cannot be read, a published *.json fails Self::read_manifest, or an unexpected non-sidecar file is present.

BackupRepository::delete_manifest

pub fn delete_manifest(&self, id: &str) -> Result<bool>

Deletes one published manifest (not its objects). Returns whether a file was removed.

Errors

Returns when the id is unsafe or unlink fails for a reason other than not found.

BackupRepository::gc_unreferenced_objects

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.

Errors

Returns when a published manifest cannot be verified, a directory cannot be read, or an unreferenced object cannot be unlinked.

Implements: Clone, Debug

BackupListEntry

pub struct BackupListEntry {
    pub manifest: BackupManifest,
}

Catalog entry used by bookclerk db backup list.

Fields

  • manifest: Parsed manifest.

Implements: Clone, Debug

BackupManifest

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 (1 for content-addressed canonical objects).
  • id: Stable recovery-point id (UUID).
  • created_at: RFC 3339 UTC timestamp.
  • schema_state: SchemaState::display at 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).

BackupManifest::referenced_objects

pub fn referenced_objects(&self) -> BTreeSet<String>

Union of every object digest referenced by this recovery point.

BackupManifest::library_unit

pub fn library_unit(&self) -> Result<&BackupUnit>

Library unit from this manifest.

Errors

Returns when the library unit is missing or duplicated.

BackupManifest::plugin_units

pub fn plugin_units(&self) -> Vec<&BackupUnit>

Plugin binding units.

Implements: Clone, Debug, Deserialize<'de>, Serialize

BackupOutcome

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

BackupRequest

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::Uninitialized skips.
  • reason: Operator vs pre-migrate.
  • to_version: Version the upcoming migrate step will target (0 for 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: Negotiated maxResultRows (clamped).
  • max_result_bytes: Negotiated maxResultBytes for one SELECT page.
  • max_atomic_result_bytes: Negotiated maxAtomicResultBytes (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. None uses the in-process SDK (tests).
  • in_process: True when leftover SQL is physically lowered on the opened connection.

Implements: Clone, Debug

BackupUnit

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 when DatabaseUnitKind::PluginBinding.
  • binding: Binding name when DatabaseUnitKind::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 when DatabaseUnitKind::PluginBinding (owner identity).
  • plugin_schema_state: crate::PluginMigrationHistory::display at capture (history@{n}+{digest}).
  • plugin_schema_checksum: Digest of the complete ordered (migration_id, checksum) journal.

BackupUnit::restore_kind

pub fn restore_kind(&self) -> CanonicalRestoreKind

Restore companion kind for this unit.

BackupUnit::referenced_objects

pub fn referenced_objects(&self) -> BTreeSet<String>

Object digests this unit needs to restore.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

CanonicalDatabaseSchema

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 TABLE statements in FK-safe order after crate::sort_tables_by_foreign_keys.
  • indexes: CREATE INDEX statements (after tables).

CanonicalDatabaseSchema::schema_sql

pub fn schema_sql(&self) -> Vec<String>

Ordered canonical DDL (tables then indexes).

CanonicalDatabaseSchema::table_names

pub fn table_names(&self) -> Vec<String>

Folded user table names in CREATE order.

Implements: Clone, Debug, Eq, PartialEq

CanonicalExportOpts

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 advertised DbCapabilities::supports_consistent_backup_read.
  • skip_tables: Folded table names omitted from row capture (library plugin_databases).
  • max_result_rows: Page size for SELECT … LIMIT (honors adapter maxResultRows).
  • 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. None uses the in-process SDK (tests).
  • in_process: True when leftover SQL is physically lowered on the opened connection.

CanonicalExportOpts::from_caps

pub fn from_caps(caps: &DbCapabilities) -> Self

Page-size and result-byte limits from negotiated adapter capabilities.

CanonicalExportOpts::page_byte_budget

pub fn page_byte_budget(&self) -> usize

Effective encoded-byte budget for one capture SELECT page.

Implements: Clone, Debug, Default

CanonicalRestoreOpts

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 advertised atomicUnitRestore.
  • 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 one bookclerk_plugin_abi::ExecuteRequest.
  • adapter: Adapter restore hooks. None uses the in-process SDK (tests).
  • in_process: True when leftover SQL is physically lowered on the opened connection.

CanonicalRestoreOpts::from_caps

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.

Errors

Returns when caps is not a known versioning contract (schemaMigrations missing).

Implements: Clone, Debug, Default

CanonicalTableSchema

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

IdentityHighWater

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

PreparedPluginUnit

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: Negotiated maxResultRows for this binding session.
  • max_result_bytes: Negotiated maxResultBytes for this binding session.
  • max_atomic_result_bytes: Negotiated maxAtomicResultBytes for this binding session.
  • adapter: Binding-scoped adapter hooks. None uses the in-process SDK (tests).

Implements: Clone, Debug

RestorePlan

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

SchemaBackupOpts

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_DIR root for backups/.
  • 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. None uses the in-process SDK (tests).

Implements: Clone, Debug, Default

ValidatedBackup

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

Missing

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

SchemaApplyOptions

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

SchemaBatch

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.

SchemaBatch::from_statements_and_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.

SchemaBatch::unreleased

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

InProcessSqlite

pub struct InProcessSqlite {
    /* private fields */
}

Runs compiled named plans on a local SeaORM SQLite connection.

Implements: Clone, Debug, NamedAtomicRunner

PluginMigrationHistory

pub struct PluginMigrationHistory {
    pub entries: Vec<PluginJournalEntry>,
}

Ordered durable plugin migration history.

Fields

  • entries: Journal rows in ordinal order.

PluginMigrationHistory::digest

pub fn digest(&self) -> String

SHA-256 digest of the complete ordered (migration_id, checksum) list.

PluginMigrationHistory::len

pub fn len(&self) -> usize

Number of applied journal rows.

PluginMigrationHistory::is_empty

pub fn is_empty(&self) -> bool

True when no plugin migrations have been applied.

PluginMigrationHistory::display

pub fn display(&self) -> String

Operator-facing history label (history@{n}+{digest}).

Implements: Clone, Debug, Default, Eq, PartialEq

PluginMigrationSequence

pub struct PluginMigrationSequence {
    pub migrations: Vec<ProvenPluginMigration>,
}

Proven, ordered plugin migration sequence.

Fields

  • migrations: Registration-order migrations with checksums.

Implements: Clone, Debug, Eq, PartialEq

ProvenPluginMigration

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

AccountLinkRecord

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 to portal_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

AccountRecord

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 example us, uk).
  • label: Optional operator-facing display label.
  • scan_enabled: When nonzero/true, scheduled scans include this account.
  • connection_status: active or revoked (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

AcquireStatusCounts

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

Implements: Clone, Copy, Debug, Default, Eq, PartialEq

BranchRequestTarget

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

ClaimTicketRecord

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 to portal_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

DomainEventRecord

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: pending or dispatched.
  • created_at: Insert time.
  • wake_pending: True until a wake pass for this event has completed.
  • queue_name: Queue this row belongs to (core.events for domain events).
  • content_type: Body encoding of payload (json, text, bytes).
  • deliver_after: Earliest delivery time for a delayed queue message.

DomainEventRecord::is_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

EmbeddingRecord

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 within target_kind.
  • model: Embedding model identifier used to produce vector.
  • 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

EnqueueJobSpec

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

EventCatalogSubscription

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: Whether EventResult::Suspended is 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; None uses the host default.
  • dead_letter_queue: Queue that receives a message once max_retries is 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's message_retention_period). None uses EVENT_DELIVERY_DEFAULT_RETENTION_SECS.

EventCatalogSubscription::new

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.

EventCatalogSubscription::queue

pub fn queue(queue: impl Into<String>) -> Self

Build a plugin-owned queue subscription ([[queues.consumers]]).

EventCatalogSubscription::queue_name

pub fn queue_name(&self) -> &str

Queue this subscription consumes (core.events when unset).

EventCatalogSubscription::is_queue

pub fn is_queue(&self) -> bool

True for a plugin-owned queue subscription (not the domain-event bus).

EventCatalogSubscription::max_attempts

pub fn max_attempts(&self) -> Option<u32>

max_attempts for deliveries created from this subscription.

Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize

EventDeliveryFence

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 in lease_owner.
  • generation: lease_generation assigned by the successful claim.

Implements: Clone, Debug, Deserialize<'de>, Serialize

EventDeliveryMetrics

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: pending rows with no checkpoint (not suspended).
  • running: Currently claimed rows.
  • suspended: pending rows that hold a suspend checkpoint.
  • dead_letter: Dead-lettered rows.
  • acked: Successfully acked rows.
  • oldest_pending_age_secs: Age in seconds of the oldest pending row, when any exist.
  • retries_total: Durable retry outcomes (including reclaim-as-retry).
  • suspensions_total: Durable suspend outcomes.
  • dead_letters_total: Durable transitions into dead_letter.
  • dispatch_latency_ms_avg: Average first-dispatch latency in milliseconds, when sampled.
  • handler_latency_ms_avg: Average onEvent handler duration in milliseconds, when sampled.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

EventDeliveryRecord

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 (network today).
  • 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.

EventDeliveryRecord::fence

pub fn fence(&self) -> EventDeliveryFence

Fence for heartbeat / complete / fail / suspend.

Implements: Clone, Debug, Deserialize<'de>, Serialize

EventStreamPage

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; None when 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

EventStreamRead

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: Some limits the read to one account's events; None reads 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 before now are left for a later read (crate::EVENT_STREAM_SETTLE_SECS in 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

EventSubscriber

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; None uses the host default (EVENT_DELIVERY_MAX_ATTEMPTS). Derived from the consumer's max_retries + 1.

EventSubscriber::plugin

pub fn plugin(plugin_id: impl Into<String>) -> Self

Catalog match for plugin_id with the default network resource class.

EventSubscriber::max_attempts_or_default

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

EventSubscriberCatalogRecord

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

EventSubscriberNodeRecord

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 for plugin_id.
  • heartbeat_at: Last heartbeat from this node.

Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize

EventWakeGrant

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

GlobalQueueEntry

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 (see TitleRequestRecord::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.

GlobalQueueEntry::push_wisher

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.

Arguments
  • wisher - Person who has this title on an open wishlist.

Implements: Clone, Debug, Deserialize<'de>, Serialize

JobClaimCursor

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

JobClaimPage

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, or None when no row remains.

Implements: Clone, Debug, Default

JobFence

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 in lease_owner.
  • generation: lease_generation assigned by the successful claim.

Implements: Clone, Debug, Eq, PartialEq

JobPayload

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 equal JOB_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. None routes 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 unrouted crate::LibraryStore::claim_next_job never claims a job that has any.

  • trigger: Admission source (api or scheduler).

  • integration_id: Integration plugin id for JobKind::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 for JobKind::PluginCopy.

  • source_key: Source object key for JobKind::PluginCopy.

  • dest_key: Destination object key for JobKind::PluginCopy.

  • checkpoint: Bounded checkpoint restored after bookclerk_plugin_abi::JobOutcome::Suspended.

  • invocation_sequence: Resume ordinal; distinct from failure Self attempt_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::checkpoint after 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's Self::requires unsettled: 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] crons schedule that fired.

  • scheduled_time_ms: For [JobKind::PluginScheduled]: the fire time the handler sees as scheduledTime, in Unix milliseconds (always a whole UTC minute).

  • subject: For JobKind::DiscoverCandidates and [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).

    None lets any node that meets Self::requires claim it. The routed claim (control_plane::claim_routed_job) skips a job pinned to another node, the unrouted crate::LibraryStore::claim_next_job never 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]: the ingest_batches.id to 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::force makes 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]: the notify_deliveries.id to send.

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

JobRecord

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.

JobRecord::fence

pub fn fence(&self) -> Option<JobFence>

Lease identity for heartbeat and finalization, when this row is claimed.

Implements: Clone, Debug, Deserialize<'de>, Serialize

JobTempPath

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

ListeningProgressRecord

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 to portal_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

OidcClientRecord

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; None for 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; None for operator-created clients.
  • created_at: RFC 3339 timestamp when the row was inserted.

OidcClientRecord::has_secret

pub fn has_secret(&self) -> bool

True when a client secret hash is stored (confidential client).

OidcClientRecord::is_plugin_provided

pub fn is_plugin_provided(&self) -> bool

True when a plugin owns this client's identity and redirect URIs.

Implements: Clone, Debug

OperatorSessionRecord

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

PendingWakeProgress

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

PortalIdentity

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

PortalSessionRecord

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

PublishDomainEventSpec

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 with event_type (duplicate publishes coalesce).
  • payload: Bounded JSON payload (never media bytes).
  • ordering_key: FIFO key copied onto each delivery (book uuid for book_acquired).
  • queue_name: Queue name; empty means the domain-event bus (CORE_EVENTS_QUEUE).
  • content_type: Body encoding (json, text, bytes); empty means json.
  • delay_seconds: Seconds before the first delivery may be claimed (queue messages).

Implements: Clone, Debug, Default, Deserialize<'de>, Serialize

QueueWisher

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-party users.id when 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 of picture_url for the web app to show (filled by the daemon; never stored).

QueueWisher::same_person

pub fn same_person(&self, other: &Self) -> bool

Returns true when both rows represent the same person for aggregation.

Arguments
  • other - Candidate wisher to compare.
Returns

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

SecurityAuditEvent

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 example login, rotate_token).
  • detail_json: JSON object with structured event details (no secrets).

Implements: Clone, Debug, Deserialize<'de>, Serialize

StoredPasskey

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: Serialized webauthn_rs passkey JSON.
  • name: Label chosen at registration; None for rows created before names existed.

Implements: Clone, Debug

TasteHolder

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

TasteTitle

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's source), 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

TitleRequestRecord

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 to portal_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 when cover_url is an https URL. Append /128 (thumbnail), /360 (card) or /full, so a client can show covers without loading cover_url from 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

TitleRequestSourceRecord

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 to title_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

UserIntegrationHint

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

UserInviteRecord

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 (administrator or member).
  • 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

UserListeningHint

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

UserPreferences

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 to portal_identities.id.
  • default_view: Preferred library SPA view identifier (for example grid or list).
  • disabled_shelves: Shelf kind ids to hide (author, chirp_deals, …). Empty = all on.
  • discover_sort: Preferred Discover sort column (for example title or added).
  • 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, or dark).
  • updated_at: RFC 3339 timestamp when the row was last modified.

UserPreferences::defaults_for

pub fn defaults_for(subject_key: &str, identity_id: Option<i64>) -> Self

Defaults when no row exists yet.

Implements: Clone, Debug, Deserialize<'de>, Serialize

UserPresenceExtras

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

UserRecord

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, or member).
  • 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}); None is auto.
  • totp_enabled: True when a TOTP authenticator has been confirmed for local password login.

Implements: Clone, Debug, Deserialize<'de>, Serialize

UserSsoPicture

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.id this 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

UserTitleState

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

WishlistPurchaseHint

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

WishlistStoreEdition

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

WorkRecord

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

NamedAtomicBackend

pub struct NamedAtomicBackend<R> {
    /* private fields */
}

An AtomicTxnBackend that compiles every named operation and hands the plan to a NamedAtomicRunner.

NamedAtomicBackend::on

pub fn on(db: DatabaseConnection) -> Self

The backend over db, an open and migrated library connection.

NamedAtomicBackend::new

pub fn new(runner: R) -> Self

Wraps runner.

Implements: AtomicTxnBackend, Debug

SchemaWalk

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 than requested_to when an irreversible step blocks a downgrade).
  • ups: Remaining up steps in order (empty when rolling back).
  • downs: down steps newest-first (empty when upgrading).
  • blocked: True when a missing down stopped a rollback short of requested_to.

SchemaWalk::is_noop

pub fn is_noop(&self) -> bool

True when no DDL remains to apply.

Implements: Clone, Debug, Eq, PartialEq

SessionClientInfo

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 synthetic API / empty).
  • device_type: High-level device class: desktop, mobile, tablet, api, or unknown.
  • client_label: Human label such as Windows, macOS, Android, iPhone, or API.

Implements: Clone, Debug, Eq, PartialEq

FacetValue

pub struct FacetValue {
    pub key: String,
    pub value: String,
    pub works: u64,
}

One value of a facet value list.

Fields

  • key: The value's facet_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

FacetValuesPage

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; None on the last page.

Implements: Clone, Debug, Eq, PartialEq

LibraryWorkRow

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 in Self::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

UnheldItem

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; None when no store said.

Implements: Clone, Copy, Debug, Default, Eq, PartialEq

WorkCursor

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 for WorkSort::Author and WorkSort::Series, whose ties break on title.
  • work_id: The last row's work id, the final tie-break.

WorkCursor::encode

pub fn encode(&self) -> String

The opaque token a client sends back: URL-safe base64 of the JSON.

WorkCursor::decode

pub fn decode(token: &str) -> Result<Self>

Parses a token from Self::encode.

Errors

Returns LibraryError::Invalid when the token is not one this library issued.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

WorkPage

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; None on the last page.

Implements: Clone, Debug, Eq, PartialEq

WorkPageQuery

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; None for a caller who sees the whole library.
  • after: Continue after this cursor.
  • limit: Most rows to return; at least 1.

Implements: Clone, Debug, Default

WorkScope

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, whatever include says.
  • owner: The patron (users.id) whose linked store accounts' books always pass; None for a caller with no accounts of their own.

WorkScope::sees_everything

pub fn sees_everything(&self) -> bool

True when the scope hides nothing.

WorkScope::admits_unheld

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.

Arguments
  • item - What the store listing says about the item.

WorkScope::key_set_id

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

EditionDetail

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

EditionListing

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

ListingHolding

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

WorkDetail

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 in Self::series.
  • editions: Editions, by id; a show's episodes' editions included.

Implements: Clone, Debug, PartialEq

WorkSearchDoc

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 than Self::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

WorkTag

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

WorkTagsBody

pub struct WorkTagsBody {
    /* private fields */
}

PUT /api/library/works/{id}/tags body: the tags an Administrator sets.

WorkTagsBody::validate

pub fn validate(self) -> Result<WorkTagsRequest>

Checks the body (normalize_work_tags).

Errors

Returns LibraryError::Invalid for too many or too long tags.

Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema

WorkTagsRequest

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.

WorkTagsRequest::tags

pub fn tags(&self) -> &[String]

The tags as written, trimmed and distinct.

Implements: Clone, Debug, Eq, PartialEq

CatalogListing

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

CatalogListingRecord

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.

CatalogListingRecord::offer

pub fn offer(&self, audience: OfferAudience) -> Option<&ListingOffer>

The stored offer for audience.

Implements: Clone, Debug

ListingDetail

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.

ListingDetail::of_new_book

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.

ListingDetail::of_catalog_hit

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

ListingOffer

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 of Self::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.

ListingOffer::is_empty

pub fn is_empty(&self) -> bool

True when the offer carries neither a price nor a label.

Implements: Clone, Debug, PartialEq

RecordedListings

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, or None for 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

Chapter

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

ChapterClaim

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; None while 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

ChapterClaimWrite

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

ChapterDigest

pub struct ChapterDigest(/* private */);

Lower-case hex SHA-256 naming one stored chapter list (ChapterList::digest).

ChapterDigest::parse

pub fn parse(stored: &str) -> Option<Self>

Reads a stored digest, refusing anything but 64 lower-case hex characters.

ChapterDigest::as_str

pub fn as_str(&self) -> &str

The digest as stored.

Implements: Clone, Debug, Display, Eq, Hash, Ord, PartialEq, PartialOrd

ChapterInput

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

ChapterList

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.

ChapterList::new

pub fn new(input: Vec<ChapterInput>, check: ChapterCheck) -> Result<Self>

Checks input into a list.

Arguments
  • input - The chapters in pre-order.
  • check - Whether to refuse or repair what breaks a rule.
Errors

Returns LibraryError::Invalid naming the first chapter that breaks a rule ChapterCheck does not repair.

ChapterList::chapters

pub fn chapters(&self) -> &[Chapter]

The chapters, in pre-order.

ChapterList::is_empty

pub fn is_empty(&self) -> bool

True when the list has no chapters.

ChapterList::spans

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.

Arguments
  • 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.
Returns

One span per chapter, starts non-decreasing, every end at or after its start.

ChapterList::digest

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

ChapterSpan

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 before start_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

EditionChapters

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

ChapterEditBody

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.

ChapterEditBody::validate

pub fn validate(self) -> Result<ChapterList>

Checks the chapters strictly (ChapterCheck::Strict).

Errors

Returns LibraryError::Invalid naming the first chapter that breaks a rule.

Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema

ChapterEditEntry

pub struct ChapterEditEntry {
    /* private fields */
}

One chapter of an edit, as JSON carries it.

Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema

ChapterPinBody

pub struct ChapterPinBody {
    /* private fields */
}

PUT /api/library/editions/{id}/chapters/pin body: the claim to pin.

ChapterPinBody::validate

pub fn validate(self) -> Result<ChapterPinRequest>

Checks the source id's length and characters.

Errors

Returns LibraryError::Invalid for a source id over MAX_CHAPTER_SOURCE_ID_BYTES or with a control character.

Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema

ChapterPinRequest

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

TitleQuery

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

WorkEnrichment

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.

WorkEnrichment::of_new_book

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).

WorkEnrichment::is_empty

pub fn is_empty(&self) -> bool

True when no field is set.

Implements: Clone, Debug, Default, Eq, PartialEq

ListeningIdentifiers

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

ListeningMatch

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

ListeningProgressWrite

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; None when the write inserted it.
  • after: The row as written: every report for its key merged over before the way LibraryStore::upsert_listening_progress merges one.

Implements: Clone, Debug

ConflictCursor

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).

ConflictCursor::encode

pub fn encode(&self) -> String

The cursor as an opaque URL-safe token.

ConflictCursor::decode

pub fn decode(token: &str) -> Result<Self>

Reads a token made by Self::encode.

Errors

Returns LibraryError::Invalid when the token is not one.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

ResolutionConflict

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_work or work_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

AccountPaceState

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 last BUDGET_WINDOW, oldest first.

Implements: Clone, Debug, Default, Eq, PartialEq

DownloadId

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.

DownloadId::new

pub fn new() -> Self

A fresh identity (a random UUID) for a new download.

DownloadId::as_str

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

Bookmark

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

NewPlaybackSession

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 most MAX_PLAYER_NAME_BYTES bytes are kept.

Implements: Clone, Copy, Debug

PlaybackChange

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

PlaybackEdition

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; None only 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

PlaybackMs

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.

PlaybackMs::ZERO

pub const ZERO: Self = _

The start of a recording.

PlaybackMs::new

pub fn new(ms: u64) -> Option<Self>

ms as a timeline length.

Returns

None when ms is past MAX_PLAYBACK_MS.

PlaybackMs::get

pub fn get(self) -> u64

The length in milliseconds.

Implements: Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd

PlaybackProgress

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

PlaybackProgressEdit

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; None keeps it.
  • duration: The runtime to store; None keeps it.
  • finished: Some(true) marks the edition (and its work) finished, Some(false) clears the edition's flag only, None decides from the position and runtime.

Implements: Clone, Copy, Debug, Eq, PartialEq

PlaybackSession

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; None while open.

Implements: Clone, Debug, Eq, PartialEq

PlaybackSync

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

ProgressCursor

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's updated_at, as stored.
  • edition_id: That row's edition.

Implements: Clone, Debug, Eq, PartialEq

BookmarkEditBody

pub struct BookmarkEditBody {
    /* private fields */
}

PUT /api/playback/bookmarks/{id} body: what to change. A field left out keeps its stored value.

BookmarkEditBody::validate

pub fn validate(self) -> Result<BookmarkEditRequest>

Checks the body.

Errors

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

BookmarkEditRequest

pub struct BookmarkEditRequest {
    pub position: Option<PlaybackMs>,
    pub title: Option<String>,
}

A checked change to a bookmark.

Fields

  • position: The new place; None keeps it.
  • title: The new note, trimmed; None keeps it.

Implements: Clone, Debug, Eq, PartialEq

NewBookmarkBody

pub struct NewBookmarkBody {
    /* private fields */
}

POST /api/library/editions/{id}/bookmarks body.

NewBookmarkBody::validate

pub fn validate(self) -> Result<NewBookmarkRequest>

Checks the body.

Errors

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

NewBookmarkRequest

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

OpenSessionBody

pub struct OpenSessionBody {
    /* private fields */
}

POST /api/playback/sessions body.

OpenSessionBody::validate

pub fn validate(self) -> Result<OpenSessionRequest>

Checks the body and tidies the player's name.

Errors

Returns LibraryError::Invalid for an empty edition id or one over MAX_EDITION_ID_BYTES.

Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema

OpenSessionRequest

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 most MAX_PLAYER_NAME_BYTES bytes.

Implements: Clone, Debug, Eq, PartialEq

PlaybackSyncBody

pub struct PlaybackSyncBody {
    /* private fields */
}

POST /api/playback/sessions/{id}/sync and .../close body: where the listener is.

PlaybackSyncBody::validate

pub fn validate(self, close: bool) -> Result<PlaybackSync>

Checks the body: every length at most MAX_PLAYBACK_MS.

Arguments
  • close - True for the close route: the report ends the session.
Errors

Returns LibraryError::Invalid naming the field that is too large.

Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema

ProgressEditBody

pub struct ProgressEditBody {
    /* private fields */
}

PUT /api/playback/progress/{edition_id} body: what to set. A field left out keeps its stored value.

ProgressEditBody::validate

pub fn validate(self) -> Result<PlaybackProgressEdit>

Checks the body: every length at most MAX_PLAYBACK_MS.

Errors

Returns LibraryError::Invalid naming the field that is too large.

Implements: ComposeSchema, Debug, Default, Deserialize<'de>, ToSchema

TrackPath

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, below MAX_PLAYBACK_TRACKS.

Implements: Clone, Debug, Eq, PartialEq

NewPlayerCard

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's User-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

PlayerCard

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's portal_sessions.id.
  • identity: The identity it signs in as.

Implements: Clone, Debug

PlayerCardTokens

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

PlayerPassword

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

PlayerFacet

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

PlayerItem

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

PluginDatabaseRecord

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 from plugin.toml capabilities.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

KvEntry

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

KvListPage

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

KvWriteSpec

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; None never expires.
  • max_value_bytes: Largest value this namespace accepts.
  • max_keys: Most live keys this namespace holds.

Implements: Clone, Debug, Eq, PartialEq

PassStart

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

QualityCheckState

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; None before it first ran.

Implements: Clone, Debug, Default, Eq, PartialEq

ScanState

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

UserStateEdit

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; None keeps 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

WorkSplitBody

pub struct WorkSplitBody {
    /* private fields */
}

POST /api/library/works/{id}/split body: the expressions to move.

WorkSplitBody::validate

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).

Errors

Returns LibraryError::Invalid for an empty or overlong id, or a count outside the bounds.

Implements: ComposeSchema, Debug, Deserialize<'de>, ToSchema

WorkSplitRequest

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.

WorkSplitRequest::expression_ids

pub fn expression_ids(&self) -> &[String]

The expressions to move, sorted and distinct.

Implements: Clone, Debug, Eq, PartialEq

AcquireTitle

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.id of 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's content_kind labels: episode for a podcast episode, podcast for a show, book otherwise.
  • 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; None when 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; None as for Self::acquired_by.

AcquireTitle::acquired_here

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.

AcquireTitle::pdf_acquired_here

pub fn pdf_acquired_here(&self) -> bool

True when this title's holding set the edition's companion PDF state.

AcquireTitle::asin_or_isbn

pub fn asin_or_isbn(&self) -> &str

Naming and display fallback: ASIN, else ISBN, else the store's product id.

Implements: Clone, Debug, PartialEq

AcquireTitlePage

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; None once the walk is done.

Implements: Clone, Debug, PartialEq

AcquiredTitleKey

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

AcquiredTitleKeyPage

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), or None after the last.

Implements: Clone, Debug, Default, Eq, PartialEq

AudioStream

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).

AudioStream::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

CandidateRef

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: The store_listings row.
  • 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

ChangedObject

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

DestinationFeed

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; None before 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; None between 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; None between listings.
  • revision: The row revision this value was read at (0 before the first save); LibraryStore::save_destination_feed refuses a save from an older one.

DestinationFeed::new

pub fn new(destination: &str) -> Self

A destination never followed before: no feed read, no listing.

DestinationFeed::next_seq

pub fn next_seq(&mut self) -> i64

Takes the next change sequence number.

DestinationFeed::listing_due

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

EditionAcquisition

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 as AcquireStatus::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 as AcquireStatus::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; None until a PDF write happens.

Implements: Clone, Debug, Eq, From<Model>, PartialEq

EditionAsin

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 as us).

Implements: Clone, Debug, Eq, PartialEq

EditionCopy

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; None unless pending.
  • last_error: The last write failure; None once stored.

EditionCopy::wants_attempt

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

EditionEnrichment

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 as editions.enrich_source.
  • confidence: How sure the enricher was, from 0.0 to 1.0.

Implements: Clone, Debug, Default, PartialEq

EditionFile

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, or ACQUIRE_WRITER.
  • role: What the file is.
  • sha256: Lowercase hex SHA-256 of the content, when known (host uploads).

Implements: Clone, Debug, Eq, PartialEq

EnrichCandidate

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 as us), 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

EnrichCandidatePage

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; None once the walk is done.

Implements: Clone, Debug, PartialEq

FileProbe

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; None when 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.

FileProbe::MAX_CONTENT_TYPE_BYTES

pub const MAX_CONTENT_TYPE_BYTES: usize = 64

Longest media type a probe may carry, in bytes.

FileProbe::MAX_BITRATE_KBPS

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.

FileProbe::is_better_than

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.

FileProbe::is_well_formed

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

HeldIdentifiers

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

LibraryStore

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.

LibraryStore::scope

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.

LibraryStore::acquire_title

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.

Arguments
  • 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.
Returns

None when the store's listing is not resolved yet or the account does not hold it.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::acquire_titles_named

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.

Arguments
  • 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.
Returns

Every matching account holding's title; empty when nothing matches.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::acquire_titles_of_listings

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.

Arguments
  • listing_ids - store_listings.id values.
Returns

One title per account holding of a listing; empty when none is held.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::held_titles_of_edition

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::acquire_title_of_holding

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.

Returns

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::accounts_holding_titles

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.

Arguments
  • account_id - Only the accounts this id or label names (ignoring ASCII case), when set.
  • plugin_key - Only accounts on this plugin, when set.
Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::acquire_titles_page

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.

Arguments
  • account_id - Only the titles of the accounts this id or label names (ignoring ASCII case), when set.
  • after - The previous page's AcquireTitlePage::next; None for the first page.
  • limit - Most holdings the page reads (1 to 64, and at most the database's maxResultRows).
Returns

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::all_acquire_titles

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.

Arguments
  • account_id - Only the titles of the accounts this id or label names (ignoring ASCII case), when set.
Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::acquired_title_keys_page

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.

Arguments
Returns

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::record_catalog_listings

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.

Arguments
  • listings - The titles, in the store's order.
Returns

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.

Errors

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.

LibraryStore::record_listing_offers

pub async fn record_listing_offers(&self, offers: &[(String, ListingOffer)]) -> Result<()>

Stores prices a store quoted for listings already in the pool.

Arguments
  • 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.
Errors

Returns the first batch's database error, after every batch was tried.

LibraryStore::record_store_text

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.

Arguments
  • 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.

Returns

How many of texts named a stored listing.

Errors

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.

LibraryStore::catalog_listings

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.

Arguments
  • ids - store_listings ids; duplicates are read once.
Returns

The listings found, in the order of ids (first occurrence); ids no longer stored are left out.

Errors

Returns the database error.

LibraryStore::listing_expressions

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.

Arguments
  • products - (plugin_key, product_id) pairs, as stores report them (the product id is compared in its stored spelling).
Returns

Each pooled product's expression ids, keyed by the pair as given.

Errors

Returns the database error.

LibraryStore::prune_catalog_listings

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.

Returns

How many listings were deleted.

Errors

Returns the database error.

LibraryStore::record_chapter_claim

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.

Arguments
  • edition_id - The edition (editions.id).
  • write - The claim.
Returns

Whether the edition's chapters changed.

Errors

Returns LibraryError::NotFound for an unknown edition, or the database error.

LibraryStore::remove_chapter_edit

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.

Returns

Whether the edition's chapters changed; ChaptersOutcome::Unchanged when there was no edit.

Errors

Returns LibraryError::NotFound for an unknown edition, or the database error.

LibraryStore::pin_chapter_claim

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.

Arguments
  • edition_id - The edition.
  • target - The claim to pin, by source kind and source id; None removes the pin.
  • user_id - The Administrator; None for the operator.
Errors

Returns LibraryError::NotFound for an unknown edition or a claim it does not have, or the database error.

LibraryStore::chapter_claims

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.

Errors

Returns the read error.

LibraryStore::edition_chapters

pub async fn edition_chapters(&self, edition_id: &str) -> Result<Option<EditionChapters>>

The chapters an edition resolved to; None when it has none.

Errors

Returns the read error, or LibraryError::Other when the stored list is missing or no longer passes its own checks.

LibraryStore::chapter_list

pub async fn chapter_list(&self, digest: &ChapterDigest) -> Result<Option<ChapterList>>

A stored chapter list; None when no complete list has this digest.

Errors

Returns the read error, or LibraryError::Other when the entries do not match the list's row or its digest.

LibraryStore::resolve_edition_chapters

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.

Errors

Returns the database error, or LibraryError::Conflict when claims kept changing for every attempt.

LibraryStore::destination_feed

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).

Errors

Returns an error when the read fails.

LibraryStore::destination_feeds

pub async fn destination_feeds(&self) -> Result<Vec<DestinationFeed>>

Every destination's feed row, ordered by destination.

Errors

Returns an error when the read fails.

LibraryStore::save_destination_feed

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.

Errors

Returns LibraryError::Conflict when the row changed since feed was read, or the error of a failed write.

LibraryStore::record_seen_objects

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.

Returns

How many objects changed.

Errors

Returns an error when a read or a write fails.

LibraryStore::remove_seen_objects

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.

Returns

How many objects were marked removed.

Errors

Returns an error when a write fails.

LibraryStore::unlisted_object_count

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.

Errors

Returns an error when the read fails.

LibraryStore::known_object_count

pub async fn known_object_count(&self, destination: &str) -> Result<u64>

Objects destination is known to hold now.

Errors

Returns an error when the read fails.

LibraryStore::finish_listing

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.

Returns

How many objects were marked removed.

Errors

Returns an error when the write fails.

LibraryStore::keep_unlisted_objects

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.

Errors

Returns an error when the write fails.

LibraryStore::changed_objects

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.

Errors

Returns an error when the read fails.

LibraryStore::prune_object_tombstones

pub async fn prune_object_tombstones(&self, before: DateTime<Utc>) -> Result<u64>

Deletes tombstones of objects removed before before.

Returns

How many tombstones were deleted.

Errors

Returns an error when the delete fails.

LibraryStore::lose_copies

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 at now, 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.
Errors

Returns an error when a read or a write fails.

LibraryStore::release_missing_editions

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.

Returns

How many editions turned not acquired.

Errors

Returns an error when a read or a write fails.

LibraryStore::unlisted_copy_keys

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.

Returns

The missing keys, and how many distinct keys the destination's stored copies name.

Errors

Returns an error when a read fails.

LibraryStore::replace_discover_candidates

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.

Arguments
  • 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.
Errors

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.

LibraryStore::list_discover_candidates

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.

Errors

Returns the database error.

LibraryStore::discover_subject_exists

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.

Errors

Returns the database error.

LibraryStore::forget_discover_subject

pub async fn forget_discover_subject(&self, subject: &DiscoverSubject) -> Result<()>

Deletes every stored Discover row of one subject (candidates, feed, taste and fetch marker).

Errors

Returns the database error.

LibraryStore::put_discover_taste

pub async fn put_discover_taste(
    &self,
    subject: &DiscoverSubject,
    taste_json: &str,
    scope: SeedScope,
) -> Result<()>

Stores one subject's taste, replacing the previous one.

Arguments
  • subject - Whose taste it is.
  • taste_json - The taste, as the Discover crate encodes it.
  • scope - Seeds it comes from.
Errors

Returns the database error.

LibraryStore::get_discover_taste

pub async fn get_discover_taste(
    &self,
    subject: &DiscoverSubject,
) -> Result<Option<StoredDiscoverTaste>>

Returns one subject's stored taste, when it has one.

Errors

Returns the database error.

LibraryStore::mark_discover_fetch

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.

Errors

Returns the database error.

LibraryStore::newest_discover_candidate_fetch

pub async fn newest_discover_candidate_fetch(
    &self,
    subject: &DiscoverSubject,
) -> Result<Option<DateTime<Utc>>>

Returns when one subject's last candidate fetch finished.

Returns

None when no fetch has finished for the subject yet.

Errors

Returns the database error.

LibraryStore::get_discover_store_call

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.

Arguments
  • call_key - Key the caller derived from the store, call kind and query.
  • max_age - Oldest answer still worth reusing.
Returns

The listings the call answered, in the store's order, or None when absent or too old.

Errors

Returns the database error.

LibraryStore::get_discover_store_calls

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.

Arguments
  • call_keys - Keys the caller derived; duplicates are read once.
  • max_age - Oldest answer still worth reusing.
Returns

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.

Errors

Returns the database error.

LibraryStore::put_discover_store_call

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.

Arguments
  • call_key - The call's key.
  • source - Storefront plugin id that answered.
  • hits - The listings, in the store's order.
Errors

Returns the database error.

LibraryStore::prune_discover_store_calls

pub async fn prune_discover_store_calls(&self, cutoff: DateTime<Utc>) -> Result<u64>

Deletes cached storefront answers fetched before cutoff.

Returns

How many answers were deleted.

Errors

Returns the database error.

LibraryStore::put_discover_feed

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.

Arguments
  • 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.
Errors

Returns the database error.

LibraryStore::get_discover_feed

pub async fn get_discover_feed(
    &self,
    subject: &DiscoverSubject,
) -> Result<Option<StoredFeed>>

Returns one subject's stored feed, when it has one.

Errors

Returns the database error.

LibraryStore::list_discover_feed_subjects

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.

Errors

Returns the database error.

LibraryStore::set_copy_stored

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.

Errors

Returns an error when the write fails.

LibraryStore::set_copy_pending

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.

Returns

The copy's state after the failure.

Errors

Returns an error when the read or the write fails.

LibraryStore::record_copies_from_files

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.

Returns

How many copies were recorded.

Errors

Returns an error when the read or a write fails.

LibraryStore::copies_of_editions

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.

Errors

Returns an error when the read fails.

LibraryStore::due_copy_editions

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.

Errors

Returns an error when the read fails.

LibraryStore::defer_copy_retries

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.

Errors

Returns an error when the read or a write fails.

LibraryStore::enrich_candidates_page

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.

Arguments
  • after - The previous page's EnrichCandidatePage::next; None for the first page.
  • limit - Most editions the page reads (1 to 200, and at most the database's maxResultRows).
Returns

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::enrich_edition

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.

Arguments
  • edition_id - The edition filled.
  • fill - The values offered and who offers them.
Errors

Returns LibraryError::NotFound when the edition is gone, or LibraryError::Orm when a read or write fails.

LibraryStore::edition_acquisition

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.

Errors

Returns an error when the read fails.

LibraryStore::edition_of_holding

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.

Errors

Returns an error when a read fails.

LibraryStore::file_owner_of_holding

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.

Errors

Returns an error when a read fails.

LibraryStore::record_edition_file

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.

Returns

true when the key is now owner's; false when another live edition holds it.

Errors

Returns an error when a write fails.

LibraryStore::record_edition_copy_file

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.

Returns

true when the key is now owner's; false when another live edition holds it.

Errors

Returns an error when a write fails.

LibraryStore::claim_edition_file

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.

Arguments
  • 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 (catalog false), as an acquire on this node would replace a delivered copy with its own.
  • catalog - True for a catalog upload's claim.
Errors

Returns an error when a write fails.

LibraryStore::release_edition_file

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.

Errors

Returns an error when the write fails.

LibraryStore::count_edition_files_by

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.

Errors

Returns an error when the read fails.

LibraryStore::edition_file

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.

Errors

Returns an error when the read fails.

LibraryStore::set_edition_file_probe

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.

Returns

true when the row was owner's and now carries probe.

Errors

Returns an error when probe is not well formed (FileProbe::is_well_formed) or the write fails.

LibraryStore::set_uploaded_file_probe

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.

Returns

true when the row was writer's and now carries probe.

Errors

Returns an error when probe is not well formed or the write fails.

LibraryStore::set_edition_file_stream

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.

Returns

true when the row was owner's and now carries stream.

Errors

Returns an error when stream is not well formed (AudioStream::is_well_formed) or the write fails.

LibraryStore::edition_audio_files

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.

Errors

Returns an error when the read fails.

LibraryStore::edition_file_probe

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.

Errors

Returns an error when the read fails.

LibraryStore::edition_file_copy

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.

Errors

Returns an error when the read fails.

LibraryStore::audio_keys_of

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.

Errors

Returns an error when the read fails.

LibraryStore::name_held_by_another_owner

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.

Errors

Returns an error when the read fails.

LibraryStore::publish_domain_event

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.

Errors

Returns LibraryError::Orm when the write fails, or LibraryError::Other when the payload exceeds 64 KiB.

LibraryStore::dispatch_event_deliveries

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.

Errors

Returns LibraryError::Orm when the write fails.

LibraryStore::next_undispatched_event

pub async fn next_undispatched_event(&self) -> Result<Option<DomainEventRecord>>

Next undispatched outbox row (oldest first).

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::process_pending_wakes

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.

Errors

Returns LibraryError::Orm when the read or wake write fails.

LibraryStore::lease_next_event_delivery

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).

Errors

Returns LibraryError::Orm when the claim write fails.

LibraryStore::lease_next_event_delivery_due_by

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.

Errors

Returns LibraryError::Orm when the claim write fails.

LibraryStore::release_unexecuted_event_delivery

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).

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::heartbeat_event_delivery

pub async fn heartbeat_event_delivery(
    &self,
    fence: &EventDeliveryFence,
    lease_secs: u64,
) -> Result<bool>

Refresh the lease when fence still owns the running generation.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::ack_event_delivery

pub async fn ack_event_delivery(&self, fence: &EventDeliveryFence) -> Result<bool>

Mark a fenced delivery acked.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::reject_event_delivery

pub async fn reject_event_delivery(
    &self,
    fence: &EventDeliveryFence,
    reason: &str,
) -> Result<bool>

Mark a fenced delivery permanently rejected.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::dead_letter_event_delivery

pub async fn dead_letter_event_delivery(
    &self,
    fence: &EventDeliveryFence,
    reason: &str,
) -> Result<bool>

Mark a fenced delivery dead_letter.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::retry_event_delivery

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.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::suspend_event_delivery

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.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::fail_event_delivery

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.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::reclaim_expired_event_deliveries

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.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::get_domain_event

pub async fn get_domain_event(&self, id: &str) -> Result<Option<DomainEventRecord>>

Load one event envelope.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::get_event_delivery

pub async fn get_event_delivery(&self, id: &str) -> Result<Option<EventDeliveryRecord>>

Load one delivery.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_domain_events

pub async fn list_domain_events(&self, limit: u64) -> Result<Vec<DomainEventRecord>>

Recent outbox events, newest first.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_domain_events_for_queue

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.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_queue_names

pub async fn list_queue_names(&self) -> Result<Vec<String>>

Distinct queue names that hold at least one outbox row, sorted.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::count_queue_deliveries

pub async fn count_queue_deliveries(&self, queue_name: &str, state: &str) -> Result<i64>

Delivery rows on one queue in state.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_event_deliveries_for_queue

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.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_event_deliveries

pub async fn list_event_deliveries(
    &self,
    state: Option<&str>,
    limit: u64,
) -> Result<Vec<EventDeliveryRecord>>

Deliveries filtered by optional state, newest first.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::retry_dead_letter_delivery

pub async fn retry_dead_letter_delivery(&self, id: &str) -> Result<bool>

Re-queue a dead-lettered delivery for operator retry.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::acknowledge_dead_letter_delivery

pub async fn acknowledge_dead_letter_delivery(&self, id: &str) -> Result<bool>

Operator acknowledge: mark a dead-letter as rejected (no further retry).

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::count_event_deliveries

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.

Errors

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.

LibraryStore::event_delivery_metrics

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.

Errors

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.

LibraryStore::record_event_handler_latency

pub async fn record_event_handler_latency(&self, duration_ms: i64) -> Result<()>

Record one onEvent duration sample.

Errors

Returns LibraryError::Orm when the write fails.

LibraryStore::list_domain_events_by_dispatch_state

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.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_dispatched_events_page

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.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::upsert_event_subscriber

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).

Errors

Returns LibraryError::Orm when the write fails.

LibraryStore::upsert_event_subscriber_at

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.

Errors

Returns LibraryError::Orm when the write fails.

LibraryStore::list_live_event_subscribers

pub async fn list_live_event_subscribers(
    &self,
) -> Result<Vec<EventSubscriberCatalogRecord>>

Live catalog collapsed by plugin_id using the default heartbeat TTL.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_live_event_subscribers_with_ttl

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.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_live_event_subscriber_nodes

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.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::dispatch_catalog_matches

pub async fn dispatch_catalog_matches(
    &self,
    event: &DomainEventRecord,
    operation_id: &str,
) -> Result<u32>

Create deliveries from the live catalog for one event.

Errors

Returns LibraryError::Orm when the write fails.

LibraryStore::reconcile_catalog_deliveries

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.

Errors

Returns LibraryError::Orm when a read or write fails.

LibraryStore::request_event_delivery_cancel

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.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::event_delivery_cancel_requested

pub async fn event_delivery_cancel_requested(&self, id: &str) -> Result<bool>

True when a running delivery worker should abort after the current step.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::resume_event_delivery

pub async fn resume_event_delivery(&self, id: &str) -> Result<bool>

Wake a suspended delivery: run_after = now and resume_pending = 1.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::expire_unleased_event_deliveries

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.

Arguments
  • retention_days - The events retention window, which caps every delivery retention.
  • now - The time the retention periods are measured back from.
Returns

The number of deliveries moved to expired.

Errors

Returns LibraryError::Orm when a read or the update fails.

LibraryStore::read_event_stream

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::prune_event_deliveries

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.

Errors

Returns LibraryError::Orm when the delete fails.

LibraryStore::prune_event_step

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.

Arguments
  • 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.
Returns

The number of rows expired or removed.

Errors

Returns LibraryError::Orm when the delete fails.

LibraryStore::mark_holdings_seen

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.

Arguments
  • 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.
Errors

Returns an error when a batch fails.

LibraryStore::remove_account_holdings

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.

Arguments
  • plugin_key - The account's plugin.
  • account_id - The account.
  • selection - Which of its holdings go.
Returns

How many holdings were selected for removal (a concurrent writer may have kept or removed some of them first).

Errors

Returns an error when a read or a batch fails; holdings removed by earlier batches stay removed.

LibraryStore::remove_node_holdings

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.

Returns

How many holdings were selected for removal.

Errors

Returns an error when a read or a batch fails; holdings removed by earlier batches stay removed.

LibraryStore::refresh_library_works

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.

Arguments
  • work_ids - Works whose editions, listings or holdings changed.
Returns

How many rows were written or deleted (a write skipped because a later refresh already wrote the row is not counted).

Errors

Returns LibraryError::Orm or a batch error when a read or write fails.

LibraryStore::rebuild_library_index_page

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.

Arguments
  • after - The last work id of the previous page; None to start.
Returns

The last work id of this page, or None when the walk is done.

Errors

Returns LibraryError::Orm or a batch error when a read or write fails.

LibraryStore::top_level_work_ids_page

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.

Arguments
  • after - The last id of the previous page; None to start.
  • limit - Most ids to return, further capped at the database's result-row limit.
Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::library_index_built

pub async fn library_index_built(&self) -> Result<bool>

True when the page index has a finished build of LIBRARY_INDEX_LAYOUT.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::drop_library_index_build

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.

Errors

Returns a batch error when the write fails.

LibraryStore::finish_library_index_build

pub async fn finish_library_index_build(&self) -> Result<()>

Records a finished build of LIBRARY_INDEX_LAYOUT.

Errors

Returns a batch error when the write fails.

LibraryStore::work_of_edition

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).

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::work_of_listing

pub async fn work_of_listing(&self, listing_id: &str) -> Result<Option<String>>

The work a listing's edition belongs to.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::library_works_by_ids

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.

Arguments
  • ids - Top-level work ids.
  • query - The filters to apply.
Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::work_in_scope

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::edition_in_scope

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.

Arguments
  • edition_id - The edition (editions.id).
  • scope - The patron's filter, None when nothing is hidden.
Errors

Returns LibraryError::Orm when a read fails; callers fail closed.

LibraryStore::library_facet_values

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.

Arguments
  • of - The facet, or the user whose tags to list.
  • after - The next key of the previous page; None to 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; None for a caller who sees the whole library.
Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::library_works_page

pub async fn library_works_page(&self, query: &WorkPageQuery) -> Result<WorkPage>

One page of the library's works from the page index.

Arguments
  • query - Order, filters, cursor and page size.
Errors

Returns LibraryError::Invalid when the cursor belongs to another order, or LibraryError::Orm when the read fails.

LibraryStore::library_works_at

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.

Arguments
  • query - Order and filters.
  • offset - Rows to skip.
  • limit - Most rows to return.
  • reversed - True to read the order backwards.
Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::owned_work_for

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.

Errors

Returns LibraryError when a read fails.

LibraryStore::work_for

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.

Errors

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.

LibraryStore::existing_edition_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.

Errors

Returns LibraryError when a read fails.

LibraryStore::work_for_wish

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.

Arguments
  • query - The wished title, authors, identifiers and series.
Returns

The work, and the existing edition the query's identifiers reached (None when they reached none).

Errors

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.

LibraryStore::record_listing

pub async fn record_listing(
    &self,
    listing: &Listing,
    holding: &HoldingDraft,
) -> Result<Plan>

Resolves listing into the library and records holding of it.

Arguments
  • listing - The validated listing a storefront reported.
  • holding - Who holds it, and how.
Returns

The plan that was written (a no-op plan when nothing changed).

Errors

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.

LibraryStore::record_catalog_listing

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.

Returns

The plan that was written (a no-op plan when nothing changed).

Errors

As Self::record_listing.

LibraryStore::works_by_ids

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.

Arguments
  • ids - Work ids; unknown ids are left out of the result.
Returns

The works found, keyed by id.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::get_work

pub async fn get_work(&self, id: &str) -> Result<Option<WorkRecord>>

Loads a work by id, with its work-level credits and series.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::list_works_page

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.

Arguments
  • after_id - Exclusive lower bound on works.id; None starts at the first work.
  • limit - Page size, clamped to 1..=500.
Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::embedding_text_hashes

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::prune_orphan_work_embeddings

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.

Errors

Returns LibraryError::Orm when the delete fails.

LibraryStore::list_works

pub async fn list_works(&self) -> Result<Vec<WorkRecord>>

Lists every work by title, with its work-level credits and series.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::work_of_holding

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::works_of_editions

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.

Returns

Edition id to work id; an edition that no longer exists, or whose expression row is missing, is left out.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::set_work_enrichment

pub async fn set_work_enrichment(
    &self,
    work_id: &str,
    enrichment: &WorkEnrichment,
) -> Result<()>

Fills a work's enrichment fields; None keeps the stored value.

Arguments
  • work_id - The work.
  • enrichment - Description, subjects and cover found by enrichment.
Errors

Returns LibraryError::NotFound when the work is gone, or LibraryError::Orm when the write fails.

LibraryStore::add_work_identifier

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.

Errors

Returns LibraryError::Orm when the write fails.

LibraryStore::match_listening_items

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.

Arguments
  • items - Each item's identifiers.
Returns

One match per item, in the same order; an item no identifier resolves has neither a work nor an edition.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::portal_identity_ids

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.

Arguments
  • provider - Identity provider / integration id.
  • external_user_ids - User ids at that provider.
Returns

portal_identities.id keyed by external user id; users with no identity are absent.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::upsert_listening_progress_batch

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.

Arguments
  • rows - Reports to store, in the order the provider sent them.
Returns

One write per distinct row key, in the order the keys first appear.

Errors

Returns the database error. Batches sent before a failing one stay written.

LibraryStore::route_notification

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.

Arguments
  • new - The notification, already rendered.
  • limits - The queue limits the send jobs are admitted under.
Returns

The stored id and the deliveries made.

Errors

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.

LibraryStore::route_notification_to

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.

Errors

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.

LibraryStore::user_holds_account

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.

Errors

An error when a read fails.

LibraryStore::enqueue_notify_send

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.

Returns

The job id, or None when the queue is full (the sweep tries again).

Errors

An error when the enqueue or the write fails.

LibraryStore::unscheduled_notify_deliveries

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.

Errors

An error when the read fails.

LibraryStore::drop_orphaned_notify_deliveries

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.

Returns

How many deliveries were dropped.

Errors

An error when the batch fails.

LibraryStore::stalled_notify_sends

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.

Errors

An error when a read fails.

LibraryStore::fail_stalled_notify_send

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.

Returns

What happened; StallOutcome::NotStalled when the job was claimed, retried or ended since it was read.

Errors

An error when the batch fails.

LibraryStore::drop_notify_delivery_if_job_ended

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.

Returns

Whether the delivery was dropped (and must not be enqueued again).

Errors

An error when the read or the batch fails.

LibraryStore::notify_send_work

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).

Errors

An error when a read fails or a stored value is malformed.

LibraryStore::record_notify_delivered

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.

Returns

false when the delivery was no longer pending (a replayed job).

Arguments
  • 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.
Errors

An error when the batch fails.

LibraryStore::record_notify_retry

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.

Returns

The attempts made, this one included; None when the delivery was no longer pending.

Arguments
  • 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.
Errors

An error when the batch or the read fails.

LibraryStore::record_notify_failed

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.

Returns

Whether this failure paused the destination; None when the delivery was no longer pending.

Arguments
  • 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.
Errors

An error when the batch or the read fails.

LibraryStore::record_notify_dropped

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.

Returns

false when the delivery was no longer pending.

Arguments
  • 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.
Errors

An error when the batch fails.

LibraryStore::create_notify_destination

pub async fn create_notify_destination(&self, new: &NewDestination) -> Result<Destination>

Creates a destination.

Errors

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.

LibraryStore::notify_destination

pub async fn notify_destination(&self, id: &str) -> Result<Option<Destination>>

One destination by id.

Errors

An error when the read fails or the row is malformed.

LibraryStore::notify_channels

pub async fn notify_channels(&self) -> Result<Vec<Destination>>

Every library channel, oldest first.

Errors

An error when the read fails.

LibraryStore::personal_destinations

pub async fn personal_destinations(&self, user_id: i64) -> Result<Vec<Destination>>

One patron's personal destinations, oldest first.

Errors

An error when the read fails.

LibraryStore::rename_notify_destination

pub async fn rename_notify_destination(&self, id: &str, label: &str) -> Result<()>

Renames a destination.

Errors

LibraryError::Invalid for a bad label; LibraryError::NotFound when the destination does not exist.

LibraryStore::resume_notify_destination

pub async fn resume_notify_destination(&self, id: &str) -> Result<()>

Resumes a paused destination and clears its failure count.

Errors

LibraryError::NotFound when the destination does not exist.

LibraryStore::delete_notify_destination

pub async fn delete_notify_destination(&self, id: &str) -> Result<()>

Deletes a destination with its routes, patron targets and delivery log rows.

Errors

LibraryError::NotFound when the destination does not exist.

LibraryStore::notify_routes

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.

Errors

An error when the read fails or a stored severity is malformed.

LibraryStore::set_notify_routes

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.

Errors

LibraryError::Invalid for too many routes, a repeated destination or one that is not a channel; LibraryError::NotFound when a destination does not exist.

LibraryStore::patron_offers

pub async fn patron_offers(&self) -> Result<BTreeMap<String, Vec<PatronOffer>>>

Every patron offer, by type.

Errors

An error when the read fails.

LibraryStore::set_patron_offers

pub async fn set_patron_offers(
    &self,
    notification_type: &str,
    offers: &[PatronOffer],
) -> Result<()>

Replaces the instances offered to patrons for one patron type.

Errors

LibraryError::Invalid for too many offers or a repeated instance.

LibraryStore::patron_choices

pub async fn patron_choices(&self, user_id: i64) -> Result<Vec<PatronChoice>>

One patron's choices, by type.

Errors

An error when a read fails.

LibraryStore::set_patron_choice

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.

Errors

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.

LibraryStore::clear_patron_choice

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.

Errors

An error when the batch fails.

LibraryStore::notify_deliveries

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.

Arguments
  • destination_id - Only this destination's rows, when set.
  • before - Where the page starts (the previous page's last row).
  • limit - Page size, clamped to 1..=MAX_NOTIFY_PAGE.
Errors

An error when a read fails or a stored value is malformed.

LibraryStore::inbox

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.

Arguments
  • 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 to 1..=MAX_NOTIFY_PAGE.
Errors

An error when a read fails or a stored value is malformed.

LibraryStore::inbox_unread

pub async fn inbox_unread(&self, user_id: i64) -> Result<u64>

How many entries in a patron's inbox are unread.

Errors

An error when the read fails.

LibraryStore::mark_inbox_read

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.

Returns

How many entries changed.

Errors

LibraryError::NotFound when the named entry is not in this patron's inbox; an error when the batch fails.

LibraryStore::prune_notifications

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.

Returns

How many notifications were deleted.

Errors

An error when the batch fails; nothing is deleted then.

LibraryStore::pin_listing

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.

Arguments
  • listing_id - The listing (store_listings.id).
  • edition_id - The edition it sells (editions.id).
  • user_id - The Administrator (users.id); None for the operator.
Returns

What the pin did.

Errors

Returns the database error of a failed read or write.

LibraryStore::unpin_listing

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.

Returns

Whether a pin was removed.

Errors

Returns the database error of a failed read or write.

LibraryStore::listing_pin

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.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_resolution_conflicts

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.

Arguments
  • after - Where the previous page stopped; None starts at the first conflict.
  • limit - Page size, clamped to 1..=MAX_CONFLICT_PAGE and to the database plugin's result-row cap.
Returns

The page, and the cursor of the next page when this one is full.

Errors

Returns LibraryError::Orm when a read fails, or LibraryError::Invalid when a stored subject list is not a JSON array of strings.

LibraryStore::record_resolution_conflict_for_test

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.

Panics

When the write fails.

LibraryStore::account_pace_state

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.

Arguments
  • plugin_key - The account's plugin.
  • account_id - The account.
  • now - The current time (the window ends here).
Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::set_account_pace_override

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).

Errors

Returns LibraryError::Other when the override is out of range (PaceOverride::validate), or an error when the batch fails.

LibraryStore::extend_account_cooldown

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.

Errors

Returns an error when the batch fails.

LibraryStore::clear_account_cooldown

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).

Errors

Returns an error when the batch fails.

LibraryStore::record_account_download

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.

Arguments
  • 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.
Errors

Returns an error when the batch fails.

LibraryStore::playback_edition

pub async fn playback_edition(&self, edition_id: &str) -> Result<Option<PlaybackEdition>>

The edition a player asks about, with its work and catalog runtime.

Returns

None for an unknown edition.

Errors

Returns the read error.

LibraryStore::playback_progress

pub async fn playback_progress(
    &self,
    user_id: i64,
    edition_id: &str,
) -> Result<Option<PlaybackProgress>>

One person's progress in one edition.

Errors

Returns the read error.

LibraryStore::list_playback_progress

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.

Arguments
  • user_id - The listener.
  • include_finished - False lists only editions not yet finished (Continue listening).
  • after - The last row of the page before; None for the first.
  • limit - Most rows to return.
Returns

The rows, and the cursor of the next page when there may be one.

Errors

Returns the read error.

LibraryStore::set_playback_progress

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.

Arguments
  • user_id - The listener.
  • edition_id - The edition.
  • work_id - The edition's work, for the finished flag.
  • edit - What to store.
Errors

Returns the database error.

LibraryStore::delete_playback_progress

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.

Returns

True when a row was removed.

Errors

Returns the database error.

LibraryStore::open_playback_session

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.

Errors

Returns the database error, for example for an unknown edition on an engine that checks foreign keys.

LibraryStore::playback_session

pub async fn playback_session(&self, id: &str) -> Result<Option<PlaybackSession>>

One play session by id.

Errors

Returns the read error.

LibraryStore::sync_playback_session

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.

Arguments
  • session - The session, as read just before.
  • work_id - The edition's work, for the finished flag.
  • sync - The player's report.
Returns

None when the session had already closed; nothing is written then.

Errors

Returns the database error.

LibraryStore::publish_playback_event

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).

Arguments
  • 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.

LibraryStore::list_bookmarks

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.

Errors

Returns the read error.

LibraryStore::bookmark

pub async fn bookmark(&self, id: &str) -> Result<Option<Bookmark>>

One bookmark by id.

Errors

Returns the read error.

LibraryStore::add_bookmark

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.

Arguments
  • user_id - The person.
  • edition_id - The edition.
  • position - The place to mark.
  • title - Their note; at most MAX_BOOKMARK_TITLE_BYTES bytes are kept.
Returns

The bookmark, or None when the person already keeps MAX_BOOKMARKS_PER_EDITION in the edition.

Errors

Returns the database error.

LibraryStore::edit_bookmark

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.

Arguments
  • user_id - The person; another person's bookmark is not found.
  • id - The bookmark.
  • position - The new place; None keeps it.
  • title - The new note; None keeps it.
Returns

The bookmark after the change, or None when the person has no such bookmark.

Errors

Returns the database error.

LibraryStore::delete_bookmark

pub async fn delete_bookmark(&self, user_id: i64, id: &str) -> Result<bool>

Removes one of a person's bookmarks.

Returns

True when a bookmark of theirs was removed.

Errors

Returns the database error.

LibraryStore::insert_player_password

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.

Arguments
  • user_id - The patron.
  • label - Its name; trimmed, and at most MAX_PLAYER_PASSWORD_LABEL_BYTES bytes are kept.
  • password_hash - SHA-256 hex of the generated password.
Returns

The password, or None when the patron already keeps MAX_PLAYER_PASSWORDS.

Errors

Returns the database error.

LibraryStore::list_player_passwords

pub async fn list_player_passwords(&self, user_id: i64) -> Result<Vec<PlayerPassword>>

A patron's player passwords, newest first.

Errors

Returns the read error.

LibraryStore::delete_player_password

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.

Returns

True when a password of theirs was removed.

Errors

Returns the database error.

LibraryStore::use_player_password

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.

Returns

The password, or None for no such password.

Errors

Returns the database error.

LibraryStore::mint_player_card

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.

Returns

The card's session id, or None when the player password it names was removed meanwhile.

Errors

Returns the database error.

LibraryStore::player_card_by_access

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.

Arguments
  • access_hash - SHA-256 hex of the access token.
Returns

None for an unknown or expired token or an ended card.

Errors

Returns the database error.

LibraryStore::refresh_player_card

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.

Arguments
  • refresh_hash - SHA-256 hex of the presented refresh token.
  • tokens - Digests of the new pair.
Returns

The card, or None when the token does not refresh: unknown, expired, or its card ended.

Errors

Returns the database error.

LibraryStore::end_player_card

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.

Returns

True when a live card was ended.

Errors

Returns the database error.

LibraryStore::player_editions_of_works

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.

Arguments
  • work_ids - Works (top-level works of the page index).
Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::player_items

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::player_items_page

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.

Arguments
  • query - Order and filters of the page index.
  • offset - Works to skip.
  • limit - Most works to read.
  • reversed - True to read the order backwards.
Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::list_playback_sessions

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::list_user_bookmarks

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.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::record_plugin_database

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).

Errors

Returns an error when the insert or lookup fails.

LibraryStore::get_plugin_database

pub async fn get_plugin_database(
    &self,
    plugin_id: &str,
    binding: &str,
) -> Result<Option<PluginDatabaseRecord>>

The registry row for (plugin_id, binding), if provisioned.

Errors

Returns an error when the query fails.

LibraryStore::list_plugin_databases

pub async fn list_plugin_databases(
    &self,
    plugin_id: Option<&str>,
) -> Result<Vec<PluginDatabaseRecord>>

All registry rows, optionally filtered to one owner PluginKey.

Errors

Returns an error when the query fails.

LibraryStore::remove_plugin_databases

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).

Errors

Returns an error when the delete fails.

LibraryStore::rebind_plugin_database

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.

Errors

Returns when the upsert fails.

LibraryStore::kv_get

pub async fn kv_get(
    &self,
    plugin_key: &str,
    namespace: &str,
    key: &str,
) -> Result<Option<KvEntry>>

Reads one key; None when absent or expired.

Errors

Returns an error when the query fails.

LibraryStore::kv_put

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).

Errors

Returns an error when the write fails.

LibraryStore::kv_delete

pub async fn kv_delete(
    &self,
    plugin_key: &str,
    namespace: &str,
    key: &str,
) -> Result<bool>

Deletes one key. Returns whether a live value existed.

Errors

Returns an error when the delete fails.

LibraryStore::kv_list

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.

Errors

Returns an error when the query fails or the cursor is malformed.

LibraryStore::kv_count

pub async fn kv_count(&self, plugin_key: &str, namespace: &str) -> Result<u64>

Live keys in one namespace.

Errors

Returns an error when the query fails.

LibraryStore::kv_prune_expired_in

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.

Errors

Returns an error when the delete fails.

LibraryStore::kv_prune_expired

pub async fn kv_prune_expired(&self) -> Result<u64>

Removes every expired row across all plugins and namespaces.

Errors

Returns an error when the delete fails.

LibraryStore::kv_delete_plugin

pub async fn kv_delete_plugin(&self, plugin_key: &str) -> Result<u64>

Removes every row of one plugin (retire / uninstall).

Errors

Returns an error when the delete fails.

LibraryStore::replace_request_queue_ranks

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.

Arguments
  • ranks - One ranking per queue entry; a repeated work_id keeps the last.
Errors

Returns the database error. Batches written before it stay; old rows are deleted only once every new row is stored.

LibraryStore::list_request_queue_ranks

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.

Errors

Returns the database error.

LibraryStore::prune_record_step

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.

Arguments
  • 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.
Errors

Returns LibraryError::Orm when a read or delete fails; rows the step had not reached yet are left for the next pass.

LibraryStore::quality_check_state

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.

Returns

None when the account has no scan state yet (it was never scanned, so it holds nothing to check).

Errors

Returns an error when the read fails.

LibraryStore::save_quality_check

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.

Errors

Returns an error when the batch fails.

LibraryStore::scan_state

pub async fn scan_state(
    &self,
    plugin_key: &str,
    account_id: &str,
) -> Result<Option<ScanState>>

Reads where an account's scan stands.

Errors

Returns an error when the read fails.

LibraryStore::save_scan_checkpoint

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.

Arguments
  • 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.
Errors

Returns an error when the batch fails.

LibraryStore::finish_scan_pass

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.

Errors

Returns an error when the batch fails.

LibraryStore::reset_scan_state

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.

Errors

Returns an error when the batch fails.

LibraryStore::storage_scan_put_object

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.

Errors

Returns LibraryError::Orm when the write fails.

LibraryStore::storage_scan_put_identity

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.

Errors

Returns LibraryError::Orm when the write fails.

LibraryStore::storage_scan_identity_page

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.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::storage_scan_object_page

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.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::storage_scan_claim

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.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::storage_scan_unclaimed_audio

pub async fn storage_scan_unclaimed_audio(&self, scan_id: &str) -> Result<u64>

Audio objects in the scan that no library row claimed.

Errors

Returns LibraryError::Orm when the count fails.

LibraryStore::storage_scan_delete

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.

Errors

Returns the batch error when the delete fails.

LibraryStore::storage_scan_register

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.

Errors

Returns LibraryError::Orm when the write fails, or LibraryError::Other when instance_id does not match the existing row.

LibraryStore::storage_scan_mark_complete

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.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::storage_scan_adoption

pub async fn storage_scan_adoption(&self, scan_id: &str) -> Result<Option<(String, bool)>>

Returns (instance_id, completed) when the generation row still exists.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::storage_scan_touch

pub async fn storage_scan_touch(&self, scan_id: &str) -> Result<()>

Refreshes the generation heartbeat after a page is stored.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::storage_scan_generation_count

pub async fn storage_scan_generation_count(&self) -> Result<u64>

How many generation rows exist. Tests use this to bound retained scans.

Errors

Returns LibraryError::Orm when the count fails.

LibraryStore::storage_scan_reclaim_abandoned

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.

Errors

Returns LibraryError::Orm when a read or delete fails.

LibraryStore::storage_scan_reclaim_if_terminal

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.

Errors

Returns LibraryError::Orm when a read or delete fails.

LibraryStore::storage_scan_reclaim_terminal_page

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.

Errors

Returns LibraryError::Orm when a read or delete fails. A delete error leaves that generation for a later retry.

LibraryStore::taste_titles

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).

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::user_title_states_for_works

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.

Arguments
  • work_ids - Works whose state to read.
Returns

The stored rows, ordered by work then user.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::held_works

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.

Arguments
  • work_ids - Works to check.
Returns

The held ones.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::held_identifiers

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.

Arguments
  • asins - ASINs to check, in any case.
  • isbns - ISBNs to check, as stored (canonical ISBN-13).
  • product_ids - Store product ids to check.
Returns

The held ones; ASINs upper-cased.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::set_user_title_state

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.

Arguments
  • user_id - The user (users.id).
  • work_id - The work (works.id).
  • fields - The fields to set.
Errors

Returns the database error, for example when the user or the work does not exist on an engine that checks foreign keys.

LibraryStore::edit_user_title_state

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.

Arguments
  • user_id - The user (users.id).
  • work_id - The work (works.id).
  • edit - What to change.
Returns

The stored state, or None when no such work exists.

Errors

Returns the database error.

LibraryStore::user_title_states

pub async fn user_title_states(&self, user_ids: &[i64]) -> Result<Vec<UserTitleState>>

Every work state of the given users, read in chunks.

Arguments
  • user_ids - Users whose state to read.
Returns

The stored rows, ordered by user then work.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::user_title_states_of_works

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.

Arguments
  • user_id - The user (users.id).
  • work_ids - Works whose state to read; duplicates are read once.
Returns

The stored rows, one per work the user has state for, ordered by work.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::users_linked_to_account

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.

Arguments
  • plugin_key - The account's plugin.
  • account_id - The account id at that plugin.
Returns

Distinct user ids, ascending; empty when no linked identity has a user.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::library_work_detail

pub async fn library_work_detail(&self, work_id: &str) -> Result<Option<WorkDetail>>

One top-level work with its editions, listings and holdings.

Arguments
  • work_id - The work. A podcast episode's id reads as missing: its show is the work the library lists.
Returns

None when there is no such top-level work.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::edition_cover_urls

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).

Returns

Edition id to cover URL; editions with no cover are left out.

Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::user_title_state

pub async fn user_title_state(
    &self,
    user_id: i64,
    work_id: &str,
) -> Result<Option<UserTitleState>>

One user's own state for one work.

Arguments
  • user_id - The user (users.id).
  • work_id - The work (works.id).
Returns

None when the user recorded nothing for the work.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::work_search_document

pub async fn work_search_document(
    &self,
    work_id: &str,
) -> Result<(String, Option<WorkSearchDoc>)>

The search document of work_id's top-level work.

Arguments
  • work_id - A work; an episode stands for its show.
Returns

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).

Errors

Returns crate::LibraryError::Orm when a read fails.

LibraryStore::work_search_documents

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.

Arguments
  • work_ids - Works; an episode stands for its show.
Returns

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).

Errors

Returns crate::LibraryError::Orm when a read fails.

LibraryStore::split_work

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.

Arguments
  • work_id - The work to split (works.id).
  • expression_ids - The expressions to move, 1 to MAX_SPLIT_EXPRESSIONS; duplicates count once.
  • user_id - The Administrator (users.id); None for the operator.
Returns

What the split did. SplitOutcome::Split is returned only when the expressions were moved.

Errors

Returns the database error of a failed read or write, or LibraryError::Conflict when the work changed between the read and the write.

LibraryStore::work_tags

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).

Errors

Returns LibraryError::NotFound for a missing work or an episode, or the read error.

LibraryStore::set_work_tags

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.

Arguments
  • work_id - A top-level work (works.id).
  • values - The tags; blanks and repeats (ignoring case) are dropped.
Returns

The work's tags afterwards, every source.

Errors

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.

LibraryStore::enqueue_job

pub async fn enqueue_job(&self, spec: EnqueueJobSpec) -> Result<EnqueueOutcome>

Admit a job in one transaction, coalescing onto an active dedup key.

Arguments
  • spec - Kind, payload, priority, attempt cap, and pending cap.
Returns

EnqueueOutcome::Created, EnqueueOutcome::Duplicate, or EnqueueOutcome::QueueFull.

Errors

Returns LibraryError::Orm when the database write fails.

LibraryStore::claim_next_job

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.

Errors

Returns LibraryError::Orm when the claim write fails.

LibraryStore::list_job_claim_candidates

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.

Errors

Returns LibraryError::Orm when a read or write fails.

LibraryStore::claim_job_by_id

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.

Arguments
  • job_id - The job to claim.
  • expected_generation - lease_generation of the record the caller evaluated; a successful claim runs at expected_generation + 1.
  • owner - Worker lease owner written on the row.
  • lease_secs - Lease length.
Returns

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.

Errors

Returns LibraryError::Orm when a read or write fails.

LibraryStore::list_pending_jobs_page

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).

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::wake_paced_acquires

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.

Returns

How many jobs were woken.

Errors

Returns LibraryError::Orm when a read or write fails.

LibraryStore::rewrite_pending_job_payload

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.

Returns

true when this write won; false when the row moved on.

Errors

Returns LibraryError::Orm when the write fails, or LibraryError::Other when the payload cannot be serialized.

LibraryStore::fail_pending_job

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.

Returns

true when this write won; false when the row moved on.

Errors

Returns LibraryError::Orm when the write fails.

LibraryStore::release_job_claim

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.

Returns

true when the row was released; false when fence no longer owns the running generation.

Errors

Returns LibraryError::Orm when a read or write fails, or LibraryError::Other when the stored payload is not valid JSON.

LibraryStore::heartbeat_job

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.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::set_job_progress

pub async fn set_job_progress(&self, fence: &JobFence, progress: &str) -> Result<bool>

Persist progress when fence still owns the running generation.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::complete_job

pub async fn complete_job(&self, fence: &JobFence, progress: Option<&str>) -> Result<bool>

Mark a running job succeeded when fence still owns the generation.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::suspend_job

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).

Errors

Returns LibraryError::Orm when the read or update fails, or LibraryError::Other when the stored payload is not valid JSON.

LibraryStore::defer_job

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.

Returns

true when the row was parked; false when fence no longer owns the running generation.

Errors

Returns LibraryError::Orm when the read or update fails, or LibraryError::Other when the stored payload is not valid JSON.

LibraryStore::checkpoint_running_job

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.

Errors

Returns LibraryError::Orm on database failure, or LibraryError::Other when the checkpoint exceeds bookclerk_plugin_abi::MAX_CHECKPOINT_BYTES.

LibraryStore::fail_job

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.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::fail_job_without_retry

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).

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::request_job_cancel

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.

Returns

The updated record, or None when the id is unknown.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::job_cancel_requested

pub async fn job_cancel_requested(&self, id: &str) -> Result<bool>

True when a running worker should abort after the current step.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::reclaim_expired_leases

pub async fn reclaim_expired_leases(&self) -> Result<u32>

Reclaim expired running leases with a conditional running update.

Returns

Number of rows moved out of running.

Errors

Returns LibraryError::Orm when the update fails.

LibraryStore::get_job

pub async fn get_job(&self, id: &str) -> Result<Option<JobRecord>>

Load one job by id, rejecting unreadable rows as invalid_job.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_jobs

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.

Errors

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.

LibraryStore::prune_terminal_jobs

pub async fn prune_terminal_jobs(&self, retention_days: u64) -> Result<u64>

Delete terminal jobs older than retention_days.

Errors

Returns LibraryError::Orm when the delete fails.

LibraryStore::reserve_job_temp_path

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.

Errors

Returns LibraryError::Orm when the write fails, or LibraryError::Other when the quota would be exceeded.

LibraryStore::register_job_temp_path

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).

Errors

Returns LibraryError::Orm when the insert fails.

LibraryStore::list_job_temp_paths

pub async fn list_job_temp_paths(&self, job_id: &str) -> Result<Vec<JobTempPath>>

List scratch paths registered for job_id.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::list_all_job_temp_paths

pub async fn list_all_job_temp_paths(&self) -> Result<Vec<JobTempPath>>

List every registered scratch path (used by the startup sweeper).

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::unregister_job_temp_path

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.

Errors

Returns LibraryError::Orm when the delete fails.

LibraryStore::reserved_temp_bytes

pub async fn reserved_temp_bytes(&self) -> Result<u64>

Sum of reserved scratch bytes across all jobs.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::has_running_acquire_job

pub async fn has_running_acquire_job(&self) -> Result<bool>

True when any acquire job is currently running.

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::reconcile_orphaned_acquire_rows

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.

Returns

Number of edition states updated.

Errors

Returns LibraryError::Orm when a status write fails.

LibraryStore::count_active_jobs

pub async fn count_active_jobs(&self) -> Result<i64>

Count pending + running jobs (admission cap).

Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::job_admitted_since

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.

Arguments
  • dedup_key - The JobKind::dedup_key of the job.
  • since - The moment the job must have been admitted after.
Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::job_is_active

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.

Arguments
Errors

Returns LibraryError::Orm when the read fails.

LibraryStore::from_connection

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.

LibraryStore::with_atomic_txn

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.

LibraryStore::with_typed_exec

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.

LibraryStore::with_max_binds

pub fn with_max_binds(self, max_binds: u32) -> Self

Records the guest's negotiated bind cap for wake IN (…) chunking.

LibraryStore::with_plan_limits

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.

LibraryStore::with_db_capabilities

pub fn with_db_capabilities(self, caps: DbCapabilities) -> Self

Records the full negotiated bookclerk_plugin_abi::DbCapabilities.

LibraryStore::db_capabilities

pub fn db_capabilities(&self) -> &DbCapabilities

Negotiated capability advertisement used for plan validation.

LibraryStore::execute_guest_atomic

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).

Errors

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.

LibraryStore::dispatch_chunk_size

pub fn dispatch_chunk_size(&self) -> usize

Subscribers packed into one dispatch plan (receipt overhead and the live counter bump are ~13 statements).

LibraryStore::wake_page

pub fn wake_page(&self) -> u64

Wake delivery page size derived from negotiated maxBinds.

LibraryStore::connection

pub fn connection(&self) -> &DatabaseConnection

Borrow the underlying SeaORM connection (e.g. for crate::secrets).

LibraryStore::db

pub fn db(&self) -> &DatabaseConnection

Alias for Self::connection — convenience name used by credential modules.

LibraryStore::delete_elevated_operator_sessions_for_user

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.

Errors

Returns an error when the operation fails.

LibraryStore::upsert_account

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.

Errors

Returns an error when the operation fails.

LibraryStore::ensure_account

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.

Errors

Returns an error when the operation fails.

LibraryStore::remap_account_id

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.

Errors

Returns an error when the operation fails.

LibraryStore::reconcile_account_id

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.

Errors

Returns an error when the operation fails.

LibraryStore::get_account

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.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::find_accounts_by_id

pub async fn find_accounts_by_id(&self, account_id: &str) -> Result<Vec<AccountRecord>>

Every account row with this store id, across plugins.

Errors

Returns a crate error when the database operation fails.

LibraryStore::get_account_unique

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.

Errors

Returns LibraryError::Conflict when the id is ambiguous.

LibraryStore::list_accounts

pub async fn list_accounts(&self) -> Result<Vec<AccountRecord>>

Lists all store accounts in the library database.

Returns

Result<Vec<AccountRecord>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::list_accounts_for_plugin

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.

Arguments
  • plugin_key - Canonical plugin key whose accounts to read.
Errors

Returns the read error.

LibraryStore::count_identities

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.

Errors

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.

LibraryStore::count_accounts

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.

Errors

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.

LibraryStore::find_accounts

pub async fn find_accounts(&self, identifier: &str) -> Result<Vec<AccountRecord>>

Every account whose id or nickname (label) matches, case-insensitive.

Errors

Returns an error when the operation fails.

LibraryStore::find_account

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.

Errors

Returns LibraryError::Conflict when the needle is ambiguous.

LibraryStore::set_scan_enabled

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.

Errors

Returns an error when the operation fails.

LibraryStore::mark_connection_active

pub async fn mark_connection_active(
    &self,
    plugin_key: &str,
    account_id: &str,
) -> Result<()>

Mark bookstore credentials active again (after reconnect).

Errors

Returns an error when the operation fails.

LibraryStore::delete_account_secrets

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).

Errors

Returns an error when the operation fails.

LibraryStore::revoke_credentials

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.

Errors

Returns an error when the operation fails.

LibraryStore::upsert_portal_identity

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.

Errors

Returns an error when the operation fails.

LibraryStore::create_user

pub async fn create_user(
    &self,
    role: UserRole,
    display_name: Option<&str>,
    password_hash: Option<&str>,
) -> Result<UserRecord>

Create a first-party user.

Errors

Returns an error when the operation fails.

LibraryStore::create_user_with_login

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.

Errors

Returns an error when the operation fails.

LibraryStore::create_user_with_profile

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.

Errors

Returns an error when the operation fails.

LibraryStore::get_user

pub async fn get_user(&self, id: i64) -> Result<Option<UserRecord>>

Look up a first-party user by id.

Errors

Returns an error when the operation fails.

LibraryStore::get_user_by_login_name

pub async fn get_user_by_login_name(&self, login_name: &str) -> Result<Option<UserRecord>>

Look up by local login_name (case-insensitive).

Errors

Returns an error when the operation fails.

LibraryStore::get_user_by_email

pub async fn get_user_by_email(&self, email: &str) -> Result<Option<UserRecord>>

Look up by email (case-insensitive).

Errors

Returns an error when the operation fails.

LibraryStore::get_user_password_hash

pub async fn get_user_password_hash(&self, id: i64) -> Result<Option<String>>

Raw password hash for verification (never expose via API).

Errors

Returns an error when the operation fails.

LibraryStore::list_users

pub async fn list_users(&self) -> Result<Vec<UserRecord>>

List all first-party users (admin tooling).

Errors

Returns an error when the operation fails.

LibraryStore::list_user_presence_extras

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.

Errors

Returns an error when the operation fails.

LibraryStore::delete_user

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.

Errors

Returns an error when the operation fails.

LibraryStore::set_user_status

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.

Errors

Returns an error when the operation fails.

LibraryStore::set_user_display_name

pub async fn set_user_display_name(
    &self,
    id: i64,
    display_name: Option<&str>,
) -> Result<UserRecord>

Set display name (does not bump security_version).

Errors

Returns an error when the operation fails.

LibraryStore::set_user_password_hash

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.

Errors

Returns an error when the operation fails.

LibraryStore::set_user_login_name

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.

Errors

Returns an error when the operation fails.

LibraryStore::set_user_email

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.

Errors

Returns an error when the operation fails.

LibraryStore::set_user_avatar_source

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).

Errors

Returns an error when the user is missing or the write fails.

LibraryStore::set_portal_identity_picture

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.

Errors

Returns an error when the write fails.

LibraryStore::list_user_sso_pictures

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.

Errors

Returns an error when the query fails.

LibraryStore::delete_portal_sessions_for_user

pub async fn delete_portal_sessions_for_user(&self, user_id: i64) -> Result<u64>

Delete all portal sessions for identities linked to user_id.

Errors

Returns an error when the operation fails.

LibraryStore::insert_user_invite

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).

Errors

Returns an error when the operation fails.

LibraryStore::redeem_user_invite

pub async fn redeem_user_invite(&self, token_hash: &str) -> Result<UserInviteRecord>

Atomically redeem a user invite.

Errors

Returns an error when the operation fails.

LibraryStore::set_user_role

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.

Errors

Returns an error when the operation fails.

LibraryStore::count_administrators

pub async fn count_administrators(&self) -> Result<u64>

Count administrators (includes disabled).

Errors

Returns an error when the operation fails.

LibraryStore::count_active_administrators

pub async fn count_active_administrators(&self) -> Result<u64>

Count administrators with status active.

Errors

Returns an error when the operation fails.

LibraryStore::count_owners

pub async fn count_owners(&self) -> Result<u64>

Count owners (includes disabled) — bootstrap / inventory.

Errors

Returns an error when the operation fails.

LibraryStore::count_active_owners

pub async fn count_active_owners(&self) -> Result<u64>

Count owners with status active (last-owner demote/disable/delete guard).

Errors

Returns an error when the operation fails.

LibraryStore::ensure_users_bridged

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).

Errors

Returns an error when the operation fails.

LibraryStore::ensure_local_portal_identity

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.

Errors

Returns an error when the operation fails.

LibraryStore::get_portal_identity

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.

Arguments
  • provider - External provider id.
  • external_user_id - User id at the external provider.
Returns

Result<Option<crate::models::PortalIdentity>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::get_portal_identity_by_id

pub async fn get_portal_identity_by_id(&self, id: i64) -> Result<Option<PortalIdentity>>

Look up portal identity by row id.

Errors

Returns an error when the operation fails.

LibraryStore::insert_claim_ticket

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).

Errors

Returns an error when the operation fails.

LibraryStore::get_claim_ticket_by_hash

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.

Arguments
  • token_hash - SHA-256 hex digest of the opaque token.
Returns

Result<Option<crate::models::ClaimTicketRecord>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::list_open_claim_tickets

pub async fn list_open_claim_tickets(&self) -> Result<Vec<ClaimTicketRecord>>

List unredeemed, unexpired claim tickets (newest first).

Errors

Returns an error when the operation fails.

LibraryStore::redeem_claim_ticket

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.

Errors

Returns an error when the operation fails.

LibraryStore::redeem_claim_ticket_to_session

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.

Arguments
  • 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.
Returns

The portal identity bound to the consumed ticket.

Errors

Returns a crate error when the ticket is invalid/consumed, a required invite password is missing, or the database operation fails.

LibraryStore::insert_portal_session

pub async fn insert_portal_session(
    &self,
    token_hash: &str,
    identity_id: i64,
    expires_at: DateTime<Utc>,
) -> Result<()>

Create a portal session (hash only).

Errors

Returns an error when the operation fails.

LibraryStore::insert_portal_session_with_client

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.

Errors

Returns an error when the operation fails.

LibraryStore::insert_clerk_session

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.

Arguments
  • 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.
Returns

The new session's row id.

Errors

Returns an error when the insert fails.

LibraryStore::delete_clerk_session

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.

Errors

Returns an error when the delete fails.

LibraryStore::delete_portal_session

pub async fn delete_portal_session(&self, token_hash: &str) -> Result<bool>

Delete a portal session by token hash (logout / revoke).

Errors

Returns an error when the operation fails.

LibraryStore::list_portal_sessions_for_identity

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).

Errors

Returns an error when the operation fails.

LibraryStore::list_portal_session_records_for_identity

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.

Errors

Returns an error when the operation fails.

LibraryStore::delete_portal_session_by_id_for_identity

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.

Errors

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.

Errors

Returns an error when the operation fails.

LibraryStore::get_portal_session_identity

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.

Errors

Returns an error when the operation fails.

LibraryStore::get_clerk_session_identity

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.

Errors

Returns an error when the operation fails.

LibraryStore::clerk_session_person

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).

Arguments
  • token_hash - SHA-256 hex of the card's token.
Errors

Returns an error when a read fails.

LibraryStore::insert_operator_session

pub async fn insert_operator_session(
    &self,
    token_hash: &str,
    expires_at: DateTime<Utc>,
) -> Result<()>

Create a durable operator session (hash only).

Errors

Returns an error when the operation fails.

LibraryStore::insert_operator_session_with_client

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.

Errors

Returns an error when the operation fails.

LibraryStore::insert_elevated_operator_session

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).

Errors

Returns an error when the operation fails.

LibraryStore::insert_elevated_operator_session_with_client

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.

Errors

Returns an error when the operation fails.

LibraryStore::get_operator_session

pub async fn get_operator_session(
    &self,
    token_hash: &str,
) -> Result<Option<OperatorSessionRecord>>

Look up a valid operator session (touches last_used_at).

Errors

Returns an error when the operation fails.

LibraryStore::operator_session_valid

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).

Errors

Returns an error when the operation fails.

LibraryStore::set_operator_session_impersonating

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.

Errors

Returns an error when the operation fails.

LibraryStore::delete_operator_session

pub async fn delete_operator_session(&self, token_hash: &str) -> Result<bool>

Delete an operator session by token hash (logout / revoke).

Errors

Returns an error when the operation fails.

LibraryStore::delete_operator_session_by_id

pub async fn delete_operator_session_by_id(&self, id: i64) -> Result<bool>

Delete an operator session by row id.

Errors

Returns an error when the operation fails.

LibraryStore::prune_expired_operator_sessions

pub async fn prune_expired_operator_sessions(&self) -> Result<u64>

Delete expired operator sessions (bounded cleanup).

Errors

Returns an error when the operation fails.

LibraryStore::list_operator_sessions

pub async fn list_operator_sessions(&self) -> Result<Vec<OperatorSessionRecord>>

List active operator sessions (newest first) for remote sign-out UI.

Errors

Returns an error when the operation fails.

LibraryStore::first_portal_identity_for_user

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).

Errors

Returns an error when the operation fails.

LibraryStore::list_portal_identities_for_user

pub async fn list_portal_identities_for_user(
    &self,
    user_id: i64,
) -> Result<Vec<PortalIdentity>>

All portal identities linked to a first-party user.

Errors

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.

Errors

Returns an error when the operation fails.

LibraryStore::insert_oidc_rp_state

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.

Errors

Returns an error when the operation fails.

LibraryStore::take_oidc_rp_state

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.

Errors

Returns an error when the operation fails.

LibraryStore::insert_webauthn_credential

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.

Arguments
  • user_id - First-party user who owns the passkey.
  • credential_id - Base64url credential id.
  • passkey_json - Serialized webauthn_rs passkey.
  • name - Label shown in Settings; empty becomes None.
Errors

Returns an error when the insert fails (including unique credential id).

LibraryStore::list_webauthn_credentials

pub async fn list_webauthn_credentials(&self, user_id: i64) -> Result<Vec<StoredPasskey>>

Passkeys registered to a user.

Errors

Returns an error when the operation fails.

LibraryStore::count_webauthn_credentials

pub async fn count_webauthn_credentials(&self, user_id: i64) -> Result<u64>

Count passkeys for a user.

Errors

Returns an error when the operation fails.

LibraryStore::get_webauthn_credential_by_cred_id

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.

Errors

Returns an error when the operation fails.

LibraryStore::update_webauthn_credential

pub async fn update_webauthn_credential(&self, id: i64, passkey_json: &str) -> Result<()>

Replace passkey JSON after a successful assertion (counter update).

Errors

Returns an error when the operation fails.

LibraryStore::delete_webauthn_credential

pub async fn delete_webauthn_credential(&self, user_id: i64, id: i64) -> Result<bool>

Delete a passkey owned by user_id.

Errors

Returns an error when the operation fails.

LibraryStore::set_user_totp_enabled

pub async fn set_user_totp_enabled(&self, user_id: i64, enabled: bool) -> Result<()>

Set whether this user has a confirmed TOTP authenticator.

Arguments
  • user_id - First-party user id.
  • enabled - true after a successful enroll confirm; false on disable.
Errors

Returns LibraryError::NotFound when the user does not exist.

LibraryStore::confirm_totp_enrollment

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.

Errors

Returns LibraryError::NotFound when the user does not exist.

LibraryStore::disable_user_totp

pub async fn disable_user_totp(&self, user_id: i64) -> Result<()>

Delete TOTP secrets and clear totp_enabled in one transaction.

Errors

Returns LibraryError::NotFound when the user does not exist.

LibraryStore::insert_webauthn_challenge

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.

Errors

Returns an error when the operation fails.

LibraryStore::take_webauthn_challenge

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).

Errors

Returns an error when the operation fails.

LibraryStore::prune_expired_oidc_rp_states

pub async fn prune_expired_oidc_rp_states(&self) -> Result<u64>

Drop expired OIDC RP states (bounded cleanup).

Errors

Returns an error when the operation fails.

LibraryStore::prune_expired_webauthn_challenges

pub async fn prune_expired_webauthn_challenges(&self) -> Result<u64>

Drop expired WebAuthn challenges (bounded cleanup).

Errors

Returns an error when the operation fails.

LibraryStore::count_oidc_rp_states

pub async fn count_oidc_rp_states(&self) -> Result<u64>

Count pending OIDC RP states (for public-begin caps).

Errors

Returns an error when the operation fails.

LibraryStore::count_webauthn_challenges

pub async fn count_webauthn_challenges(&self) -> Result<u64>

Count pending WebAuthn challenges (for public-begin caps).

Errors

Returns an error when the operation fails.

LibraryStore::portal_session_created_at

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).

Errors

Returns an error when the operation fails.

LibraryStore::set_portal_session_created_at

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).

Errors

Returns an error when the operation fails.

LibraryStore::insert_security_audit_event

pub async fn insert_security_audit_event(
    &self,
    actor: &str,
    action: &str,
    detail_json: Option<&str>,
) -> Result<SecurityAuditEvent>

Appends one security audit event row.

Arguments
  • actor - Actor label.
  • action - Audit action verb.
  • detail_json - detail_json argument for this call.
Returns

Result<crate::models::SecurityAuditEvent> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::insert_oidc_client

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.

Errors

Returns an error when the operation fails.

LibraryStore::upsert_plugin_oidc_client

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.

Errors

Returns LibraryError::Conflict when client_id is already owned by a custom client or another plugin.

LibraryStore::update_oidc_client

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.

Errors

Returns an error when the operation fails.

LibraryStore::set_oidc_client_secret

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).

Errors

Returns an error when the operation fails.

LibraryStore::delete_oidc_client

pub async fn delete_oidc_client(&self, client_id: &str) -> Result<bool>

Delete a registered OIDC client by client_id.

Errors

Returns an error when the operation fails.

LibraryStore::list_oidc_clients

pub async fn list_oidc_clients(&self) -> Result<Vec<OidcClientRecord>>

List registered OIDC clients, oldest first.

Errors

Returns an error when the operation fails.

LibraryStore::get_oidc_client

pub async fn get_oidc_client(&self, client_id: &str) -> Result<Option<OidcClientRecord>>

Loads a registered OIDC client by client_id, if present.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::insert_oidc_auth_code

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.

Arguments
  • 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 (S256 or plain).
  • scope - OAuth scope string.
  • expires_at - Expiry timestamp.
Returns

Result<()> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::peek_oidc_auth_code

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.

Errors

Returns an error when the read fails.

LibraryStore::consume_oidc_auth_code

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).

Errors

Returns an error when the operation fails.

LibraryStore::insert_oidc_refresh_token

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.

Arguments
  • 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.
Returns

Result<()> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::get_oidc_refresh_token

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.

Arguments
  • token_hash - SHA-256 hex digest of the opaque token.
Returns

Result<Option<(String, i64, String)>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::revoke_oidc_refresh_token

pub async fn revoke_oidc_refresh_token(&self, token_hash: &str) -> Result<bool>

Marks a refresh token revoked; returns whether a row was updated.

Arguments
  • token_hash - SHA-256 hex digest of the opaque token.
Returns

Result<bool> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::list_security_audit_events

pub async fn list_security_audit_events(
    &self,
    limit: u64,
) -> Result<Vec<SecurityAuditEvent>>

List recent security audit events (newest first).

Errors

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).

Errors

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.

Arguments
  • identity_id - Portal identity id.
Returns

Result<Vec<crate::models::AccountLinkRecord>> — Ok on success.

Errors

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).

Errors

Returns an error when the operation fails.

LibraryStore::upsert_book

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.

Returns

The account's title, as acquire reads it.

Errors

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.

LibraryStore::update_book_metadata

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.

Errors

Returns LibraryError::Invalid when book has no plugin key or fails listing validation, or the database error.

LibraryStore::upsert_scanned_title

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.

Returns

The account's title, as acquire reads it.

Errors

As Self::upsert_book.

LibraryStore::upsert_scanned_titles

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.

Returns

How many of titles were recorded.

Errors

Returns LibraryError::Invalid when a title has no plugin key; nothing is written then.

LibraryStore::held_title

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.

Errors

Returns LibraryError::Conflict when the match is ambiguous, or the database error.

LibraryStore::held_title_in

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.

Errors

Returns LibraryError::Conflict when the match is ambiguous, or the database error.

LibraryStore::has_held_titles

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.

Errors

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.

LibraryStore::update_user_fields

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.

Errors

Returns LibraryError::NotFound when the account holds no title title_id names, LibraryError::Conflict when the name is ambiguous, or the database error.

LibraryStore::set_pdf_status

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.

Arguments
  • 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.
Errors

Returns LibraryError::NotFound when the account holds no such title, LibraryError::Conflict when the name is ambiguous, or the database error.

LibraryStore::set_holding_pdf_status

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.

Arguments
  • holding_id - The account holding that wrote the state.
  • status - The new PDF state.
  • pdf_storage_key - Object-storage key for the companion PDF.
Errors

Returns LibraryError::NotFound when no account holding has that id, or the database error.

LibraryStore::is_ignored

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.

Arguments
  • title_id - Product id / ASIN / ISBN used as the title key.
  • account_id - Store account id.
Returns

Result<bool> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::set_ignored

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.

Arguments
  • 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.
Returns

Result<()> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::set_acquire_status

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.

Arguments
  • 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.
Errors

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.

LibraryStore::set_holding_acquire_status

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.

Arguments
  • 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.
Errors

Returns LibraryError::NotFound when no account holding has that id or it no longer holds the edition, or the database error.

LibraryStore::bulk_set_acquire_status

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.

Returns

How many titles were written.

Errors

Returns the first read or write error; titles written before it stay written.

LibraryStore::list_saved_filters

pub async fn list_saved_filters(&self) -> Result<Vec<SavedFilterRecord>>

List saved quick-filter expressions.

Errors

Returns an error when the operation fails.

LibraryStore::upsert_saved_filter

pub async fn upsert_saved_filter(
    &self,
    name: &str,
    query: &str,
) -> Result<SavedFilterRecord>

Inserts or replaces a named saved library filter query.

Arguments
  • name - Logical name (filter, secret, …).
  • query - Saved filter query string.
Returns

Result<SavedFilterRecord> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::get_saved_filter

pub async fn get_saved_filter(&self, name: &str) -> Result<Option<SavedFilterRecord>>

Loads a saved filter by name, if present.

Arguments
  • name - Logical name (filter, secret, …).
Returns

Result<Option<SavedFilterRecord>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::delete_saved_filter

pub async fn delete_saved_filter(&self, name: &str) -> Result<()>

Deletes a saved filter by name.

Arguments
  • name - Logical name (filter, secret, …).
Returns

Result<()> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::count_works_by_status

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.

Returns

The count for each AcquireStatus and the total. A row with a status this build does not know is counted in the total only.

Errors

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.

LibraryStore::upsert_listening_progress

pub async fn upsert_listening_progress(
    &self,
    row: &NewListeningProgress,
) -> Result<ListeningProgressRecord>

Inserts or updates listening progress for a title.

Arguments
  • row - row argument for this call.
Returns

Result<ListeningProgressRecord> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::get_listening_progress

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.

Arguments
  • provider - External provider id.
  • external_user_id - User id at the external provider.
  • external_item_id - external_item_id argument for this call.
Returns

Result<Option<ListeningProgressRecord>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::list_listening_progress

pub async fn list_listening_progress(
    &self,
    external_user_id: Option<&str>,
) -> Result<Vec<ListeningProgressRecord>>

Lists listening progress rows for an identity.

Arguments
  • external_user_id - User id at the external provider.
Returns

Result<Vec<ListeningProgressRecord>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::create_title_request

pub async fn create_title_request(
    &self,
    req: &NewTitleRequest,
) -> Result<TitleRequestRecord>

Creates a wishlist / title-request row.

Arguments
  • req - Insert / update request payload.
Returns

Result<TitleRequestRecord> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::create_title_request_for

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).

Arguments
  • req - Insert / update request payload.
  • work - The work (and edition) of a pooled listing the wish names, or None to resolve it from req.
Returns

The new wish, or the caller's open wish for the same work.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::upsert_title_request_sources

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.

Errors

Returns an error when the operation fails.

LibraryStore::list_title_request_sources

pub async fn list_title_request_sources(
    &self,
    title_request_id: i64,
) -> Result<Vec<TitleRequestSourceRecord>>

Lists per-storefront snapshots for a title request.

Arguments
  • title_request_id - title_request_id argument for this call.
Returns

Result<Vec<TitleRequestSourceRecord>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::find_open_wishlist

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.

Arguments
  • identity_id - The wisher's portal identity; None for the operator.
  • work_id - The work wished for.
Errors

Returns LibraryError::Orm when a read fails.

LibraryStore::list_wishlist

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).

Errors

Returns an error when the operation fails.

LibraryStore::list_global_request_queue

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.

Errors

Returns an error when the operation fails.

LibraryStore::get_title_request_by_uuid

pub async fn get_title_request_by_uuid(
    &self,
    uuid: &str,
) -> Result<Option<TitleRequestRecord>>

Loads a wishlist title-request row by UUID, if present.

Arguments
  • uuid - Book UUID.
Returns

Result<Option<TitleRequestRecord>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::list_title_requests

pub async fn list_title_requests(
    &self,
    status: Option<RequestStatus>,
) -> Result<Vec<TitleRequestRecord>>

Lists wishlist / title-request rows.

Arguments
  • status - Acquire or request status value.
Returns

Result<Vec<TitleRequestRecord>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::update_title_request_status

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.

Arguments
  • uuid - Book UUID.
  • status - Acquire or request status value.
  • resolved_edition_id - Edition that fulfilled the request, when it is now held.
Returns

Result<()> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::upsert_embedding

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.

Arguments
  • 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.
Returns

Result<()> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::get_embedding_vector

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.

Arguments
  • target_kind - Embedding target kind.
  • target_id - Embedding target id.
  • model - Embedding model id.
Returns

Result<Option<(String, Vec<u8>)>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::list_embeddings

pub async fn list_embeddings(
    &self,
    target_kind: &str,
    model: &str,
) -> Result<Vec<(String, Vec<u8>)>>

Lists embedding metadata rows (optionally filtered).

Arguments
  • target_kind - Embedding target kind.
  • model - Embedding model id.
Returns

Result<Vec<(String, Vec<u8>)>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::embedding_text_hash

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.

Arguments
  • target_kind - Embedding target kind.
  • target_id - Embedding target id.
  • model - Embedding model id.
Returns

Result<Option<String>> — Ok on success.

Errors

Returns a crate error when the database operation fails or inputs are invalid.

LibraryStore::get_user_preferences

pub async fn get_user_preferences(
    &self,
    subject_key: &str,
) -> Result<Option<UserPreferences>>

Load per-user GUI / Discover preferences by subject key.

Errors

Returns an error when the operation fails.

LibraryStore::get_user_preferences_or_default

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.

Errors

Returns an error when the operation fails.

LibraryStore::upsert_user_preferences

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).

Errors

Returns an error when the operation fails.

Implements: Clone, Debug

LostCopies

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

NewBook

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 example us, 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.

NewBook::needs_html_entity_decode

pub fn needs_html_entity_decode(&self) -> bool

True when any human-readable field may contain an HTML entity.

NewBook::decode_html_entities

pub fn decode_html_entities(&mut self)

Decode HTML entities in human-readable metadata fields (titles, etc.).

NewBook::minimal

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>

NewListeningProgress

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 to portal_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

NewTitleRequest

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 to portal_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 like title.
  • asin: Amazon ASIN the wisher gave, used like title.
  • isbn: ISBN-10/13 the wisher gave, used like title.
  • 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.

NewTitleRequest::needs_html_entity_decode

pub fn needs_html_entity_decode(&self) -> bool

Returns true when the string still contains HTML character entities.

NewTitleRequest::decode_html_entities

pub fn decode_html_entities(&mut self)

Decode HTML entities in human-readable fields.

Implements: Clone, Debug

NewTitleRequestSource

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); None keeps what the row already names.

NewTitleRequestSource::needs_html_entity_decode

pub fn needs_html_entity_decode(&self) -> bool

Returns true when the string still contains HTML character entities.

NewTitleRequestSource::decode_html_entities

pub fn decode_html_entities(&mut self)

Decode HTML entities in human-readable metadata fields.

Implements: Clone, Debug, Default

ProbedAudioFile

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; None for an upload or a copy this build cannot read.
  • probe: What the last probe found; None until the file has been probed.
  • stream: What the last probe found about the stream; all None until the file has been probed, or for a probe from before streams were stored.

Implements: Clone, Debug, Eq, PartialEq

QueueRank

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 most MAX_QUEUE_REASONS are stored.

Implements: Clone, Debug, PartialEq

SavedFilterRecord

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

ScannedTitle

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, without Self::listing, the listing it describes.
  • listing: The listing the plugin's structured record describes; None when only book is known.
  • is_explicit: Whether the store marks the edition explicit (adult) content: Some(true) explicit, Some(false) clean, None unknown. Kept on the listing (store_listings.is_explicit).

Implements: Clone, Debug, From<NewBook>

SeenObject

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; None when 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

StoreCallHit

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: The store_listings row 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

StoredCandidate

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

StoredDiscoverTaste

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

StoredFeed

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

StoredQueueRank

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

TitleHolding

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

UserBookFields

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

WishWork

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.id of the listing's resolution.
  • edition_id: editions.id the listing is an edition of.

Implements: Clone, Debug, Eq, PartialEq

NotifyCursor

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).

NotifyCursor::encode

pub fn encode(&self) -> String

The opaque token a page answer carries.

NotifyCursor::decode

pub fn decode(token: &str) -> Result<Self>

Reads a token made by Self::encode.

Errors

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

NotifyPage

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

NotifyQueueLimits

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

Enums

DbAtomicParams

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.id to delete.
  • SetUserStatus: Set users.status (active / disabled; last-owner guarded).

    • user_id: users.id to update.
    • status: Canonical status string (active or disabled).
  • SetUserPasswordHash: Set or clear the Argon2id password hash and bump security_version.

    • user_id: users.id to update.
    • password_hash: New hash, or null to clear.
  • SetUserRole: Set users.role (last-owner guarded on demotion).

    • user_id: users.id to 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 OAuth state parameter.
  • TakeWebauthnChallenge: Consume a one-time WebAuthn challenge (DELETE + expiry check).

    • challenge_id: Public ceremony id returned to the browser.
    • kind: register, login, or elevate.
  • 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 in resource_class for owner.

    • resource_class: Resource class wire string (network, …).
    • owner: Worker id stored as lease_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 to primary and set users.totp_enabled.

    • user_id: users.id to 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 as created_at on the primary row.
  • DisableUserTotp: Delete TOTP secrets and clear users.totp_enabled.

    • user_id: users.id to 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 with eventType.
    • 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 means json.
    • 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 holding edition_id.
    • edition_id: The edition whose edition_acquisitions row 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 with eventType.
    • 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 for owner.

    • owner: Worker id stored as lease_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 max running deliveries 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 retry when 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

CanonicalObject

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: Admitted CREATE TABLE / CREATE INDEX in 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-major DbValue cells.
  • Identity: Identity high-water for generated columns.
    • entries: Folded table name → high-water.

Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize

BackupReason

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

BackupResolve

pub enum BackupResolve {
    Id(String),
    Archive(PathBuf),
}

How resolve_backup_spec located a recovery point.

Variants

  • Id: Catalog id under backups/manifests/.
  • Archive: .tar.gz archive of one recovery point.

Implements: Clone, Debug

CanonicalRestoreKind

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

DatabaseUnitKind

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

EntityKind

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.

EntityKind::ALL

pub const ALL: [Self; 37] = _

Every kind, in declaration order.

EntityKind::as_str

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

LibraryError

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 OIDC client_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.

LibraryError::not_found

pub fn not_found(entity: EntityKind, id: impl Display) -> Self

A Self::NotFound for entity with the id id.

Arguments
  • entity - The kind of row that is missing.
  • id - The id that was asked for, as the caller names it.

LibraryError::missing

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).

LibraryError::from_db_err

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.

LibraryError::from_abi_err

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.

LibraryError::limit

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.

LibraryError::is_schema_apply_retryable

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>

AcquireStatus

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's error_message.

AcquireStatus::ALL

pub const ALL: [Self; 5] = _

Every status, in pipeline order (the edition_acquisitions.status CHECK lists the same strings).

AcquireStatus::as_str

pub fn as_str(self) -> &'static str

Returns the canonical snake_case / lowercase wire string.

AcquireStatus::parse

pub fn parse(s: &str) -> Option<Self>

Parses the canonical wire string; returns None when unknown.

AcquireStatus::to_classic

pub fn to_classic(self) -> i32

Classic EF LiberatedStatus integer.

AcquireStatus::from_classic

pub fn from_classic(status: i64) -> Self

Parse classic EF LiberatedStatus integer.

Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema

EnqueueOutcome

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 + running already equals max_pending.

Implements: Clone, Debug, Eq, PartialEq

EventStreamStart

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: Stored created_at text of the last row already read.
    • id: Event id of the last row already read.

Implements: Clone, Debug, Eq, PartialEq

JobKind

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: ABI JobRunner stream-copy vertical slice (plugin_copy).
  • PluginScheduled: One fire of a plugin's [triggers] crons schedule (plugin_scheduled), delivered to its scheduled(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 by JobPayload::node_id claims it.
  • SearchIndexRebuild: Rebuild one node's full-text search index from the library (search_index_rebuild); only the node named by JobPayload::node_id claims 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 by JobPayload::node_id to 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 by JobPayload::node_id to 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 row JobPayload::notify_delivery names, through its notifier instance (JobPayload::plugin_instance_id, also in JobPayload::requires), so only a node running that instance claims it.
  • Invalid: Terminal placeholder after an unreadable persisted command is rejected.

JobKind::ALL

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.

JobKind::as_str

pub fn as_str(self) -> &'static str

Returns the canonical snake_case wire string.

JobKind::parse

pub fn parse(s: &str) -> Option<Self>

Parses the canonical wire string; returns None when unknown.

JobKind::resource_class

pub fn resource_class(self) -> JobResourceClass

Resource class used for admission and worker concurrency.

JobKind::dedup_key

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

JobResourceClass

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).

JobResourceClass::as_str

pub fn as_str(self) -> &'static str

Returns the canonical snake_case wire string.

JobResourceClass::parse

pub fn parse(s: &str) -> Option<Self>

Parses the canonical wire string; returns None when unknown.

JobResourceClass::ALL

pub const ALL: &'static [&'static str] = _

Canonical wire strings for every known class.

Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

JobState

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.

JobState::as_str

pub fn as_str(self) -> &'static str

Returns the canonical snake_case wire string.

JobState::parse

pub fn parse(s: &str) -> Option<Self>

Parses the canonical wire string; returns None when unknown.

JobState::is_active

pub fn is_active(self) -> bool

True when the job may still be claimed or is executing.

JobState::is_terminal

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

JobTrigger

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.

JobTrigger::as_str

pub fn as_str(self) -> &'static str

Returns the canonical snake_case wire string.

JobTrigger::parse

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

PortalSessionKind

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 /player API. Its tokens live in player_card_tokens; the row's own token hash is never handed out.

PortalSessionKind::as_str

pub fn as_str(self) -> &'static str

Returns the column value.

PortalSessionKind::parse

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

PublishDomainEventOutcome

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

RequestStatus

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.

RequestStatus::as_str

pub fn as_str(self) -> &'static str

Returns the canonical snake_case / lowercase wire string.

RequestStatus::parse

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

UserRole

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).

UserRole::as_str

pub fn as_str(self) -> &'static str

Returns the canonical snake_case / lowercase wire string.

UserRole::parse

pub fn parse(s: &str) -> Option<Self>

Parses the canonical wire string; returns None when unknown.

UserRole::is_privileged

pub fn is_privileged(self) -> bool

Whether this role may provision users and manage the host library.

UserRole::can_elevate

pub fn can_elevate(self) -> bool

Whether this role may elevate to a short-lived Operator session.

UserRole::can_administer_owned_nodes

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

UserStatus

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.

UserStatus::as_str

pub fn as_str(self) -> &'static str

Returns the canonical snake_case / lowercase wire string.

UserStatus::parse

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

SchemaState

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).
  • Frozen: A frozen crate::migrations::HostMigrationStep is applied.
    • version: Frozen plan version (>= 1).
    • checksum: SHA-256 hex recorded for that frozen step.

SchemaState::display

pub fn display(&self) -> String

CLI / JSON display: uninitialized, unreleased@base<n>+<checksum>, frozen@<version>+<checksum>.

SchemaState::frozen_version

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.

SchemaState::unreleased_base_version

pub fn unreleased_base_version(&self) -> Option<i64>

Frozen base recorded on an unreleased database (0 = pre-v1).

SchemaState::checksum

pub fn checksum(&self) -> Option<&str>

Checksum when the database has applied Bookclerk schema.

Implements: Clone, Debug, Display, Eq, PartialEq

FacetValuesOf

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

WorkFacet

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 value explicit, which a patron scope that hides explicit books excludes. Not offered as a Library filter.

WorkFacet::ALL

pub const ALL: [Self; 9] = _

Every facet, in the order a work's values are written.

WorkFacet::as_str

pub fn as_str(self) -> &'static str

The stored facet value.

Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Hash, PartialEq, Serialize

WorkFilter

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 by facet_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 by facet_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: true for finished works, false for the rest.

Implements: Clone, Debug, Eq, PartialEq

WorkSort

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

HoldingHolder

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's users.id.

Implements: Clone, Debug, Eq, PartialEq

WorkTagSource

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.

WorkTagSource::as_str

pub fn as_str(self) -> &'static str

The stored value.

Implements: Clone, ComposeSchema, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize, ToSchema

OfferAudience

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.

OfferAudience::as_str

pub fn as_str(self) -> &'static str

The stored listing_offers.audience text.

OfferAudience::parse

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

ChapterCheck

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 to MAX_CHAPTER_TITLE_BYTES, an empty title becomes "Chapter n", and a depth that skips a level or passes MAX_CHAPTER_DEPTH is lifted. Starts out of order and too many chapters are still refused, because no repair keeps their meaning.

Implements: Clone, Copy, Debug, Eq, PartialEq

ChapterSource

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); None for 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

ChapterSourceKind

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.

ChapterSourceKind::ALL

pub const ALL: [Self; 7] = _

Every kind, in the order the stored values are documented.

ChapterSourceKind::as_str

pub fn as_str(self) -> &'static str

The stored spelling.

ChapterSourceKind::parse

pub fn parse(stored: &str) -> Option<Self>

Reads a stored spelling.

Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Display, Eq, Hash, PartialEq, Serialize, ToSchema

ChaptersOutcome

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

ClaimQuality

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.

ClaimQuality::ALL

pub const ALL: [Self; 7] = _

Every quality, in the order the stored values are documented.

ClaimQuality::as_str

pub fn as_str(self) -> &'static str

The stored spelling; empty for Self::None.

ClaimQuality::parse

pub fn parse(stored: &str) -> Option<Self>

Reads a stored spelling.

Implements: Clone, ComposeSchema, Copy, Debug, Eq, Hash, PartialEq, Serialize, ToSchema

MarkerKind

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

ProviderQuality

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

EventPruneStep

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 become expired (see LibraryStore::expire_unleased_event_deliveries).
  • TerminalDeliveries: Acked, rejected and expired deliveries past retention_days.
  • DeadLetters: Dead letters past dead_letter_retention_days.
  • StaleSubscriberNodes: Per-node subscriber heartbeats past their TTL.
  • EmptyEvents: Dispatched events past retention_days with no deliveries left.

EventPruneStep::ALL

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

PinOutcome

pub enum PinOutcome {
    Moved { from: String },
    Unchanged,
    UnknownListing,
    UnknownEdition,
}

What LibraryStore::pin_listing did.

Variants

  • Moved: The listing now sells the pinned edition; it sold from before.
    • 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

DownloadStarter

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

PlaybackEvent

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).

PlaybackEvent::ALL

pub const ALL: [Self; 3] = _

Every event, in the order of a listen.

PlaybackEvent::as_str

pub fn as_str(self) -> &'static str

The event type plugins subscribe to.

Implements: Clone, Copy, Debug, Eq, PartialEq

PlayerKind

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.

PlayerKind::ALL

pub const ALL: [Self; 3] = _

Every kind, in stored order (the playback_sessions.client_kind CHECK list).

PlayerKind::as_str

pub fn as_str(self) -> &'static str

The stored spelling.

PlayerKind::parse

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

PlayerKindParam

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

KvPutOutcome

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: value exceeds max_value_bytes.
    • len: Bytes offered.
    • max: Namespace cap.
  • KeyLimitReached: The namespace already holds max_keys other live keys.
    • max: Namespace cap.

Implements: Clone, Debug, Eq, PartialEq

RecordPruneStep

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 by consumed_at until 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 than TOKEN_HISTORY_DAYS ago.
  • UserInvites: User invites expired more than TOKEN_HISTORY_DAYS ago.
  • EnrollmentLinks: Node enrollment links expired more than TOKEN_HISTORY_DAYS ago.
  • UploadSessions: Committed or aborted uploads expired more than UPLOAD_HISTORY_DAYS ago.
  • 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 for STORAGE_SCAN_STALE_DAYS, with their rows.
  • SecurityAudit: Security audit events older than AUDIT_RETENTION_DAYS.
  • ConfigurationAudit: Configuration audit rows older than AUDIT_RETENTION_DAYS.
  • ConfigurationChanges: Configuration change notices older than CONFIGURATION_CHANGE_RETENTION_DAYS.
  • Notifications: Notifications older than crate::notifications::NOTIFICATION_RETENTION_DAYS, with their inbox entries and delivery-log rows.

RecordPruneStep::ALL

pub const ALL: [Self; 13] = _

Every step, in the order a maintenance pass runs them.

Implements: Clone, Copy, Debug, Eq, PartialEq

FieldEdit

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

SplitOutcome

pub enum SplitOutcome {
    Split { work_id: String },
    UnknownWork,
    BadCount,
    NotOfWork(Vec<String>),
    WouldEmpty,
}

What LibraryStore::split_work did.

Variants

  • Split: The expressions now belong to work_id, a new work.
    • work_id: The new work.
  • UnknownWork: No work has this id.
  • BadCount: No expression was named, or more than MAX_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

CopyState

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 failed MAX_COPY_ATTEMPTS times in a row and is no longer retried on its own.
  • Missing: The destination's file disappeared outside Bookclerk and output.missing_files is mark_missing: the copy is left alone until an acquire of the title writes it again.

CopyState::ALL

pub const ALL: [Self; 4] = _

Every state, in stored order (the edition_copies.state CHECK list).

CopyState::as_str

pub fn as_str(self) -> &'static str

The stored spelling.

CopyState::parse

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

DiscoverSubject

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, by users.id.
  • Portal: A portal identity that has no first-party user, by portal_identities.id.

DiscoverSubject::parse

pub fn parse(key: &str) -> Option<Self>

Parses a stored subject key (operator, user:<id>, portal:<id>).

Returns

None for any other text, including a non-numeric or negative id.

DiscoverSubject::key

pub fn key(&self) -> String

The subject's stored key, the inverse of Self::parse.

Implements: Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd

FeedState

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.

FeedState::ALL

pub const ALL: [Self; 4] = _

Every state, in stored order (the destination_feeds.feed_state CHECK list).

FeedState::as_str

pub fn as_str(self) -> &'static str

The stored spelling.

FeedState::parse

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

FileOwner

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.

FileOwner::kind

pub fn kind(&self) -> &'static str

The stored owner_kind.

FileOwner::id

pub fn id(&self) -> &str

The stored owner_id.

Implements: Clone, Debug, Eq, Ord, PartialEq, PartialOrd

FileRole

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.

FileRole::ALL

pub const ALL: [Self; 8] = _

Every role, in stored order (the edition_files.role CHECK list).

FileRole::as_str

pub fn as_str(self) -> &'static str

The stored spelling.

FileRole::parse

pub fn parse(stored: &str) -> Self

The role a stored spelling names; Self::Sidecar for an unknown one, the role that gates nothing.

FileRole::for_key

pub fn for_key(key: &str, primary: Option<&str>) -> Self

The role of the file at key, from its extension.

Arguments
  • key - The storage key.
  • primary - The edition's primary audio key, when known: another audio file is then a Self::Part. Without it every audio file is Self::Audio.

Implements: Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd

HoldingSelection

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's removed ids).
  • UnseenBy: The account's holdings that the scan pass pass_id did not list.
  • All: Every holding of the account (it was revoked).

Implements: Clone, Debug, Eq, PartialEq

NodeHoldingSelection

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 pass pass (the node's catalog_pass_started_at) did not name, while that pass is still the node's and fence still 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 while fence is 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), while fence is 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

SeedScope

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).

SeedScope::as_str

pub fn as_str(self) -> &'static str

Wire and column text (own, household).

SeedScope::parse

pub fn parse(text: &str) -> Option<Self>

Parses Self::as_str text; anything else is None.

Implements: Clone, Copy, Debug, Eq, PartialEq

Functions

migrate_library_backend

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.

Arguments

  • source - Existing library backend to read from.
  • dest - Target backend to write into (must already be migrated).
  • opts - Dry-run / force behavior.

Returns

Per-table row counts copied (or that would be copied when dry_run).

Errors

Returns LibraryError when the destination is non-empty without force, or when any read/write fails.

restore_backup_unit

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.

Errors

Returns when validation fails, the adapter cannot provide complete unit replacement, a bind/payload/request budget is exceeded, or DDL/DML cannot be applied.

library_ddl_for_schema_state

pub fn library_ddl_for_schema_state(state: &SchemaState) -> Result<String>

Library DDL that matches state, not necessarily this binary's latest pack.

Errors

Returns when the database is uninitialized, checksums do not match, or a frozen version is unknown to this binary.

sort_tables_by_foreign_keys

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.

Errors

Returns when the FK graph contains a cycle.

verify_recovery_point

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.

Errors

Returns when the manifest is malformed, an object is missing/corrupt, schema is not fully admitted, or typed cells violate the contract.

admit_canonical_schema

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.

Errors

Returns when the packer rejects sql or any statement is not admitted.

admit_canonical_statements

pub fn admit_canonical_statements(
    sql_contract_version: u32,
    statements: &[&str],
) -> Result<CanonicalDatabaseSchema>

Admits already-separated canonical CREATE TABLE / CREATE INDEX statements.

Errors

Returns when any statement is not admitted Bookclerk SQL.

apply_admitted_sql

pub async fn apply_admitted_sql(
    db: &DatabaseConnection,
    statements: &[&str],
    kind: CanonicalRestoreKind,
) -> Result<()>

Applies admitted canonical DDL plus binding companions (tests / bootstrap).

Errors

Returns when a statement fails.

archive_backup

pub fn archive_backup(files_dir: &Path, id: &str, dest: &Path) -> Result<()>

Packages one recovery point (manifest + referenced objects) as .tar.gz.

Errors

Returns when the destination cannot be written or objects are missing.

backup_library

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.

Errors

Returns when the files dir cannot be written, capture fails, or a requested plugin binding is missing from BackupRequest::plugin_units.

extract_backup_archive

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.

Errors

Returns when the archive is missing, malformed, a path escapes dest, or an extract budget would be exceeded.

filter_library_pack_ddl

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.

Errors

Returns when a non-empty statement is neither admitted DDL nor seed DML.

library_canonical_schema

pub fn library_canonical_schema() -> Result<CanonicalDatabaseSchema>

Admitted library schema for this binary's current pack (frozen ups + unreleased).

Errors

Returns when current canonical SQL is not fully admitted.

library_canonical_schema_for_state

pub fn library_canonical_schema_for_state(
    state: &SchemaState,
) -> Result<CanonicalDatabaseSchema>

Admitted library schema for state.

Errors

Returns when DDL cannot be resolved or is not fully admitted.

list_backups

pub fn list_backups(files_dir: &Path) -> Result<Vec<BackupListEntry>>

Lists published recovery points oldest-first.

Errors

Returns when the repository cannot be opened.

plugin_canonical_schema_from_ddl_catalog

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.

Errors

Returns when the DDL catalog is missing, incomplete, or malformed.

prune_automatic_backups

pub fn prune_automatic_backups(files_dir: &Path) -> Result<usize>

Deletes oldest automatic pre-migrate recovery points. Never deletes manual.

Errors

Returns when a manifest cannot be unlinked.

resolve_backup_spec

pub fn resolve_backup_spec(files_dir: &Path, spec: &str) -> Result<BackupResolve>

Resolves a recovery-point id, timestamp prefix, or archive path.

Errors

Returns when no complete backup matches or the spec is ambiguous.

restore_backup

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.

Errors

Returns when the backup is unsupported, an object is missing/corrupt, or library replace fails. Destructive SQL starts only after complete preflight.

restore_backup_in_repo

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.

Errors

Same as restore_backup.

apply_binding_bootstrap

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.

Errors

Returns when schema apply or the binding state machine fails closed.

binding_bootstrap_plan

pub fn binding_bootstrap_plan(state: &SchemaState) -> Result<Option<Vec<String>>>

Statements to apply for state, or None when the binding already matches.

Errors

Returns when state is a checksum/base mismatch or an unexpected frozen binding (this binary has no frozen binding plan).

db_atomic_operation_id

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.

db_atomic_request_hash

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.

Errors

Returns an error when the operation fails.

execute_db_atomic

pub async fn execute_db_atomic(
    db: &DatabaseConnection,
    compiled: CompiledAtomic,
) -> Result<DbAtomicResult>

Runs a compiled named atomic as one native SQL transaction.

Errors

Returns LibraryError for engine failures. Application outcomes (lastOwner, empty, …) are returned as DbAtomicResult, not errors.

execute_named_atomic

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.

Errors

Returns LibraryError for engine failures or invalid named operations.

apply_host_schema

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.

Errors

Returns LibraryError when a version read or DDL statement fails, the database is newer than this binary, or a frozen checksum does not match.

apply_host_schema_with_batch

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.

Errors

Returns LibraryError when a version read, DDL statement, or batch fails.

apply_host_schema_with_batch_opts

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.

Errors

Returns LibraryError when a version read, backup, DDL, or batch fails.

apply_host_schema_with_options

pub async fn apply_host_schema_with_options(
    db: &DatabaseConnection,
    opts: SchemaApplyOptions,
) -> Result<()>

Applies pending host schema with optional in-place backups.

Errors

Returns LibraryError when a version read, backup, or DDL statement fails.

current_schema_state

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.

Errors

Returns LibraryError::Schema on malformed, partial, or contradictory markers.

current_schema_state_in

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.

Errors

Returns LibraryError::Schema on malformed, partial, or contradictory markers.

current_schema_version

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.”

Errors

Returns when the state query fails or the marker is malformed.

ensure_restore_target_is_replaceable

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.

Errors

Returns LibraryError::Schema when the target is newer or uninterpretable.

migrate_host_schema_to

pub async fn migrate_host_schema_to(
    db: &DatabaseConnection,
    target: i64,
    opts: SchemaApplyOptions,
) -> Result<SchemaWalk>

Migrates toward target, including reversible downs for CLI rollback.

Errors

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).

migrate_host_schema_to_with_batch

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.

Errors

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.

require_schema_migrations

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.

Errors

Returns LibraryError::Other when schemaMigrations is missing.

schema_state_compatible

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.

apply_plugin_migrations

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.

Errors

Returns when prefix verification fails, apply exhausts retries, or the journal is contradictory.

history_from_execute_reply

pub fn history_from_execute_reply(reply: &ExecuteReply) -> Result<PluginMigrationHistory>

Parses journal rows from a typed select reply.

Errors

Returns when row shape or ordinals are invalid.

load_plugin_migration_history

pub async fn load_plugin_migration_history(
    db: &DatabaseConnection,
) -> Result<PluginMigrationHistory>

Reads the host-private plugin migration journal.

Errors

Returns when the journal cannot be read or ordinals are not contiguous.

next_pending_plugin_migration

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.

Errors

Returns require_history_prefix errors.

plugin_apply_statements

pub fn plugin_apply_statements(
    ordinal: i64,
    migration: &ProvenPluginMigration,
) -> Vec<String>

One atomic apply unit: serialization slot, registered ops, host journal append.

plugin_binding_type_env

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.

plugin_history_session_matches

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.

Errors

Returns when the digest differs (peer advanced or rewritten history).

plugin_journal_has_entry

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.

plugin_journal_select_request

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.

prove_plugin_migration_sequence

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.

Errors

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.

require_history_prefix

pub fn require_history_prefix(
    history: &PluginMigrationHistory,
    registered: &PluginMigrationSequence,
) -> Result<()>

Fail closed unless durable history is an exact prefix of registered.

Errors

Returns when an applied id/checksum/order does not match, or durable history is longer than the current registration (older/incompatible plugin).

sql_string_literal

pub fn sql_string_literal(value: &str) -> String

SQL string literal with ' doubled.

branch_request_dedup_key

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).

catalog_subscribers_for_event

pub fn catalog_subscribers_for_event(
    catalog: &[EventSubscriberCatalogRecord],
    event: &DomainEventRecord,
) -> Vec<EventSubscriber>

Enabled catalog rows that match event type, schema version, and filter.

collapse_live_subscriber_nodes

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).

content_kind_from_classic

pub fn content_kind_from_classic(content_type: i64) -> String

Map classic EF ContentType to bookclerk content_kind.

content_kind_to_classic

pub fn content_kind_to_classic(content_kind: &str) -> i32

Classic EF ContentType enum value.

event_filter_matches

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.

event_matches_wake_grants

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.

intersect_event_filters

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.

is_downloadable

pub fn is_downloadable(content_kind: &str) -> bool

True when the title can be downloaded (classic WithoutParents).

is_valid_queue_name

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.

job_backoff_run_after

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).

normalize_theme

pub fn normalize_theme(raw: &str) -> String

Canonical appearance preference; unknown values become system.

plugin_scheduled_dedup_key

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).

portal_prefs_key

pub fn portal_prefs_key(identity_id: i64) -> String

Subject key for a portal identity (legacy; prefer user_prefs_key).

push_queue_wisher

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.

Arguments

  • wishers - Accumulated people for this work.
  • wisher - Person who has this title on an open wishlist.

queue_name_or_bus

pub fn queue_name_or_bus(name: &str) -> &str

Resolves an optional queue name: empty means CORE_EVENTS_QUEUE.

subscription_matches_event

pub fn subscription_matches_event(
    sub: &EventCatalogSubscription,
    event: &DomainEventRecord,
) -> bool

True when one catalog subscription matches event type, schema, class, and filter.

user_prefs_key

pub fn user_prefs_key(user_id: i64) -> String

Subject key for a first-party user.

wake_grants_from_subscriptions

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".

Errors

Returns a static reason when the type is undeclared or the requested filter cannot intersect any declared filter.

plan_schema_walk

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.

Errors

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.

plan_schema_walk_from_state

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.

Errors

Returns LibraryError::Schema when an unreleased database is asked to become a frozen revision, or when plan_schema_walk fails.

classify_session_client

pub fn classify_session_client(
    user_agent: Option<&str>,
    is_api: bool,
) -> SessionClientInfo

Classify a User-Agent (or missing UA for API/bearer clients).

Arguments

  • user_agent - Optional User-Agent header value.
  • is_api - When true (no browser UA / bearer-style client), label as API.

Panics

Panics when an internal invariant does not hold.

compile_claim_event_delivery

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.

Errors

Returns DbErr::Custom when wrapping the plan fails.

compile_named_request

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.

Errors

Returns DbErr::Custom when the named operation is missing or invalid.

interpret_typed_exec

pub fn interpret_typed_exec(
    compiled: &CompiledAtomic,
    reply: &ExecuteReply,
    expected_hash: &str,
) -> DbAtomicResult

Maps a typed ExecuteReply onto a host DbAtomicResult.

validate_execute_reply

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.

Errors

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.

validate_streamed_execute_reply

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.

Errors

As validate_execute_reply.

facet_key

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.

Arguments

  • value - A value as shown or as a client sent it.

sort_title

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.

Arguments

  • title - The display title.

normalize_work_tags

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.

Errors

Returns LibraryError::Invalid for more than MAX_WORK_TAGS tags or a tag longer than MAX_WORK_TAG_BYTES.

parse_work_tags_request

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.

Errors

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.

apply_user_states

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).

Arguments

  • titles - Titles to fill, as LibraryStore::taste_titles returns them.
  • states - Stored state rows for the titles' works.
  • users - Whose state counts; empty for everyone's.

resolve_chapters

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.

parse_chapter_edit_request

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.

Errors

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.

parse_chapter_pin_request

pub fn parse_chapter_pin_request(body: &[u8]) -> Result<ChapterPinRequest>

Parses and checks a pin body from its raw bytes, sans IO.

Errors

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.

copy_retry_delay

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.

deliver_after_for

pub fn deliver_after_for(spec: &PublishDomainEventSpec, now: &str) -> String

RFC 3339 earliest delivery time for spec; empty when it may deliver now.

prepare_publish_domain_event

pub fn prepare_publish_domain_event(
    spec: PublishDomainEventSpec,
) -> Result<PublishDomainEventSpec>

Mint an event id when empty and reject oversized or blank publish fields.

Errors

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.

fallback_work_key

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.

inject_dispatch_page_failures

pub fn inject_dispatch_page_failures(n: u32)

Fail after the next n successful dispatch pages (tests only).

call_number

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.

edition_id_for_listing

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.

holding_from_book

pub fn holding_from_book(book: &NewBook) -> HoldingDraft

The holding a flat library row describes.

listing_from_book

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.

Errors

Returns resolve::ListingError when the row fails listing validation.

reaches_end

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.

Arguments

  • position - Where the listener is.
  • duration - The recording's whole runtime; a zero duration is unknown and never finished.

parse_bookmark_edit_request

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.

Errors

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.

parse_new_bookmark_request

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.

Errors

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.

parse_open_session_request

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.

Errors

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.

parse_playback_sync_request

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.

Arguments

  • body - The request body.
  • close - True for the close route.

Errors

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.

parse_progress_cursor

pub fn parse_progress_cursor(token: &str) -> Option<ProgressCursor>

Parses the cursor of GET /api/playback/progress, sans IO.

Arguments

  • token - The query value as sent.

Returns

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.

parse_progress_edit_request

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.

Errors

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.

parse_track_path

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.

Arguments

  • session_id - The {id} part as sent.
  • index - The {n} part as sent.

Returns

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.

progress_cursor_token

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.

plan_pass

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.

Arguments

  • state - The stored row, None before the account's first pass.
  • now - The current time.

set_dispatch_chunk_for_test

pub fn set_dispatch_chunk_for_test(chunk: Option<usize>)

Override subscribers-per-plan for dispatch paging tests.

parse_work_split_request

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.

Errors

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.

derive_claim_password_fingerprint

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.

derive_claim_session_token

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.

Arguments

hash_token

pub fn hash_token(raw: &str) -> String

SHA-256 hex digest of a raw ticket/session token for durable storage.

Arguments

  • raw - Opaque plaintext token; callers must not persist this value.

Returns

Lowercase hex SHA-256 digest (64 characters).

parse_claim_redeem_nonce

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.

Errors

Returns an error when the value is missing, the wrong length, or not hex.

apply_merged_sources

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.

Arguments

  • row - Wishlist title-request record whose sources snapshots are merged.

pick_better_description

pub fn pick_better_description(a: Option<&str>, b: Option<&str>) -> Option<String>

Prefer HTML blurbs over plain text; otherwise the longer string wins.

Arguments

  • a - First candidate description (may be HTML or plain).
  • b - Second candidate description.

Returns

The richer non-empty description, or None when both are empty.

Type aliases

Result

pub type Result<T> = Result<T, LibraryError>;

Result alias for LibraryError.

InProcessSqliteAtomic

pub type InProcessSqliteAtomic = NamedAtomicBackend<InProcessSqlite>;

The crate::AtomicTxnBackend over a local SQLite connection.

Constants

LEFT_BEHIND_TABLES

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.

CHUNK_TARGET_UNCOMPRESSED_BYTES

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.

BACKUPS_DIR

pub const BACKUPS_DIR: &str = "backups";

Subdirectory of $BOOKCLERK_FILES_DIR holding the backup repository.

BACKUP_FORMAT_VERSION

pub const BACKUP_FORMAT_VERSION: u32 = 1;

Manifest format written by this binary.

BACKUP_RETENTION

pub const BACKUP_RETENTION: usize = 5;

Automatic pre-migrate recovery points retained after prune.

LIBRARY_SKIP_TABLES

pub const LIBRARY_SKIP_TABLES: &[&str] = _;

Library registry rows are environment-local (unit_ref is not portable).

MIGRATION_LEASE_TTL

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.

MIGRATION_LEASE_WAIT

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.

BOOKCLERK_SCHEMA_NAMESPACE

pub const BOOKCLERK_SCHEMA_NAMESPACE: &str = "bookclerk";

Ledger namespace for host library schema and Bookclerk-owned binding bootstrap.

MAX_PLUGIN_MIGRATION_APPLY_ATTEMPTS

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.

CORE_EVENTS_QUEUE

pub const CORE_EVENTS_QUEUE: &str = "core.events";

Queue that carries the domain-event bus ([events] producers and consumers).

EDITION_ACQUIRE_CHANGED

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).

EVENT_DELIVERY_DEFAULT_RETENTION_SECS

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.

EVENT_DELIVERY_MAX_ATTEMPTS

pub const EVENT_DELIVERY_MAX_ATTEMPTS: i64 = 8;

Default max delivery attempts before dead-letter.

EVENT_RESOURCE_CLASS_NETWORK

pub const EVENT_RESOURCE_CLASS_NETWORK: &str = "network";

Default delivery resource class (network).

EVENT_SUBSCRIBER_HEARTBEAT_TTL_SECS

pub const EVENT_SUBSCRIBER_HEARTBEAT_TTL_SECS: i64 = 60;

Live catalog rows quieter than this many seconds are ignored at dispatch.

HOST_CONSUMER_PREFIX

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.

INGEST_BATCH_FINISHED

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).

JOB_PAYLOAD_VERSION

pub const JOB_PAYLOAD_VERSION: u32 = 1;

Current job command envelope version stored in JobPayload::v.

LISTENING_SYNCED

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).

MAX_QUEUE_NAME_LEN

pub const MAX_QUEUE_NAME_LEN: usize = 63;

Longest queue name.

MAX_QUEUE_WISHERS

pub const MAX_QUEUE_WISHERS: usize = 16;

Maximum distinct people serialized on a global-queue or Discover card.

NODE_QUEUE_PREFIX

pub const NODE_QUEUE_PREFIX: &str = "node.";

Prefix of the per-node queues (node.<node_id>) node subsystems consume.

OPERATOR_PREFS_KEY

pub const OPERATOR_PREFS_KEY: &str = "operator";

Subject key for the shared operator account.

QUEUE_CONTENT_TYPE_BYTES

pub const QUEUE_CONTENT_TYPE_BYTES: &str = "bytes";

Queue message body is raw bytes stored as base64 text.

QUEUE_CONTENT_TYPE_JSON

pub const QUEUE_CONTENT_TYPE_JSON: &str = "json";

Queue message body is UTF-8 JSON text.

QUEUE_CONTENT_TYPE_TEXT

pub const QUEUE_CONTENT_TYPE_TEXT: &str = "text";

Queue message body is plain UTF-8 text.

WISHLIST_CHANGED

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).

SCHEMA_STATE_FROZEN

pub const SCHEMA_STATE_FROZEN: &str = "frozen";

On-disk bookclerk_schema_migrations.state for a frozen plan version.

SCHEMA_STATE_UNRELEASED

pub const SCHEMA_STATE_UNRELEASED: &str = "unreleased";

On-disk bookclerk_schema_migrations.state for an unreleased development pack.

EVENT_STREAM_SCAN_FACTOR

pub const EVENT_STREAM_SCAN_FACTOR: usize = 8;

Rows one LibraryStore::read_event_stream call may examine per event it may return.

EVENT_STREAM_SETTLE_SECS

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.

LIBRARY_INDEX_LAYOUT

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.

MAX_WORK_TAGS

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).

MAX_WORK_TAG_BYTES

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.

CATALOG_LISTING_REFRESH

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.

MAX_CHAPTERS

pub const MAX_CHAPTERS: usize = 2000;

Most chapters one list holds, the same cap as a metadata file's (maxMetadataFileChapters in plugin.capnp).

MAX_CHAPTER_DEPTH

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.

MAX_CHAPTER_START_MS

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).

MAX_CHAPTER_TITLE_BYTES

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.

MAX_CHAPTER_EDIT_BYTES

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.

MAX_CHAPTER_PIN_BYTES

pub const MAX_CHAPTER_PIN_BYTES: usize = 1024;

Largest pin body the route reads, in bytes.

MAX_CHAPTER_SOURCE_ID_BYTES

pub const MAX_CHAPTER_SOURCE_ID_BYTES: usize = 256;

Longest source_id a pin names, in bytes; a PluginKey is far shorter.

MAX_CONFLICT_PAGE

pub const MAX_CONFLICT_PAGE: u64 = 200;

Largest conflicts page LibraryStore::list_resolution_conflicts reads.

MAX_BOOKMARKS_PER_EDITION

pub const MAX_BOOKMARKS_PER_EDITION: u64 = 200;

Most bookmarks one person keeps in one edition.

MAX_BOOKMARK_TITLE_BYTES

pub const MAX_BOOKMARK_TITLE_BYTES: usize = 200;

Longest bookmark title, in bytes (well inside the minimum database profile's cell size).

MAX_PLAYBACK_MS

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.

MAX_PLAYER_NAME_BYTES

pub const MAX_PLAYER_NAME_BYTES: usize = 64;

Longest player name a session stores, in bytes.

MAX_EDITION_ID_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.

MAX_PLAYBACK_BODY_BYTES

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.

MAX_PLAYBACK_SYNC_BYTES

pub const MAX_PLAYBACK_SYNC_BYTES: usize = 1024;

Largest sync body the routes read, in bytes; a real one is under 100.

MAX_PLAYBACK_TRACKS

pub const MAX_PLAYBACK_TRACKS: usize = 512;

Most tracks a play session lists: a stream path's index is below it.

MAX_PROGRESS_CURSOR_BYTES

pub const MAX_PROGRESS_CURSOR_BYTES: usize = 256;

Longest progress cursor token the route reads, in bytes; a real one is about 100.

MAX_PLAYER_PASSWORDS

pub const MAX_PLAYER_PASSWORDS: u64 = 20;

Most player passwords one patron keeps.

MAX_PLAYER_PASSWORD_LABEL_BYTES

pub const MAX_PLAYER_PASSWORD_LABEL_BYTES: usize = 64;

Longest player password label, in bytes.

PLAYER_ACCESS_TTL_SECS

pub const PLAYER_ACCESS_TTL_SECS: i64 = _;

Lifetime of a player card's access token.

PLAYER_REFRESH_GRACE_SECS

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).

PLAYER_REFRESH_TTL_DAYS

pub const PLAYER_REFRESH_TTL_DAYS: i64 = 30;

Lifetime of a player card's refresh token; each refresh starts it again.

KV_LIST_DEFAULT_LIMIT

pub const KV_LIST_DEFAULT_LIMIT: u32 = 100;

Default page size for LibraryStore::kv_list when the caller passes 0.

AUDIT_RETENTION_DAYS

pub const AUDIT_RETENTION_DAYS: i64 = 365;

Days security_audit_events and configuration_audit rows are kept.

CONFIGURATION_CHANGE_RETENTION_DAYS

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.

STORAGE_SCAN_STALE_DAYS

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.

TOKEN_HISTORY_DAYS

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.

UPLOAD_HISTORY_DAYS

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.

FULL_PASS_INTERVAL

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.

RESUME_CURSOR_TTL

pub const RESUME_CURSOR_TTL: Duration = _;

Longest time a stopped pass's cursor is resumed; an older one restarts the pass (store cursors expire).

MAX_SPLIT_EXPRESSIONS

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.

MAX_SPLIT_EXPRESSION_ID_BYTES

pub const MAX_SPLIT_EXPRESSION_ID_BYTES: usize = 64;

Longest expression id a split body may name, in bytes; ids are UUIDs.

ACQUIRED_KEYS_MAX_PAGE

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.

ACQUIRE_WRITER

pub const ACQUIRE_WRITER: &str = "acquire";

The writer of a key an acquire run on this node wrote.

COPY_RETRY_BASE_DELAY

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.

COPY_RETRY_MAX_DELAY

pub const COPY_RETRY_MAX_DELAY: Duration = _;

The longest delay between two background retries of one copy.

HOLDING_REMOVED

pub const HOLDING_REMOVED: &str = "holding_removed";

Event type published when a holding is removed.

MAX_COPY_ATTEMPTS

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.

MAX_QUEUE_REASONS

pub const MAX_QUEUE_REASONS: usize = 6;

Most taste reasons one stored row keeps, so a row stays small whatever the ranking explains.

OBJECT_TOMBSTONE_DAYS

pub const OBJECT_TOMBSTONE_DAYS: i64 = 30;

Days a removed object's tombstone is kept for readers that page changes.

MAX_NOTIFY_PAGE

pub const MAX_NOTIFY_PAGE: u64 = 200;

Most rows one page of the delivery log or the inbox returns.

CLAIM_REDEEM_NONCE_HEX_LEN

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