foundationdb/timekeeper.rs
1//! There is a key range called TimeKeeper in the system key space which stores a rolling history window
2//! of time to version mappings, with one data point every 10 seconds.
3//! It is not exposed via any user-facing API, though of course the data can be read by a user.
4//! It is not an official database feature and should not be relied on for anything where accuracy
5//! is critical as nothing prevents or detects system clock skew on the FDB process logging these data points.
6//!
7//! TimeKeeper is used by backup and restore to convert timestamps to approximate versions and versions
8//! to approximate timestamps to make reasoning about backup data and restore operations easier.
9//! Lookups work by finding the nearest value for the query version or timestamp, taking the equivalent other value,
10//! and then adding an adjustment estimate based on 1 million versions per 1 second.
11//! This logic accounts for arbitrary version advancement due to recovery, DR switch operations, or any other reason.
12//!
13//! [source](https://forums.foundationdb.org/t/versionstamp-as-absolute-time/2442/3)
14
15use crate::options::TransactionOption;
16use crate::{FdbBindingError, KeySelector, RangeOption, Transaction};
17use foundationdb_tuple::{pack, unpack};
18use futures::TryStreamExt;
19
20/// Timekeeper keys are stored in a special keyspace
21/// Can be found in the [Java implementation](https://github.com/FoundationDB/fdb-record-layer/blob/main/fdb-extensions/src/main/java/com/apple/foundationdb/system/SystemKeyspace.java#L80)
22const TIME_KEEPER_PREFIX: &[u8] = b"\xff\x02/timeKeeper/map/";
23
24/// Flavor about the mode of scanning
25pub enum HintMode {
26 /// The read version is ensure to be before the timestamp
27 BeforeTimestamp,
28 /// The read version is ensured to be after the timestamp
29 AfterTimestamp,
30}
31
32/// Try to get a version ID closer as possible as the asked timestamp
33///
34/// If no result are found, either your timestamp is in the future of the
35/// Timekeeper or the data has been rolled by fresh ones.
36///
37/// The layout os follow:
38///
39/// TIME_KEEPER_PREFIX/timestamp1 => read_version1
40/// TIME_KEEPER_PREFIX/timestamp2 => read_version2
41/// TIME_KEEPER_PREFIX/timestamp3 => read_version3
42///
43/// Each key are associated to a pack read version on 8 bytes
44/// compatible with an i64.
45///
46/// Timestamps are provided from unix time as seconds
47pub async fn hint_version_from_timestamp(
48 trx: &Transaction,
49 unix_timestamp_as_seconds: u64,
50 mode: HintMode,
51 snapshot: bool,
52) -> Result<Option<u64>, FdbBindingError> {
53 // Timekeeper range keys are stored in /0x00/0x02 system namespace
54 // to be able to read this range, the transaction must have
55 // capabilities to read System Keys
56 trx.set_option(TransactionOption::ReadSystemKeys)?;
57 // The profiling should be used even when the Database has been locked
58 trx.set_option(TransactionOption::ReadLockAware)?;
59
60 // Timekeeper keys are defined has prefix/timestamp
61 let mut start_key_bytes = TIME_KEEPER_PREFIX.to_vec();
62 start_key_bytes.extend_from_slice(&pack(&unix_timestamp_as_seconds));
63 // we get the first key greater than this value because timekeeper doesn't tick
64 // each seconds but rather each 10 seconds but not each time
65 let start_key = KeySelector::first_greater_or_equal(start_key_bytes.clone());
66
67 // The end of the scan is the end of the timekeeper range
68 // but we won't scan it the whole range
69 let mut end_key_bytes = TIME_KEEPER_PREFIX.to_vec();
70 end_key_bytes.extend_from_slice(b"\xff");
71 let end_key = KeySelector::first_greater_than(end_key_bytes);
72
73 let mut range = match mode {
74 HintMode::AfterTimestamp => RangeOption::from((start_key, end_key)),
75 HintMode::BeforeTimestamp => {
76 let mut range = RangeOption::from((
77 KeySelector::first_greater_than(TIME_KEEPER_PREFIX),
78 start_key,
79 ));
80 range.reverse = true;
81 range
82 }
83 };
84 // No need to scan further than the next and previous key
85 range.limit = Some(1);
86
87 // We get the first key matching our start range bound
88 let result = trx.get_ranges_keyvalues(range, snapshot).try_next().await?;
89
90 // If any result then the value found will be the read version ID
91 if let Some(kv) = result {
92 let version = unpack(kv.value()).map_err(FdbBindingError::PackError)?;
93 return Ok(Some(version));
94 }
95 // otherwise timestamp too old or is future
96 Ok(None)
97}