bookclerk_library::pacing

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

Last updated View as Markdown

Download pacing per store account: the limits, the operator's override, and the decision whether a download may start now.

A storefront declares a pace in plugin.toml [acquire] (a daily budget over any rolling 24 hours, a minimum gap between downloads, and the cool-down to apply when the store answers rateLimited without a retry time). The operator may override it per account. Downloads the host starts itself wait for the pace (decide); downloads a person starts by hand are counted but never held. This module is pure: the ledger and the override live in the library database (LibraryStore::account_pace_state), and bookclerkd holds a paced acquire job between titles when decide says to wait.

See docs/internals/jobs.md#download-pacing.

Item Kind Summary
AcquirePace struct A storefront's declared pace ([acquire]), or the limits in force after an override.
PaceRequest struct A change to one account's pace: the body of POST /api/portal/sources/{source}/connections/{account_id}/pace.
DownloadWindow struct What the ledger says about one account's recent downloads.
PaceOverride enum The operator's override of a storefront's pace for one account.
PaceOverrideError enum Why an override was refused.
WaitReason enum Why a paced download has to wait.
PaceVerdict enum Whether a paced download may start.
parse_pace_request function Parses and checks a pace change request (sans-IO, so the fuzz target and the route run the same code).
decide function Decides whether a paced download on one account may start at now.
cooldown_end function The cool-down end to record after the store answered rateLimited.
BUDGET_WINDOW constant The window the daily budget counts downloads over.
LEDGER_RETENTION constant How long a download stays in the ledger; older rows are pruned. Longer than BUDGET_WINDOW so a clock step never empties the window early.
DEFAULT_COOLDOWN constant Cool-down when the store says to slow down without a retry time and the storefront declares no cooldown_seconds.
MAX_COOLDOWN constant Longest cool-down the host records, whatever the store asked for: a store answer that names a later time is capped here, so a bad retryAfterMs cannot stop an account for good.
MAX_DOWNLOADS_PER_DAY constant Most downloads a day an override may set (the manifest's cap too).
MAX_MIN_GAP_SECONDS constant Longest gap an override may set, in seconds (one day).

Structs

AcquirePace

pub struct AcquirePace {
    pub downloads_per_day: Option<NonZeroU32>,
    pub min_gap: Duration,
    pub cooldown: Duration,
}

A storefront's declared pace ([acquire]), or the limits in force after an override.

Fields

  • downloads_per_day: Downloads allowed in any rolling BUDGET_WINDOW; None for no daily budget.
  • min_gap: Least time between the start of two downloads on one account.
  • cooldown: Cool-down when the store says to slow down without a retry time.

AcquirePace::from_declared

pub fn from_declared(
    downloads_per_day: Option<i64>,
    min_gap_seconds: Option<i64>,
    cooldown_seconds: Option<i64>,
) -> Self

Builds a pace from a manifest's [acquire] values.

Values the manifest validation already bounds are taken as they are; a value out of range here (a manifest built without validation) is clamped rather than refused, and a non-positive budget means none.

Arguments
  • downloads_per_day - [acquire].downloads_per_day.
  • min_gap_seconds - [acquire].min_gap_seconds.
  • cooldown_seconds - [acquire].cooldown_seconds.

AcquirePace::with_override

pub fn with_override(self, override_: &PaceOverride) -> Self

The limits in force once override_ applies to this declared pace.

PaceOverride::Unlimited lifts the budget and the gap but keeps the cool-down: a store that asked to slow down is still obeyed by automatic downloads until the operator clears the cool-down.

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

PaceRequest

pub struct PaceRequest {
    pub override_: Option<PaceOverride>,
    pub clear_cooldown: bool,
}

A change to one account's pace: the body of POST /api/portal/sources/{source}/connections/{account_id}/pace.

Fields

  • override_: The override to store, or None for a request that only clears the cool-down and leaves the stored pace as it is.
  • clear_cooldown: End the store's cool-down too.

Implements: Clone, Copy, Debug, Eq, PartialEq

DownloadWindow

pub struct DownloadWindow {
    pub starts: Vec<DateTime<Utc>>,
}

What the ledger says about one account's recent downloads.

Fields

  • starts: Start times of the downloads in the last BUDGET_WINDOW, oldest first.

DownloadWindow::last

pub fn last(&self) -> Option<DateTime<Utc>>

The latest download start, if any.

DownloadWindow::count

pub fn count(&self) -> usize

Downloads in the window.

Implements: Clone, Debug, Default, Eq, PartialEq

Enums

PaceOverride

pub enum PaceOverride {
    Default,
    Custom { downloads_per_day: Option<NonZeroU32>, min_gap_seconds: Option<u32> },
    Unlimited,
}

The operator's override of a storefront's pace for one account.

Variants

  • Default: The storefront's declared pace.
  • Custom: Custom values; a field left None keeps the storefront's value.
    • downloads_per_day: Downloads allowed in any rolling 24 hours.
    • min_gap_seconds: Least seconds between two downloads, at most MAX_MIN_GAP_SECONDS.
  • Unlimited: No budget and no gap (the cool-down still applies).

PaceOverride::mode_str

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

The stored pace_mode spelling (default, custom, unlimited).

PaceOverride::MODES

pub const MODES: [&'static str; 3] = _

The modes Self::mode_str returns, for the schema's CHECK list.

PaceOverride::validate

pub fn validate(&self) -> Result<(), PaceOverrideError>

Checks an override's values against their ranges.

Errors

Returns a PaceOverrideError naming the first value out of range, or PaceOverrideError::EmptyCustom for a custom override that sets nothing.

PaceOverride::from_row

pub fn from_row(
    mode: &str,
    downloads_per_day: Option<i64>,
    min_gap_seconds: Option<i64>,
) -> Self

Rebuilds an override from its stored row.

An unknown mode or a custom row with any value out of range (a row written by something other than this crate) falls back to Self::Default, so a bad row never lifts the storefront's pace; a value that is absent leaves that limit unset.

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

PaceOverrideError

pub enum PaceOverrideError {
    DownloadsPerDay,
    MinGap,
    EmptyCustom,
}

Why an override was refused.

Variants

Implements: Clone, Debug, Display, Eq, Error, PartialEq

WaitReason

pub enum WaitReason {
    Cooldown,
    DailyBudget,
    Gap,
}

Why a paced download has to wait.

Variants

  • Cooldown: The store asked to slow down.
  • DailyBudget: The rolling 24-hour budget is used up.
  • Gap: The previous download started less than the gap ago.

WaitReason::phrase

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

A short phrase for job progress and logs ("the daily download budget").

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

PaceVerdict

pub enum PaceVerdict {
    Go,
    Wait { until: DateTime<Utc>, reason: WaitReason },
}

Whether a paced download may start.

Variants

  • Go: Start it now.
  • Wait: Wait until until.
    • until: When the download may start.
    • reason: What it is waiting for (the limit that ends last).

Implements: Clone, Copy, Debug, Eq, PartialEq

Functions

parse_pace_request

pub fn parse_pace_request(body: &[u8]) -> Result<PaceRequest>

Parses and checks a pace change request (sans-IO, so the fuzz target and the route run the same code).

The body is one JSON object with a mode of default, custom or unlimited, optional downloads_per_day (1 to MAX_DOWNLOADS_PER_DAY) and min_gap_seconds (0 to MAX_MIN_GAP_SECONDS) that only custom may carry and that it needs at least one of, and an optional boolean clear_cooldown. A body without mode only clears the cool-down: it carries no number and clear_cooldown must be true, and the stored pace is left alone. No other key and no repeated key is accepted; null counts as absent.

Errors

Returns crate::LibraryError::Invalid describing the first rule the body breaks.

decide

pub fn decide(
    pace: &AcquirePace,
    window: &DownloadWindow,
    cooldown_until: Option<DateTime<Utc>>,
    now: DateTime<Utc>,
) -> PaceVerdict

Decides whether a paced download on one account may start at now.

Every limit that holds is checked and the one that ends last wins, so a job parked until until finds every limit clear when it wakes (unless another download started meanwhile).

Arguments

  • pace - The limits in force (AcquirePace::with_override).
  • window - The account's downloads in the last BUDGET_WINDOW.
  • cooldown_until - The end of the store's cool-down, if one is set.
  • now - The current time.

cooldown_end

pub fn cooldown_end(
    pace: &AcquirePace,
    retry_after: Option<Duration>,
    now: DateTime<Utc>,
) -> DateTime<Utc>

The cool-down end to record after the store answered rateLimited.

The store's retry_after wins when it gave one; otherwise the storefront's declared cool-down. Either is capped at MAX_COOLDOWN.

Arguments

  • pace - The account's declared pace (for its cool-down).
  • retry_after - How long the store asked to be left alone, if it said.
  • now - The current time.

Constants

BUDGET_WINDOW

pub const BUDGET_WINDOW: Duration = _;

The window the daily budget counts downloads over.

LEDGER_RETENTION

pub const LEDGER_RETENTION: Duration = _;

How long a download stays in the ledger; older rows are pruned. Longer than BUDGET_WINDOW so a clock step never empties the window early.

DEFAULT_COOLDOWN

pub const DEFAULT_COOLDOWN: Duration = _;

Cool-down when the store says to slow down without a retry time and the storefront declares no cooldown_seconds.

MAX_COOLDOWN

pub const MAX_COOLDOWN: Duration = _;

Longest cool-down the host records, whatever the store asked for: a store answer that names a later time is capped here, so a bad retryAfterMs cannot stop an account for good.

MAX_DOWNLOADS_PER_DAY

pub const MAX_DOWNLOADS_PER_DAY: u32 = 10_000;

Most downloads a day an override may set (the manifest's cap too).

MAX_MIN_GAP_SECONDS

pub const MAX_MIN_GAP_SECONDS: u32 = 86_400;

Longest gap an override may set, in seconds (one day).

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