pdk_cache_lib/
lib.rs

1// Copyright (c) 2026, Salesforce, Inc.,
2// All rights reserved.
3// For full license text, see the LICENSE.txt file
4
5//! Cache Library
6//!
7//! A caching library that provides a simple [`Cache`] trait with multiple eviction strategies.
8//! It is designed to be injected and configured during the policy
9//! configuration phase and supports both policy-isolated and shared caches across policies.
10//!
11//! This library provides data storage functionality with support for:
12//!
13//! - FIFO eviction strategy (First-In-First-Out)
14//! - LRU eviction strategy (Least Recently Used)
15//! - Builder pattern via [`builder::CacheBuilder`] and [`builder::CacheBuilderInstance`]
16//! - Policy-isolated caches by default; opt-in shared caches via [`builder::CacheBuilderInstance::shared()`]
17//! - Configurable maximum entries per cache
18//!
19
20pub mod builder;
21pub mod error;
22
23// The user is agnostic to the implementation of the cache since the builder returns a trait object.
24// this crate should have been pub(crate), too late to change it now, we just hide it from the doc.
25#[doc(hidden)]
26pub mod fifo_cache;
27
28#[doc(hidden)]
29pub mod lru_cache;
30
31#[doc(hidden)]
32pub mod ttl_cache;
33
34#[cfg(test)]
35mod mocks;
36
37use self::error::CacheError;
38
39// Re-export the eviction strategy types for easy access
40pub use builder::{EvictionStrategy, LruStrategy};
41
42/// Represents a cache. It stores each element as a new entry.
43pub trait Cache {
44    /// Stores value in cache with provided key. Value should be already serialized.
45    ///
46    /// If it already exists, stored value will be overridden with the new param value.
47    /// Have in consideration that this might affect the Cache order, depending on the
48    /// eviction strategy (FIFO or LRU caches).
49    ///
50    /// If it is not possible to store the value in cache, it results in a [`CacheError`].
51    fn save(&self, key: &str, value: Vec<u8>) -> Result<(), CacheError>;
52
53    /// Returns stored value in cache for provided key.
54    ///
55    /// If it exists in the cache, returns [`Some`] with bytes slice value.
56    /// Otherwise, it returns [`None`].
57    fn get(&self, key: &str) -> Option<Vec<u8>>;
58
59    /// Removes an element from cache by key.
60    ///
61    /// Returns the deleted value if present, or [`None`] otherwise.
62    fn delete(&self, key: &str) -> Option<Vec<u8>>;
63
64    /// Clears all elements in cache.
65    fn purge(&self);
66}
pdk_cache_lib/lib.rs

pdk_cache_lib/
lib.rs
