bookclerk_source

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

Last updated View as Markdown

Host-side content-source traits plus the storefront types guests share.

Audience

Host registration code and the plugin host adapter implementing ContentSource. The types a storefront guest also needs (DTOs, ABI conversions, listing / record helpers) live in the slim bookclerk_storefront crate and are re-exported here unchanged, so host code keeps importing them from bookclerk_source. Guests depend on bookclerk-storefront directly and never link this crate, which pulls in the library store and host configuration.

Product narrative: docs/plugins/README.md. Style: docs/contributing/code-documentation.md.

Item Kind Summary
ContentSource trait Pluggable audiobook storefront (auth, scan, fetch, catalog).
FetchOptions struct Options passed to crate::ContentSource::fetch_title.
DownloadOptions struct Options for acquire / fetch packaging and naming.
SourceRegistry struct Maps a registry address to an installed ContentSource.
PortalAuthMode enum How the connect portal authenticates this source.
revoke_credentials_default function Shared revoke path for plugins that seal as .plugin.auth (and legacy names).
source_scope function Opens the SourceScope for source: rows are isolated by its ContentSource::plugin_key and labelled with its ContentSource::id.

Re-exports

Modules

  • abi: Host-side conversions between storefront types and the typed plugin ABI.

Traits

ContentSource

pub trait ContentSource: Send + Sync {
    fn id(&self) -> &str;
    fn plugin_key(&self) -> &str;
    fn plugin_instance_id(&self) -> Option<&str>;
    fn guest_pid(&self) -> Option<u32>;
    fn display_name(&self) -> &str;
    fn aliases(&self) -> &'static [&'static str];
    fn portal_auth_mode(&self) -> PortalAuthMode;
    fn portal_brand(&self) -> SourceBrand;
    fn sort_key(&self) -> u32;
    fn login<'life0, 'life1, 'async_trait>(
        &'life0 self,
        scope: &'life1 SourceScope,
        opts: LoginOptions,
    ) -> Pin<Box<dyn Future<Output = Result<SourceAccount>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn login_with_oauth_progress<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        scope: &'life1 SourceScope,
        opts: LoginOptions,
        on_progress: &'life2 dyn Fn(OAuthProgress) + Send + Sync,
    ) -> Pin<Box<dyn Future<Output = Result<SourceAccount>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,;
    fn import_credentials<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        scope: &'life1 SourceScope,
        path: &'life2 Path,
        opts: ImportCredentialsOptions,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<SourceAccount>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,;
    fn revoke_credentials<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        scope: &'life1 SourceScope,
        account_id: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,;
    fn list_accounts<'life0, 'life1, 'async_trait>(
        &'life0 self,
        scope: &'life1 SourceScope,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<SourceAccount>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn scan<'life0, 'life1, 'async_trait>(
        &'life0 self,
        scope: &'life1 SourceScope,
        opts: ScanOptions,
    ) -> Pin<Box<dyn Future<Output = Result<ScanSummary>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn fetch_title<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
        &'life0 self,
        scope: &'life1 SourceScope,
        account_id: &'life2 str,
        title_id: &'life3 str,
        opts: &'life4 FetchOptions,
    ) -> Pin<Box<dyn Future<Output = Result<SourceFetch>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,
        'life3: 'async_trait,
        'life4: 'async_trait,;
    fn config_options(&self) -> &'static [SourceConfigOption];
    fn inspect_title<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
        &'life0 self,
        scope: &'life1 SourceScope,
        account_id: &'life2 str,
        title_id: &'life3 str,
        opts: &'life4 FetchOptions,
    ) -> Pin<Box<dyn Future<Output = Result<Value>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,
        'life3: 'async_trait,
        'life4: 'async_trait,;
    fn search_catalog<'life0, 'life1, 'async_trait>(
        &'life0 self,
        opts: &'life1 CatalogSearchOpts,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn catalog_detail<'life0, 'life1, 'async_trait>(
        &'life0 self,
        product_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<CatalogHit>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn answers_catalog_detail_by_product_id(&self) -> bool;
    fn answers_catalog_detail_by_isbn(&self) -> bool;
    fn catalog_detail_by_isbn<'life0, 'life1, 'async_trait>(
        &'life0 self,
        isbn: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<CatalogHit>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn expand_candidates<'life0, 'life1, 'async_trait>(
        &'life0 self,
        seed: &'life1 ExpandSeed,
        limit: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn purchase_hint<'life0, 'life1, 'async_trait>(
        &'life0 self,
        opts: &'life1 PurchaseHintOpts,
    ) -> Pin<Box<dyn Future<Output = Result<Option<SourcePurchaseHint>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn purchase_hints<'life0, 'life1, 'async_trait>(
        &'life0 self,
        opts: &'life1 [PurchaseHintOpts],
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Option<SourcePurchaseHint>>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn answers_price_by_isbn(&self) -> bool;
    fn answers_price_by_asin(&self) -> bool;
    fn acquire_pace(&self) -> AcquirePace;
    fn purchase_hint_answers<'life0, 'life1, 'async_trait>(
        &'life0 self,
        opts: &'life1 [PurchaseHintOpts],
    ) -> Pin<Box<dyn Future<Output = Result<Vec<PricedAnswer>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,;
    fn answers_quality_offers(&self) -> bool;
    fn quality_offers<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
        &'life0 self,
        scope: &'life1 SourceScope,
        account_id: &'life2 str,
        title_ids: &'life3 [String],
        download: &'life4 DownloadOptions,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Option<StreamQuality>>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,
        'life3: 'async_trait,
        'life4: 'async_trait,;
    fn list_deals<'life0, 'async_trait>(
        &'life0 self,
        limit: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
    where
        Self: 'async_trait,
        'life0: 'async_trait,;
}

Pluggable audiobook storefront (auth, scan, fetch, catalog).

Plugins own their id, brand, auth mode, and config parsing. Hosts register concrete crates at startup and talk only through this trait.

All credential and library mutations go through SourceScope, which forces source / provider to this plugin's id. First-party in-repo adapters and third-party JSON-RPC plugins share the same scope rules.

ContentSource::id

fn id(&self) -> &str

Display / CLI alias (audible, libro, …). Globally unique within one installation; durable identity is Self::plugin_key.

ContentSource::plugin_key

fn plugin_key(&self) -> &str

Provenance-qualified PluginKey when this adapter is an external guest.

Defaults to Self::id for in-crate test doubles.

ContentSource::plugin_instance_id

fn plugin_instance_id(&self) -> Option<&str>

Plugin instance that owns this deployed source.

None for transitional startup and in-crate adapters, which stay addressable by Self::plugin_key and Self::id. Two deployed instances of one key each return their own id.

ContentSource::guest_pid

fn guest_pid(&self) -> Option<u32>

Native guest pid when this process spawned the source.

None for in-process adapters and sources that have not recorded a pid.

ContentSource::display_name

fn display_name(&self) -> &str

Human-facing store name for UI / logs.

ContentSource::aliases

fn aliases(&self) -> &'static [&'static str]

Alternate ids accepted by CLI / config (libro.fm, ga, …).

ContentSource::portal_auth_mode

fn portal_auth_mode(&self) -> PortalAuthMode

Connect-portal auth mode.

ContentSource::portal_brand

fn portal_brand(&self) -> SourceBrand

Portal button brand (colors + favicon).

ContentSource::sort_key

fn sort_key(&self) -> u32

Stable sort key for registry listing (lower first).

ContentSource::login

fn login<'life0, 'life1, 'async_trait>(
    &'life0 self,
    scope: &'life1 SourceScope,
    opts: LoginOptions,
) -> Pin<Box<dyn Future<Output = Result<SourceAccount>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Authenticate and persist credentials via SourceScope.

ContentSource::login_with_oauth_progress

fn login_with_oauth_progress<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    scope: &'life1 SourceScope,
    opts: LoginOptions,
    on_progress: &'life2 dyn Fn(OAuthProgress) + Send + Sync,
) -> Pin<Box<dyn Future<Output = Result<SourceAccount>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,

Interactive OAuth login with progress (URL / waiting).

Default: ignores progress and calls Self::login. OAuth sources (Audible, external guests with login.start) override this.

ContentSource::import_credentials

fn import_credentials<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    scope: &'life1 SourceScope,
    path: &'life2 Path,
    opts: ImportCredentialsOptions,
) -> Pin<Box<dyn Future<Output = Result<Vec<SourceAccount>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,

Import credentials from a file (auth JSON, Libation export, …).

Default: unsupported. Audible implements auth-file / Libation / mkb79.

ContentSource::revoke_credentials

fn revoke_credentials<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    scope: &'life1 SourceScope,
    account_id: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,

Delete stored credentials for account_id (books / account rows kept).

Default: removes {account}.plugin.auth, any other source_auth secrets for the account, common legacy name patterns, and a Widevine {id}.wvd.

ContentSource::list_accounts

fn list_accounts<'life0, 'life1, 'async_trait>(
    &'life0 self,
    scope: &'life1 SourceScope,
) -> Pin<Box<dyn Future<Output = Result<Vec<SourceAccount>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

List accounts for this plugin (scope filters by source id).

ContentSource::scan

fn scan<'life0, 'life1, 'async_trait>(
    &'life0 self,
    scope: &'life1 SourceScope,
    opts: ScanOptions,
) -> Pin<Box<dyn Future<Output = Result<ScanSummary>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Sync library rows using scoped credentials / upserts.

ContentSource::fetch_title

fn fetch_title<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
    &'life0 self,
    scope: &'life1 SourceScope,
    account_id: &'life2 str,
    title_id: &'life3 str,
    opts: &'life4 FetchOptions,
) -> Pin<Box<dyn Future<Output = Result<SourceFetch>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    'life3: 'async_trait,
    'life4: 'async_trait,

Fetch everything needed to acquire one title (no storage writes).

title_id is the source-native product id (Audible ASIN or Libro ISBN). Auth is loaded through scope; opts.files_dir carries the BOOKCLERK_FILES_DIR path for CDM / Widevine resolution.

ContentSource::config_options

fn config_options(&self) -> &'static [SourceConfigOption]

Source-native [sources.<id>] knobs for config / UI discovery.

ContentSource::inspect_title

fn inspect_title<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
    &'life0 self,
    scope: &'life1 SourceScope,
    account_id: &'life2 str,
    title_id: &'life3 str,
    opts: &'life4 FetchOptions,
) -> Pin<Box<dyn Future<Output = Result<Value>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    'life3: 'async_trait,
    'life4: 'async_trait,

Optional diagnostic / license inspect for one title (opaque JSON).

Default: unsupported. Hosts must not special-case store APIs — sources that expose license dumps (e.g. Audible) override this.

ContentSource::search_catalog

fn search_catalog<'life0, 'life1, 'async_trait>(
    &'life0 self,
    opts: &'life1 CatalogSearchOpts,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Public catalog typeahead / search (no account required).

Default: empty. Discover aggregates hits across registered sources.

ContentSource::catalog_detail

fn catalog_detail<'life0, 'life1, 'async_trait>(
    &'life0 self,
    product_id: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<CatalogHit>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Fetch rich bibliographic metadata for one catalog product (no account).

Default: none. Used when search/expand hits are lean (e.g. HTML scrape) and a title detail dialog needs narrator, runtime, description, etc.

ContentSource::answers_catalog_detail_by_product_id

fn answers_catalog_detail_by_product_id(&self) -> bool

Whether Self::catalog_detail resolves this source's own product ids (the ids its search, expand and deals hits carry) to a full record: the guest's declared CatalogCapabilities.detailByProductId.

Catalog search and title dialogs ask a source for an edition it listed only when this is true, so a source without a detail lookup is never woken for one. Default: false.

ContentSource::answers_catalog_detail_by_isbn

fn answers_catalog_detail_by_isbn(&self) -> bool

Whether Self::catalog_detail_by_isbn resolves any audiobook ISBN to a full record (the guest's declared CatalogCapabilities.detailByIsbn).

Catalog search asks every source that returns true to fill lean result rows from other stores, instead of naming one storefront. Default: false.

ContentSource::catalog_detail_by_isbn

fn catalog_detail_by_isbn<'life0, 'life1, 'async_trait>(
    &'life0 self,
    isbn: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<CatalogHit>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Full catalog record for an ISBN, from a source that declares Self::answers_catalog_detail_by_isbn.

Default: Self::catalog_detail with the ISBN as the product id.

Errors

Returns the source's error; external guests soft-fail to Ok(None).

ContentSource::expand_candidates

fn expand_candidates<'life0, 'life1, 'async_trait>(
    &'life0 self,
    seed: &'life1 ExpandSeed,
    limit: usize,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Expand related / series / author candidates from a taste seed.

Default: empty. limit caps returned hits (sources may also budget HTTP).

ContentSource::purchase_hint

fn purchase_hint<'life0, 'life1, 'async_trait>(
    &'life0 self,
    opts: &'life1 PurchaseHintOpts,
) -> Pin<Box<dyn Future<Output = Result<Option<SourcePurchaseHint>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Resolve a purchase / catalog URL (optionally with live price).

Default: none.

ContentSource::purchase_hints

fn purchase_hints<'life0, 'life1, 'async_trait>(
    &'life0 self,
    opts: &'life1 [PurchaseHintOpts],
) -> Pin<Box<dyn Future<Output = Result<Vec<Option<SourcePurchaseHint>>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Resolve purchase hints for several titles in one call, one answer per query in order.

Default: Self::purchase_hint for each query, stopping at the first error. A store whose catalog prices many products per request overrides this to make one request. A SourceError::RateLimited error applies to the whole batch.

Errors

Returns the first query's error.

ContentSource::answers_price_by_isbn

fn answers_price_by_isbn(&self) -> bool

Whether Self::purchase_hint_answers prices a query with lookup = PriceLookup::Isbn by that exact ISBN (the guest's declared CatalogCapabilities.priceByIsbn).

Default: false, so the host never sends ISBN lookups.

ContentSource::answers_price_by_asin

fn answers_price_by_asin(&self) -> bool

Whether Self::purchase_hint_answers prices a query with lookup = PriceLookup::Asin by that exact ASIN (the guest's declared CatalogCapabilities.priceByAsin).

Default: false, so the host never sends ASIN lookups.

ContentSource::acquire_pace

fn acquire_pace(&self) -> AcquirePace

How fast the host may download from one store account of this storefront when it starts the downloads itself (the manifest's [acquire] table; see bookclerk_library::pacing).

Default: no budget, no gap, the host's default cool-down.

ContentSource::purchase_hint_answers

fn purchase_hint_answers<'life0, 'life1, 'async_trait>(
    &'life0 self,
    opts: &'life1 [PurchaseHintOpts],
) -> Pin<Box<dyn Future<Output = Result<Vec<PricedAnswer>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Self::purchase_hints with each query's title-search records (PricedAnswer::records), one answer per query in order.

Default: Self::purchase_hints with no records, so a caller falls back to the store's own pick. External guests override this to pass the records a PriceLookup::Title query returned.

Errors

As Self::purchase_hints.

ContentSource::answers_quality_offers

fn answers_quality_offers(&self) -> bool

Whether Self::quality_offers answers which stream an account would download today (the guest's declared CatalogCapabilities.qualityOffers).

Default: false, so the quality-upgrade check skips the store.

ContentSource::quality_offers

fn quality_offers<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
    &'life0 self,
    scope: &'life1 SourceScope,
    account_id: &'life2 str,
    title_ids: &'life3 [String],
    download: &'life4 DownloadOptions,
) -> Pin<Box<dyn Future<Output = Result<Vec<Option<StreamQuality>>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    'life3: 'async_trait,
    'life4: 'async_trait,

The stream account_id would download for each of title_ids (the store's product ids) today with download's fetch options, one answer per id in order; None where the store could not say. Nothing is licensed or downloaded.

Default: no answers.

Errors

Returns SourceError::RateLimited when the store asked to slow down, and another error when the credentials cannot be read or the call or its reply fails; either applies to the whole batch.

ContentSource::list_deals

fn list_deals<'life0, 'async_trait>(
    &'life0 self,
    limit: usize,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
where
    Self: 'async_trait,
    'life0: 'async_trait,

Current deals / promos for discovery shelves.

Default: empty.

Structs

FetchOptions

pub struct FetchOptions {
    pub download: DownloadOptions,
    pub cache_dir: PathBuf,
    pub files_dir: PathBuf,
    pub max_cache_bytes: Option<u64>,
    pub cancel: Option<Arc<AtomicBool>>,
}

Options passed to crate::ContentSource::fetch_title.

Fields

  • download: Packaging / naming knobs for this acquire (from [output] + destination).
  • cache_dir: Absolute directory for scratch downloads for this fetch.
  • files_dir: Root files directory (BOOKCLERK_FILES_DIR). Used for CDM / Widevine path resolution by Audible. Non-auth operations only; auth is loaded from the bookclerk_library::LibraryStore passed directly to the trait method.
  • max_cache_bytes: Optional on-disk budget for cache_dir (bytes). Sources should call Self::enforce_cache_budget between chunks.
  • cancel: Cooperative cancel for mid-fetch quota or a lost job fence.

FetchOptions::enforce_cache_budget

pub fn enforce_cache_budget(&self) -> Result<()>

Fails when cancel is set or cache_dir exceeds Self::max_cache_bytes.

Errors

Returns SourceError::Other when the fetch was cancelled or the cache directory is over the remaining scratch quota.

Implements: Clone, Debug

DownloadOptions

pub struct DownloadOptions {
    pub quality: AudioQuality,
    pub format: OutputFormat,
    pub widevine: bool,
    pub xhe_aac: bool,
    pub widevine_cdm: Option<PathBuf>,
    pub widevine_cdm_provider: Option<String>,
    pub naming_profile: NamingProfile,
    pub folder_template: Option<String>,
    pub file_template: Option<String>,
    pub download_cover: bool,
    pub download_pdf: bool,
    pub create_cue: bool,
    pub fixup_metadata: bool,
    pub keep_codec_in_m4b: bool,
    pub chapter_json: ChapterJsonMode,
    pub save_metadata_json: bool,
    pub cover_size: String,
    pub chapter_layout: String,
    pub overwrite_existing: bool,
    pub split_files_by_chapter: bool,
    pub split_mp3_max_mb: u32,
    pub chapter_file_template: Option<String>,
    pub chapter_title_template: Option<String>,
    pub minimum_file_duration_minutes: u32,
    pub combine_nested_chapter_titles: bool,
    pub merge_opening_and_end_credits: bool,
    pub strip_unabridged: bool,
    pub strip_audible_brand_audio: bool,
    pub download_clips_bookmarks: bool,
    pub retain_aax_file: bool,
    pub download_speed_limit_kbps: u32,
    pub lame: LameConfig,
    pub copies: Vec<OutputCopy>,
    pub opus: OpusSettings,
    pub max_sample_rate: Option<u32>,
    pub creation_time: FileTimestampMode,
    pub last_write_time: FileTimestampMode,
    pub replacement_characters: Vec<ReplacementRule>,
    pub path_limits: PathLimits,
    pub save_podcasts_to_parent_folder: bool,
}

Options for acquire / fetch packaging and naming.

Store-specific ingest knobs live on each crate::ContentSource instance (parsed from [sources.<id>] at registration). quality remains here so Audible’s download helpers can overlay the plugin bitrate for a single fetch.

Fields

  • quality: Optional per-fetch audio quality overlay (set by plugins that need it).
  • format: Post-download packaging format (M4B / MP3 / passthrough).
  • widevine: Prefer Widevine/CENC download when the store offers it.
  • xhe_aac: Prefer xHE-AAC on the Widevine path when offered.
  • widevine_cdm: Optional local Widevine .wvd path (absolute or under files dir).
  • widevine_cdm_provider: Remote L3 CDM provider URL (None = classic Libation AudibleCdm; empty/off = disable).
  • naming_profile: Path-template profile; per-field template overrides win when set.
  • folder_template: Optional folder-path template override; None uses the naming profile.
  • file_template: Optional file-stem template override; None uses the naming profile.
  • download_cover: When true, download a cover JPEG alongside audio.
  • download_pdf: When true, download a companion PDF when the store exposes one.
  • create_cue: When true, write a .cue sidecar from API chapters.
  • fixup_metadata: When true, embed tags, cover, and chapters after packaging.
  • keep_codec_in_m4b: When true, an M4B keeps Opus, FLAC, ALAC, E-AC-3 or AC-4 audio as it is instead of encoding it to AAC (output.keep_codec_in_m4b).
  • chapter_json: Which chapter JSON sidecars to write (off / flat / tree / both).
  • save_metadata_json: When true, persist raw catalog API JSON as metadata.json.
  • cover_size: Cover image size request (500, 1215, or native).
  • chapter_layout: Preferred Audible chapter API layout when fetching (tree or flat).
  • overwrite_existing: When true, re-acquire even if media already exists at the destination.
  • split_files_by_chapter: When true, also split packaged output into per-chapter files.
  • split_mp3_max_mb: Max MP3 part size in MiB when format is split_mp3_by_size.
  • chapter_file_template: Optional per-chapter file-stem template.
  • chapter_title_template: Optional embedded chapter-title template.
  • minimum_file_duration_minutes: Drop chapter splits shorter than this many minutes (0 = keep all).
  • combine_nested_chapter_titles: When true, flatten nested chapter titles into a single path segment.
  • merge_opening_and_end_credits: When true, merge opening/end credit chapters into adjacent chapters.
  • strip_unabridged: When true, strip an "Unabridged" suffix from titles used in naming.
  • strip_audible_brand_audio: When true, trim Audible brand intro/outro from the remux window.
  • download_clips_bookmarks: When true, download Audible clips/bookmarks sidecars when offered.
  • retain_aax_file: When true, keep the encrypted download in storage (RetainAaxFile).
  • download_speed_limit_kbps: Fetch speed cap in KB/s (0 = unlimited).
  • lame: LAME encoder knobs used when packaging to MP3.
  • copies: Further copies of each book beside the one Self::format and Self::lame make (output.copies).
  • opus: Opus encoder settings used when Self::format is opus: the main output's defaults, or an Opus copy's quality after Self::for_copy.
  • max_sample_rate: Optional ceiling for output sample rate in Hz (None = leave source rate).
  • creation_time: How to set the file creation / birth timestamp after acquire.
  • last_write_time: How to set the file last-write / mtime after acquire.
  • replacement_characters: Resolved find/replace rules the host applies to tag values when it fills a naming template.
  • path_limits: Length limits for the host keys naming templates build.
  • save_podcasts_to_parent_folder: Save podcast episodes under the parent show folder.

DownloadOptions::from_fetch_options

pub fn from_fetch_options(fetch: &FetchOptions) -> Self

Guest-side reconstruction: host defaults overlaid with the fetch knobs the host sent in abi::FetchTitleParams::fetch.

DownloadOptions::apply_fetch_options

pub fn apply_fetch_options(&mut self, fetch: &FetchOptions)

Overlays wire fetch knobs onto these options (packaging knobs untouched).

DownloadOptions::for_destination

pub fn for_destination(cfg: &Config, naming: &DestinationNaming, prefix: &str) -> Self

Build acquire options stamped for one output destination.

Packaging knobs come from global [output]; naming templates prefer the destination's own overrides, which a storage plugin may declare as [[settings]] and the host reads from the deployed instance document. prefix is that document's key prefix, which the host-key length budget leaves room for. The storage plugin translates each host key into the key it stores.

DownloadOptions::effective_output

pub fn effective_output(&self) -> OutputFormat

Resolved post-processing format.

DownloadOptions::copies_to_make

pub fn copies_to_make(&self) -> Vec<OutputCopy>

Every copy an acquire makes, the one Self::format and Self::lame make first (bookclerk_config::copies_to_make).

DownloadOptions::for_copy

pub fn for_copy(&self, copy: &OutputCopy) -> Self

The options packaging copy: its format and the encoder settings its quality gives, with chapter splitting on exactly for mp3_chapters.

DownloadOptions::wants_mp3

pub fn wants_mp3(&self) -> bool

True when the effective format re-encodes to MP3.

DownloadOptions::wants_split_by_chapter

pub fn wants_split_by_chapter(&self) -> bool

True when output should be split into per-chapter files.

DownloadOptions::is_noop_output

pub fn is_noop_output(&self) -> bool

True when store-delivered media is left as-is (no remux/transcode).

DownloadOptions::wants_opus

pub fn wants_opus(&self) -> bool

True when the effective format encodes to Ogg Opus.

DownloadOptions::wants_split_by_size

pub fn wants_split_by_size(&self) -> bool

True when output is split into MP3 parts by target size.

DownloadOptions::chapter_json_flat

pub fn chapter_json_flat(&self) -> bool

True when a flat chapters.flat.json sidecar should be written.

DownloadOptions::chapter_json_tree

pub fn chapter_json_tree(&self) -> bool

True when a nested chapters.tree.json sidecar should be written.

DownloadOptions::wants_chapter_json

pub fn wants_chapter_json(&self) -> bool

True when any chapter JSON sidecar should be written.

DownloadOptions::naming_templates

pub fn naming_templates(&self) -> ResolvedNamingTemplates

Resolve folder / file / chapter-file templates from the naming profile with per-field overrides.

Implements: Clone, Debug, Default, Deserialize<'de>, From<&Config>, From<&DownloadOptions>, From<&OutputConfig>, PartialEq, Serialize

SourceRegistry

pub struct SourceRegistry {
    /* private fields */
}

Maps a registry address to an installed ContentSource.

A deployed source is addressed by ContentSource::plugin_instance_id. A source with no instance id is addressed by ContentSource::plugin_key. A plugin key or display alias that several instances share routes to the plugin's default instance (see Self::set_default_instance); a job may pin another instance through Self::route. Nothing fails closed on a shared key: accounts belong to the plugin, so any instance may serve them.

SourceRegistry::new

pub fn new() -> Self

Empty registry with no sources registered.

SourceRegistry::register

pub fn register(&mut self, source: Arc<dyn ContentSource>)

Register (or replace) a source at its instance id, or its PluginKey.

A second instance of the same plugin key stays in the map. Re-registering the same instance id replaces that guest only.

SourceRegistry::remove_instance

pub fn remove_instance(&mut self, plugin_instance_id: &str) -> bool

Drops the source registered under plugin_instance_id.

Other instances of the same plugin key stay. Returns whether a row was removed.

SourceRegistry::set_default_instance

pub fn set_default_instance(&mut self, plugin_key: &str, plugin_instance_id: &str)

Names the instance a bare plugin key or alias routes to when several instances of plugin_key are registered.

SourceRegistry::default_instance

pub fn default_instance(&self, plugin_key: &str) -> Option<&str>

Default instance id recorded for plugin_key, if any.

SourceRegistry::get

pub fn get(&self, id_or_alias: &str) -> Option<Arc<dyn ContentSource>>

Look up a source by plugin instance id, PluginKey, or display alias.

An instance id matches that deployed source. A plugin key or alias shared by several instances of one plugin routes to the default instance, else the lowest instance id, so a bare key always resolves while any instance is registered. An alias that two different plugins claim is ambiguous and resolves to nothing: the caller names the PluginKey or an instance id instead.

SourceRegistry::route

pub fn route(
    &self,
    id_or_alias: &str,
    preferred_instance: Option<&str>,
) -> Option<Arc<dyn ContentSource>>

Self::get with an optional pinned instance.

preferred_instance must be a registered instance of the plugin that id_or_alias names; a pin for another plugin, or an unknown id, yields None rather than silently falling back.

SourceRegistry::require

pub fn require(&self, id_or_alias: &str) -> Result<Arc<dyn ContentSource>>

Look up a source or return crate::SourceError::Api when missing.

Errors

Returns an API error when id_or_alias is not registered.

SourceRegistry::require_routed

pub fn require_routed(
    &self,
    id_or_alias: &str,
    preferred_instance: Option<&str>,
) -> Result<Arc<dyn ContentSource>>

Self::require with an optional pinned instance.

Errors

Returns an API error when nothing is registered under id_or_alias, or when preferred_instance is not one of its instances.

SourceRegistry::resolve_id

pub fn resolve_id(&self, id_or_alias: &str) -> Option<String>

Resolve a needle to the canonical plugin id when registered.

SourceRegistry::all

pub fn all(&self) -> Vec<Arc<dyn ContentSource>>

All registered sources in stable plugin order.

SourceRegistry::routed

pub fn routed(&self) -> Vec<Arc<dyn ContentSource>>

One routed source per registered plugin key, in stable plugin order.

Accounts belong to the plugin, so a scan that visited every instance of one key would read and write the same rows twice. Bare-key routing picks the instance; a pinned job goes through Self::route.

SourceRegistry::scan_all

pub async fn scan_all(
    &self,
    library: &LibraryStore,
    opts: ScanOptions,
) -> Result<ScanSummary>

Scan every registered plugin once (honoring per-source account filters).

When opts.accounts is non-empty, each source only receives the subset of account needles that resolve to an account on that source. Sources with no matching accounts are skipped instead of failing the whole multi-source scan. ScanOptions::cancel is checked between sources.

Errors

Returns an error when the operation fails.

SourceRegistry::scan_one

pub async fn scan_one(
    &self,
    library: &LibraryStore,
    source: Arc<dyn ContentSource>,
    opts: ScanOptions,
) -> Result<ScanSummary>

Scan one registered source (a job pinned to a plugin instance).

Account filters apply as in Self::scan_all.

Errors

Returns an error when the scan fails or no account matches.

Implements: Clone, Default

Enums

PortalAuthMode

pub enum PortalAuthMode {
    Oauth,
    Password,
}

How the connect portal authenticates this source.

Variants

  • Oauth: Browser / QR OAuth (Audible).
  • Password: Username + password form.

PortalAuthMode::as_str

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

Wire / portal id (oauth or password).

Implements: Clone, Copy, Debug, Eq, PartialEq

Functions

revoke_credentials_default

pub async fn revoke_credentials_default(
    scope: &SourceScope,
    account_id: &str,
) -> Result<()>

Shared revoke path for plugins that seal as .plugin.auth (and legacy names).

Errors

Returns an error when the operation fails.

source_scope

pub fn source_scope(library: &LibraryStore, source: &dyn ContentSource) -> SourceScope

Opens the SourceScope for source: rows are isolated by its ContentSource::plugin_key and labelled with its ContentSource::id.

Every instance of one plugin shares this scope; accounts are not tied to a plugin instance.

Generated from crates/bookclerk-source at main · View as Markdown