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}