Skip to main content

etcdrs_util/cache/
driver.rs

1use std::future::{Future, IntoFuture};
2use std::pin::Pin;
3use std::sync::Arc;
4use std::sync::atomic::Ordering;
5use std::task::{Context, Poll, ready};
6use std::time::Duration;
7
8use etcdrs::client::{
9    Compact, CompactFuture as RemoteCompactFuture, CountResponse, Delete, DeleteError,
10    DeleteFuture as RemoteDeleteFuture, DeleteResponse, Get, GetFuture as RemoteGetFuture, GetResponse, List,
11    ListFuture as RemoteListFuture, ListIterator, ListView as RemoteListView, Put, PutError,
12    PutFuture as RemotePutFuture, PutResponse, Transaction, TransactionFuture as RemoteTransactionFuture,
13};
14use etcdrs::driver::KvDriver;
15use etcdrs::{Client, GetError, KeyWithMetadata, Record, ResponseHeader, Revision};
16use futures_core::Stream;
17
18use super::range_spec::RangeSpec;
19use super::{CacheClient, RangeState, Shared};
20
21/// Minimum interval between watch progress requests fired by gated reads.
22const PROGRESS_DEBOUNCE: Duration = Duration::from_millis(100);
23
24impl Shared {
25    /// Serve a read from range `index` if it can prove freshness, extracting the result with
26    /// `read` under the state lock.
27    ///
28    /// The gate: a range serves iff it is seeded and its coherent revision has caught up to every
29    /// revision observed through this client. A seeded-but-behind range additionally nudges the
30    /// watch for a progress notification so it can prove freshness again soon; an unseeded range
31    /// has no watch to nudge.
32    fn try_serve<T>(&self, index: usize, read: impl FnOnce(&RangeState) -> T) -> Option<(ResponseHeader, T)> {
33        let last_known = self.last_known.load(Ordering::Acquire);
34
35        let state = self.state.lock().unwrap();
36        let range = &state[index];
37        match range.header {
38            Some(header) if header.revision().get() >= last_known => Some((header, read(range))),
39            behind => {
40                let nudge = behind.is_some();
41                drop(state);
42                if nudge {
43                    self.request_progress();
44                }
45                None
46            }
47        }
48    }
49
50    /// Serve a get from the cache, or `None` if it must pass through.
51    ///
52    /// A revision-pinned get always passes through: the cache holds only latest values, never
53    /// history.
54    fn try_serve_get(&self, get: &Get<()>) -> Option<GetResponse> {
55        if get.revision().is_some() {
56            return None;
57        }
58        let key = get.target_key();
59        let index = self.ranges.iter().position(|range| range.contains_key(key))?;
60        self.try_serve(index, |range| range.store.get(key).cloned())
61            .map(|(header, record)| GetResponse::new(header, record))
62    }
63
64    /// The configured range that fully contains `query`, unless the query is revision-pinned.
65    fn span_range_index(&self, query: &RangeSpec, pinned: Option<Revision>) -> Option<usize> {
66        if pinned.is_some() {
67            return None;
68        }
69        self.ranges.iter().position(|range| range.contains_span(query))
70    }
71
72    /// Serve a listing from the cache, or `None` if it must pass through. Records come back in
73    /// key order, exactly as the server would return them.
74    fn try_serve_records(&self, query: &RangeSpec, pinned: Option<Revision>) -> Option<(ResponseHeader, Vec<Record>)> {
75        let index = self.span_range_index(query, pinned)?;
76        self.try_serve(index, |range| {
77            range
78                .store
79                .range::<[u8], _>(query.as_bounds())
80                .map(|(_, record)| record.clone())
81                .collect()
82        })
83    }
84
85    /// Serve a count from the cache, or `None` if it must pass through.
86    fn try_serve_count(&self, query: &RangeSpec, pinned: Option<Revision>) -> Option<CountResponse> {
87        let index = self.span_range_index(query, pinned)?;
88        self.try_serve(index, |range| range.store.range::<[u8], _>(query.as_bounds()).count())
89            .map(|(header, count)| CountResponse::new(header, count))
90    }
91
92    /// Ask the watch for a progress notification so ranges left behind by an observed revision
93    /// can prove freshness again, typically within one server round trip.
94    ///
95    /// Debounced, and a no-op while the watch is down — reads keep passing through in the
96    /// meantime, which is always correct.
97    fn request_progress(&self) {
98        let mut progress = self.progress.lock().unwrap();
99        let now = tokio::time::Instant::now();
100        if progress
101            .last_request
102            .is_some_and(|last| now.duration_since(last) < PROGRESS_DEBOUNCE)
103        {
104            return;
105        }
106        if let Some(sender) = progress.sender.as_ref() {
107            sender.request_progress();
108            progress.last_request = Some(now);
109        }
110    }
111}
112
113/// The [`Future`] type returned by [`CacheClient`] operations.
114///
115/// Either resolves immediately with a cache-served response, or drives the wrapped client's
116/// future `F` and maps its output into `T` (observing the response header for the freshness
117/// gate along the way).
118pub struct CacheFuture<F: Future, T = <F as Future>::Output> {
119    inner: CacheFutureInner<F, T>,
120}
121
122enum CacheFutureInner<F: Future, T> {
123    /// Resolved from the cache.
124    Ready(Option<T>),
125    /// Passing through to the wrapped client.
126    Remote {
127        future: F,
128        shared: Arc<Shared>,
129        map: fn(F::Output, &Shared) -> T,
130    },
131}
132
133impl<F: Future, T> CacheFuture<F, T> {
134    fn ready(output: T) -> Self {
135        Self {
136            inner: CacheFutureInner::Ready(Some(output)),
137        }
138    }
139
140    fn remote(future: F, shared: Arc<Shared>, map: fn(F::Output, &Shared) -> T) -> Self {
141        Self {
142            inner: CacheFutureInner::Remote { future, shared, map },
143        }
144    }
145}
146
147impl<F, T> Future for CacheFuture<F, T>
148where
149    F: Future + Unpin,
150    T: Unpin,
151{
152    type Output = T;
153
154    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<T> {
155        match &mut self.get_mut().inner {
156            CacheFutureInner::Ready(output) => Poll::Ready(output.take().expect("CacheFuture polled after completion")),
157            CacheFutureInner::Remote { future, shared, map } => {
158                let output = ready!(Pin::new(future).poll(cx));
159                Poll::Ready(map(output, shared))
160            }
161        }
162    }
163}
164
165/// The list view returned by [`CacheClient`] list operations.
166///
167/// Mirrors [`etcdrs::client::ListView`]: either a snapshot cloned from a cached range, or the
168/// wrapped client's view for queries that passed through.
169pub struct CacheListView<R> {
170    header: ResponseHeader,
171    source: CacheListSource<R>,
172}
173
174enum CacheListSource<R> {
175    /// A snapshot cloned from a cached range.
176    Cached {
177        records: Vec<Record>,
178        convert: fn(Record) -> R,
179    },
180    /// The wrapped client's view, for queries that passed through.
181    Remote(RemoteListView<R>),
182}
183
184impl<R> CacheListView<R> {
185    /// The response header. For cache-served queries, its revision is the coherent revision of
186    /// the range that served it.
187    pub fn header(&self) -> &ResponseHeader {
188        &self.header
189    }
190
191    /// The revision of the database this listing reads as of.
192    ///
193    /// This is the same as what you would find in the response [`header`][Self::header].
194    pub fn revision(&self) -> Revision {
195        self.header.revision()
196    }
197
198    /// Convert this view into a stream of records.
199    pub fn into_stream(self) -> CacheListStream<R> {
200        CacheListStream(match self.source {
201            CacheListSource::Cached { records, convert } => CacheListStreamInner::Cached {
202                records: records.into_iter(),
203                convert,
204            },
205            CacheListSource::Remote(view) => CacheListStreamInner::Remote(view.into_stream()),
206        })
207    }
208}
209
210impl<R> etcdrs::driver::ListView<R> for CacheListView<R> {
211    type Stream = CacheListStream<R>;
212
213    fn header(&self) -> &ResponseHeader {
214        &self.header
215    }
216
217    fn into_stream(self) -> CacheListStream<R> {
218        self.into_stream()
219    }
220}
221
222/// The stream of records produced by [`CacheListView::into_stream`].
223pub struct CacheListStream<R>(CacheListStreamInner<R>);
224
225enum CacheListStreamInner<R> {
226    Cached {
227        records: std::vec::IntoIter<Record>,
228        convert: fn(Record) -> R,
229    },
230    Remote(ListIterator<R>),
231}
232
233impl<R> Stream for CacheListStream<R> {
234    type Item = Result<R, GetError>;
235
236    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
237        match &mut self.get_mut().0 {
238            CacheListStreamInner::Cached { records, convert } => {
239                Poll::Ready(records.next().map(|record| Ok(convert(record))))
240            }
241            CacheListStreamInner::Remote(inner) => Pin::new(inner).poll_next(cx),
242        }
243    }
244}
245
246fn keep_record(record: Record) -> Record {
247    record
248}
249
250fn drop_value(record: Record) -> KeyWithMetadata {
251    record.without_value()
252}
253
254/// Serve a list from the cache when possible, otherwise delegate to the wrapped client via
255/// `remote` and wrap its view.
256#[allow(
257    clippy::type_complexity,
258    reason = "the type is the KvDriver ListViewFuture GAT spelled out"
259)]
260fn execute_list<R>(
261    shared: Arc<Shared>,
262    list: List<(), R>,
263    convert: fn(Record) -> R,
264    remote: fn(Client, List<(), R>) -> RemoteListFuture<Result<RemoteListView<R>, GetError>>,
265) -> CacheFuture<RemoteListFuture<Result<RemoteListView<R>, GetError>>, Result<CacheListView<R>, GetError>> {
266    let query = RangeSpec::from_target(list.target_range());
267    if let Some((header, records)) = shared.try_serve_records(&query, list.revision()) {
268        return CacheFuture::ready(Ok(CacheListView {
269            header,
270            source: CacheListSource::Cached { records, convert },
271        }));
272    }
273    let future = remote(shared.client.clone(), list);
274    CacheFuture::remote(future, shared, |output, shared| {
275        output.map(|view| {
276            shared.observe_header(view.header());
277            CacheListView {
278                header: *view.header(),
279                source: CacheListSource::Remote(view),
280            }
281        })
282    })
283}
284
285impl KvDriver for CacheClient {
286    type GetFuture = CacheFuture<RemoteGetFuture>;
287    type PutFuture<R> = CacheFuture<RemotePutFuture<Result<PutResponse<R>, PutError>>>;
288    type DeleteFuture<R, P> = CacheFuture<RemoteDeleteFuture<Result<DeleteResponse<R, P>, DeleteError>>>;
289    type ListView<R> = CacheListView<R>;
290    type ListViewFuture<R> =
291        CacheFuture<RemoteListFuture<Result<RemoteListView<R>, GetError>>, Result<CacheListView<R>, GetError>>;
292    type CountFuture = CacheFuture<RemoteListFuture<Result<CountResponse, GetError>>>;
293    type CommitFuture = CacheFuture<RemoteTransactionFuture>;
294    type CompactFuture = CacheFuture<RemoteCompactFuture>;
295
296    fn execute_get(self, get: Get<()>) -> Self::GetFuture {
297        let shared = Arc::clone(&self.0.shared);
298        if let Some(response) = shared.try_serve_get(&get) {
299            return CacheFuture::ready(Ok(response));
300        }
301        let future = get.with_client(shared.client.clone()).into_future();
302        CacheFuture::remote(future, shared, |output, shared| {
303            if let Ok(response) = &output {
304                shared.observe_header(response.header());
305            }
306            output
307        })
308    }
309
310    fn execute_put<R>(self, put: Put<(), R>) -> Self::PutFuture<R> {
311        let shared = Arc::clone(&self.0.shared);
312        let future = put.with_client(shared.client.clone()).into_future();
313        CacheFuture::remote(future, shared, |output, shared| {
314            if let Ok(response) = &output {
315                shared.observe_header(response.header());
316            }
317            output
318        })
319    }
320
321    fn execute_delete<R, P>(self, delete: Delete<(), R, P>) -> Self::DeleteFuture<R, P> {
322        let shared = Arc::clone(&self.0.shared);
323        let future = delete.with_client(shared.client.clone()).into_future();
324        CacheFuture::remote(future, shared, |output, shared| {
325            if let Ok(response) = &output {
326                shared.observe_header(response.header());
327            }
328            output
329        })
330    }
331
332    fn execute_list_records(self, list: List<(), Record>) -> Self::ListViewFuture<Record> {
333        execute_list(Arc::clone(&self.0.shared), list, keep_record, |client, list| {
334            client.execute_list_records(list)
335        })
336    }
337
338    fn execute_list_keys(self, list: List<(), KeyWithMetadata>) -> Self::ListViewFuture<KeyWithMetadata> {
339        execute_list(Arc::clone(&self.0.shared), list, drop_value, |client, list| {
340            client.execute_list_keys(list)
341        })
342    }
343
344    fn execute_count(self, list: List<(), usize>) -> Self::CountFuture {
345        let shared = Arc::clone(&self.0.shared);
346        let query = RangeSpec::from_target(list.target_range());
347        if let Some(response) = shared.try_serve_count(&query, list.revision()) {
348            return CacheFuture::ready(Ok(response));
349        }
350        let future = list.with_client(shared.client.clone()).into_future();
351        CacheFuture::remote(future, shared, |output, shared| {
352            if let Ok(response) = &output {
353                shared.observe_header(response.header());
354            }
355            output
356        })
357    }
358
359    fn execute_transaction(self, txn: Transaction<()>) -> Self::CommitFuture {
360        let shared = Arc::clone(&self.0.shared);
361        let future = txn.with_client(shared.client.clone()).commit();
362        CacheFuture::remote(future, shared, |output, shared| {
363            if let Ok(response) = &output {
364                shared.observe_header(response.header());
365            }
366            output
367        })
368    }
369
370    fn execute_compact(self, compact: Compact<()>) -> Self::CompactFuture {
371        let shared = Arc::clone(&self.0.shared);
372        let future = compact.with_client(shared.client.clone()).into_future();
373        CacheFuture::remote(future, shared, |output, shared| {
374            if let Ok(response) = &output {
375                shared.observe_header(response.header());
376            }
377            output
378        })
379    }
380}