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}