Skip to main content

etcdrs_util/cache/
mod.rs

1#![doc = include_str!("README.md")]
2
3mod coherence;
4mod driver;
5mod range_spec;
6
7use std::collections::BTreeMap;
8use std::sync::atomic::{AtomicI64, Ordering};
9use std::sync::{Arc, Mutex};
10
11use bytes::Bytes;
12use etcdrs::client::{Compact, Delete, Get, List, Put, Transaction, WatchSender};
13use etcdrs::record::AsKey;
14use etcdrs::{AsRange, Client, Prefix, Record, ResponseHeader, Revision};
15
16pub use driver::{CacheFuture, CacheListStream, CacheListView};
17use range_spec::RangeSpec;
18
19/// A caching wrapper around [`Client`] that serves reads of configured key ranges from a local,
20/// watch-maintained, in-memory store.
21///
22/// Configure the ranges to cache with [`builder`][Self::builder], then use the cache like a
23/// client. Reads of keys outside the configured ranges — and reads the cache cannot prove are
24/// fresh — transparently pass through to the server, so a read through the cache is never slower
25/// than one through the wrapped [`Client`].
26///
27/// Handles are cheap to clone and share one cache. Dropping the last handle stops the background
28/// coherence task, which cancels its watches.
29///
30/// See the [module-level documentation](self) for the coherence model.
31#[derive(Clone)]
32pub struct CacheClient(Arc<CacheClientInner>);
33
34struct CacheClientInner {
35    shared: Arc<Shared>,
36    task: tokio::task::AbortHandle,
37}
38
39impl Drop for CacheClientInner {
40    fn drop(&mut self) {
41        self.task.abort();
42    }
43}
44
45/// State shared between [`CacheClient`] handles and the coherence task.
46struct Shared {
47    client: Client,
48    /// The configured cache ranges. Immutable after construction; a range's index in this list
49    /// identifies it everywhere else (the state vector and watch routing).
50    ranges: Vec<RangeSpec>,
51    /// Per-range cache contents, index-aligned with `ranges`. Never held across an `.await`.
52    state: Mutex<Vec<RangeState>>,
53    /// The highest store revision observed through this client (response headers, seed snapshots,
54    /// and watch events). Zero means nothing has been observed yet.
55    last_known: AtomicI64,
56    /// Control channel to the active watch. Never locked together with `state`.
57    progress: Mutex<ProgressControl>,
58}
59
60impl Shared {
61    /// Record an observed response header, advancing the last-known revision.
62    fn observe_header(&self, header: &ResponseHeader) {
63        self.last_known.fetch_max(header.revision().get(), Ordering::AcqRel);
64    }
65
66    /// The highest observed store revision, if any.
67    fn last_known_revision(&self) -> Option<Revision> {
68        Revision::new(self.last_known.load(Ordering::Acquire))
69    }
70}
71
72/// Handle to the active watch, shared between the coherence task and the read path.
73#[derive(Default)]
74struct ProgressControl {
75    /// The current watcher generation's sender; `None` while the watch is being (re)established.
76    sender: Option<WatchSender>,
77    /// When the last progress request was fired by a gated read, for debouncing. Cleared when a
78    /// stream-wide progress notification arrives so the next gated read may re-request
79    /// immediately.
80    last_request: Option<tokio::time::Instant>,
81}
82
83/// The cached contents of a single configured range.
84#[derive(Default)]
85struct RangeState {
86    /// The latest known records within the range.
87    store: BTreeMap<Bytes, Record>,
88    /// The header of the most recent snapshot, progress notification or event applied to `store`,
89    /// with an event's revision in place of its response's: the store is exact as of
90    /// `header.revision()`. `None` while the range is unseeded: until a listing of it first
91    /// succeeds, and from a refusal of its watch, or a failed listing after compaction, until a
92    /// retry lists it again.
93    header: Option<ResponseHeader>,
94}
95
96impl CacheClient {
97    /// Start building a cache backed by `client`.
98    ///
99    /// ```no_run
100    /// # let client: etcdrs::Client = todo!();
101    /// let cache = etcdrs_util::cache::CacheClient::builder(client)
102    ///     .cache(etcdrs::Prefix("config/"))
103    ///     .cache("leader")
104    ///     .build();
105    /// ```
106    pub fn builder(client: Client) -> CacheClientBuilder {
107        CacheClientBuilder {
108            client,
109            ranges: Vec::new(),
110        }
111    }
112
113    /// The wrapped [`Client`], for operations that should never involve the cache.
114    pub fn client(&self) -> &Client {
115        &self.0.shared.client
116    }
117
118    /// The highest store revision observed through this cache, or `None` if nothing has been
119    /// observed yet.
120    ///
121    /// Every response header seen by this cache — from operations executed through it, from seed
122    /// snapshots, and from the watch's progress notifications — advances this value, as does the
123    /// revision of every watch event. It never decreases.
124    pub fn last_known_revision(&self) -> Option<Revision> {
125        self.0.shared.last_known_revision()
126    }
127
128    /// The revision the cached contents of `range` are exact as of.
129    ///
130    /// Returns `None` if `range` is not one of the configured cache ranges (compared by exact
131    /// boundaries, so e.g. `Prefix("a/")` only matches a range cached as that same prefix) or if
132    /// it is not seeded: it has not been listed yet, it could not be listed, or etcd refused to
133    /// watch it, and no retry has listed it since.
134    pub fn coherent_revision(&self, range: impl AsRange) -> Option<Revision> {
135        let spec = RangeSpec::from_range(range);
136        let index = self.0.shared.ranges.iter().position(|configured| *configured == spec)?;
137        let state = self.0.shared.state.lock().unwrap();
138        state[index].header.map(|header| header.revision())
139    }
140
141    /// Get the record associated with a key.
142    ///
143    /// Served from the local store when the key lies in a configured range that can prove
144    /// freshness; otherwise the read passes through to the server. Revision-pinned gets
145    /// ([`at_revision`][Get::at_revision]) always pass through, since the cache holds only the
146    /// latest values.
147    ///
148    /// ```no_run
149    /// # async {
150    /// # let cache: etcdrs_util::cache::CacheClient = todo!();
151    /// let response = cache.get("my-key").await.unwrap();
152    /// if let Some(record) = response.record() {
153    ///     println!("value: {:?}", record.value());
154    /// }
155    /// # };
156    /// ```
157    pub fn get(&self, key: impl AsKey) -> Get<Self> {
158        Get::new(key).with_client(self.clone())
159    }
160
161    /// Put a value for a key.
162    ///
163    /// Always executed on the server. The cache never applies writes locally — the change becomes
164    /// visible through the watch — but the response's revision immediately gates cached reads, so
165    /// a get issued after this put resolves will never observe the pre-put value.
166    pub fn put(&self, key: impl AsKey) -> Put<Self, ()> {
167        Put::new(key).with_client(self.clone())
168    }
169
170    /// Delete a single key. Always executed on the server; see [`put`][Self::put] for how writes
171    /// interact with the cache.
172    pub fn delete(&self, key: impl AsKey) -> Delete<Self, bool> {
173        Delete::new(key).with_client(self.clone())
174    }
175
176    /// Delete a range of keys. Always executed on the server; see [`put`][Self::put] for how
177    /// writes interact with the cache.
178    pub fn delete_range(&self, range: impl AsRange) -> Delete<Self, usize> {
179        Delete::with_range(range).with_client(self.clone())
180    }
181
182    /// Delete all keys with the given prefix. Always executed on the server; see
183    /// [`put`][Self::put] for how writes interact with the cache.
184    pub fn delete_prefix(&self, prefix: impl AsKey) -> Delete<Self, usize> {
185        Delete::with_prefix(prefix).with_client(self.clone())
186    }
187
188    /// List the records within a range.
189    ///
190    /// Served from the local store when the query is fully contained in a single configured range
191    /// that can prove freshness; otherwise it passes through to the server. Revision-pinned lists
192    /// always pass through.
193    pub fn list(&self, query: impl AsRange) -> List<Self, Record> {
194        List::new(query).with_client(self.clone())
195    }
196
197    /// List the records associated with a prefix.
198    ///
199    /// This is the same as calling [`list`][Self::list] with a [`Prefix`] query.
200    pub fn list_prefix(&self, prefix: impl AsKey) -> List<Self, Record> {
201        self.list(Prefix(prefix))
202    }
203
204    /// Begin a transaction. Always executed on the server, including any read operations it
205    /// contains; see [`put`][Self::put] for how writes interact with the cache.
206    pub fn transaction(&self) -> Transaction<Self> {
207        Transaction::default().with_client(self.clone())
208    }
209
210    /// Compact the store's history up to `revision`. Always executed on the server. If compaction
211    /// outruns a cached range's watch, the coherence task recovers by taking a fresh snapshot.
212    pub fn compact(&self, revision: Revision) -> Compact<Self> {
213        Compact::new(revision).with_client(self.clone())
214    }
215}
216
217/// Builder for a [`CacheClient`]. Created by [`CacheClient::builder`].
218#[must_use = "CacheClientBuilder does nothing unless you call `build`"]
219pub struct CacheClientBuilder {
220    client: Client,
221    ranges: Vec<RangeSpec>,
222}
223
224impl CacheClientBuilder {
225    /// Add a key, range, or prefix whose contents should live in the cache.
226    ///
227    /// Overlapping ranges are allowed but each maintains an independent copy of the overlap.
228    /// etcd has no empty key, so `cache("")` caches no keys, while `cache(..)` caches every key.
229    pub fn cache(mut self, range: impl AsRange) -> Self {
230        self.ranges.push(RangeSpec::from_range(range));
231        self
232    }
233
234    /// Add a prefix whose contents should live in the cache.
235    ///
236    /// Equivalent to calling [`cache`][Self::cache] with a [`Prefix`] query.
237    pub fn cache_prefix(self, prefix: impl AsKey) -> Self {
238        self.cache(Prefix(prefix))
239    }
240
241    /// Build the cache client using the provided Tokio runtime handle.
242    ///
243    /// This is equivalent to calling [`build`][Self::build] from within a Tokio runtime, but allows
244    /// you to specify the runtime explicitly.
245    pub fn build_on(self, runtime: &tokio::runtime::Handle) -> CacheClient {
246        let range_count = self.ranges.len();
247        let shared = Arc::new(Shared {
248            client: self.client,
249            ranges: self.ranges,
250            state: Mutex::new(std::iter::repeat_with(RangeState::default).take(range_count).collect()),
251            last_known: AtomicI64::new(0),
252            progress: Mutex::new(ProgressControl::default()),
253        });
254
255        let task_shared = Arc::clone(&shared);
256        let task = runtime.spawn(coherence::run(task_shared));
257
258        CacheClient(Arc::new(CacheClientInner {
259            shared,
260            task: task.abort_handle(),
261        }))
262    }
263
264    /// Spawn the coherence task and return the cache handle.
265    ///
266    /// Construction never fails and does not wait for the cache to warm: the returned handle is
267    /// usable immediately, and reads of a configured range pass through to the server until that
268    /// range's initial seed completes in the background. With no configured ranges the cache is a
269    /// plain passthrough.
270    ///
271    /// # Panics
272    ///
273    /// Panics if called from outside a Tokio runtime, which is required to spawn the background
274    /// coherence task. Use [`build_on`][Self::build_on] to provide a runtime handle explicitly.
275    pub fn build(self) -> CacheClient {
276        self.build_on(&tokio::runtime::Handle::current())
277    }
278}