Struct CalendarClient 

pub struct CalendarClient { /* private fields */ }

Client responsible for fetching economic calendar releases over HTTP and managing disk caching.

Implementations

impl CalendarClient

pub fn default_cache_dir() -> PathBuf

Returns the default platform cache directory for redfolder.

• On Windows: Respects %LOCALAPPDATA%\redfolder\cache, %APPDATA%\redfolder\cache, or %USERPROFILE%\.cache\redfolder.
• On Linux/Unix: Respects $XDG_CACHE_HOME/redfolder or $HOME/.cache/redfolder.
• Fallback: System temporary directory (redfolder_cache).

pub fn try_new(cache_dir: Option<PathBuf>) -> Result<Self>

Create a new CalendarClient with an optional cache directory fallibly.

pub fn new(cache_dir: Option<PathBuf>) -> Self

Create a new CalendarClient with an optional cache directory. If None, defaults to CalendarClient::default_cache_dir().

pub fn try_without_cache() -> Result<Self>

Create a new CalendarClient without any local disk caching fallibly.

pub fn without_cache() -> Self

Create a new CalendarClient without any local disk caching.

pub fn with_user_agent( cache_dir: Option<PathBuf>, user_agent: &str, ) -> Result<Self>

Create a new CalendarClient with a custom User-Agent string.

pub fn with_options( client: Client, calendar_url: impl Into<String>, cache_dir: Option<PathBuf>, request_timeout: Duration, ) -> Self

Create with custom options.

pub fn with_fallback_url(self, url: impl Into<String>) -> Self

Add a fallback calendar endpoint URL used if the primary URL fails.

pub fn with_fallback_urls<I, S>(self, urls: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Add multiple fallback calendar endpoint URLs.

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

Configured fallback calendar URLs.

pub fn calendar_url(&self) -> &str

Primary calendar URL.

pub fn set_calendar_url(&mut self, url: impl Into<String>)

Set the primary calendar URL.

pub fn add_fallback_url(&mut self, url: impl Into<String>)

Add a fallback calendar URL.

pub fn with_max_response_bytes(self, max_bytes: usize) -> Self

Configure the maximum response body size in bytes to prevent unbounded allocations.

pub fn set_max_response_bytes(&mut self, max_bytes: usize)

Set maximum allowable response body size in bytes.

pub fn max_response_bytes(&self) -> usize

Maximum allowable response body size in bytes.

pub fn with_max_event_count(self, max_events: usize) -> Self

Configure the maximum number of raw events permitted from upstream.

pub fn set_max_event_count(&mut self, max_events: usize)

Set maximum allowable raw event count.

pub fn max_event_count(&self) -> usize

Maximum allowable raw event count.

pub fn with_max_retries(self, max_retries: usize) -> Self

Configure maximum HTTP retry attempts for transient errors (429, 408, 5xx).

pub fn max_retries(&self) -> usize

Configured maximum retry attempts.

pub fn with_backoff( self, initial_delay: Duration, max_retry_after: Duration, ) -> Self

Configure exponential backoff parameters.

pub fn backoff_initial_delay(&self) -> Duration

Initial exponential backoff delay duration.

pub fn max_retry_after(&self) -> Duration

Maximum duration allowed for server-specified Retry-After delays.

pub fn with_overall_timeout(self, timeout: Duration) -> Self

Configure an overall wall-clock timeout ceiling spanning all retry attempts and backoffs.

pub fn overall_timeout(&self) -> Option<Duration>

Overall wall-clock timeout ceiling if set.

pub fn with_integrity_validator( self, validator: impl Fn(&[RawCalendarEvent]) -> Result<()> + Send + Sync + 'static, ) -> Self

Configure a custom pluggable integrity validator callback.

pub fn with_timezone(self, tz: Tz) -> Self

Configure the default source timezone for naive calendar timestamps.

pub fn set_calendar_timezone(&mut self, tz: Option<Tz>)

Set the default source timezone for naive calendar timestamps.

pub fn calendar_timezone(&self) -> Option<Tz>

Default source timezone if configured.

pub fn with_max_stale_age(self, max_age: Option<Duration>) -> Self

Configure the maximum allowable age for stale cache fallback on network failures. If None, stale cache fallback is disabled.

pub fn set_max_stale_cache_age(&mut self, max_age: Option<Duration>)

Set maximum allowable age for stale cache fallback.

pub fn max_stale_cache_age(&self) -> Option<Duration>

Configured maximum stale cache age.

pub fn with_ttl(self, ttl: Duration) -> Self

Configure an optional Time-To-Live (TTL) for the local disk cache.

pub fn set_cache_ttl(&mut self, ttl: Option<Duration>)

Set an optional Time-To-Live (TTL) for the local disk cache.

pub fn cache_ttl(&self) -> Option<Duration>

Configured cache TTL if set.

pub fn set_cache_path(&mut self, path: impl AsRef<Path>)

Set an explicit cache file path.

pub fn cache_path(&self) -> Option<&Path>

Cache file path if configured.

pub async fn fetch_remote(&self) -> Result<Vec<RawCalendarEvent>>

Fetch fresh calendar events directly from the remote API with bounded retry, response size checks, and fallback URL failover.

Latency Ceiling Guarantee

Worst-case wall-clock latency per URL candidate is strictly bounded: with default settings (30s request timeout, 2 retries, 10s max backoff), worst-case latency under total network timeouts is (1 + 2) * 30s + 20s = 110s. Under immediate 429/5xx status responses, worst-case latency is <= 21s.

If an overall_timeout is set, the entire operation across all candidates is terminated when the deadline expires.

pub fn save_cache(&self, events: &[RawCalendarEvent]) -> Result<()>

Save raw calendar events to the local disk cache atomically (if cache path is set).

On Unix systems, applies restrictive file permissions (0600) and directory permissions (0700) to prevent unauthorized access or tampering on shared multi-user hosts.

pub fn load_cache_data(&self) -> Option<CachedCalendarData>

Load full cached calendar data including metadata, with recovery from legacy and corrupted caches.

pub fn load_cache(&self) -> Option<Vec<RawCalendarEvent>>

Load raw calendar events from the local disk cache (if exists and readable).

pub fn is_cache_valid(&self) -> bool

Checks whether the disk cache exists and is within its configured TTL.

Legacy caches (version 0) lacking fetch timestamps are rejected.

pub async fn force_fetch(&self) -> Result<Vec<RawCalendarEvent>>

Fetch fresh calendar events directly from the remote API, bypassing cache, protecting against empty responses overwriting good data, and saving to cache on success.

pub async fn fetch_or_cached(&self) -> Result<Vec<RawCalendarEvent>>

Fetch fresh events from the remote API, automatically saving to cache on success, or falling back to local cache if the remote request fails.

Respects configured cache TTL and protects against empty responses overwriting good data.

Trait Implementations

impl Clone for CalendarClient

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CalendarClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CalendarClient

fn default() -> Self

Returns the “default value” for a type.