hydracache 0.49.0

User-facing HydraCache runtime crate.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

use std::time::Duration;

/// Refresh behavior for loader-based cache reads.
///
/// `RefreshOptions` is opt-in and does not affect [`HydraCache::get_or_load`].
/// Use it with [`HydraCache::get_or_load_with_refresh`] when an application can
/// tolerate a recently expired value while a refresh is running or when a
/// loader temporarily fails.
///
/// # Example
///
/// ```rust
/// use std::time::Duration;
///
/// use hydracache::RefreshOptions;
///
/// let options = RefreshOptions::new()
///     .refresh_ahead(Duration::from_secs(10))
///     .stale_while_revalidate(Duration::from_secs(300))
///     .stale_on_loader_error(Duration::from_secs(600))
///     .serve_stale_on_loader_error(true);
///
/// assert_eq!(options.refresh_ahead_value(), Some(Duration::from_secs(10)));
/// assert_eq!(
///     options.stale_while_revalidate_value(),
///     Some(Duration::from_secs(300))
/// );
/// assert_eq!(
///     options.stale_on_loader_error_value(),
///     Some(Duration::from_secs(600))
/// );
/// assert!(options.serve_stale_on_loader_error_value());
/// ```
///
/// [`HydraCache::get_or_load`]: crate::HydraCache::get_or_load
/// [`HydraCache::get_or_load_with_refresh`]: crate::HydraCache::get_or_load_with_refresh
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct RefreshOptions {
    stale_while_revalidate: Option<Duration>,
    stale_on_loader_error: Option<Duration>,
    refresh_ahead: Option<Duration>,
    serve_stale_on_loader_error: bool,
}

impl RefreshOptions {
    /// Create empty refresh options.
    pub fn new() -> Self {
        Self::default()
    }

    /// Return recently expired values for this window while refreshing in the
    /// background.
    pub fn stale_while_revalidate(mut self, window: Duration) -> Self {
        self.stale_while_revalidate = Some(window);
        self
    }

    /// Use a stale value for this window when the foreground loader fails.
    pub fn stale_on_loader_error(mut self, window: Duration) -> Self {
        self.stale_on_loader_error = Some(window);
        self.serve_stale_on_loader_error = true;
        self
    }

    /// Refresh a still-fresh value in the background when it is this close to
    /// expiration.
    pub fn refresh_ahead(mut self, threshold: Duration) -> Self {
        self.refresh_ahead = Some(threshold);
        self
    }

    /// Return a stale value when the foreground loader fails.
    ///
    /// When [`RefreshOptions::stale_on_loader_error`] is not configured, this
    /// uses the [`RefreshOptions::stale_while_revalidate`] window as the
    /// fallback window.
    pub fn serve_stale_on_loader_error(mut self, enabled: bool) -> Self {
        self.serve_stale_on_loader_error = enabled;
        self
    }

    /// Return the stale-while-revalidate window.
    pub fn stale_while_revalidate_value(&self) -> Option<Duration> {
        self.stale_while_revalidate
    }

    /// Return the refresh-ahead threshold.
    pub fn refresh_ahead_value(&self) -> Option<Duration> {
        self.refresh_ahead
    }

    /// Return the explicit stale-on-loader-error window.
    pub fn stale_on_loader_error_value(&self) -> Option<Duration> {
        self.stale_on_loader_error
    }

    /// Return whether loader failures may fall back to stale values.
    pub fn serve_stale_on_loader_error_value(&self) -> bool {
        self.serve_stale_on_loader_error
    }

    pub(crate) fn stale_on_loader_error_window(&self) -> Option<Duration> {
        if !self.serve_stale_on_loader_error {
            return None;
        }
        self.stale_on_loader_error.or(self.stale_while_revalidate)
    }
}

#[cfg(test)]
mod tests {
    use std::time::Duration;

    use super::RefreshOptions;

    #[test]
    fn refresh_options_default_to_strict_cache_behavior() {
        let options = RefreshOptions::new();

        assert_eq!(options.stale_while_revalidate_value(), None);
        assert_eq!(options.stale_on_loader_error_value(), None);
        assert_eq!(options.refresh_ahead_value(), None);
        assert_eq!(options.stale_on_loader_error_window(), None);
        assert!(!options.serve_stale_on_loader_error_value());
    }

    #[test]
    fn refresh_options_builder_sets_all_values() {
        let options = RefreshOptions::new()
            .stale_while_revalidate(Duration::from_secs(60))
            .stale_on_loader_error(Duration::from_secs(120))
            .refresh_ahead(Duration::from_secs(5))
            .serve_stale_on_loader_error(true);

        assert_eq!(
            options.stale_while_revalidate_value(),
            Some(Duration::from_secs(60))
        );
        assert_eq!(
            options.stale_on_loader_error_value(),
            Some(Duration::from_secs(120))
        );
        assert_eq!(options.refresh_ahead_value(), Some(Duration::from_secs(5)));
        assert_eq!(
            options.stale_on_loader_error_window(),
            Some(Duration::from_secs(120))
        );
        assert!(options.serve_stale_on_loader_error_value());
    }

    #[test]
    fn refresh_options_can_reuse_stale_while_revalidate_window_for_loader_errors() {
        let options = RefreshOptions::new()
            .stale_while_revalidate(Duration::from_secs(60))
            .serve_stale_on_loader_error(true);

        assert_eq!(
            options.stale_on_loader_error_window(),
            Some(Duration::from_secs(60))
        );
    }
}