asimov_patterns/options/
caching.rs

1// This is free and unencumbered software released into the public domain.
2
3//! Shared cache freshness options for source commands.
4
5#[cfg(feature = "clap")]
6use alloc::string::ToString;
7#[cfg(any(feature = "std", feature = "clap"))]
8use alloc::{format, string::String};
9use bon::Builder;
10use core::time::Duration;
11
12#[cfg(feature = "clap")]
13const HELP_MAX_AGE: &str = r#"Maximum acceptable cache age.
14
15Use a positive duration such as 1h, 7d, or "1m 30s".
16If omitted, the default is module-specific."#;
17
18/// Cache freshness requests shared by fetcher and lister commands.
19///
20/// Flatten this alongside [`crate::FetcherOptions`] or [`crate::ListerOptions`]
21/// in a host's Clap arguments. The maximum age defaults to `None`, leaving
22/// policy to the selected module. Clap accepts durations such as `1h`,
23/// `7d`, or `1m 30s`; it rejects a zero maximum age.
24/// Builders and direct field assignments do not validate durations.
25///
26/// With `serde`, the wire name is `max-age`; `max_age` and `maxAge` are accepted
27/// as input aliases. Supplying multiple spellings of the field is an error.
28///
29/// These options describe requests; they do not implement caching. Hosts can
30/// forward explicit values using `max_age_option()` (available with `std` or
31/// `clap`). Execution deadlines are configured separately by
32/// [`crate::TimingOptions`].
33#[derive(Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd, Builder)]
34#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
35#[builder(derive(Debug))]
36#[cfg_attr(feature = "clap", derive(clap::Args))]
37#[cfg_attr(feature = "clap", command(about = None, long_about = None))]
38pub struct CachingOptions {
39    /// Maximum acceptable cache age (for example, 1h or 7d).
40    /// Default is module-specific.
41    #[cfg_attr(
42        feature = "clap",
43        clap(
44            long,
45            value_name = "DURATION",
46            value_parser = parse_max_age,
47            help = "Maximum acceptable cache age",
48            long_help = HELP_MAX_AGE
49        )
50    )]
51    #[cfg_attr(
52        feature = "serde",
53        serde(
54            rename = "max-age",
55            alias = "max_age",
56            alias = "maxAge",
57            default,
58            skip_serializing_if = "Option::is_none",
59            with = "crate::serialization::optional_duration"
60        )
61    )]
62    pub max_age: Option<Duration>,
63}
64
65#[cfg(any(feature = "std", feature = "clap"))]
66impl CachingOptions {
67    /// Formats an explicit maximum age as one `--max-age=DURATION` argument.
68    ///
69    /// Returns `None` when unset, preserving the module's default policy.
70    pub fn max_age_option(&self) -> Option<String> {
71        self.max_age
72            .map(|value| format!("--max-age={}", humantime::format_duration(value)))
73    }
74}
75
76#[cfg(feature = "clap")]
77fn parse_max_age(value: &str) -> Result<Duration, String> {
78    let duration = humantime::parse_duration(value).map_err(|error| error.to_string())?;
79    if duration.is_zero() {
80        return Err("max age must be positive".into());
81    }
82    Ok(duration)
83}
asimov_patterns/options/caching.rs

asimov_patterns/options/
caching.rs
