bookclerk_config
Host configuration, files-dir layout, and logging for Bookclerk.
Host binaries (bookclerk, bookclerkd) and in-process host crates — not
guest plugins. Parses config.toml, applies env overrides, resolves
BOOKCLERK_FILES_DIR, and installs tracing / diagnostics.
Product narrative: docs/server/configuration.md, docs/server/diagnostics.md. Style:
docs/contributing/code-documentation.md.
| Item | Kind | Summary |
|---|---|---|
DatabaseConfig |
struct | Top-level [database] — selects the active backend plugin. |
DatabaseD1Config |
struct | Cloudflare D1 backend ([database.d1]). |
DatabasePostgresConfig |
struct | PostgreSQL backend ([database.postgres]). |
DatabaseSqliteConfig |
struct | Local SQLite destination ([database.sqlite]). |
BufferedEvent |
struct | Snapshot of a single redacted log event kept for crash / error uploads. |
DiagnosticsHandle |
struct | Process-global diagnostics handle installed by crate::logging::init_tracing_with. |
UploadPayload |
struct | JSON body POSTed to the diagnostics collector /submit endpoint. |
EventsConfig |
struct | [events] — outbox retention and local delivery-worker concurrency. |
LameConfig |
struct | LAME encoder tuning (classic Lame* settings). |
ReplacementRule |
struct | Character replacement rule (ReplacementCharacters in classic Settings.json). |
CheckIn |
struct | Body of POST /checkin. |
InstallId |
struct | A random install ID: a version-4 UUID in lowercase hyphenated form. |
IntakeSettings |
struct | The settings of one drop folder (core.intake). |
IntakeSettingsError |
struct | Why IntakeSettings were refused. |
IntakeSettingsRequest |
struct | The drop folder settings as a request body may send them: every field may be left out and takes the default IntakeSettings names. Only the published API schema uses it; the body is read as IntakeSettings. |
JobsConcurrencyConfig |
struct | Per-resource-class worker counts and library-wide job semaphores. |
JobsConfig |
struct | [jobs] — durable queue admission, leases, and resource-class concurrency. |
OsLogLayer |
struct | Structured sink that writes redacted events to the platform log facility. |
ListenAddrs |
struct | One or more bind addresses for the HTTP control plane. |
LoggingHandle |
struct | Result of installing the global subscriber. |
TracingOptions |
struct | Options for init_tracing_with. |
MediaConfig |
struct | [media] — decode, encode, and packaging worker pool. |
NamingProfileTemplates |
struct | Concrete templates contributed by a NamingProfile. |
ResolvedNamingTemplates |
struct | Resolved folder / file / chapter-file templates after applying profile defaults and optional per-field overrides. |
OidcBrokerConfig |
struct | [auth.oidc] — optional identity broker. |
OidcProviderConfig |
struct | One upstream OIDC or OAuth 2.0 provider. |
DestinationId |
struct | Id of one output destination: the plugin instance id of the deployed storage plugin instance that serves it. |
DestinationNaming |
struct | Optional naming overrides for one destination plugin. |
OutputConfig |
struct | Acquire packaging ([output]). |
CopyError |
struct | Why a copy list was refused. |
CopyQuality |
struct | The quality of one copy, by name. |
OpusSettings |
struct | The Opus encoder settings one output is written with. |
OutputCopy |
struct | One copy of every acquired book: a format at a quality. |
PathLimits |
struct | Limits applied when hardening acquired storage keys. |
Paths |
struct | Resolved filesystem locations for Bookclerk data. |
DestinationFilter |
struct | Which books one destination takes. |
FilterError |
struct | Why a DestinationFilter was refused. |
FilterRule |
struct | One rule of a destination filter: a field, one value of it, and its effect. |
PlacementFacts |
struct | What a destination filter knows about one book when an acquire starts. |
NodeLimits |
struct | The CPU and memory a node may use, as its cgroup limits them. |
IntegrationsConfig |
struct | Connect-portal settings under [integrations]. |
PluginRegistryEntry |
struct | One configured plugin registry source ([[plugins.registries]]). |
PluginsConfig |
struct | [plugins] — how external plugin guests are run. |
PluginsJailConfig |
struct | Optional global resource ceilings for plugin guest jails under [plugins.jail]. |
RelayedLine |
struct | One relayed line: its level and its text without the timestamp and level. |
AccessCode |
struct | A report's access code: the credential that reads the report back from the collector or deletes it. Canonical form: exactly ACCESS_CODE_LENGTH characters of ACCESS_CODE_ALPHABET, no separators. Debug never prints it. |
ReportId |
struct | A report ID the collector assigned: a version-4 UUID in lowercase hyphenated form. |
ReportRecord |
struct | One report this install sent. |
SubmitReply |
struct | What the collector's POST /submit reply names. |
LookupAnswer |
struct | The collector's answer to a lookup. |
LookupEvent |
struct | One logged event in a stored report, already redacted by the install that sent it. |
LookupFix |
struct | The fix recorded for the report's tracking issue. |
LookupIssue |
struct | A GitHub issue that tracks the report. |
LookupReport |
struct | A stored report as the collector returns it. |
AuthConfig |
struct | Auth encryption settings ([auth] section). |
Config |
struct | Top-level Bookclerk configuration. |
DaemonAuthConfig |
struct | Operator token / session settings for the daemon HTTP API. |
DaemonConfig |
struct | Daemon / HTTP control plane settings. |
DiagnosticsConfig |
struct | Opt-in sharing of recent redacted logs on crash or error bursts. |
DiscoveryConfig |
struct | Discovery / recommendations / embeddings settings. |
LibraryConfig |
struct | Library / scan related settings. |
NodeApiConfig |
struct | [daemon.node_api]: transport policy for branch nodes. |
ProcessEnvGuard |
struct | Process-wide lock around BOOKCLERK_* environment reads and test writes. |
UploadsConfig |
struct | [uploads]: per-node upload limits. |
CacheSettingError |
enum | Why a cache.* value was refused. |
CacheSettingKey |
enum | A cache.* settings key. |
DatabasePluginKind |
enum | Which first-party database plugin is active. |
ProcessRole |
enum | Which kind of Bookclerk process installed the subscriber. |
ConfigError |
enum | Errors produced while loading or validating configuration. |
FileTimestampMode |
enum | Which timestamp to apply after acquire (CreationTime / LastWriteTime). |
PathSanitizationMode |
enum | How to sanitize storage path segments when crate::OutputConfig::replacement_characters is empty (explicit rules always win). |
AfterIngest |
enum | What happens to a drop folder item once it has been ingested. |
IntakeAttribution |
enum | Who holds the books a drop folder ingests. |
Isolation |
enum | What to do when a child process cannot be confined. |
OsLogFacility |
enum | Which OS facility was attached (if any). |
LogFormat |
enum | Output format for the stderr sink. |
NamingProfile |
enum | Preset path-template profile. |
OidcProvisionMode |
enum | How an upstream provider decides who may become a first-party User. |
ResolveOperatorTokenEnv |
enum | How an operator token was resolved from env (config-layer only). |
BadBookAction |
enum | How to handle acquire failures (BadBook setting). |
MissingFileAction |
enum | What happens to a stored copy whose file disappears from its destination outside Bookclerk (noticed by the destination's change feed or listing). |
MultiDestinationMode |
enum | Behavior when some output destinations already have a title and others do not. |
CopyFormat |
enum | The format of one copy of a book. |
PathLengthMeasure |
enum | How to measure path component length when truncating. |
ChapterJsonMode |
enum | Whether / which chapter JSON sidecars to write beside acquired audio. |
OutputFormat |
enum | Post-download output formatting. Default is enriched M4B (tags + chapters). split_mp3_by_size parses but is not implemented yet: the acquire pipeline rejects a job that selects it before downloading. |
FilterEffect |
enum | Whether a FilterRule lets matching books in or keeps them out. |
FilterField |
enum | The book field a FilterRule matches one value of. |
PlacementMediaKind |
enum | What a book is, as a destination filter sees it. |
WebhooksExposure |
enum | plugins.webhooks: whether the public webhook route is open. |
RelayedLevel |
enum | The level a relayed line is logged at. |
SubmitReplyError |
enum | Why a collector reply was refused. |
EventLevel |
enum | Severity of one logged event in a report. |
IssueState |
enum | Whether a GitHub issue is open. |
LookupError |
enum | Why a lookup or delete did not succeed. |
LookupReplyError |
enum | Why a collector answer was refused. |
AudioQuality |
enum | Audible download bitrate tier (high / normal in TOML). |
KeyStoreKind |
enum | Where an install keeps the library's data-encryption key. |
NodeApiMode |
enum | How branch nodes may reach the node API ([daemon.node_api] mode). |
replace_file |
function | Replace to with from, both in the same directory. to may already exist; on Windows this goes through MoveFileExW with MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH (see the module docs), retrying briefly while another replace of to settles. The moved file keeps its own permissions, so a 0600 staging file lands as a 0600 target. |
parse_cache_setting |
function | Parses one cache.* setting. |
cookie_secure_suffix |
function | Append ; Secure when the configured public origin is HTTPS. |
oidc_transaction_cookie_flags |
function | Cookie flags for the OIDC login transaction (state binding). |
session_cookie_flags |
function | Build common session cookie attributes (HttpOnly; SameSite=Lax + optional Secure). |
resolve_d1_api_token |
function | Resolve the D1 API token from the environment (host-mediated secret). |
resolve_postgres_url |
function | Resolve the Postgres connection URL from config (env already applied). |
graphical_session_available |
function | True when it is reasonable to start the in-process tray (windowing + session bus). |
diagnostics_global |
function | Accessor for the process-global diagnostics handle. |
apply_replacements |
function | Apply replacement rules to a string (classic filename sanitization). |
classic_key_aliases |
function | Classic Settings.json key → dotted config path for config get / config set. |
default_replacement_characters |
function | Alias for windows_replacement_characters (classic default name). |
key_matches_reconcile_pattern |
function | True when key matches a reconcile pattern built with reconciliation_wildcard_rules (wildcard = any single character). |
parse_replacement_characters |
function | Parse classic ReplacementCharacters JSON. |
posix_replacement_characters |
function | Path-separator sanitization for POSIX local filesystems. |
reconciliation_wildcard_rules |
function | Replacement rules that turn every known sanitizable character into RECONCILE_WILDCARD. |
resolve_replacement_characters |
function | Resolve the character-replacement map the host applies to tag values when it fills a naming template. |
s3_replacement_characters |
function | Characters AWS recommends avoiding in S3 object keys, plus path separators. |
windows_replacement_characters |
function | NTFS-safe replacement map (classic Libation Windows defaults subset). |
checkin_due |
function | Whether a check-in is due. |
record_checkin |
function | Records an accepted check-in. |
send_checkin |
function | Sends one check-in to the collector. |
glob_matches |
function | True when name matches pattern, where * matches any run of characters (empty included) and ? exactly one, compared without ASCII case. Runs in time proportional to the product of the two lengths. |
parse_intake_settings |
function | Reads and validates the settings an operator sent, or a stored core.intake body. |
journald_available |
function | Back-compat alias. |
os_log_available |
function | Probe whether an OS log facility appears available. |
init_tracing |
function | Convenience wrapper matching the historical CLI/daemon call site. |
init_tracing_with |
function | Install a global tracing subscriber (stderr + optional OS facility + diagnostics). |
ring_filter |
function | The diagnostics ring's per-layer filter: TRACE for RING_TRACE_TARGETS (matched as prefixes, so bookclerkd and bookclerk_library count), RING_DEPENDENCY_LEVEL for the rest. |
strip_ansi_escapes |
function | Remove ECMA-48/ANSI escape sequences so piped guest logs stay plain text. |
allowlist_permits |
function | Whether an allowlist provider admits this (email, sub). |
email_domain_allowed |
function | Whether email matches an allowlist of domains (empty list = unrestricted). |
oidc_apple_private_key_env_key |
function | Environment variable holding a Sign in with Apple .p8 private key. |
oidc_client_secret_env_key |
function | Environment variable holding a provider's client secret. |
oidc_secret_store_name |
function | encrypted_secrets.name for an OIDC client secret or Apple key. |
resolve_mapped_role |
function | Pick the highest Bookclerk role from mapped claim values. |
generate_operator_token |
function | Generate a 32-byte hex operator token. |
read_operator_token_env |
function | Read BOOKCLERK_OPERATOR_TOKEN when set and non-empty. |
validate_operator_token |
function | Reject tokens that can break URL fragments, HTTP headers, or shell pastes. |
normalize_storage_prefix |
function | Normalize a storage key prefix: empty stays empty; otherwise ensure a trailing /. |
copies_to_make |
function | Every copy an acquire makes, in order: the main output's copy first (when the pipeline can make it), then each valid extra copy that differs from every earlier one, at most MAX_EXTRA_COPIES of them whatever the list holds. |
mp3_cbr_kbps |
function | The constant bitrate, in kbit/s, the MP3 encoder writes for a requested kbps: the smallest of MP3_CBR_KBPS at or above it, else 320. |
validate_copies |
function | Checks a list of extra copies: at most MAX_EXTRA_COPIES, each valid (OutputCopy::validate), none given twice and none the main output's copy main. |
apply_config_updates |
function | Load config, apply pairs, and write the result back to the resolved config path. |
apply_config_updates_from_path |
function | Load path, apply pairs, and write the updated TOML back to the same path. |
apply_setting_overrides |
function | Apply classic-style -o Setting=value overrides onto config. |
enforce_storage_key_limits |
function | Enforce per-segment and full-key limits on a relative storage key. |
path_len |
function | Measure s according to measure. |
truncate_filename_stem |
function | Truncate a filename stem so stem + "." + ext fits in max_filename_length. |
truncate_path_component |
function | Truncate s so its measured length is ≤ limit. Never splits a UTF-8 char. |
resolve_config_path |
function | Resolve config file path: BOOKCLERK_CONFIG → {files_dir}/config.toml. |
resolve_files_dir |
function | Resolve the Bookclerk files directory. |
parse_destination_filter |
function | Parses a destination filter from its raw JSON bytes, sans IO, the way the web API reads it: the strict JSON shape, then trimmed (DestinationFilter::normalized) and checked (DestinationFilter::validate). |
detect_distro |
function | Best-effort OS distribution string (e.g. Ubuntu 24.04.1 LTS). |
node_limits |
function | This process's cgroup v2 CPU and memory limits, or None when it has neither (or the platform has no cgroups). |
host_cpu_rate_max |
function | Host CPU rate ceiling in one-core percent units (logical_cpus × 100). |
node_logical_cpus |
function | Logical CPUs visible to this process (at least 1). |
contains_registered_secret |
function | True if haystack still contains any registered exact secret (post-redaction check). |
is_sensitive_field |
function | Returns true when a tracing field name should never be logged in cleartext. |
is_upload_identifying_field |
function | Field names scrubbed from remote diagnostics uploads in addition to is_sensitive_field. Local journal/stderr may still show them. |
redact_field_value |
function | Redact a field value: sensitive names are fully replaced; others are scrubbed. |
redact_str |
function | Scrub known secrets: exact registered values, then pattern matches. |
register_secret |
function | Register a known secret so it is always scrubbed from logs and diagnostics. |
register_secret_bytes |
function | Registers one secret value given as bytes, when it is UTF-8 text. |
register_secrets |
function | Register several secrets at once. |
register_secrets_from_env |
function | Register secrets commonly present in the process environment / config. |
sanitize_for_remote_upload |
function | Extra sanitization for payloads that leave the machine (collector / B2). |
truncate_upload_message |
function | Cap message length used in remote diagnostics events. |
unregister_secret |
function | Forget a secret register_secret registered, with its encoded forms, once nothing in the process holds it any more (a short-lived bearer token whose holder was dropped), so per-request credentials do not pile up in the registry every log line is checked against. Lines captured while it was registered were scrubbed then. Only for values unique to one holder: the registry keeps no count, so a value two holders share would stop being scrubbed for both. |
parse_relayed_line |
function | Splits a tracing-format prefix (optional timestamp, then a level word) off a relayed stderr line. |
find_report |
function | The report with this ID in the history, if it is there. |
load_report_history |
function | Reads the report history, oldest first. |
mark_report_deleted |
function | Notes in the history that the collector's copy of a report was deleted. |
parse_submit_reply |
function | Reads the report ID and access code from the collector's POST /submit reply. |
record_report |
function | Adds a report to the history, keeping the newest MAX_REPORT_HISTORY. |
delete_report |
function | Deletes the collector's stored copy of a sent report. Its one-line index entry and issue links stay on the collector. |
fetch_report |
function | Reads a sent report back from the collector. |
parse_delete_reply |
function | Reads the collector's answer to POST /lookup/delete. |
parse_lookup_reply |
function | Reads the collector's answer to POST /lookup. |
read_node_api_spki_pin |
function | The SPKI pin of the daemon's self-signed node API certificate, once the daemon has generated it. Enrollment links carry it in [daemon.node_api] mode = "self_signed". |
Result |
type alias | Result alias for configuration load and validation helpers in this crate. |
DEFAULT_CACHE_BUDGET_BYTES |
constant | Default disk budget for one node's image caches: 1 GiB. |
DEFAULT_CACHE_UNVIEWED_DAYS |
constant | Default days an entry may go unviewed before it is evicted. |
MAX_CACHE_BUDGET_BYTES |
constant | Largest accepted cache budget: 1 TiB. |
MAX_CACHE_UNVIEWED_DAYS |
constant | Largest accepted unviewed_days, about ten years. |
MIN_CACHE_BUDGET_BYTES |
constant | Smallest accepted cache budget: 16 MiB, room for a few hundred covers. |
SLOW_TARGET |
constant | Target of the events that mark a slow response. |
RECONCILE_WILDCARD |
constant | Sentinel placed in reconcile path patterns where a sanitizable character appeared in metadata. Matches any single character in an on-disk key. |
CHECKIN_INTERVAL_MS |
constant | Time between check-ins: one week, in milliseconds. |
BUILTIN_IGNORE_PATTERNS |
constant | File name patterns every drop folder ignores: partial downloads, editor and sync-tool temporaries, and desktop metadata files. A name starting with . is always ignored as well. |
DEFAULT_SCAN_INTERVAL_SECONDS |
constant | Default time between two listings of a drop folder, in seconds. |
DEFAULT_SETTLE_SECONDS |
constant | Default quiet time before an item is ingested, in seconds. |
FAILED_FOLDER |
constant | Folder the host moves items that failed to ingest into, at the drop folder's root. |
IMPORTED_FOLDER |
constant | Folder the host moves ingested items into, at the drop folder's root. |
MAX_IGNORE_PATTERNS |
constant | Most extra ignore patterns one drop folder may hold. |
MAX_IGNORE_PATTERN_BYTES |
constant | Longest ignore pattern, in UTF-8 bytes. |
MAX_INTAKE_CANONICAL_BYTES |
constant | Largest the settings may be once written out with every default filled in, in bytes. IntakeSettings::validate holds them to it, so accepted settings always fit, with room for the {"intake":…} wrapper, both the 16 KiB stored-document cap and MAX_INTAKE_SETTINGS_BYTES when they are read back. Only patterns full of ", which JSON escapes, come near it: 64 plain 128-byte patterns take under 9 KiB. |
MAX_INTAKE_SETTINGS_BYTES |
constant | Largest settings body parse_intake_settings reads, in bytes. |
MAX_PRUNE_IMPORTED_DAYS |
constant | Longest time _imported folders may be kept before pruning, in days (about ten years). |
MAX_SCAN_INTERVAL_SECONDS |
constant | Longest time between two listings an operator may set, in seconds. |
MAX_SETTLE_SECONDS |
constant | Longest quiet time an operator may set, in seconds (one day). |
MIN_SCAN_INTERVAL_SECONDS |
constant | Shortest time between two listings an operator may set, in seconds. |
MIN_SETTLE_SECONDS |
constant | Shortest quiet time an operator may set, in seconds. |
RING_DEPENDENCY_LEVEL |
constant | Level the diagnostics ring keeps for targets outside RING_TRACE_TARGETS. |
RING_TRACE_TARGETS |
constant | Target prefixes the diagnostics ring keeps through TRACE. Every other target (dependencies such as h2, hyper, rustls, reqwest, and log-crate records) is kept from INFO up, so their per-frame TRACE events do not crowd Bookclerk's own events out of the ring. |
MAX_EXTRA_COPIES |
constant | Most copies a library may keep beside its main output. |
MAX_QUALITY_BYTES |
constant | Longest quality name, in bytes (320k-mono is nine). |
MP3_CBR_KBPS |
constant | The constant bitrates, in kbit/s, the MP3 encoder writes. |
OPUS_KBPS |
constant | The bitrates, in kbit/s, an Opus copy is named by. Opus encodes in variable bitrate around the target, so these are targets, not caps. |
OPUS_MAIN_KBPS |
constant | The quality of the main output when it is Opus (format = "opus"): 64 kbit/s, keeping the source's channels up to stereo. Another bitrate takes an Opus extra copy beside an M4B main output. |
DEFAULT_MAX_FILENAME_LENGTH |
constant | Classic Libation LongPath.MaxFilenameLength — per path component. |
MAX_HOST_KEY_BYTES |
constant | Largest host key, in UTF-8 bytes, including the destination's prefix: the S3 object-key limit, which file systems also accept. |
BOOKCLERK_CONFIG_ENV |
constant | Override for the config file path (BOOKCLERK_CONFIG). |
BOOKCLERK_FILES_DIR_ENV |
constant | Environment variable for the Bookclerk data directory. |
MAX_FILTER_RULES |
constant | Most rules one destination filter may hold. |
MAX_FILTER_VALUE_BYTES |
constant | Longest rule value, in UTF-8 bytes. |
REDACTED |
constant | Replacement token used wherever a secret or sensitive value is scrubbed. |
ACCESS_CODE_ALPHABET |
constant | Crockford's base32 alphabet, which access codes are written in: digits and letters without I, L, O and U. |
ACCESS_CODE_LENGTH |
constant | Characters in an access code, without the group separators. |
MAX_REPORT_HISTORY |
constant | How many reports the history keeps; older ones are dropped first. |
MAX_SUBMIT_REPLY_BYTES |
constant | Longest collector reply, in bytes, that parse_submit_reply reads. The real reply is about 200 bytes. |
REPORT_HISTORY_FILE |
constant | File, relative to the files directory, that holds the report history. |
MAX_LOOKUP_REPLY_BYTES |
constant | Longest collector answer, in bytes, that parse_lookup_reply and parse_delete_reply read. A stored report is at most 256 KiB, and the answer caps every event, so a real answer is well under this. |
DEFAULT_UPGRADE_DAILY_LIMIT |
constant | Default for LibraryConfig::upgrade_daily_limit. |
LETS_ENCRYPT_DIRECTORY |
constant | Let's Encrypt's production ACME directory. |
MAX_UPGRADE_DAILY_LIMIT |
constant | Highest LibraryConfig::upgrade_daily_limit the settings accept. |
NODE_API_ACME_DIR |
constant | Directory under $BOOKCLERK_FILES_DIR holding the ACME account and certificate cache (mode 0700 on Unix). |
NODE_API_SELF_SIGNED_DIR |
constant | Directory under $BOOKCLERK_FILES_DIR holding the self-signed node API certificate, its key, and its SPKI pin (mode 0700 on Unix). |
NODE_API_SPKI_PIN_FILE |
constant | File in NODE_API_SELF_SIGNED_DIR holding the SPKI pin (base64url SHA-256 of the certificate's SubjectPublicKeyInfo). |
TRAY_HANDOFF_TTL_SECS_DEFAULT |
constant | Default tray/CLI loopback sign-in link lifetime (seconds). |
TRAY_HANDOFF_TTL_SECS_MAX |
constant | Maximum allowed DaemonAuthConfig::tray_handoff_ttl_secs. |
TRAY_HANDOFF_TTL_SECS_MIN |
constant | Minimum allowed DaemonAuthConfig::tray_handoff_ttl_secs. |
pub struct DatabaseConfig {
pub plugin: String,
pub sqlite: DatabaseSqliteConfig,
pub d1: DatabaseD1Config,
pub postgres: DatabasePostgresConfig,
pub plugins: Table,
}
Top-level [database] — selects the active backend plugin.
Fields
-
plugin: Active plugin id (first-partysqlite/d1/postgres, or any third-party database adapter plugin id). -
sqlite: Local SQLite knobs ([database.sqlite]). -
d1: Cloudflare D1 knobs ([database.d1]). -
postgres: PostgreSQL knobs ([database.postgres]). -
plugins: Opaque[database.<id>]tables for third-party database adapters.The host does not interpret these; the granted table is delivered to the adapter as its
DatabaseAdapterConfig.configpayload.
pub fn active_plugin(&self) -> Result<DatabasePluginKind>
Parsed first-party active plugin; Err for third-party adapter ids.
Returns an error when the id is not a first-party plugin id.
pub fn plugin_table(&self, id: &str) -> Option<&Table>
Borrow the opaque [database.<id>] table for a third-party adapter.
pub fn sqlite_path(&self, files_dir: &Path) -> PathBuf
Resolve the SQLite file path (relative paths join files_dir).
pub fn validate(&self) -> Result<()>
Soft validation for the selected plugin (required ids / URL presence).
Returns crate::ConfigError::Invalid when the active plugin is unknown
or missing required fields.
Implements: Clone, Debug, Default, Deserialize<'de>, PartialEq, Serialize
pub struct DatabaseD1Config {
pub enabled: bool,
pub account_id: String,
pub database_id: String,
pub api_base: String,
}
Cloudflare D1 backend ([database.d1]).
The API token is supplied via the BOOKCLERK_D1_API_TOKEN or
CLOUDFLARE_API_TOKEN environment variable (no credentials file).
Fields
enabled: Kept for symmetry with other plugins; ignored when another plugin is active.account_id: Cloudflare account id that owns the D1 database.database_id: D1 database UUID from the Cloudflare dashboard / API.api_base: Cloudflare API base (defaulthttps://api.cloudflare.com/client/v4).
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct DatabasePostgresConfig {
pub enabled: bool,
pub url: Option<String>,
pub url_file: Option<PathBuf>,
}
PostgreSQL backend ([database.postgres]).
Connect via a standard Postgres connection URL:
postgres://user:password@host:5432/dbname
The URL contains credentials — prefer url_file (pointing at a secrets volume)
or the BOOKCLERK_DATABASE_POSTGRES_URL environment variable over embedding the
URL in TOML.
Fields
enabled: Kept for symmetry with other plugins; ignored when another plugin is active.url: PostgreSQL connection URL (e.g.postgres://user:pass@host/db). Registered as a secret for redaction. Preferurl_filein production.url_file: Path to a file containing the connection URL (one line, trimmed). Relative paths are resolved under$BOOKCLERK_FILES_DIR.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct DatabaseSqliteConfig {
pub enabled: bool,
pub path: Option<PathBuf>,
}
Local SQLite destination ([database.sqlite]).
Fields
enabled: Kept for symmetry with other plugins; ignored when another plugin is active.path: DB file path (defaultlibrary.dbunder the files dir).
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct BufferedEvent {
pub ts_unix_ms: u64,
pub level: String,
pub target: String,
pub message: String,
pub fields: Vec<(String, String)>,
}
Snapshot of a single redacted log event kept for crash / error uploads.
Fields
ts_unix_ms: Event time as Unix milliseconds (wall clock).level: Tracing level name (ERROR,WARN,INFO, …).target: Tracing target / module path.message: Redacted primary message text.fields: Additional redacted structured fields as(name, value)pairs.
Implements: Clone, Debug, Serialize
pub struct DiagnosticsHandle {
/* private fields */
}
Process-global diagnostics handle installed by crate::logging::init_tracing_with.
pub fn new(
config: DiagnosticsConfig,
version: impl Into<String>,
role: ProcessRole,
) -> Self
A new handle with ring capacity from config (at least 1). The
process installs one with install_global; tests build their own.
pub fn upload_enabled(&self) -> bool
Whether automatic upload is configured and ready (token/url present).
pub fn share_usage(&self) -> bool
Whether the weekly usage check-in and the install ID are on right now
(diagnostics.share_usage, following Settings changes).
pub fn set_sharing(&self, share_reports: bool, share_usage: bool)
Applies new diagnostics.share_reports / share_usage values without
a restart (the daemon calls it after a config reload).
share_reports- Whether reports are uploaded from now on.share_usage- Whether uploads carry the install ID and the check-in runs from now on.
pub fn set_files_dir(&self, files_dir: &Path)
Tells the handle where the files directory is, so accepted reports are recorded in the install's report history. The first call wins.
files_dir- The Bookclerk files directory.
pub fn snapshot_events(&self) -> Vec<BufferedEvent>
Snapshot of the in-memory diagnostics ring (newest last).
pub fn version(&self) -> &str
Bookclerk version string recorded at subscriber install.
pub fn set_install_id(&self, id: &InstallId)
Attaches the install's random ID to later uploads. Does nothing unless
diagnostics.share_usage is on; the first ID set stays.
id- The install ID (crate::InstallId).
pub fn deployment(&self) -> &'static str
What uploads report as deployment: demo for a copy of the hosted
demo, otherwise the process role.
pub fn uploads_attempted(&self) -> u64
Number of upload attempts since init (successful or failed HTTP tries).
pub fn record_event(&self, event: &Event<'_>)
Record a redacted event into the ring buffer and maybe trigger a burst upload.
pub fn record_event_with_spans(
&self,
event: &Event<'_>,
span_fields: Vec<(String, String)>,
)
Record a redacted event with fields copied from the spans it happened in, and maybe trigger a burst upload.
log-crate records take their own target (log.target) and lose the
fields that describe the record itself (module path, file, line).
event- The tracing event.span_fields- Redacted(span.field, value)pairs, innermost span first (seeDiagnosticsLayer).
pub fn request_upload(&self, trigger: &'static str)
Request an upload of the current ring (e.g. after a failed daemon job).
Explicit failure uploads bypass the burst cooldown so a recent burst cannot
suppress cli_error / job_failed reports. If another upload is in flight,
this waits briefly for the slot rather than dropping the request.
pub fn upload_blocking(&self, trigger: &str)
Best-effort upload of the current ring buffer (blocking).
Used by the panic hook, CLI exit path, and tests. Waits for any in-flight upload to finish (serialized upload gate) so crash reports are not dropped and concurrent POSTs cannot overlap.
Implements: Clone
pub struct UploadPayload {
pub trigger: String,
pub deployment: String,
pub install_id: Option<String>,
pub version: String,
pub os: String,
pub arch: String,
pub distro: Option<String>,
pub build_commit: String,
pub limits: Option<NodeLimits>,
pub rustc_release: String,
pub rustc_channel: String,
pub archived_at_unix_ms: u64,
pub events: Vec<BufferedEvent>,
}
JSON body POSTed to the diagnostics collector /submit endpoint.
Fields
trigger: Why this upload was produced (crash,error_burst,slow_burst,cli_error, …).deployment: What sent it:daemon,desktop,cli, ordemofor a copy of the hosted demo.install_id: The install's random ID, sent only whendiagnostics.share_usageis on. The collector keeps only a monthly-salted hash of it.version: Bookclerk version string recorded at subscriber install.os: Host OS (linux,macos,windows, …).arch: CPU architecture (x86_64,aarch64, …).distro: Best-effort Linux distro id when detectable.build_commit: The source commit this build was made from (or"unknown").limits: The CPU and memory limits of the process's cgroup when it has any (a container or a systemd slice), so a slow report from a small node says so.rustc_release:rustcrelease baked in at build time (or"unknown").rustc_channel:rustcchannel baked in at build time (or"unknown").archived_at_unix_ms: Upload assembly time as Unix milliseconds.events: Redacted ring-buffer snapshot (oldest first).
Implements: Clone, Debug, Serialize
pub struct EventsConfig {
pub retention_days: u64,
pub dead_letter_retention_days: u64,
pub concurrency: u32,
}
[events] — outbox retention and local delivery-worker concurrency.
Fields
retention_days: Days to retain acked/rejected deliveries and parent events with no remaining live deliveries.dead_letter_retention_days: Days to retaindead_letterdeliveries (independent ofSelf::retention_days).concurrency: Local delivery workers ([events.concurrency]; default 1).
pub fn apply_env_overrides(&mut self)
Apply BOOKCLERK_EVENTS_* environment overrides.
Environment wins over TOML, matching every other section.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct LameConfig {
pub target: String,
pub vbr_quality: u8,
pub bitrate_kbps: u32,
pub mode: String,
pub downsample_mono: bool,
pub constant_bitrate: bool,
}
LAME encoder tuning (classic Lame* settings).
Fields
target:LameTarget:quality,bitrate,constant, etc.vbr_quality:LameVBRQuality(0–9, lower = better).bitrate_kbps:LameBitratein kbps when target is bitrate/constant.mode:LameMode:default,mono,stereo.downsample_mono:LameDownsampleMono.constant_bitrate:LameConstantBitrate.
Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct ReplacementRule {
pub find: String,
pub replace: String,
}
Character replacement rule (ReplacementCharacters in classic Settings.json).
Fields
find: Substring to search for in each path segment / tag value.replace: Replacement text (may be empty to stripfind).
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct CheckIn {
pub install_id: String,
pub version: String,
pub os: String,
pub arch: String,
pub kind: String,
}
Body of POST /checkin.
Fields
install_id: The install's random ID.version: Bookclerk version.os: Operating system (linux,macos,windows, …).arch: CPU architecture (x86_64,aarch64, …).kind: Kind of process:daemonordesktop.
Implements: Clone, Debug, Eq, PartialEq, Serialize
pub struct InstallId(/* private */);
A random install ID: a version-4 UUID in lowercase hyphenated form.
pub fn generate() -> Result<Self>
Generates a new random ID from the operating system's random source.
Returns an error when the random source is unavailable.
pub fn parse(text: &str) -> Option<Self>
Parses an ID as InstallId::generate writes it.
text- Candidate text; surrounding whitespace is ignored.
The ID, or None unless the text is a lowercase hyphenated version-4
UUID.
pub fn as_str(&self) -> &str
The ID as text.
pub fn load_or_create(files_dir: &Path) -> Result<Self>
Reads the ID from the files directory, creating it on first use (or when the file does not hold a valid ID).
files_dir- The Bookclerk files directory.
Returns an error when the file cannot be read or written.
pub fn reset(files_dir: &Path) -> Result<Self>
Replaces the ID with a new random one and forgets the last check-in, so the new ID checks in on the next pass.
files_dir- The Bookclerk files directory.
Returns an error when the file cannot be written.
Implements: Clone, Debug, Eq, PartialEq
pub struct IntakeSettings {
pub settle_seconds: u32,
pub scan_interval_seconds: u32,
pub after_ingest: AfterIngest,
pub attribute_to: IntakeAttribution,
pub patron: Option<i64>,
pub ignore: Vec<String>,
pub prune_imported_days: Option<u16>,
}
The settings of one drop folder (core.intake).
Every field has a default, so {} is a valid body only when
attribute_to is subfolder; owner needs a patron.
Fields
settle_seconds: Seconds an item's files must stay unchanged before it is ingested, 5 to 86,400 (default 60).scan_interval_seconds: Seconds between two full listings of the folder, 30 to 86,400 (default 300). A change feed starts a listing sooner.after_ingest: What happens to an item once it is ingested (defaultmove).attribute_to: Who holds the ingested books (defaultowner).patron: The user id that holds every book inownermode; required there and refused insubfoldermode.ignore: Extra file name patterns to ignore, at most 64, each 1 to 128 bytes with no/:*matches any run of characters and?one character, compared without ASCII case. The built-in list always applies too (BUILTIN_IGNORE_PATTERNS).prune_imported_days: Withafter_ingest = move, delete_importedday folders older than this many days, 1 to 3,650; absent keeps them.
pub fn for_patron(patron: i64) -> Self
Settings with every default and patron holding every book.
pub fn validate(&self) -> Result<(), IntakeSettingsError>
Checks every bound and the rules between fields.
Returns an IntakeSettingsError naming the first broken bound: a
number out of range, a missing or unwanted patron, a bad ignore
pattern, prune_imported_days without after_ingest = move, or
settings longer than MAX_INTAKE_CANONICAL_BYTES written out.
pub fn ignores(&self, name: &str, at_root: bool) -> bool
True when the file or folder name name (one path segment) is never
part of an item: a dot name, a built-in pattern, an extra pattern,
or one of the host's own folders at the root.
name- One path segment.at_root- True whennamesits directly under the folder's root, where_importedand_failedlive.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct IntakeSettingsError(/* private */);
Why IntakeSettings were refused.
Implements: Clone, Debug, Display, Eq, Error, PartialEq
pub struct IntakeSettingsRequest {
pub settle_seconds: u32,
pub scan_interval_seconds: u32,
pub after_ingest: AfterIngest,
pub attribute_to: IntakeAttribution,
pub patron: Option<i64>,
pub ignore: Vec<String>,
pub prune_imported_days: Option<u16>,
}
The drop folder settings as a request body may send them: every field
may be left out and takes the default IntakeSettings names. Only the
published API schema uses it; the body is read as IntakeSettings.
Fields
settle_seconds: Seconds an item's files must stay unchanged before it is ingested, 5 to 86,400 (default 60).scan_interval_seconds: Seconds between two full listings of the folder, 30 to 86,400 (default 300).after_ingest: What happens to an item once it is ingested (defaultmove).attribute_to: Who holds the ingested books (defaultowner).patron: The user id that holds every book inownermode; required there and refused insubfoldermode. It must name an active user.ignore: Extra file name patterns to ignore, at most 64, each 1 to 128 bytes with no/(default none).prune_imported_days: Withafter_ingest = move, delete_importedday folders older than this many days, 1 to 3,650; absent keeps them.
Implements: Clone, ComposeSchema, Debug, Eq, PartialEq, ToSchema
pub struct JobsConcurrencyConfig {
pub network: u32,
pub plugin_instance: u32,
}
Per-resource-class worker counts and library-wide job semaphores.
Fields
network: Scan / acquire / listening-sync workers on this node (default 1), and the library-wide number of running network jobs (thejobs:networksemaphore).plugin_instance: Library-wide running jobs that require one plugin instance (theplugin-instance:<id>semaphore; default 1).
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct JobsConfig {
pub max_pending: u32,
pub lease_seconds: u64,
pub max_attempts: u32,
pub retention_days: u64,
pub temp_quota_bytes: u64,
pub concurrency: JobsConcurrencyConfig,
}
[jobs] — durable queue admission, leases, and resource-class concurrency.
Fields
max_pending: Maximum pending+running jobs. Further admits return queue-full.lease_seconds: Lease length in seconds; expired running jobs are reclaimed.max_attempts: Maximum claims before a failure is terminal.retention_days: Days to retain succeeded/failed/cancelled rows.temp_quota_bytes: Refuse new acquire scratch dirs when registered temps exceed this.concurrency: Per-class concurrency ([jobs.concurrency]).
pub fn apply_env_overrides(&mut self)
Apply BOOKCLERK_JOBS_* environment overrides.
Environment wins over TOML, matching every other section.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct OsLogLayer {
/* private fields */
}
Structured sink that writes redacted events to the platform log facility.
pub fn new(syslog_identifier: impl Into<String>) -> Result<Self>
Connect to the platform facility. Returns Err when unavailable.
Returns an error when the operation fails.
pub fn facility(&self) -> OsLogFacility
Which platform sink this layer is writing to.
Implements: Layer<S>
pub struct ListenAddrs(/* private */);
One or more bind addresses for the HTTP control plane.
TOML accepts either a string or an array; we always serialize as an array.
pub fn new(addrs: Vec<String>) -> Self
Build from raw address strings, dropping empties; falls back to defaults when every entry is empty.
pub fn parse_list(raw: &str) -> Result<Self, String>
Parse a single address or a comma-separated list
(127.0.0.1:8787,[::1]:8787).
Returns an error when the operation fails.
pub fn as_slice(&self) -> &[String]
Configured bind strings in declaration order.
pub fn is_empty(&self) -> bool
True when no bind addresses remain (should not occur after Self::new).
pub fn join_comma(&self) -> String
Comma-joined form for settings API / overrides.
pub fn socket_addrs(&self) -> Result<Vec<SocketAddr>, String>
Parse each entry as a SocketAddr.
Returns an error when the operation fails.
pub fn validate(&self) -> Result<(), String>
Validate every entry parses as a socket address.
Returns an error when the operation fails.
pub fn ui_port(&self) -> u16
Port used for tray http://localhost:<port> (first entry's port).
pub fn ports(&self) -> Vec<u16>
Distinct TCP ports from configured bind addresses.
pub fn has_loopback(&self) -> bool
Whether any configured bind is loopback.
pub fn has_unspecified(&self) -> bool
Whether any configured bind is unspecified (0.0.0.0 / ::).
pub fn tray_base_url(&self) -> String
Prefer http://localhost:<port> when any loopback or unspecified bind is
configured (wildcard listeners still accept loopback); else the first
concrete bind (bracket IPv6 as needed).
Implements: Clone, Debug, Default, Deserialize<'de>, Display, Eq, From<&str>, FromStr, PartialEq, Serialize
pub struct LoggingHandle {
pub diagnostics: DiagnosticsHandle,
pub journald: bool,
pub os_facility: Option<OsLogFacility>,
/* private fields */
}
Result of installing the global subscriber.
Keep this value alive for the process lifetime so the stderr worker thread
stays running (WorkerGuard).
Fields
diagnostics: Diagnostics ring buffer / upload handle.journald: Whether an OS facility sink was attached.os_facility: Which facility was attached (if any).
pub struct TracingOptions {
pub format: LogFormat,
pub default_level: String,
pub syslog_identifier: String,
pub diagnostics: DiagnosticsConfig,
pub version: String,
pub enable_journald: bool,
pub role: ProcessRole,
}
Options for init_tracing_with.
Fields
format: Stderr format (text vs JSON).default_level: DefaultEnvFilterdirective whenBOOKCLERK_LOG/RUST_LOGare unset. Affects stderr + OS facility only — the diagnostics ring has its own filter (ring_filter).syslog_identifier: Identifier for journald / Event Log source / os_log category.diagnostics: Opt-in crash / error-burst upload settings.version: Package version embedded in diagnostics uploads.enable_journald: Attempt to attach an OS log facility (no-op when unavailable).role: What kind of process this is, reported in diagnostics uploads.
Implements: Clone, Debug, Default
pub struct MediaConfig {
pub workers: usize,
pub isolation: Isolation,
pub worker_bin: Option<PathBuf>,
}
[media] — decode, encode, and packaging worker pool.
Fields
workers: Maximum codec jobs running at once.0derives one worker per core, capped at 8, unless this process's cgroup reportsmemory.maxat or below 1 GiB or acpu.maxquota of at most one core — then the automatic choice is 1. A value above 0 is an explicit operator cap.isolation: How strictly workers must be confined.worker_bin: Explicit path tobookclerk-media-worker. Normally left unset, in which case the worker is found beside the running executable.
pub fn apply_env_overrides(&mut self)
Apply BOOKCLERK_MEDIA_* environment overrides.
Environment wins over TOML, matching every other section.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct NamingProfileTemplates {
pub folder: &'static str,
pub file: &'static str,
pub chapter_file: &'static str,
}
Concrete templates contributed by a NamingProfile.
Fields
folder: Default folder-path template for this profile (Libation tag syntax).file: Default file-stem template for this profile (no extension).chapter_file: Default per-chapter file-stem template when splitting by chapter.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct ResolvedNamingTemplates {
pub folder: String,
pub file: String,
pub chapter_file: String,
}
Resolved folder / file / chapter-file templates after applying profile defaults and optional per-field overrides.
Fields
folder: Folder-path template after profile defaults and optional overrides.file: File-stem template after profile defaults and optional overrides.chapter_file: Chapter file-stem template after profile defaults and optional overrides.
pub fn resolve(
profile: NamingProfile,
folder: Option<&str>,
file: Option<&str>,
chapter_file: Option<&str>,
) -> Self
Resolve templates: each explicit override wins over the profile default.
Implements: Clone, Debug, Eq, PartialEq
pub struct OidcBrokerConfig {
pub enabled: bool,
pub allowed_email_domains: Vec<String>,
pub providers: Vec<OidcProviderConfig>,
pub secret_generation: u64,
}
[auth.oidc] — optional identity broker.
Fields
-
enabled: When false, RP routes report disabled and login buttons are hidden. -
allowed_email_domains: Global email-domain allowlist applied after the provider policy. -
providers: Upstream providers (enterprise and/or social). -
secret_generation: Durableencrypted_secretsgeneration for this broker revision.Runtime and
config.tomlmust agree before rows for this generation are used.0is the unversioned legacy name.
pub fn is_unset(&self) -> bool
Whether this section is the serde default (disabled, no providers).
pub fn enabled_providers(&self) -> Vec<&OidcProviderConfig>
Enabled providers with a non-empty id.
pub fn provider(&self, id: &str) -> Option<&OidcProviderConfig>
Look up a provider by id.
pub fn validate(&self) -> Result<()>
Reject operator maps, unknown roles, duplicate ids, and empty ids when enabled.
Returns an error when the operation fails.
pub fn validate_providers(&self) -> Result<()>
Validate provider rows even when the broker is disabled.
Used by the Settings API so a disabled-but-invalid draft cannot be
written and then fail crate::Config::load when later enabled.
Returns an error when the operation fails.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct OidcProviderConfig {
pub id: String,
pub name: String,
pub preset: Option<String>,
pub issuer: Option<String>,
pub client_id: String,
pub client_secret: Option<String>,
pub scopes: Vec<String>,
pub provision: OidcProvisionMode,
pub default_role: String,
pub role_claim: String,
pub role_map: BTreeMap<String, String>,
pub link_by_email: bool,
pub apple_team_id: Option<String>,
pub apple_key_id: Option<String>,
pub apple_private_key: Option<String>,
pub allowed_email_domains: Vec<String>,
pub allowed_emails: Vec<String>,
pub allowed_subjects: Vec<String>,
}
One upstream OIDC or OAuth 2.0 provider.
Fields
-
id: Stable id used in URLs andportal_identities.provider(oidc:{id}). -
name: Login-button label. -
preset: Optional well-known preset (google,github,apple,discord). -
issuer: OIDC issuer URL (discovery). Ignored whenpresetfills endpoints. -
client_id: OAuth client id. -
client_secret: Optional client secret (prefer env /encrypted_secrets). -
scopes: Scopes requested at authorize. -
provision: Provisioning policy for this provider. -
default_role: Role used forOidcProvisionMode::Any(and allowlist without maps). -
role_claim: Claim name holding groups/roles (typicallygroupsorroles). -
role_map: Upstream group/role value → Bookclerk role (owner/administrator/member). -
link_by_email: When true, a newsubmay attach to the unique matching verified email User.Defaults off in TOML for generic issuers: an unverified upstream email must not attach to an existing Owner. Settings defaults this on for Google / GitHub / Apple / Discord presets.
-
apple_team_id: Sign in with Apple team ID (issof the client-secret JWT). -
apple_key_id: Sign in with Apple key ID (kidheader of the client-secret JWT). -
apple_private_key: PEM-encoded Apple.p8private key (prefer env /encrypted_secrets). -
allowed_email_domains: Email domains allowed for this provider (empty = no extra filter). -
allowed_emails: Exact emails allowed whenprovision = allowlist. -
allowed_subjects: Explicit upstreamsubvalues allowed whenprovision = allowlist.
pub fn portal_provider(&self) -> String
Portal identity provider key (oidc:{id}).
pub fn display_name(&self) -> &str
Display name, falling back to id.
pub fn social_preset(&self) -> Option<&'static str>
Canonical social preset (google, github, apple, discord).
Matching is ASCII case-insensitive so GitHub and apple select the
same endpoints, scopes, and profile adapter.
pub fn effective_scopes(&self) -> Vec<String>
Scopes sent at authorize, with social-preset defaults when unset.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct DestinationId(/* private */);
Id of one output destination: the plugin instance id of the deployed storage plugin instance that serves it.
Plans, upload manifests and edition_files name destinations by it.
Several instances of one storage plugin are separate destinations
(docs/adr/storage-destinations.md).
pub const MAX_LEN: usize = 64
Longest destination id in bytes; a hyphenated UUID is 36.
pub fn new(id: impl Into<String>) -> Result<Self, String>
Checks id: 1 to Self::MAX_LEN lowercase ASCII letters, digits,
_ or -, the characters a plugin instance id uses.
Returns a message naming what is wrong with id.
pub fn as_str(&self) -> &str
The id as text.
Implements: Clone, Debug, Deserialize<'de>, Display, Eq, From<DestinationId>, Hash, Ord, PartialEq, PartialOrd, Serialize, TryFrom<String>
pub struct DestinationNaming {
pub naming_profile: Option<NamingProfile>,
pub folder_template: Option<String>,
pub file_template: Option<String>,
pub chapter_file_template: Option<String>,
}
Optional naming overrides for one destination plugin.
Fields
naming_profile: Override[output].naming_profilefor this destination when set.folder_template: Optional folder-path template override (Libation tag syntax).file_template: Optional file-stem template override (no extension).chapter_file_template: Optional per-chapter file-stem template when splitting by chapter.
pub fn resolve_over(&self, global: &OutputConfig) -> ResolvedNamingTemplates
Merge destination overrides over global [output] naming.
pub fn effective_profile(&self, global: &OutputConfig) -> NamingProfile
Profile after destination override (else global).
pub fn effective_folder_template(&self, global: &OutputConfig) -> Option<String>
Destination folder template, falling back to global [output].
pub fn effective_file_template(&self, global: &OutputConfig) -> Option<String>
Destination file-stem template, falling back to global [output].
pub fn effective_chapter_file_template(&self, global: &OutputConfig) -> Option<String>
Destination chapter-file template, falling back to global [output].
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct OutputConfig {
pub format: OutputFormat,
pub copies: Vec<OutputCopy>,
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_chapter_json: Option<bool>,
pub save_metadata_json: bool,
pub cover_size: String,
pub chapter_layout: String,
pub overwrite_existing: bool,
pub multi_destination: MultiDestinationMode,
pub missing_files: MissingFileAction,
pub in_progress: Option<PathBuf>,
pub bad_book_action: BadBookAction,
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 max_sample_rate: Option<u32>,
pub creation_time: FileTimestampMode,
pub last_write_time: FileTimestampMode,
pub path_sanitization: PathSanitizationMode,
pub replacement_characters: Vec<ReplacementRule>,
pub max_filename_length: u32,
}
Acquire packaging ([output]).
Destination plugins (local, s3, …) declare their own [[settings]]
(root, bucket, prefix, per-destination naming overrides) and are
configured on their plugin instances; nothing destination-specific lives
in config.toml.
Fields
format: Post-acquire packaging format (default: enriched M4B).copies: Further copies of every acquired book, beside the main output (Self::formatwithSelf::lame), at mostcrate::MAX_EXTRA_COPIES. Empty (the default) keeps one copy.widevine: Prefer Widevine/CENC (also enables Adrm→Widevine fallback; auto-provisions L3 CDM).xhe_aac: Prefer xHE-AAC on the Widevine path when offered.widevine_cdm: Optional local Widevine.wvdpath (absolute or relative toBOOKCLERK_FILES_DIR).widevine_cdm_provider: Remote L3 CDM provider.Noneuses classic Libation AudibleCdm; empty/offdisables.naming_profile: Named path-template preset (audiobookshelfdefault, orclassic).folder_template: Optional folder-path template override;Noneuses the naming profile default.file_template: Optional file-stem template override;Noneuses the naming profile default.download_cover: Save cover JPEG alongside audio.download_pdf: Download companion PDF when available.create_cue: Write a.cuesidecar from API chapters.fixup_metadata: Embed tags, cover, and chapters natively.keep_codec_in_m4b: Keep Opus, FLAC, ALAC, E-AC-3 and AC-4 audio unchanged inside an M4B copy instead of encoding it to AAC (an advanced setting: fewer players open those codecs in MP4). Off by default.chapter_json: Chapter JSON sidecars:off|flat|tree|both.save_chapter_json: Deprecated: useSelf::chapter_json.save_metadata_json: Persist raw catalog API JSON (metadata.json).cover_size: Cover image size for download/embed (500,1215, ornative).chapter_layout: Preferred Audible chapter API layout when fetching (treeorflat).overwrite_existing: Re-acquire when media already exists at the destination.multi_destination: When multiple destinations are enabled and only some already have the title: copy from a present dest, re-fetch into missing only, or re-fetch into every destination.missing_files: What happens to a stored copy whose file disappears from its destination outside Bookclerk.in_progress: Scratch directory for in-progress work; relative to files_dir.bad_book_action: Operator action when a title fails to acquire (ask/abort/retry/ignore).split_mp3_max_mb: Max MP3 part size in MiB when format issplit_mp3_by_size.chapter_file_template: Optional per-chapter file-stem template;Noneuses the naming profile default.chapter_title_template: Optional embedded chapter-title template when rewriting chapter names.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 content 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 audio from the remux window.download_clips_bookmarks: When true, download Audible clips/bookmarks sidecars when the store offers them.retain_aax_file: Keep 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.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.path_sanitization: Auto / Windows / POSIX / S3 sanitisation profile when replacement rules are empty.replacement_characters: Explicit find/replace rules for path segments (wins overSelf::path_sanitization).max_filename_length: Max length per path segment. Default 255;0disables truncation.
pub fn effective_format(&self) -> OutputFormat
Packaging format used for acquire (currently the raw Self::format field).
pub fn copies_to_make(&self) -> Vec<OutputCopy>
Every copy an acquire makes, main output first
(crate::copies_to_make).
pub fn effective_chapter_json(&self) -> ChapterJsonMode
Resolved chapter JSON sidecar mode (default off).
pub fn resolve_naming_templates(&self) -> ResolvedNamingTemplates
Resolve folder / file / chapter-file templates.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct CopyError(/* private */);
Why a copy list was refused.
Implements: Clone, Debug, Display, Eq, Error, PartialEq
pub struct CopyQuality {
/* private fields */
}
The quality of one copy, by name.
The names are original (the store's audio, re-packaged without
re-encoding where the format allows), a bitrate such as 64k (one of
the MP3 encoder's constant rates, MP3_CBR_KBPS, or an Opus target,
OPUS_KBPS) or a LAME VBR quality v0 to v9; either of the last
two may end in -mono for a copy mixed down to one channel. Which names
suit which format is OutputCopy::validate's to say. Names are stored
in lower case.
pub const ORIGINAL: Self = _
The original quality.
pub fn parse(raw: &str) -> Option<Self>
Reads a quality name, without case; None for any text that is not
one (see the type's documentation).
pub fn is_original(&self) -> bool
True for original.
pub fn is_mono(&self) -> bool
True for a copy mixed down to one channel (-mono).
pub fn kbps(&self) -> Option<u16>
The bitrate the name gives, in kbit/s; None for original and
the VBR levels.
pub fn of_lame(lame: &LameConfig) -> Self
The quality the library's LAME settings give an MP3.
pub fn lame(&self, base: &LameConfig) -> LameConfig
base with this quality's encoder settings: a bitrate selects a
constant bitrate, a VBR level a VBR quality, and -mono mixes down.
original leaves base as it is.
Implements: Clone, Debug, Deserialize<'de>, Display, Eq, Hash, Ord, PartialEq, PartialOrd, PartialSchema, Serialize, ToSchema
pub struct OpusSettings {
pub kbps: u16,
pub mono: bool,
}
The Opus encoder settings one output is written with.
The main output uses OPUS_MAIN_KBPS, keeping the source's channels
up to stereo; an Opus copy takes the
bitrate and channel choice its quality names (OutputCopy::opus_kbps).
Fields
kbps: Target bitrate in kbit/s; Opus encodes in variable bitrate around it.mono: When true, the encoder downmixes to one channel.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct OutputCopy {
pub format: CopyFormat,
pub quality: CopyQuality,
}
One copy of every acquired book: a format at a quality.
Fields
format: The copy's format.quality: The copy's quality.
pub fn main(format: OutputFormat, lame: &LameConfig) -> Option<Self>
The copy the library's main output makes: its format, with
original quality for M4B and as-delivered output, the LAME
settings' quality for MP3 and OPUS_MAIN_KBPS for Opus. None
for an output format the acquire pipeline refuses.
pub fn validate(&self) -> Result<(), CopyError>
Checks that the quality suits the format: M4B and as-delivered
copies are original only (the M4B is re-packaged, not
re-encoded), MP3 copies need one of the MP3 encoder's constant
rates or a VBR quality, and Opus copies one of the Opus targets.
Returns a CopyError naming the copy when they do not suit.
pub fn opus_kbps(&self) -> Option<(u16, bool)>
The Opus encoder settings for an Opus copy at this quality; None
for any other format or a quality without a bitrate.
pub fn label(&self) -> String
The copy's label in a storage key, for a destination that keeps
more than one copy of a book: mp3 64k-mono.
pub fn parse(raw: &str) -> Result<Self, CopyError>
Reads one copy written format:quality (mp3:64k-mono), as the
output.copies setting lists them.
Returns a CopyError for text that is not that shape, an unknown
format or quality, or a quality that does not suit the format.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Display, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize, ToSchema
pub struct PathLimits {
pub max_filename_length: usize,
pub max_storage_key_bytes: usize,
pub measure: PathLengthMeasure,
}
Limits applied when hardening acquired storage keys.
Fields
max_filename_length: Max length per folder / file-stem segment.0disables per-segment caps.max_storage_key_bytes: Max UTF-8 bytes for the full relative storage key (folder/…/file.ext).0disables. Host keys useMAX_HOST_KEY_BYTESminus the prefix length.measure: Whether segment truncation counts Unicode scalars or UTF-8 bytes.
pub fn for_host_keys(max_filename_length: u32, prefix: &str) -> Self
Host-key limits for a destination whose keys sit under prefix:
segments of at most max_filename_length UTF-8 bytes, and a whole
key of MAX_HOST_KEY_BYTES minus the normalized prefix length
(its trailing / included when the prefix is non-empty).
Bytes are counted for every destination: a name that fits in bytes fits in characters and UTF-16 units too.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct Paths {
pub files_dir: PathBuf,
pub config_file: PathBuf,
pub library_db: PathBuf,
pub cache_dir: PathBuf,
pub log_dir: PathBuf,
pub search_index_dir: PathBuf,
}
Resolved filesystem locations for Bookclerk data.
Fields
files_dir: Root data directory (accounts, DB, settings).config_file: Resolved config.toml path (may be overridden by--config/BOOKCLERK_CONFIG).library_db: SQLite library database path.cache_dir: Temporary download / decrypt scratch space.log_dir: Reserved path (legacy). Logging goes to stderr + journald; Bookclerk does not write or rotate files here.search_index_dir: The node's Tantivy works search index (search_index_works/).
pub fn from_files_dir(files_dir: PathBuf) -> Self
Build path set from an explicit files directory.
pub fn ensure_dirs(&self) -> Result<()>
Ensure directories that Bookclerk expects to exist are present.
Returns an error when the operation fails.
Implements: Clone, Debug, Eq, PartialEq
pub struct DestinationFilter {
pub rules: Vec<FilterRule>,
}
Which books one destination takes.
Fields
rules: Filter rules, at most 64. Empty means the destination takes every book.
pub fn takes_everything(&self) -> bool
A filter that takes every book: no rules.
pub fn accepts(&self, facts: &PlacementFacts) -> bool
True when the destination takes the book described by facts:
among the book rules (every rule but format and quality), no
exclude rule matches, and either there is no include rule or one of
them matches. Copy rules are not considered.
pub fn accepts_copy(&self, copy: &OutputCopy) -> bool
True when the destination receives copy of a book it takes: among
the copy rules (format and quality), no exclude rule matches,
and either there is no include rule or one of them matches. Book
rules are not considered; a filter with no copy rules receives every
copy.
pub fn has_copy_rules(&self) -> bool
True when the filter has a format or quality rule.
pub fn validate(&self) -> Result<(), FilterError>
Checks the filter's bounds.
Returns a FilterError for more than MAX_FILTER_RULES rules,
an empty or over-long value, a value with a NUL, a patron value
that is not a positive user id, a media_kind value other than
book or podcast, a format value that is not a copy format, a
quality value that is not a copy quality, or a rule given twice
(the same field, value and effect, compared without case).
pub fn normalized(self) -> Self
The filter with each value trimmed, as it is stored.
Implements: Clone, ComposeSchema, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct FilterError(/* private */);
Why a DestinationFilter was refused.
Implements: Clone, Debug, Display, Eq, Error, PartialEq
pub struct FilterRule {
pub field: FilterField,
pub value: String,
pub effect: FilterEffect,
}
One rule of a destination filter: a field, one value of it, and its effect.
Fields
field: The field the rule matches.value: The value: a user id forpatron,bookorpodcastformedia_kind, a copy format forformat, a copy quality forquality, otherwise 1 to 128 bytes of text.effect: Include or exclude.
pub fn matches(&self, facts: &PlacementFacts) -> bool
True when the book described by facts has this rule's value in
the rule's field. The effect is not considered, and a copy rule
(format, quality) never matches a book.
pub fn matches_copy(&self, copy: &OutputCopy) -> bool
True when copy has this rule's value in the rule's field. The
effect is not considered, and a book rule never matches a copy.
Implements: Clone, ComposeSchema, Debug, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub struct PlacementFacts {
pub patrons: Vec<i64>,
pub storefront: String,
pub account: String,
pub media_kind: PlacementMediaKind,
}
What a destination filter knows about one book when an acquire starts.
Fields
patrons: Users linked to the store account that holds the book, ascending. Empty when the account is linked to nobody.storefront: The storefront plugin's alias (audible,libro, …).account: The holding account's id at that store.media_kind: What the book is.
Implements: Clone, Debug, Eq, PartialEq
pub struct NodeLimits {
pub cpu_millis: Option<u64>,
pub memory_bytes: Option<u64>,
pub cpus: u64,
}
The CPU and memory a node may use, as its cgroup limits them.
Fields
cpu_millis: CPU limit in thousandths of a CPU (250is a quarter of one), from cgroup v2cpu.max;Nonewhen unlimited or unknown.memory_bytes: Memory limit in bytes, from cgroup v2memory.max;Nonewhen unlimited or unknown.cpus: CPUs the process may run on (available_parallelism), at least 1.
Implements: Clone, Copy, Debug, Eq, PartialEq, Serialize
pub struct IntegrationsConfig {
pub claim_ticket_ttl_hours: u64,
pub public_origin: Option<String>,
pub portal_session_ttl_hours: u64,
pub ingress_origin: Option<String>,
}
Connect-portal settings under [integrations].
Integration plugins themselves (Audiobookshelf, …) are deployed plugin instances; their settings live on the instance, not here.
Fields
-
claim_ticket_ttl_hours: Hours a connect-portal claim ticket remains valid (default 72). -
public_origin: Public HTTPS origin for portal redirects when behind a reverse proxy (e.g.https://bookclerk.example.com).Noneaccepts only a bound loopbackOrigin/Host; non-loopback hosts must set this pin. -
portal_session_ttl_hours: Hours a portal browser session cookie remains valid (default 12). -
ingress_origin: Public origin the library's active ingress plugin reported, loaded from the database at run time.Never read from or written to
config.toml: handlers write the in-memory configuration back to the file, and a plugin-reported name must not become the operator's override. Read the origin throughIntegrationsConfig::effective_public_origin.
pub fn effective_public_origin(&self) -> Option<&str>
The library's public origin: the operator's
integrations.public_origin when set, otherwise the origin the
active ingress plugin reported.
The origin as written (callers trim and normalize it), or None when
neither is set.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PluginRegistryEntry {
pub kind: String,
pub url: Option<String>,
pub name: Option<String>,
}
One configured plugin registry source ([[plugins.registries]]).
Fields
kind: Adapter kind:static,cargo,npm, orpypi.url: Index / registry URL (required forstatic; optional overrides for others).name: Optional operator-facing name.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PluginsConfig {
pub isolation: Isolation,
pub jail_bin: Option<PathBuf>,
pub jail: PluginsJailConfig,
pub registries: Vec<PluginRegistryEntry>,
pub allow_unverified_publisher: bool,
pub webhooks: WebhooksExposure,
}
[plugins] — how external plugin guests are run.
Separate from [sources.*] / [integrations.*], which say which plugins
to load and pass them their own knobs. This says how the host runs whichever
ones it loads.
Fields
-
isolation: How strictly guest processes must be confined. -
jail_bin: Explicit path tobookclerk-jail. Normally left unset, in which case the launcher is found beside the running executable. -
jail: Optional global jail resource ceilings for all plugin guests. -
registries: Federated discovery sources (static indexes, cargo, npm, pypi).Search order is list order; default when empty is crates.io only.
-
allow_unverified_publisher: When true, community packages without independent publisher authenticity may be installed without--allow-unverified-publisher(digests are still required). Bookclerk does not verify publisher signatures. -
webhooks: Whether plugins'[[webhooks]]take requests from the Internet onPOST /hooks/<token>/<name>.
pub fn apply_env_overrides(&mut self)
Apply BOOKCLERK_PLUGIN_* environment overrides.
Environment wins over TOML, matching every other section.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PluginsJailConfig {
pub memory_mib: Option<u64>,
pub cpu_rate_percent: Option<u32>,
pub extra_processes: Option<u32>,
}
Optional global resource ceilings for plugin guest jails under [plugins.jail].
These override label defaults when building a guest jail spec. Guest filesystem access remains install read-only plus host-managed data/tmp — not a free-form path widen.
cpu_rate_percent is percent of one logical CPU (100 = one core) and is a
per-jail ceiling only (min(grant, this, host_max)). Quotas are rate
limits, not reservations: if many plugins’ ceilings sum above host capacity,
the OS scheduler shares CPU among runnable guests. Bookclerk does not keep a
cumulative Σ ledger or throttle later spawns.
Fields
memory_mib: Soft memory ceiling in mebibytes (mapped to Specmemory_bytes).cpu_rate_percent: Per-jail CPU rate ceiling (one-core percent units). Defaults to 80.extra_processes: Ceiling on extra processes/threads beyond launcher overhead. Defaults to 2.
pub fn clamp(&mut self)
Clamp CPU / extra-process ceilings into host-safe ranges when set.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct RelayedLine<'a> {
pub level: RelayedLevel,
pub text: &'a str,
}
One relayed line: its level and its text without the timestamp and level.
Fields
level: The level to log it at.text: The text after the prefix (usually<target>: <message> <fields>), or the whole line, trimmed, when it had no prefix.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct AccessCode(/* private */);
A report's access code: the credential that reads the report back from
the collector or deletes it. Canonical form: exactly
ACCESS_CODE_LENGTH characters of ACCESS_CODE_ALPHABET, no
separators. Debug never prints it.
pub fn parse(text: &str) -> Option<Self>
Parses a canonical access code, as the collector sends it.
text- Candidate text.
The code, or None unless the text is exactly
ACCESS_CODE_LENGTH alphabet characters.
pub fn as_str(&self) -> &str
The canonical code.
pub fn display(&self) -> String
The code as people read it, in hyphenated groups of four
(K7QM-3XRD-PW9T-H2CF).
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct ReportId(/* private */);
A report ID the collector assigned: a version-4 UUID in lowercase hyphenated form.
pub fn parse(text: &str) -> Option<Self>
Parses a report ID.
text- Candidate text. Unlike the install ID file, no surrounding whitespace is allowed.
The ID, or None unless the text is a lowercase hyphenated
version-4 UUID.
pub fn as_str(&self) -> &str
The ID as text.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct ReportRecord {
pub report_id: ReportId,
pub trigger: String,
pub version: String,
pub sent_at_unix_ms: u64,
pub access_code: Option<AccessCode>,
pub deleted_at_unix_ms: Option<u64>,
}
One report this install sent.
Fields
report_id: The collector's ID for the report.trigger: Why it was sent (crash,error_burst,cli_error, …).version: The Bookclerk version that sent it.sent_at_unix_ms: When the collector accepted it, Unix milliseconds.access_code: The code that reads it back or deletes it, when the collector issued one.deleted_at_unix_ms: When this install deleted the collector's stored copy, Unix milliseconds, orNonewhile it is stored.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct SubmitReply {
pub report_id: ReportId,
pub access_code: Option<AccessCode>,
}
What the collector's POST /submit reply names.
Fields
report_id: The report's ID.access_code: Its access code, orNonewhen the collector issued none (no dashboard database, its daily cap reached, or an older collector) or sent one that is not a canonical code.
Implements: Clone, Debug, Eq, PartialEq
pub struct LookupAnswer {
pub report_id: ReportId,
pub received_at_unix_ms: u64,
pub deleted_at_unix_ms: Option<u64>,
pub report: Option<LookupReport>,
pub issues: Vec<LookupIssue>,
pub fix: Option<LookupFix>,
}
The collector's answer to a lookup.
Fields
report_id: The report's ID; always the one that was asked for.received_at_unix_ms: When the collector received it, Unix milliseconds.deleted_at_unix_ms: When its sender deleted the stored copy, Unix milliseconds, orNonewhile it is stored.report: The stored report, orNoneonce deleted (or when the collector could not read it).issues: Issues tracking it, the tracking issue first.fix: The tracking issue's fix, if one is recorded.
Implements: Clone, Debug, Eq, PartialEq, Serialize
pub struct LookupEvent {
pub ts_unix_ms: u64,
pub level: EventLevel,
pub target: String,
pub message: String,
pub fields: Vec<(String, String)>,
}
One logged event in a stored report, already redacted by the install that sent it.
Fields
ts_unix_ms: When it happened, Unix milliseconds, or0when the report had none.level: Its severity.target: Where it was logged (the tracing target).message: The message.fields:(name, value)pairs recorded with it.
Implements: Clone, Debug, Eq, PartialEq, Serialize
pub struct LookupFix {
pub pr_number: Option<u64>,
pub pr_url: Option<String>,
pub fixed_in: Option<String>,
}
The fix recorded for the report's tracking issue.
Fields
pr_number: The pull request that fixed it, when known.pr_url: That pull request's page (https://), when known.fixed_in: The first release that contains the fix, when one has shipped.
Implements: Clone, Debug, Eq, PartialEq, Serialize
pub struct LookupIssue {
pub number: u64,
pub title: String,
pub state: IssueState,
pub url: String,
}
A GitHub issue that tracks the report.
Fields
number: The issue number.title: Its title.state: Whether it is open.url: Its page; always anhttps://link.
Implements: Clone, Debug, Eq, PartialEq, Serialize
pub struct LookupReport {
pub version: String,
pub trigger: String,
pub os: String,
pub arch: String,
pub distro: String,
pub events: Vec<LookupEvent>,
}
A stored report as the collector returns it.
Fields
version: The Bookclerk version that sent it.trigger: Why it was sent.os: The sender's operating system.arch: The sender's CPU architecture.distro: The sender's Linux distribution, or empty.events: The events it carried, oldest first.
Implements: Clone, Debug, Eq, PartialEq, Serialize
pub struct AuthConfig {
pub password: Option<String>,
pub key_store: Option<KeyStoreKind>,
pub oidc: OidcBrokerConfig,
}
Auth encryption settings ([auth] section).
Bookclerk always encrypts credentials via the process DEK (master.key).
Set BOOKCLERK_AUTH_PASSWORD (preferred) or [auth].password to wrap the
DEK with a passphrase at rest (BCK1 → BCK2). A later password can be
applied via CLI (config master-key wrap / config set auth.password) or
daemon config reload — no GUI in this surface.
Fields
password: Optional passphrase wrappingmaster.key. PreferBOOKCLERK_AUTH_PASSWORDenv (wins when both are set). Registered for log redaction on load.key_store: Where this install keeps the library's data-encryption key ([auth].key_store). Unset means the host's default: the OS keychain for the desktop app, themaster.keyfile for the daemon and CLI. Set tokeychain, it is required: a keychain that can't be reached is an error rather than a fallback to the file.systemd-credsalways falls back to the file when the key can't be sealed.oidc: Optional upstream OIDC/OAuth identity broker ([auth.oidc]).
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct Config {
pub paths: Option<Paths>,
pub library: LibraryConfig,
pub database: DatabaseConfig,
pub output: OutputConfig,
pub daemon: DaemonConfig,
pub auth: AuthConfig,
pub integrations: IntegrationsConfig,
pub discovery: DiscoveryConfig,
pub diagnostics: DiagnosticsConfig,
pub media: MediaConfig,
pub jobs: JobsConfig,
pub events: EventsConfig,
pub plugins: PluginsConfig,
pub uploads: UploadsConfig,
pub events_revision: Option<i64>,
pub events_authority: Option<String>,
pub output_revision: Option<i64>,
pub output_authority: Option<String>,
}
Top-level Bookclerk configuration.
Fields
-
paths: Filesystem layout (resolved at load time; not always present in TOML). -
library: Library / scan / acquire behaviour ([library]). -
database: Library database backend plugin ([database]). -
output: Acquire packaging ([output]). After control-plane enrollment every field except the host-localin_progressis overlaid from thecore.outputdatabase document; the TOML table only seeds it once. -
daemon: HTTP control-plane / tray settings ([daemon]). -
auth: Master-key wrapping passphrase ([auth]). -
integrations: Connect-portal settings ([integrations]). Not diagnostics. -
discovery: Discovery / recommendations / request queue ([discovery]). -
diagnostics: Opt-in crash / error-burst report upload ([diagnostics]). -
media: Media decode / encode worker pool ([media]). -
jobs: Durable job queue ([jobs]). -
events: Durable domain-event outbox ([events]). -
plugins: How external plugin guests are run ([plugins]). -
uploads: Upload limits on this node ([uploads]). -
events_revision: Revision of the DB-authoritative[events]document after overlay.Absent until control-plane bootstrap or reconcile loads
core.events. Not serialized toconfig.toml. Compared only withSelf::events_authority. -
events_authority: Library id that producedSelf::events_revision.A revision from another library is not newer or older; a database swap replaces this authority explicitly. Not serialized to
config.toml. -
output_revision: Revision of the DB-authoritative[output]document (core.output) after overlay. Absent until control-plane bootstrap or reconcile loads it; compared only withSelf::output_authority. Not serialized. -
output_authority: Library id that producedSelf::output_revision. Not serialized.
pub fn load(cli_files_dir: Option<PathBuf>, config_path: Option<PathBuf>) -> Result<Self>
Load config: defaults ← optional TOML file ← environment overrides.
cli_files_dir- Optional override forBOOKCLERK_FILES_DIR.config_path- Optional explicit path toconfig.toml.
Returns crate::ConfigError when the file cannot be read or parsed, or
when soft validation of destinations / database fails after merge.
pub fn from_toml_file(path: &Path) -> Result<Self>
Deserialize configuration from a TOML file on disk.
Returns crate::ConfigError::Read or crate::ConfigError::Parse.
pub fn from_toml_str(text: &str, origin: &str) -> Result<Self>
Deserialize configuration from a TOML string (tests / embedded configs).
Returns crate::ConfigError::Parse on invalid TOML.
pub fn apply_env_overrides(&mut self)
Apply BOOKCLERK_* environment overrides.
pub fn validate(&self) -> Result<()>
Soft validation of cross-field constraints.
Returns an error when the operation fails.
pub fn auth_password(&self) -> Option<String>
Resolve the passphrase that wraps master.key.
Prefers BOOKCLERK_AUTH_PASSWORD over [auth].password.
pub fn register_known_secrets(&self)
Register config/env secrets for exact-value log redaction.
pub fn resolve_relative_paths(&mut self)
Resolve relative file paths (Widevine CDM, scratch dir, database
files) under files_dir.
Absolute paths are unchanged; relative ones become
{BOOKCLERK_FILES_DIR}/<path> so systemd/Docker cwd does not matter.
pub fn warn_unsupported_options(&self)
Warn / note about Widevine / auth encryption setup.
pub fn write_toml_file(&self, path: &Path) -> Result<()>
Write the config as TOML (skips resolved paths).
Stages a same-directory temp file, fsyncs it, then atomically replaces
path so a crash cannot leave a truncated config.toml.
On Unix, rename replaces the destination. On Windows, std::fs::rename
cannot replace an existing file, so this uses MoveFileExW with
MOVEFILE_REPLACE_EXISTING instead of delete-then-rename.
Returns an error when the operation fails.
pub fn to_toml_string(&self) -> Result<String>
Serialize to a TOML string suitable for config.toml.
Returns an error when the operation fails.
pub fn paths(&self) -> &Paths
Resolved paths (panic only if load was not used — callers should use load).
Panics when an internal invariant does not hold.
pub fn download_cache_dir(&self) -> PathBuf
Scratch directory for downloads / decrypt (InProgress or default cache).
Implements: Clone, Debug, Default, Deserialize<'de>, PartialEq, Serialize
pub struct DaemonAuthConfig {
pub enabled: bool,
pub session_ttl_hours: u64,
pub login_max_failures: u32,
pub login_lockout_secs: u64,
pub require_second_factor: bool,
pub tray_handoff_ttl_secs: u64,
}
Operator token / session settings for the daemon HTTP API.
Fields
enabled: When true,/api/*(and legacy control routes) require Bearer or session cookie.session_ttl_hours: Browser session lifetime in hours afterPOST /api/auth/login.login_max_failures: Failed sign-in attempts before a lockout, counted per client IP across the sign-in routes, and per account for password re-checks by a signed-in user (elevation, password change,current_password).login_lockout_secs: How long a client stays locked out after exceedingSelf::login_max_failures.require_second_factor: When true, password login requires TOTP or the user must sign in with a passkey.tray_handoff_ttl_secs: How long a tray/CLI loopback?code=ticket stays valid (clamped to 30..=900).
pub fn tray_handoff_ttl_secs_clamped(&self) -> u64
Ticket lifetime used when minting a loopback sign-in code.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct DaemonConfig {
pub listen: ListenAddrs,
pub json_logs: bool,
pub tray: bool,
pub auth: DaemonAuthConfig,
pub trusted_proxies: Vec<String>,
pub node_api: NodeApiConfig,
}
Daemon / HTTP control plane settings.
Fields
-
listen: Bind addresses for the HTTP control plane (string or array in TOML).Default binds both IPv4 and IPv6 loopback on port 8787.
-
json_logs: Emit JSON logs on stderr when true (journald sink is always structured). -
tray: When true,bookclerkdstarts an in-process system tray in a graphical session (opens the web UI in the system browser).Headless hosts (no
DISPLAY/WAYLAND_DISPLAY, no session bus) skip the tray. Override withBOOKCLERK_NO_TRAY=1orBOOKCLERK_DAEMON_TRAY=0. -
auth: Operator authentication for the HTTP API / GUI. -
trusted_proxies: Peer addresses trusted to setX-Forwarded-For/Forwarded(CIDR or IP).Empty (default): always use the direct TCP peer — safe behind no proxy. When the peer matches an entry, login throttling uses the leftmost
X-Forwarded-Forclient address (typical single reverse-proxy layout).In
[daemon.node_api] mode = "proxy", a matching peer is also the only one whoseX-Forwarded-Protothe node API believes. -
node_api: Transport policy for the branch-node API ([daemon.node_api]). Bootstrap configuration, likeSelf::listen.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct DiagnosticsConfig {
pub share_reports: bool,
pub collector_url: String,
pub upload_on_crash: bool,
pub upload_on_error_burst: bool,
pub upload_on_warn_burst: bool,
pub error_burst_threshold: u32,
pub error_burst_window_secs: u64,
pub warn_burst_threshold: u32,
pub warn_burst_window_secs: u64,
pub ring_buffer_capacity: u32,
pub share_usage: bool,
pub demo: bool,
}
Opt-in sharing of recent redacted logs on crash or error bursts.
Defaults to disabled. Operators flip share_reports and set collector_url
(or bake BOOKCLERK_DIAGNOSTICS_COLLECTOR_URL at cargo build time).
The client POSTs to /submit; a GitHub Action calls /report.
Bookclerk never manages log-file rotation — use journald / the container runtime (Windows Event Log / macOS unified logging are future work).
Fields
share_reports: When true, share redacted crash/ERROR-burst reports with the collector.collector_url: Worker origin (HTTPS). When empty, usesBOOKCLERK_DIAGNOSTICS_COLLECTOR_URLfrom config/runtime env, else the value baked in atcargo buildtime.upload_on_crash: Upload the ring buffer from the panic hook.upload_on_error_burst: Upload when ERROR volume crosses the burst threshold.upload_on_warn_burst: Upload when WARN volume crosses the warn-burst threshold.error_burst_threshold: Number of ERROR events inside the window that trigger an upload.error_burst_window_secs: Sliding window length for error-burst detection, in seconds.warn_burst_threshold: Number of WARN events inside the window that trigger an upload.warn_burst_window_secs: Sliding window length for warn-burst detection, in seconds.ring_buffer_capacity: Max redacted events retained for upload: Bookclerk's own events through TRACE, other crates' from INFO up.share_usage: When true, send a weekly anonymous check-in (a random install ID, version, platform and kind) so the project can count active installs. Separate fromshare_reports; reports carry the install ID only when this is on.demo: Marks this install as a copy of the hosted demo: reports saydeployment = "demo"and no check-in is sent. The demo image sets it.
pub fn effective_collector_url(&self) -> String
Resolved Worker origin: config/env collector_url, else baked deploy URL.
pub fn effective_lookup_url(&self) -> String
HTTPS endpoint the install reads its own reports back from
(…/lookup; deletion is …/lookup/delete), or empty when no
collector is configured.
pub fn effective_submit_url(&self) -> String
HTTPS endpoint clients POST redacted JSON to (…/submit).
pub fn upload_ready(&self) -> bool
True when report sharing is enabled and a collector URL can be resolved.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct DiscoveryConfig {
pub worldcat_enabled: bool,
pub storefront_candidates: bool,
pub storefront_seed_limit: usize,
pub storefront_max_remote_calls: usize,
pub exclude_graphicaudio_series_sets: bool,
pub listen_sync_interval_minutes: u64,
pub recommend_limit: usize,
}
Discovery / recommendations / embeddings settings.
Fields
worldcat_enabled: Reserved for a future WorldCat provider (requires API key).storefront_candidates: Expand recommendations from storefront catalogs (unowned titles).storefront_seed_limit: Max local taste seeds used for storefront expansion.storefront_max_remote_calls: Cap remote storefront HTTP calls per recommend run.exclude_graphicaudio_series_sets: When true, drop GraphicAudio Magento series-set SKUs from candidates. Default false — series sets are included.listen_sync_interval_minutes: How oftenbookclerkdsyncs ABS listening progress (0 = disabled).recommend_limit: Default number of titles returned by a recommendations run (default 20).
Implements: Clone, Debug, Default, Deserialize<'de>, PartialEq, Serialize
pub struct LibraryConfig {
pub auto_acquire: bool,
pub scan_interval_minutes: u64,
pub import_episodes: bool,
pub import_plus_titles: bool,
pub download_episodes: bool,
pub save_podcasts_to_parent_folder: bool,
pub enrich_from_audible: bool,
pub enrich_min_confidence: u8,
pub fix_storage_layout: bool,
pub upgrade_quality: bool,
pub upgrade_daily_limit: u32,
}
Library / scan related settings.
Fields
auto_acquire: Automatically acquire newly scanned titles (daemon).scan_interval_minutes: Scan interval in minutes forbookclerkd(0 = disabled).import_episodes: Import podcast episodes during scan (ImportEpisodes).import_plus_titles: Import Audible Plus titles during scan (ImportPlusTitles).download_episodes: Acquire podcast episodes (DownloadEpisodes; distinct fromImportEpisodes).save_podcasts_to_parent_folder: Save podcast episodes into the parent show's folder (SavePodcastsToParentFolder).enrich_from_audible: After scan, match non-Audible rows (e.g. Libro.fm) to Audible ASINs via the public Audible catalog and the deployed metadata providers (the Audnexus plugin).enrich_min_confidence: Minimum match confidence (0–100) to accept an Audible ASIN enrichment. Uses AudioBookshelf-style duration/title/author scoring (default 90).fix_storage_layout: When matching storage to the library, relocate matched audio (and accompanying sidecars) onto the configured naming-profile layout. Default false — match in place without moving files.upgrade_quality: Once a day, ask each store that answers quality offers whether an account would now download a better file than the one the library holds, and download it again when it would (bookclerkd). Off by default.upgrade_daily_limit: Most quality upgrades queued per store account per day (at least 1); each download also waits for the account's pace.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct NodeApiConfig {
pub mode: NodeApiMode,
pub acme_contact: Option<String>,
pub tls_listen: Option<String>,
pub acme_directory: Option<String>,
pub acme_directory_ca: Option<String>,
}
[daemon.node_api]: transport policy for branch nodes.
Fields
mode: Which connections may reach the node API.acme_contact: ACME account contact (mailto:ops@example.com). Required foracme.tls_listen: Address of the built-in TLS listener (0.0.0.0:8443). Required foracmeandself_signed. ACME's TLS-ALPN-01 challenge reaches it on port 443 of the public origin's host, so forward 443 here.acme_directory: ACME directory URL. Defaults to Let's Encrypt production (LETS_ENCRYPT_DIRECTORY); set it for staging or a private ACME CA.acme_directory_ca: PEM file of extra root certificates trusted for the ACME directory's own HTTPS (a private ACME CA). The webpki roots are always trusted.
pub fn is_default(&self) -> bool
True for the default table (skipped when writing config.toml).
pub fn validate(
&self,
trusted_proxies: &[String],
public_origin: Option<&str>,
) -> Result<(), String>
Checks that the mode has what it needs. An invalid table makes the node API refuse every connection.
Returns a description of the first missing or invalid setting.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct ProcessEnvGuard {
/* private fields */
}
Process-wide lock around BOOKCLERK_* environment reads and test writes.
std::env::set_var races with std::env::var. Config::load holds this
lock while it reads overrides. A test that publishes an override holds the
same lock for the whole mutation, including the later load on that thread.
pub fn enter() -> Self
Blocks until this thread owns the process environment lock.
Implements: Drop
pub struct UploadsConfig {
pub max_file_bytes: u64,
pub max_staged_bytes: u64,
pub free_disk_floor_percent: u8,
pub idle_ttl_hours: u64,
}
[uploads]: per-node upload limits.
Fields
max_file_bytes: Largest single file, in bytes.max_staged_bytes: Most bytes one person may have staged in unfinished batches.free_disk_floor_percent: Percent of the node's disk (0 to 90) that must stay free; a batch or chunk that would leave less is refused.idle_ttl_hours: Hours an open batch may sit without a chunk before it is pruned.
pub fn free_disk_floor(&self) -> u8
The free-disk floor as a share, capped at 90 percent so a typo cannot close staging for good.
pub fn idle_ttl(&self) -> Duration
The idle time, at least one hour.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum CacheSettingError {
UnknownKey(String),
NotANumber(&'static str),
OutOfRange { key: &'static str, min: u64, max: u64 },
}
Why a cache.* value was refused.
Variants
UnknownKey: The key is not acache.*key.NotANumber: The value is not a whole number without sign or separators.OutOfRange: The value is a whole number outside the key's range.key: The dotted key.min: Smallest accepted value.max: Largest accepted value.
Implements: Clone, Debug, Display, Eq, Error, PartialEq
pub enum CacheSettingKey {
BudgetBytes,
UnviewedDays,
}
A cache.* settings key.
Variants
BudgetBytes:cache.budget_bytes: bytes one node's image caches may hold.UnviewedDays:cache.unviewed_days: days an entry may go unviewed.
pub const ALL: [Self; 2] = _
Every key, in display order.
pub const fn as_str(self) -> &'static str
The dotted key, such as cache.budget_bytes.
pub fn parse(key: &str) -> Option<Self>
The key key names, matched exactly.
key- A dotted settings key.
None for anything but a cache.* key.
pub const fn range(self) -> (u64, u64)
The smallest and largest value the key accepts.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum DatabasePluginKind {
Sqlite,
D1,
Postgres,
}
Which first-party database plugin is active.
Variants
Sqlite: Local SQLite file under the files directory (default).D1: Cloudflare D1 via the HTTP API.Postgres: PostgreSQL via a connection URL.
pub fn as_str(self) -> &'static str
Stable TOML / CLI id (sqlite, d1, postgres).
pub fn parse(s: &str) -> Option<Self>
Parse a first-party backend id or kind token (sqlite, postgres, pg, d1).
Does not inspect PluginKey text. A provenance-qualified occupancy
string such as cargo:https://evil.example#postgres is not a kind.
First-party classification belongs in plugin-host after resolving a
discovered install (PluginKey + verified provenance).
Some when recognised; None for unknown values.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum ProcessRole {
Daemon,
Desktop,
Cli,
}
Which kind of Bookclerk process installed the subscriber.
Variants
Daemon: The long-running daemon (bookclerkd).Desktop: The desktop window, which runs the host in-process.Cli: The command-line tool (bookclerk).
pub fn as_str(self) -> &'static str
Name reported in uploads and check-ins (daemon, desktop, cli).
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub enum ConfigError {
Read { path: String, source: Error },
Parse { path: String, source: Error },
Invalid(String),
Io(Error),
}
Errors produced while loading or validating configuration.
Variants
Read: Failed to open or read a config file from disk.path: Absolute or display path of the config file that could not be read.source: Underlying I/O failure.
Parse: TOML syntax or type error while deserializing a config file.path: Absolute or display path of the config file that failed to parse.source: Underlying TOML deserialize error.
Invalid: Semantic validation failure after a successful parse (missing required fields, mutually exclusive options, unknown plugin ids, …).Io: Generic I/O failure unrelated to a specific config path context.
Implements: Debug, Display, Error, From<Error>
pub enum FileTimestampMode {
Now,
Purchased,
Published,
}
Which timestamp to apply after acquire (CreationTime / LastWriteTime).
Variants
Now: Use the wall-clock time at acquire completion (default).Purchased: Use the account purchase / added-to-library timestamp when known.Published: Use the publisher release date when known.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum PathSanitizationMode {
Auto,
Windows,
Posix,
S3,
None,
}
How to sanitize storage path segments when crate::OutputConfig::replacement_characters
is empty (explicit rules always win).
Variants
Auto: Leave each destination's character rules to its storage plugin: the host only strips path separators (posix_replacement_characters), and the plugin translates the key into what it can store (a Windows-safe path forlocalon Windows, an S3-safe key for an object store).Windows: NTFS / classic Libation Windows map (: * ? " < > | / \).Posix: Path-separator only (/\) — suitable for Linux/macOS local disks.S3: AWS S3 “characters to avoid” plus path separators.None: Disable platform-specific sanitization; path separators (/\) are still stripped so metadata cannot inject extra directories.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum AfterIngest {
Move,
Delete,
Leave,
}
What happens to a drop folder item once it has been ingested.
Variants
Move: Move the item to_imported/<date>/inside the drop folder (a failed item goes to_failed/).Delete: Delete the item once every destination copy is stored (a failed item goes to_failed/).Leave: Leave the item where it is and remember its signature so it is not ingested twice.
pub const ALL: [Self; 3] = _
Every value, in the order the names are documented.
pub fn as_str(self) -> &'static str
The value's name on the wire.
pub fn parse(name: &str) -> Option<Self>
Reads a value by its wire name (Self::as_str), exactly.
pub fn writes(self) -> bool
True when the drop folder plugin must be able to write (move or
delete); leave only reads.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, Hash, PartialEq, Serialize, ToSchema
pub enum IntakeAttribution {
Owner,
Subfolder,
}
Who holds the books a drop folder ingests.
Variants
Owner: Every item is held byIntakeSettings::patron.Subfolder: Each top-level folder is named after a patron's username and holds that patron's items; an item one level deeper is one book.
pub const ALL: [Self; 2] = _
Every value, in the order the names are documented.
pub fn as_str(self) -> &'static str
The value's name on the wire.
pub fn parse(name: &str) -> Option<Self>
Reads a value by its wire name (Self::as_str), exactly.
pub fn item_depth(self) -> usize
How many leading path segments name one item: the item itself, plus
the patron folder in subfolder mode.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, Hash, PartialEq, Serialize, ToSchema
pub enum Isolation {
Required,
BestEffort,
Off,
}
What to do when a child process cannot be confined.
Shared by every tier that runs untrusted work in a child: [media] for
codec workers and [plugins] for storefront guests. The tiers differ in what
they reach for, not in how an operator wants a missing jail handled.
Variants
Required: Refuse to run the work when the jail does not engage. The default: a host that cannot sandbox should not process untrusted input in reach of the master key.BestEffort: Confine where the platform allows and log what did not engage. Use on kernels without Landlock, accepting that the work runs unconfined there.Off: Run with no jail at all. Development only.
pub fn as_str(self) -> &'static str
Canonical spelling, as written in config.toml.
pub fn parse(value: &str) -> Option<Self>
Parse a config or environment value.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum OsLogFacility {
Journald,
OsLog,
EventLog,
}
Which OS facility was attached (if any).
Variants
Journald: Linux systemd journal (/run/systemd/journal/socket).OsLog: Apple Unified Logging (os_log).EventLog: Windows Event Log Application channel.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum LogFormat {
Text,
Json,
}
Output format for the stderr sink.
Variants
Text: Human-oriented text (CLI default).Json: Structured JSON (daemon default / log aggregators).
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub enum NamingProfile {
Audiobookshelf,
Classic,
}
Preset path-template profile.
Select via output.naming_profile. Individual folder_template /
file_template / chapter_file_template values override the profile when
set.
Variants
Audiobookshelf: Audiobookshelf layout:{Author}/{Series}/{N} - {Book}or{Author}/{Book}; the file is the full title with the edition's call number.Classic: Previous Libation desktop defaults (Templates.*.DefaultTemplate).
pub fn all() -> &'static [NamingProfile]
All known profiles (for CLI listing).
pub fn as_str(self) -> &'static str
Stable config / CLI id (audiobookshelf, classic).
pub fn description(self) -> &'static str
Short human description of the profile's layout intent.
pub fn parse(value: &str) -> Option<Self>
Parse a profile id (case-insensitive). Accepts common aliases.
pub fn templates(self) -> NamingProfileTemplates
Built-in folder / file / chapter-file templates for this profile.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum OidcProvisionMode {
MappedRole,
Any,
Allowlist,
InviteOnly,
}
How an upstream provider decides who may become a first-party User.
Variants
MappedRole: Require a mapped group/role claim (owner/administrator/member).Any: Any authenticated account; JIT asOidcProviderConfig::default_role.Allowlist: Authenticated and allowlisted (email domain and/orsub).InviteOnly: No JIT; SSO only links a pre-created User.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum ResolveOperatorTokenEnv {
Env,
}
How an operator token was resolved from env (config-layer only).
Variants
Env: Value fromBOOKCLERK_OPERATOR_TOKEN.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum BadBookAction {
Ask,
Abort,
Retry,
Ignore,
}
How to handle acquire failures (BadBook setting).
Variants
Ask: Prompt the operator (interactive CLI / GUI) for how to proceed (default).Abort: Stop the acquire batch on the first hard failure.Retry: Retry the failed title before giving up.Ignore: Skip the failed title and continue the batch.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum MissingFileAction {
MarkMissing,
Restore,
}
What happens to a stored copy whose file disappears from its destination outside Bookclerk (noticed by the destination's change feed or listing).
Variants
MarkMissing: The copy is marked missing and left alone. When no destination holds the edition any more, it is no longer acquired, so a member can ask for it again. Default.Restore: The copy turns pending and the background retry writes it again.
pub fn as_str(self) -> &'static str
The stored spelling.
pub fn parse(value: &str) -> Option<Self>
The action a spelling names, ignoring ASCII case and taking - for
_; None for any other value.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum MultiDestinationMode {
SyncMissing,
RefetchMissing,
RefetchAll,
}
Behavior when some output destinations already have a title and others do not.
Variants
SyncMissing: Copy the existing object from a present destination into missing ones (no store re-download). Default.RefetchMissing: Re-run acquire fetch/encode, but write only to destinations that lack the title.RefetchAll: Re-run acquire and write to every enabled destination.
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum CopyFormat {
M4b,
Mp3,
Mp3Chapters,
Original,
Opus,
}
The format of one copy of a book.
Variants
M4b: One M4B with tags and chapters (output formatenriched_m4b).Mp3: One MP3 (output formatsingle_mp3).Mp3Chapters: One MP3 per chapter (output formatsplit_mp3_by_chapter).Original: The audio as the store delivered it (output formatnone).Opus: One Ogg Opus file with tags and chapters (output formatopus), an advanced format.
pub const ALL: [Self; 5] = _
Every format, in the order the names are documented.
pub fn as_str(self) -> &'static str
The format's name in settings, filter rules and file rows.
pub fn is_advanced(self) -> bool
True for the advanced formats: ones players and servers read less widely than M4B and MP3, which settings screens list apart from the common ones.
pub fn parse(raw: &str) -> Option<Self>
Reads a format name, without case; None for any other text.
pub fn of_output(format: OutputFormat) -> Option<Self>
The copy format an output format produces; None for the format
the acquire pipeline refuses (split_mp3_by_size).
pub fn output(self) -> OutputFormat
The output format the acquire pipeline packages this copy with.
pub fn is_encoded(self) -> bool
True for the formats an encoder writes (MP3, Opus), whose quality
is an encoder setting rather than original.
Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Display, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize, ToSchema
pub enum PathLengthMeasure {
Chars,
Utf8Bytes,
}
How to measure path component length when truncating.
Variants
Chars: Unicode scalar count (classic Libation on Windows).Utf8Bytes: UTF-8 byte count (classic Libation on Unix; always used for S3 keys).
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum ChapterJsonMode {
Off,
Flat,
Tree,
Both,
}
Whether / which chapter JSON sidecars to write beside acquired audio.
Default is Self::Off. Replaces the old save_chapter_json bool +
chapter_layout pair for sidecar output (Audible API fetch layout is
chosen separately when chapters are needed for embedding).
Variants
Off: Do not write chapter JSON sidecars.Flat: Writechapters.flat.jsononly.Tree: Writechapters.tree.json(nested) only.Both: Write both flat and tree sidecars.
pub fn wants_flat(self) -> bool
True when a flat chapters.flat.json sidecar should be written.
pub fn wants_tree(self) -> bool
True when a nested chapters.tree.json sidecar should be written.
pub fn wants_any(self) -> bool
True when any chapter JSON sidecar mode other than Self::Off is set.
pub fn parse(raw: &str) -> Option<Self>
Parse off|flat|tree|both, or legacy bool-ish values (true→tree, false→off).
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum OutputFormat {
EnrichedM4b,
SingleMp3,
SplitMp3ByChapter,
SplitMp3BySize,
Opus,
None,
}
Post-download output formatting. Default is enriched M4B (tags + chapters).
split_mp3_by_size parses but is not implemented yet: the acquire
pipeline rejects a job that selects it before downloading.
Variants
EnrichedM4b: Remux/transcode to M4B and embed metadata/chapters (default).SingleMp3: Single MP3 file (LAME re-encode).SplitMp3ByChapter: One MP3 per chapter (after M4B chapter split).SplitMp3BySize: Split MP3 by target file size (seesplit_mp3_max_mb). Not yet implemented: the acquire pipeline rejects it before downloading.Opus: One Ogg Opus file (libopus, 64 kbit/s, the source's channels up to stereo) with Vorbis comment tags, chapters and cover.None: Leave store-delivered media as-is (no remux/transcode/re-encode).
pub fn parse(raw: &str) -> Option<Self>
Parse a TOML / CLI format id (enriched_m4b, mp3, none, …).
Some when raw matches a known alias; None for unknown values.
pub fn wants_mp3(self) -> bool
True when the format re-encodes to MP3 (single or split).
pub fn wants_split_by_chapter(self) -> bool
True when output is one MP3 file per chapter.
pub fn wants_split_by_size(self) -> bool
True when output is split into MP3 parts by target size.
pub fn is_noop(self) -> bool
True when store-delivered media is left as-is (no remux/transcode).
pub fn wants_opus(self) -> bool
True when the format encodes to Ogg Opus.
pub fn prefers_m4b_container(self) -> bool
True when the pipeline prefers an M4B intermediate (enriched or chapter-split).
Implements: Clone, ComposeSchema, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize, ToSchema
pub enum FilterEffect {
Include,
Exclude,
}
Whether a FilterRule lets matching books in or keeps them out.
Variants
Include: Matching books are taken (once any include rule exists, only books that match one are).Exclude: Matching books are refused, whatever the include rules say.
Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize, ToSchema
pub enum FilterField {
Patron,
Storefront,
Account,
MediaKind,
Format,
Quality,
}
The book field a FilterRule matches one value of.
Variants
Patron: A patron whose store account holds the book, by user id (3).Storefront: The storefront the book came from, by its plugin's alias (audible,libro), compared without case.Account: The store account that holds the book, by its id at the store.MediaKind: What the book is:bookorpodcast(a podcast episode is a podcast).Format: A copy's format ([CopyFormat]:m4b,mp3,mp3_chaptersororiginal), compared without case.Quality: A copy's quality ([CopyQuality]:original,64k,v2-monoand so on), compared without case.
pub const ALL: [Self; 6] = _
Every field, in the order the names are documented.
pub fn parse(name: &str) -> Option<Self>
Reads a field by its wire name (Self::as_str), exactly; None
for any other text.
pub fn as_str(self) -> &'static str
The field's name on the wire.
pub fn is_copy_field(self) -> bool
True for the fields that describe a copy of the book (format,
quality) rather than the book.
Implements: Clone, ComposeSchema, Copy, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize, ToSchema
pub enum PlacementMediaKind {
Book,
Podcast,
}
What a book is, as a destination filter sees it.
Variants
Book: A book (any form: narration, dramatisation, ebook and so on).Podcast: A podcast show or one of its episodes.
pub fn as_str(self) -> &'static str
The kind's name on the wire and in rule values.
pub fn parse(value: &str) -> Option<Self>
Reads a rule value (book or podcast, without case).
pub fn from_content_kind(content_kind: &str) -> Self
The kind of a library title from its content kind label (book,
podcast or episode): episodes and shows are podcasts, everything
else is a book.
Implements: Clone, ComposeSchema, Copy, Debug, Eq, PartialEq, Serialize, ToSchema
pub enum WebhooksExposure {
Auto,
Off,
}
plugins.webhooks: whether the public webhook route is open.
Variants
Auto: Hand out webhook URLs and take requests whenintegrations.public_originis anhttpsorigin on a globally reachable host. The default.Off: Hand out no webhook URLs and answer every request on the route with 503; stored requests stay until they expire.
pub fn as_str(self) -> &'static str
Canonical spelling, as written in config.toml.
pub fn parse(value: &str) -> Option<Self>
Parses a config or settings value.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum RelayedLevel {
Trace,
Debug,
Info,
Warn,
}
The level a relayed line is logged at.
Variants
Trace:TRACE.Debug:DEBUG.Info:INFO, and every line without a level prefix.Warn:WARN, and also a line that saidERROR(relayed lines are capped here).
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum SubmitReplyError {
TooLong,
NotJson,
BadReportId,
}
Why a collector reply was refused.
Variants
TooLong: The reply is longer thanMAX_SUBMIT_REPLY_BYTES.NotJson: The reply is not a JSON object with a stringreport_id.BadReportId:report_idis present but not a version-4 UUID.
Implements: Clone, Copy, Debug, Display, Eq, Error, PartialEq
pub enum EventLevel {
Error,
Warn,
Info,
Debug,
Trace,
}
Severity of one logged event in a report.
Variants
Error:ERROR.Warn:WARN.Info:INFO.Debug:DEBUG.Trace:TRACE.
pub fn parse(text: &str) -> Option<Self>
Reads the collector's spelling.
text-ERROR,WARN,INFO,DEBUGorTRACE.
The level, or None for anything else.
pub fn as_str(self) -> &'static str
The level as the collector and the CLI spell it.
Implements: Clone, Copy, Debug, Eq, PartialEq, Serialize
pub enum IssueState {
Open,
Closed,
}
Whether a GitHub issue is open.
Variants
Open: Still open.Closed: Closed.
Implements: Clone, Copy, Debug, Eq, PartialEq, Serialize
pub enum LookupError {
NotConfigured,
NotFound,
RateLimited,
Unavailable,
Status(u16),
Transport(String),
BadReply(LookupReplyError),
}
Why a lookup or delete did not succeed.
Variants
NotConfigured: No collector URL is configured.NotFound: The collector knows no report with this ID and code (404); the two cases are not told apart.RateLimited: Too many attempts for this report lately (429); try again in a minute.Unavailable: The collector cannot serve lookups (503: no dashboard database).Status: The collector answered with another error status.Transport: The request did not complete.BadReply: The collector's answer was refused.
Implements: Clone, Debug, Display, Eq, Error, PartialEq
pub enum LookupReplyError {
TooLong,
NotJson,
BadShape,
OtherReport,
}
Why a collector answer was refused.
Variants
TooLong: Longer thanMAX_LOOKUP_REPLY_BYTES.NotJson: Not a JSON object.BadShape: A field is missing, of the wrong type, or a link is nothttps://.OtherReport: The answer names a report other than the one asked for.
Implements: Clone, Copy, Debug, Display, Eq, Error, PartialEq
pub enum AudioQuality {
High,
Normal,
}
Audible download bitrate tier (high / normal in TOML).
Variants
High: Highest offered bitrate for the title (default).Normal: Standard / lower bitrate when the store offers a choice.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum KeyStoreKind {
File,
Keychain,
SystemdCreds,
}
Where an install keeps the library's data-encryption key.
Variants
File:{files_dir}/master.keyholds the key itself (BCK1, orBCK2under the auth password).Keychain: The OS keychain (Keychain Services, Credential Manager or Secret Service) holds the key;master.keyonly names the item (BCK3).SystemdCreds:systemd-credsseals the key to this machine (its TPM where there is one) and the daemon's user, or the service unit hands it in;master.keyonly names the item (BCK4). For headless Linux.
pub fn as_str(self) -> &'static str
The setting's spelling: file, keychain or systemd-creds.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, FromStr, PartialEq, Serialize
pub enum NodeApiMode {
Loopback,
Proxy,
Acme,
SelfSigned,
Tunnel,
}
How branch nodes may reach the node API ([daemon.node_api] mode).
Plain HTTP is accepted only on loopback, in every mode.
Variants
Loopback: Loopback connections only (the default).Proxy: A TLS-terminating reverse proxy listed indaemon.trusted_proxies.Acme: The built-in TLS listener with an ACME (Let's Encrypt) certificate.SelfSigned: The built-in TLS listener with a self-signed certificate whose SPKI pin travels in enrollment links.Tunnel: The library's active relay ingress plugin carries public traffic through itsORIGINbinding; branches verify the relay's edge certificate against the webpki roots.
pub fn as_str(self) -> &'static str
Stable TOML spelling.
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub fn replace_file(from: &Path, to: &Path) -> Result<()>
Replace to with from, both in the same directory. to may already
exist; on Windows this goes through MoveFileExW with
MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH (see the module
docs), retrying briefly while another replace of to settles. The moved
file keeps its own permissions, so a 0600 staging file
lands as a 0600 target.
Returns an I/O error when the platform replace operation fails.
pub fn parse_cache_setting(
key: &str,
value: &str,
) -> Result<(CacheSettingKey, u64), CacheSettingError>
Parses one cache.* setting.
The value may have surrounding ASCII whitespace; inside, it must be one
or more ASCII digits, no sign, and within the key's CacheSettingKey::range.
key- The dotted key.value- The value as text.
The key and the value.
CacheSettingError for an unknown key, a value that is not a whole
number, or one out of range.
pub fn cookie_secure_suffix(public_origin: Option<&str>) -> &'static str
Append ; Secure when the configured public origin is HTTPS.
Local loopback development (no public_origin, or http://…) keeps cookies
usable over plain HTTP.
pub fn oidc_transaction_cookie_flags(public_origin: Option<&str>) -> String
Cookie flags for the OIDC login transaction (state binding).
Apple's form_post callback is a cross-site POST, so HTTPS origins use
SameSite=None; Secure. Local HTTP keeps Lax so GET callbacks still send
the cookie on loopback.
pub fn session_cookie_flags(public_origin: Option<&str>) -> String
Build common session cookie attributes (HttpOnly; SameSite=Lax + optional Secure).
pub fn resolve_d1_api_token() -> Result<String>
Resolve the D1 API token from the environment (host-mediated secret).
Uses BOOKCLERK_D1_API_TOKEN, falling back to CLOUDFLARE_API_TOKEN.
Returns an error when the operation fails.
pub fn resolve_postgres_url(config: &Config) -> Result<String>
Resolve the Postgres connection URL from config (env already applied).
url_file takes precedence over url.
Returns an error when the operation fails.
pub fn graphical_session_available() -> bool
True when it is reasonable to start the in-process tray (windowing + session bus).
Linux requires a display (DISPLAY or WAYLAND_DISPLAY) and a session-bus
signal (DBUS_SESSION_BUS_ADDRESS or XDG_RUNTIME_DIR). Windows and macOS
return true; headless CI/servers on Linux return false.
pub fn diagnostics_global() -> Option<&'static DiagnosticsHandle>
Accessor for the process-global diagnostics handle.
pub fn apply_replacements(input: &str, rules: &[ReplacementRule]) -> String
Apply replacement rules to a string (classic filename sanitization).
pub fn classic_key_aliases() -> HashMap<&'static str, &'static str>
Classic Settings.json key → dotted config path for config get / config set.
pub fn default_replacement_characters() -> Vec<ReplacementRule>
Alias for windows_replacement_characters (classic default name).
pub fn key_matches_reconcile_pattern(pattern: &str, key: &str) -> bool
True when key matches a reconcile pattern built with
reconciliation_wildcard_rules (wildcard = any single character).
pub fn parse_replacement_characters(value: &Value) -> Vec<ReplacementRule>
Parse classic ReplacementCharacters JSON.
Supports both the classic Libation Settings.json shape
({ "Replacement": [ { "CharacterToReplace": ":", "ReplacementString": "_" }, … ] })
and a flat map shape ({ ":": "_", … }). An empty or unrecognised value falls
back to windows_replacement_characters (classic migrate parity).
pub fn posix_replacement_characters() -> Vec<ReplacementRule>
Path-separator sanitization for POSIX local filesystems.
Keeps characters such as : that are legal on Linux/macOS but reserved on
Windows. / and \ are still replaced so tag values cannot inject path
segments.
pub fn reconciliation_wildcard_rules(explicit: &[ReplacementRule]) -> Vec<ReplacementRule>
Replacement rules that turn every known sanitizable character into
RECONCILE_WILDCARD.
Used when searching for existing liberations: creation still follows the
active profile, but reconcile must match files produced under Windows,
POSIX, or S3 rules (or custom replacement_characters).
pub fn resolve_replacement_characters(
explicit: &[ReplacementRule],
mode: PathSanitizationMode,
) -> Vec<ReplacementRule>
Resolve the character-replacement map the host applies to tag values when it fills a naming template.
Explicit non-empty replacement_characters always wins. Otherwise
path_sanitization selects a profile; PathSanitizationMode::Auto
strips only path separators and leaves the rest to the destination's
storage plugin, which translates the host key into the path or object
key it stores.
pub fn s3_replacement_characters() -> Vec<ReplacementRule>
Characters AWS recommends avoiding in S3 object keys, plus path separators.
See Object key naming guidelines.
Characters that only need URL encoding (e.g. :) are left intact.
pub fn windows_replacement_characters() -> Vec<ReplacementRule>
NTFS-safe replacement map (classic Libation Windows defaults subset).
pub fn checkin_due(files_dir: &Path, now_ms: u64) -> bool
Whether a check-in is due.
files_dir- The Bookclerk files directory.now_ms- Current Unix time in milliseconds.
True when no check-in was recorded, the record is unreadable, or the last
one is at least CHECKIN_INTERVAL_MS old (or in the future, after a
clock change).
pub fn record_checkin(files_dir: &Path, now_ms: u64) -> Result<()>
Records an accepted check-in.
files_dir- The Bookclerk files directory.now_ms- When it was accepted, Unix milliseconds.
Returns an error when the record cannot be written.
pub fn send_checkin(config: &DiagnosticsConfig, checkin: &CheckIn) -> Result<(), String>
Sends one check-in to the collector.
config- Diagnostics settings (collector URL).checkin- The body.
Returns an error when no collector URL is configured, the body cannot be serialized, or the request fails.
pub fn glob_matches(pattern: &str, name: &str) -> bool
True when name matches pattern, where * matches any run of
characters (empty included) and ? exactly one, compared without ASCII
case. Runs in time proportional to the product of the two lengths.
pub fn parse_intake_settings(body: &[u8]) -> Result<IntakeSettings, IntakeSettingsError>
Reads and validates the settings an operator sent, or a stored
core.intake body.
Returns an IntakeSettingsError for a body over
MAX_INTAKE_SETTINGS_BYTES, bytes that are not one JSON object, an
unknown or repeated key, a value of the wrong type, or settings that fail
IntakeSettings::validate.
pub fn journald_available() -> bool
Back-compat alias.
pub fn os_log_available() -> bool
Probe whether an OS log facility appears available.
pub fn init_tracing(format: LogFormat, default_level: &str) -> LoggingHandle
Convenience wrapper matching the historical CLI/daemon call site.
pub fn init_tracing_with(opts: TracingOptions) -> LoggingHandle
Install a global tracing subscriber (stderr + optional OS facility + diagnostics).
Filter precedence for stderr/OS facility: BOOKCLERK_LOG → RUST_LOG →
opts.default_level. The diagnostics ring buffer is not filtered by that
directive — it records Bookclerk's own TRACE and above (other crates' INFO
and above, see ring_filter) so uploads retain deep context.
Widen local verbosity with e.g. BOOKCLERK_LOG=bookclerk=debug when investigating.
Secrets are redacted on every sink via the public register_secret / redact_str helpers.
pub fn ring_filter() -> Targets
The diagnostics ring's per-layer filter: TRACE for
RING_TRACE_TARGETS (matched as prefixes, so bookclerkd and
bookclerk_library count), RING_DEPENDENCY_LEVEL for the rest.
pub fn strip_ansi_escapes(input: &str) -> Cow<'_, str>
Remove ECMA-48/ANSI escape sequences so piped guest logs stay plain text.
bookclerk-workerd and other guests may emit colored tracing_subscriber
lines on stderr. The host re-logs those lines into JSON; leaving CSI codes
in place produces \u001b[… noise in daemon.json_logs.
pub fn allowlist_permits(
email: Option<&str>,
sub: &str,
allowed_emails: &[String],
allowed_domains: &[String],
allowed_subjects: &[String],
global_domains: &[String],
) -> bool
Whether an allowlist provider admits this (email, sub).
Empty email, domain, and subject lists fail closed. When the provider lists
are empty, global_domains is used as the domain allowlist.
pub fn email_domain_allowed(email: Option<&str>, domains: &[String]) -> bool
Whether email matches an allowlist of domains (empty list = unrestricted).
pub fn oidc_apple_private_key_env_key(provider_id: &str) -> String
Environment variable holding a Sign in with Apple .p8 private key.
pub fn oidc_client_secret_env_key(provider_id: &str) -> String
Environment variable holding a provider's client secret.
Hyphens in provider_id become underscores. Example: github →
BOOKCLERK_OIDC_GITHUB_CLIENT_SECRET.
pub fn oidc_secret_store_name(logical: &str, generation: u64) -> String
encrypted_secrets.name for an OIDC client secret or Apple key.
Generation 0 is the unversioned legacy name; later generations use
name@generation so a crashed PUT cannot make new credentials visible
under the still-published config.
pub fn resolve_mapped_role(
role_map: &BTreeMap<String, String>,
claim_values: &[String],
) -> Option<String>
Pick the highest Bookclerk role from mapped claim values.
Precedence: owner > administrator > member.
pub fn generate_operator_token() -> Result<String>
Generate a 32-byte hex operator token.
Returns an error when the operation fails.
pub fn read_operator_token_env() -> Result<Option<(String, ResolveOperatorTokenEnv)>>
Read BOOKCLERK_OPERATOR_TOKEN when set and non-empty.
Returns an error when the operation fails.
pub fn validate_operator_token(token: &str, source: &str) -> Result<String>
Reject tokens that can break URL fragments, HTTP headers, or shell pastes.
Generated tokens are hex. Env overrides must stay printable single-line and
free of whitespace / control characters so they cannot inject into
Authorization headers.
Returns an error when the operation fails.
pub fn normalize_storage_prefix(prefix: &str) -> String
Normalize a storage key prefix: empty stays empty; otherwise ensure a trailing /.
pub fn copies_to_make(main: Option<OutputCopy>, extra: &[OutputCopy]) -> Vec<OutputCopy>
Every copy an acquire makes, in order: the main output's copy first
(when the pipeline can make it), then each valid extra copy that
differs from every earlier one, at most MAX_EXTRA_COPIES of them
whatever the list holds.
pub fn mp3_cbr_kbps(kbps: u32) -> u16
The constant bitrate, in kbit/s, the MP3 encoder writes for a requested
kbps: the smallest of MP3_CBR_KBPS at or above it, else 320.
pub fn validate_copies(
main: Option<&OutputCopy>,
copies: &[OutputCopy],
) -> Result<(), CopyError>
Checks a list of extra copies: at most MAX_EXTRA_COPIES, each valid
(OutputCopy::validate), none given twice and none the main output's
copy main.
Returns a CopyError for the first copy that breaks a rule.
pub fn apply_config_updates(
files_dir: Option<PathBuf>,
config_path: Option<PathBuf>,
pairs: &[(&str, &str)],
) -> Result<Config>
Load config, apply pairs, and write the result back to the resolved config path.
files_dir- OptionalBOOKCLERK_FILES_DIRoverride.config_path- Optional explicitconfig.tomlpath.pairs-(key, value)overrides (classic or dotted).
The updated Config after a successful write.
Propagates load, validation, and write failures as crate::ConfigError.
pub fn apply_config_updates_from_path(
path: &Path,
pairs: &[(&str, &str)],
) -> Result<Config>
Load path, apply pairs, and write the updated TOML back to the same path.
path- Existingconfig.tomlto mutate in place.pairs-(key, value)overrides (classic or dotted).
Propagates read, parse, and write failures as crate::ConfigError.
pub fn apply_setting_overrides(config: &mut Config, pairs: &[(&str, &str)])
Apply classic-style -o Setting=value overrides onto config.
Keys may be classic PascalCase (UseWidevine) or dotted TOML paths
(output.widevine). Plugin settings are not config.toml keys; they are
written on the plugin instance (bookclerk plugins config set).
pub fn enforce_storage_key_limits(key: &str, limits: PathLimits) -> String
Enforce per-segment and full-key limits on a relative storage key.
key uses / separators. The final component is treated as a filename
(extension preserved). Returns the possibly truncated key.
pub fn path_len(s: &str, measure: PathLengthMeasure) -> usize
Measure s according to measure.
pub fn truncate_filename_stem(
stem: &str,
ext: &str,
max_filename_length: usize,
measure: PathLengthMeasure,
) -> String
Truncate a filename stem so stem + "." + ext fits in max_filename_length.
When the stem ends with [id] (ASIN/ISBN bracket form used by naming
profiles), the id suffix is preserved and the title prefix is shortened.
pub fn truncate_path_component(
s: &str,
limit: usize,
measure: PathLengthMeasure,
) -> String
Truncate s so its measured length is ≤ limit. Never splits a UTF-8 char.
pub fn resolve_config_path(files_dir: &Path) -> PathBuf
Resolve config file path: BOOKCLERK_CONFIG → {files_dir}/config.toml.
pub fn resolve_files_dir(cli_override: Option<PathBuf>) -> PathBuf
Resolve the Bookclerk files directory.
Precedence:
- Explicit
--bookclerk-files/ caller-provided path BOOKCLERK_FILES_DIR- XDG data dir:
$XDG_DATA_HOME/bookclerk(or platform equivalent) - Fallback:
./BookclerkFiles(cwd-relative, Docker-friendly)
pub fn parse_destination_filter(body: &[u8]) -> Result<DestinationFilter, FilterError>
Parses a destination filter from its raw JSON bytes, sans IO, the way
the web API reads it: the strict JSON shape, then trimmed
(DestinationFilter::normalized) and checked
(DestinationFilter::validate).
Returns a FilterError for bytes that are not the filter's JSON shape
(unknown or repeated keys, wrong types, a missing rule key, an unknown
field or effect name) or a filter that fails
DestinationFilter::validate.
pub fn detect_distro() -> Option<String>
Best-effort OS distribution string (e.g. Ubuntu 24.04.1 LTS).
pub fn node_limits() -> Option<NodeLimits>
This process's cgroup v2 CPU and memory limits, or None when it has
neither (or the platform has no cgroups).
pub fn host_cpu_rate_max() -> u32
Host CPU rate ceiling in one-core percent units (logical_cpus × 100).
pub fn node_logical_cpus() -> u32
Logical CPUs visible to this process (at least 1).
pub fn contains_registered_secret(haystack: &str) -> bool
True if haystack still contains any registered exact secret (post-redaction check).
pub fn is_sensitive_field(name: &str) -> bool
Returns true when a tracing field name should never be logged in cleartext.
pub fn is_upload_identifying_field(name: &str) -> bool
Field names scrubbed from remote diagnostics uploads
in addition to is_sensitive_field. Local journal/stderr may still show them.
pub fn redact_field_value(name: &str, value: &str) -> String
Redact a field value: sensitive names are fully replaced; others are scrubbed.
pub fn redact_str(input: &str) -> String
Scrub known secrets: exact registered values, then pattern matches.
pub fn register_secret(value: impl AsRef<str>)
Register a known secret so it is always scrubbed from logs and diagnostics.
Call this whenever a passphrase, OAuth token, AWS key, etc. enters process memory. Values shorter than 6 characters are ignored.
Also registers common encodings (percent-encoding, + for spaces) so a secret
cannot slip through via URL/query embedding.
pub fn register_secret_bytes(value: &[u8])
Registers one secret value given as bytes, when it is UTF-8 text.
A JSON credential (a token bundle) also registers each string inside it, at any depth, since a log quotes the token field rather than the whole document. Bytes that are not UTF-8 register nothing: the text scrubber can never see them in a log line.
pub fn register_secrets<I, S>(values: I)
where
I: IntoIterator<Item = S>,
S: AsRef<str>,
Register several secrets at once.
pub fn register_secrets_from_env()
Register secrets commonly present in the process environment / config.
Safe to call multiple times. Does not log values.
pub fn sanitize_for_remote_upload(name: &str, value: &str) -> String
Extra sanitization for payloads that leave the machine (collector / B2).
Emails are partially masked (local-part truncated) so triage can still see
rough account shape without shipping a clear address. Other identifying
fields (title, path, account, …) remain fully REDACTED.
pub fn truncate_upload_message(message: &str) -> String
Cap message length used in remote diagnostics events.
pub fn unregister_secret(value: impl AsRef<str>)
Forget a secret register_secret registered, with its encoded forms,
once nothing in the process holds it any more (a short-lived bearer
token whose holder was dropped), so per-request credentials do not pile
up in the registry every log line is checked against. Lines captured
while it was registered were scrubbed then. Only for values unique to
one holder: the registry keeps no count, so a value two holders share
would stop being scrubbed for both.
pub fn parse_relayed_line(line: &str) -> RelayedLine<'_>
Splits a tracing-format prefix (optional timestamp, then a level word) off a relayed stderr line.
A line whose first word (after an optional timestamp, which is a word
starting with a digit and ending in Z) is not exactly one of TRACE,
DEBUG, INFO, WARN or ERROR is returned whole, at
RelayedLevel::Info.
line- One stderr line, ANSI escapes already stripped.
The level and the remaining text, which is always a suffix of line
with its trailing whitespace removed.
pub fn find_report(files_dir: &Path, report_id: &ReportId) -> Option<ReportRecord>
The report with this ID in the history, if it is there.
files_dir- The Bookclerk files directory.report_id- The report.
The newest record with that ID, or None.
pub fn load_report_history(files_dir: &Path) -> Vec<ReportRecord>
Reads the report history, oldest first.
files_dir- The Bookclerk files directory.
The recorded reports. A missing file is an empty history; an unreadable or damaged one is too, because the history is a convenience and the next report rewrites it. Every access code read is registered with log redaction.
pub fn mark_report_deleted(
files_dir: &Path,
report_id: &ReportId,
deleted_at_unix_ms: u64,
) -> Result<()>
Notes in the history that the collector's copy of a report was deleted.
files_dir- The Bookclerk files directory.report_id- The report.deleted_at_unix_ms- When the collector deleted it.
Returns an error when the lock cannot be taken or the history cannot be written. A report not in the history is not an error.
pub fn parse_submit_reply(body: &[u8]) -> Result<SubmitReply, SubmitReplyError>
Reads the report ID and access code from the collector's POST /submit
reply.
body- The reply body as received.
The report ID, and the access code when access_code is a string
holding a canonical code (anything else there is ignored, since the
report is stored either way).
Returns SubmitReplyError when the body is too long, is not a JSON
object with a string report_id, or that value is not a version-4 UUID.
pub fn record_report(files_dir: &Path, record: ReportRecord) -> Result<()>
Adds a report to the history, keeping the newest MAX_REPORT_HISTORY.
Its access code, if any, is registered with log redaction first.
files_dir- The Bookclerk files directory.record- The report the collector just accepted.
Returns an error when the lock cannot be taken or the history cannot be written.
pub fn delete_report(
config: &DiagnosticsConfig,
report_id: &ReportId,
code: &AccessCode,
) -> Result<u64, LookupError>
Deletes the collector's stored copy of a sent report. Its one-line index entry and issue links stay on the collector.
Blocking: call it off an async runtime's worker threads.
config- Diagnostics settings (for the collector URL).report_id- The report.code- Its access code.
When the copy was deleted, Unix milliseconds.
LookupError when no collector is configured, the request fails, the
collector refuses it, or its answer is malformed.
pub fn fetch_report(
config: &DiagnosticsConfig,
report_id: &ReportId,
code: &AccessCode,
) -> Result<LookupAnswer, LookupError>
Reads a sent report back from the collector.
Blocking: call it off an async runtime's worker threads.
config- Diagnostics settings (for the collector URL).report_id- The report.code- Its access code.
The collector's answer.
LookupError when no collector is configured, the request fails, the
collector refuses it, or its answer is malformed.
pub fn parse_delete_reply(
body: &[u8],
expected: &ReportId,
) -> Result<u64, LookupReplyError>
Reads the collector's answer to POST /lookup/delete.
body- The answer body as received.expected- The report whose deletion was asked for.
When the stored copy was deleted, Unix milliseconds (the first deletion's time when it was already gone).
Returns LookupReplyError when the body is too long, not a JSON
object, has no integer deleted_at_unix_ms, or names another report.
pub fn parse_lookup_reply(
body: &[u8],
expected: &ReportId,
) -> Result<LookupAnswer, LookupReplyError>
Reads the collector's answer to POST /lookup.
Every field the collector sends is required with its type, except that
deleted_at_unix_ms, report, fix and the fix's fields may be absent
or null; other keys are ignored and, as in any JSON reader, a repeated
key keeps its last value.
body- The answer body as received.expected- The report that was asked for.
The answer.
Returns LookupReplyError when the body is too long, not a JSON
object, malformed (including an issue or pull request link that is not
https://), or names another report.
pub fn read_node_api_spki_pin(files_dir: &Path) -> Option<String>
The SPKI pin of the daemon's self-signed node API certificate, once the
daemon has generated it. Enrollment links carry it in
[daemon.node_api] mode = "self_signed".
pub type Result<T> = Result<T, ConfigError>;
Result alias for configuration load and validation helpers in this crate.
pub const DEFAULT_CACHE_BUDGET_BYTES: u64 = _;
Default disk budget for one node's image caches: 1 GiB.
pub const DEFAULT_CACHE_UNVIEWED_DAYS: u32 = 90;
Default days an entry may go unviewed before it is evicted.
pub const MAX_CACHE_BUDGET_BYTES: u64 = _;
Largest accepted cache budget: 1 TiB.
pub const MAX_CACHE_UNVIEWED_DAYS: u32 = 3650;
Largest accepted unviewed_days, about ten years.
pub const MIN_CACHE_BUDGET_BYTES: u64 = _;
Smallest accepted cache budget: 16 MiB, room for a few hundred covers.
pub const SLOW_TARGET: &str = "bookclerk::slow";
Target of the events that mark a slow response.
Events on this target count toward the slow_burst trigger instead of
warn_burst, so slowness on a starved machine and real faults reach the
collector as different kinds of report. The daemon's request log
(bookclerkd) is the writer today.
pub const RECONCILE_WILDCARD: char = '\u{E000}';
Sentinel placed in reconcile path patterns where a sanitizable character appeared in metadata. Matches any single character in an on-disk key.
pub const CHECKIN_INTERVAL_MS: u64 = _;
Time between check-ins: one week, in milliseconds.
pub const BUILTIN_IGNORE_PATTERNS: &[&str] = _;
File name patterns every drop folder ignores: partial downloads,
editor and sync-tool temporaries, and desktop metadata files. A name
starting with . is always ignored as well.
pub const DEFAULT_SCAN_INTERVAL_SECONDS: u32 = 300;
Default time between two listings of a drop folder, in seconds.
pub const DEFAULT_SETTLE_SECONDS: u32 = 60;
Default quiet time before an item is ingested, in seconds.
pub const FAILED_FOLDER: &str = "_failed";
Folder the host moves items that failed to ingest into, at the drop folder's root.
pub const IMPORTED_FOLDER: &str = "_imported";
Folder the host moves ingested items into, at the drop folder's root.
pub const MAX_IGNORE_PATTERNS: usize = 64;
Most extra ignore patterns one drop folder may hold.
pub const MAX_IGNORE_PATTERN_BYTES: usize = 128;
Longest ignore pattern, in UTF-8 bytes.
pub const MAX_INTAKE_CANONICAL_BYTES: usize = _;
Largest the settings may be once written out with every default filled
in, in bytes. IntakeSettings::validate holds them to it, so accepted
settings always fit, with room for the {"intake":…} wrapper, both the
16 KiB stored-document cap and MAX_INTAKE_SETTINGS_BYTES when they
are read back. Only patterns full of ", which JSON escapes, come near
it: 64 plain 128-byte patterns take under 9 KiB.
pub const MAX_INTAKE_SETTINGS_BYTES: usize = _;
Largest settings body parse_intake_settings reads, in bytes.
pub const MAX_PRUNE_IMPORTED_DAYS: u16 = 3_650;
Longest time _imported folders may be kept before pruning, in days
(about ten years).
pub const MAX_SCAN_INTERVAL_SECONDS: u32 = 86_400;
Longest time between two listings an operator may set, in seconds.
pub const MAX_SETTLE_SECONDS: u32 = 86_400;
Longest quiet time an operator may set, in seconds (one day).
pub const MIN_SCAN_INTERVAL_SECONDS: u32 = 30;
Shortest time between two listings an operator may set, in seconds.
pub const MIN_SETTLE_SECONDS: u32 = 5;
Shortest quiet time an operator may set, in seconds.
pub const RING_DEPENDENCY_LEVEL: LevelFilter = LevelFilter::INFO;
Level the diagnostics ring keeps for targets outside RING_TRACE_TARGETS.
pub const RING_TRACE_TARGETS: [&str; 1] = _;
Target prefixes the diagnostics ring keeps through TRACE. Every other
target (dependencies such as h2, hyper, rustls, reqwest, and
log-crate records) is kept from INFO up, so their per-frame TRACE events
do not crowd Bookclerk's own events out of the ring.
pub const MAX_EXTRA_COPIES: usize = 8;
Most copies a library may keep beside its main output.
pub const MAX_QUALITY_BYTES: usize = 16;
Longest quality name, in bytes (320k-mono is nine).
pub const MP3_CBR_KBPS: [u16; 7] = _;
The constant bitrates, in kbit/s, the MP3 encoder writes.
bookclerk-media rounds any other requested bitrate up to the next of
these (and anything above 256 to 320), so a quality name only offers
these rates: the name then always describes the audio written.
pub const OPUS_KBPS: [u16; 7] = _;
The bitrates, in kbit/s, an Opus copy is named by. Opus encodes in variable bitrate around the target, so these are targets, not caps.
pub const OPUS_MAIN_KBPS: u16 = 64;
The quality of the main output when it is Opus (format = "opus"):
64 kbit/s, keeping the source's channels up to stereo. Another bitrate takes an Opus extra copy beside an
M4B main output.
pub const DEFAULT_MAX_FILENAME_LENGTH: usize = 255;
Classic Libation LongPath.MaxFilenameLength — per path component.
pub const MAX_HOST_KEY_BYTES: usize = 1024;
Largest host key, in UTF-8 bytes, including the destination's prefix: the S3 object-key limit, which file systems also accept.
pub const BOOKCLERK_CONFIG_ENV: &str = "BOOKCLERK_CONFIG";
Override for the config file path (BOOKCLERK_CONFIG).
pub const BOOKCLERK_FILES_DIR_ENV: &str = "BOOKCLERK_FILES_DIR";
Environment variable for the Bookclerk data directory.
pub const MAX_FILTER_RULES: usize = 64;
Most rules one destination filter may hold.
pub const MAX_FILTER_VALUE_BYTES: usize = 128;
Longest rule value, in UTF-8 bytes.
pub const REDACTED: &str = "[REDACTED]";
Replacement token used wherever a secret or sensitive value is scrubbed.
pub const ACCESS_CODE_ALPHABET: &str = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
Crockford's base32 alphabet, which access codes are written in: digits and letters without I, L, O and U.
pub const ACCESS_CODE_LENGTH: usize = 16;
Characters in an access code, without the group separators.
pub const MAX_REPORT_HISTORY: usize = 200;
How many reports the history keeps; older ones are dropped first.
pub const MAX_SUBMIT_REPLY_BYTES: usize = 4096;
Longest collector reply, in bytes, that parse_submit_reply reads.
The real reply is about 200 bytes.
pub const REPORT_HISTORY_FILE: &str = "diagnostics/reports.json";
File, relative to the files directory, that holds the report history.
pub const MAX_LOOKUP_REPLY_BYTES: usize = _;
Longest collector answer, in bytes, that parse_lookup_reply and
parse_delete_reply read. A stored report is at most 256 KiB, and the
answer caps every event, so a real answer is well under this.
pub const DEFAULT_UPGRADE_DAILY_LIMIT: u32 = 5;
Default for LibraryConfig::upgrade_daily_limit.
pub const LETS_ENCRYPT_DIRECTORY: &str = "https://acme-v02.api.letsencrypt.org/directory";
Let's Encrypt's production ACME directory.
pub const MAX_UPGRADE_DAILY_LIMIT: u32 = 100;
Highest LibraryConfig::upgrade_daily_limit the settings accept.
pub const NODE_API_ACME_DIR: &str = "acme";
Directory under $BOOKCLERK_FILES_DIR holding the ACME account and
certificate cache (mode 0700 on Unix).
pub const NODE_API_SELF_SIGNED_DIR: &str = "node-api/self-signed";
Directory under $BOOKCLERK_FILES_DIR holding the self-signed node API
certificate, its key, and its SPKI pin (mode 0700 on Unix).
pub const NODE_API_SPKI_PIN_FILE: &str = "spki-pin";
File in NODE_API_SELF_SIGNED_DIR holding the SPKI pin
(base64url SHA-256 of the certificate's SubjectPublicKeyInfo).
pub const TRAY_HANDOFF_TTL_SECS_DEFAULT: u64 = 180;
Default tray/CLI loopback sign-in link lifetime (seconds).
pub const TRAY_HANDOFF_TTL_SECS_MAX: u64 = 900;
Maximum allowed DaemonAuthConfig::tray_handoff_ttl_secs.
pub const TRAY_HANDOFF_TTL_SECS_MIN: u64 = 30;
Minimum allowed DaemonAuthConfig::tray_handoff_ttl_secs.
Generated from crates/bookclerk-config at main · View as Markdown