#![doc = include_str!("../README.md")]
use std::{
fmt::Debug,
hash::{BuildHasher, Hash, RandomState},
sync::Arc,
time::Duration,
};
use kape::{CacheBackend, KapeError, SetItem};
use tokio::time::sleep;
#[must_use]
pub fn get_random_string() -> String {
const ALPHANUMERIC: &[u8; 62] =
b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
let state = RandomState::new();
(0..16)
.map(|i| {
let index = (state.hash_one(i) % 62) as u8;
char::from(ALPHANUMERIC[usize::from(index)])
})
.collect()
}
pub async fn assert_adapter_contract<B>(backend: &B, ttl_ms: i64)
where
B: CacheBackend<String, String>,
{
assert!(ttl_ms > 0, "contract TTL must be positive");
assert_backend_contract(backend, &"contract".to_owned(), String::new()).await;
assert_expiring_contract(backend, &"ttl".to_owned(), "value".to_owned(), ttl_ms).await;
assert_batch_contract(
backend,
&"batch-first".to_owned(),
&"batch-second".to_owned(),
&"batch-missing".to_owned(),
"first".to_owned(),
"second".to_owned(),
)
.await;
assert_clear_contract(
backend,
&"clear-first".to_owned(),
&"clear-second".to_owned(),
"first".to_owned(),
"second".to_owned(),
)
.await;
}
pub async fn assert_backend_contract<B, K, V>(backend: &B, key: &K, value: V)
where
B: CacheBackend<K, V>,
K: Sync,
V: Debug + PartialEq + Send + Sync + 'static,
{
backend
.remove(key)
.await
.expect("contract setup remove failed");
assert!(
backend
.get(key)
.await
.expect("contract miss read failed")
.is_none()
);
let expected = Arc::new(value);
backend
.set(key, Arc::clone(&expected), -1)
.await
.expect("contract immortal write failed");
assert!(matches!(
backend.get(key).await.expect("contract immortal read failed"),
Some(entry) if entry.value == expected && entry.remaining_ttl == -1
));
assert!(matches!(
backend.set(key, Arc::clone(&expected), -2).await,
Err(KapeError::InvalidTtl(-2))
));
assert!(matches!(
backend.get(key).await.expect("invalid TTL changed value"),
Some(entry) if entry.value == expected && entry.remaining_ttl == -1
));
backend
.set(key, Arc::clone(&expected), 0)
.await
.expect("contract zero-TTL write failed");
assert!(
backend
.get(key)
.await
.expect("contract zero-TTL read failed")
.is_none()
);
backend
.set(key, expected, -1)
.await
.expect("contract rewrite failed");
backend.remove(key).await.expect("contract remove failed");
assert!(
backend
.get(key)
.await
.expect("contract post-remove read failed")
.is_none()
);
}
pub async fn assert_expiring_contract<B, K, V>(backend: &B, key: &K, value: V, ttl_ms: i64)
where
B: CacheBackend<K, V>,
K: Sync,
V: Debug + PartialEq + Send + Sync + 'static,
{
assert!(ttl_ms > 0, "contract TTL must be positive");
backend
.set(key, Arc::new(value), ttl_ms)
.await
.expect("contract expiring write failed");
match backend
.get(key)
.await
.expect("contract expiring read failed")
{
Some(entry) => {
assert!(entry.remaining_ttl > 0, "remaining TTL must be positive");
assert!(
entry.remaining_ttl <= ttl_ms,
"remaining TTL exceeds requested TTL"
);
}
None => panic!("expected expiring hit, got a miss"),
}
let wait_ms = u64::try_from(ttl_ms).expect("positive TTL must fit u64") + 25;
sleep(Duration::from_millis(wait_ms)).await;
assert!(
backend
.get(key)
.await
.expect("contract expired read failed")
.is_none()
);
}
pub async fn assert_batch_contract<B, K, V>(
backend: &B,
first_key: &K,
second_key: &K,
missing_key: &K,
first_value: V,
second_value: V,
) where
B: CacheBackend<K, V>,
K: Eq + Hash + Sync,
V: Debug + PartialEq + Send + Sync + 'static,
{
backend
.remove_many(&[first_key, second_key, missing_key])
.await
.expect("batch contract setup remove failed");
let first_value = Arc::new(first_value);
let second_value = Arc::new(second_value);
backend
.set_many(&[
SetItem::new(first_key, Arc::clone(&first_value), -1),
SetItem::new(second_key, Arc::clone(&second_value), 10_000),
])
.await
.expect("batch contract write failed");
let read_keys = [first_key, missing_key, first_key, second_key];
let results = backend
.get_many(&read_keys)
.await
.expect("batch contract read failed");
assert_eq!(results.len(), read_keys.len());
assert!(matches!(&results[0], Some(entry) if entry.value == first_value));
assert!(results[1].is_none());
assert!(matches!(&results[2], Some(entry) if entry.value == first_value));
assert!(matches!(&results[3], Some(entry) if entry.value == second_value));
assert!(matches!(
backend
.set_many(&[
SetItem::new(first_key, Arc::clone(&first_value), -1),
SetItem::new(second_key, Arc::clone(&second_value), -2),
])
.await,
Err(KapeError::InvalidTtl(-2))
));
assert!(matches!(
backend
.set_many(&[
SetItem::new(first_key, Arc::clone(&second_value), -1),
SetItem::new(first_key, Arc::clone(&first_value), -1),
])
.await,
Err(KapeError::DuplicateBatchKey {
first_index: 0,
duplicate_index: 1,
})
));
assert!(matches!(
backend
.get(first_key)
.await
.expect("duplicate batch write changed value"),
Some(entry) if entry.value == first_value
));
backend
.set_many(&[SetItem::new(first_key, Arc::clone(&first_value), 0)])
.await
.expect("batch zero-TTL invalidation failed");
assert!(
backend
.get(first_key)
.await
.expect("batch zero-TTL read failed")
.is_none()
);
assert!(
backend
.get(second_key)
.await
.expect("batch zero-TTL changed another key")
.is_some()
);
backend
.remove_many(&[first_key, second_key])
.await
.expect("batch contract remove failed");
assert!(
backend
.get_many(&[first_key, second_key])
.await
.expect("batch contract post-remove read failed")
.iter()
.all(Option::is_none)
);
assert!(
backend
.get_many(&[])
.await
.expect("empty batch read failed")
.is_empty()
);
backend
.set_many(&[])
.await
.expect("empty batch write failed");
backend
.remove_many(&[])
.await
.expect("empty batch remove failed");
}
pub async fn assert_clear_contract<B, K, V>(
backend: &B,
first_key: &K,
second_key: &K,
first_value: V,
second_value: V,
) where
B: CacheBackend<K, V>,
K: Eq + Hash + Sync,
V: Debug + PartialEq + Send + Sync + 'static,
{
backend
.set_many(&[
SetItem::new(first_key, Arc::new(first_value), -1),
SetItem::new(second_key, Arc::new(second_value), 10_000),
])
.await
.expect("clear contract write failed");
backend.clear().await.expect("contract clear failed");
assert!(
backend
.get_many(&[first_key, second_key])
.await
.expect("contract post-clear read failed")
.iter()
.all(Option::is_none)
);
}