Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
//! Unified provider-independent cache runtime.
mod api;
mod dynamic;
mod error;
mod executor;
#[cfg(any(test, feature = "test-utils"))]
mod memory;
mod provider;
mod redis;
mod script;
pub use api::{
Expiration, ListDirection, ListInsertPosition, ListInsertRequest, ListMoveRequest,
SetCondition, SetOptions, SetResult,
};
pub use dynamic::DynamicProviderConfig;
pub use error::{CacheError, CacheResult};
#[cfg(any(test, feature = "test-utils"))]
pub use memory::MemoryMockProvider;
pub use redis::{RedisDeploymentMode, RedisProviderConfig};
use bytes::Bytes;
use executor::RuntimeExecutor;
pub(crate) use provider::CacheOperation;
use provider::CacheProvider;
pub(crate) use script::{ScriptDefinition, ScriptRegistry, ScriptValue};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
/// Request for one named provider-side atomic program.
#[derive(Debug, Clone)]
pub struct ScriptRequest {
/// Stable program identifier.
pub script_id: String,
/// Fully-qualified keys used by the program.
pub keys: Vec<String>,
/// Opaque program arguments.
pub args: Vec<Bytes>,
}
/// Opaque provider-side program result.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ScriptResult {
/// Encoded result payload interpreted by the business module.
pub payload: Bytes,
}
/// One cache runtime bound to one provider instance.
pub struct CacheRuntime {
provider: Arc<dyn CacheProvider>,
scripts: Arc<ScriptRegistry>,
executor: Arc<RuntimeExecutor>,
closed: AtomicBool,
}
impl CacheRuntime {
#[cfg(any(test, feature = "test-utils"))]
pub(crate) fn from_provider(provider: Arc<dyn CacheProvider>) -> Arc<Self> {
Self::from_provider_with_scripts(provider, Arc::new(ScriptRegistry::default()))
}
fn from_provider_with_scripts(
provider: Arc<dyn CacheProvider>,
scripts: Arc<ScriptRegistry>,
) -> Arc<Self> {
let executor =
Arc::new(RuntimeExecutor::new().expect("CacheRuntime executor must initialize"));
Self::from_provider_with_parts(provider, scripts, executor)
}
fn from_provider_with_parts(
provider: Arc<dyn CacheProvider>,
scripts: Arc<ScriptRegistry>,
executor: Arc<RuntimeExecutor>,
) -> Arc<Self> {
Arc::new(Self {
provider,
scripts,
executor,
closed: AtomicBool::new(false),
})
}
/// Build an in-process runtime for tests and smoke validation.
#[cfg(any(test, feature = "test-utils"))]
pub fn memory() -> Arc<Self> {
Self::memory_with_provider(Arc::new(MemoryMockProvider::new()))
}
/// Build a Runtime around one controllable in-memory provider.
#[cfg(any(test, feature = "test-utils"))]
pub fn memory_with_provider(provider: Arc<MemoryMockProvider>) -> Arc<Self> {
Self::from_provider(provider)
}
/// Connect the built-in Redis provider and create one Runtime.
pub async fn redis(config: RedisProviderConfig) -> CacheResult<Arc<Self>> {
let scripts = Arc::new(ScriptRegistry::default());
let provider = redis::RedisProvider::connect(config, Arc::clone(&scripts)).await?;
Ok(Self::from_provider_with_scripts(
Arc::new(provider),
scripts,
))
}
/// Connect Redis on the dedicated RuntimeExecutor for synchronous callers.
pub fn connect_sync(config: RedisProviderConfig) -> CacheResult<Arc<Self>> {
if tokio::runtime::Handle::try_current().is_ok() {
return Err(CacheError::InvalidExecutionContext);
}
let executor = Arc::new(RuntimeExecutor::new()?);
let scripts = Arc::new(ScriptRegistry::default());
let provider_scripts = Arc::clone(&scripts);
let provider = executor.run(async move {
redis::RedisProvider::connect(config, provider_scripts)
.await
.map(|provider| Arc::new(provider) as Arc<dyn CacheProvider>)
})?;
Ok(Self::from_provider_with_parts(provider, scripts, executor))
}
/// Load one provider through the versioned dynamic C ABI.
pub async fn dynamic(config: DynamicProviderConfig) -> CacheResult<Arc<Self>> {
let scripts = Arc::new(ScriptRegistry::default());
let provider = dynamic::DynamicProvider::connect(config, Arc::clone(&scripts)).await?;
Ok(Self::from_provider_with_scripts(
Arc::new(provider),
scripts,
))
}
pub(crate) fn require_operations(&self, operations: &[CacheOperation]) -> CacheResult<()> {
self.provider.validate_operations(operations)
}
pub(crate) fn register_script(&self, definition: ScriptDefinition) -> CacheResult<()> {
self.scripts.register(definition)
}
/// Read one value.
pub async fn get(&self, key: &str) -> CacheResult<Option<Bytes>> {
self.ensure_open()?;
self.provider.get(key).await
}
/// Store one value using Redis SET semantics.
pub async fn set(
&self,
key: &str,
value: Bytes,
options: SetOptions,
) -> CacheResult<SetResult> {
self.ensure_open()?;
self.provider.set(key, value, options).await
}
/// Delete multiple keys and return the number removed.
pub async fn del(&self, keys: &[String]) -> CacheResult<u64> {
self.ensure_open()?;
self.provider.del(keys).await
}
/// Read multiple keys while preserving input order.
pub async fn mget(&self, keys: &[String]) -> CacheResult<Vec<Option<Bytes>>> {
self.ensure_open()?;
self.provider.mget(keys).await
}
/// Store multiple values.
pub async fn mset(&self, entries: Vec<(String, Bytes)>) -> CacheResult<()> {
self.ensure_open()?;
self.provider.mset(entries).await
}
/// Increment one integer value by one.
pub async fn incr(&self, key: &str) -> CacheResult<i64> {
self.incr_by(key, 1).await
}
/// Increment one integer value by `delta`.
pub async fn incr_by(&self, key: &str, delta: i64) -> CacheResult<i64> {
self.ensure_open()?;
self.provider.incr_by(key, delta).await
}
/// Decrement one integer value by one.
pub async fn decr(&self, key: &str) -> CacheResult<i64> {
self.incr_by(key, -1).await
}
/// Decrement one integer value by `delta`.
pub async fn decr_by(&self, key: &str, delta: i64) -> CacheResult<i64> {
let increment = delta.checked_neg().ok_or_else(|| {
CacheError::InvalidArgument("decrement delta is too large".to_string())
})?;
self.incr_by(key, increment).await
}
/// Check whether a set contains one member.
pub async fn sismember(&self, key: &str, member: &[u8]) -> CacheResult<bool> {
self.ensure_open()?;
self.provider.sismember(key, member).await
}
/// Return all members of one set in unspecified order.
pub async fn smembers(&self, key: &str) -> CacheResult<Vec<Bytes>> {
self.ensure_open()?;
self.provider.smembers(key).await
}
/// Return the cardinality of one set.
pub async fn scard(&self, key: &str) -> CacheResult<u64> {
self.ensure_open()?;
self.provider.scard(key).await
}
/// Push values to the head of one list.
pub async fn lpush(&self, key: &str, values: Vec<Bytes>) -> CacheResult<u64> {
self.ensure_open()?;
self.provider.lpush(key, values).await
}
/// Push values to the tail of one list.
pub async fn rpush(&self, key: &str, values: Vec<Bytes>) -> CacheResult<u64> {
self.ensure_open()?;
self.provider.rpush(key, values).await
}
/// Pop values from the head of one list.
pub async fn lpop(&self, key: &str, count: Option<u64>) -> CacheResult<Vec<Bytes>> {
self.ensure_open()?;
self.provider.lpop(key, count).await
}
/// Pop values from the tail of one list.
pub async fn rpop(&self, key: &str, count: Option<u64>) -> CacheResult<Vec<Bytes>> {
self.ensure_open()?;
self.provider.rpop(key, count).await
}
/// Return the length of one list.
pub async fn llen(&self, key: &str) -> CacheResult<u64> {
self.ensure_open()?;
self.provider.llen(key).await
}
/// Return an inclusive range from one list.
pub async fn lrange(&self, key: &str, start: i64, stop: i64) -> CacheResult<Vec<Bytes>> {
self.ensure_open()?;
self.provider.lrange(key, start, stop).await
}
/// Return one list element by index.
pub async fn lindex(&self, key: &str, index: i64) -> CacheResult<Option<Bytes>> {
self.ensure_open()?;
self.provider.lindex(key, index).await
}
/// Replace one list element by index.
pub async fn lset(&self, key: &str, index: i64, value: Bytes) -> CacheResult<()> {
self.ensure_open()?;
self.provider.lset(key, index, value).await
}
/// Trim one list to an inclusive range.
pub async fn ltrim(&self, key: &str, start: i64, stop: i64) -> CacheResult<()> {
self.ensure_open()?;
self.provider.ltrim(key, start, stop).await
}
/// Remove matching elements from one list.
pub async fn lrem(&self, key: &str, count: i64, value: Bytes) -> CacheResult<u64> {
self.ensure_open()?;
self.provider.lrem(key, count, value).await
}
/// Insert one element relative to a pivot.
pub async fn linsert(&self, request: ListInsertRequest) -> CacheResult<i64> {
self.ensure_open()?;
self.provider.linsert(request).await
}
/// Atomically move one element between lists.
pub async fn lmove(&self, request: ListMoveRequest) -> CacheResult<Option<Bytes>> {
self.ensure_open()?;
self.provider.lmove(request).await
}
/// Execute one registered script.
pub async fn execute_script(&self, request: ScriptRequest) -> CacheResult<ScriptResult> {
self.ensure_open()?;
self.provider.execute_script(request).await
}
/// Check whether the provider is healthy.
pub async fn ping(&self) -> CacheResult<()> {
self.ensure_open()?;
self.provider.ping().await
}
/// Wrap the current Runtime with synchronous primitive operations.
pub fn sync_facade(self: &Arc<Self>) -> SyncCacheRuntimeFacade {
SyncCacheRuntimeFacade {
runtime: Arc::clone(self),
executor: Arc::clone(&self.executor),
}
}
/// Close the provider and reject future operations.
pub async fn close(&self) -> CacheResult<()> {
if self.closed.swap(true, Ordering::AcqRel) {
return Ok(());
}
self.provider.close().await
}
fn ensure_open(&self) -> CacheResult<()> {
if self.closed.load(Ordering::Acquire) {
Err(CacheError::Closed)
} else {
Ok(())
}
}
}
/// Stateless synchronous facade over one CacheRuntime.
pub struct SyncCacheRuntimeFacade {
runtime: Arc<CacheRuntime>,
executor: Arc<RuntimeExecutor>,
}
impl SyncCacheRuntimeFacade {
/// Read one value.
pub fn get(&self, key: &str) -> CacheResult<Option<Bytes>> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor.run(async move { runtime.get(&key).await })
}
/// Store one value using Redis SET semantics.
pub fn set(&self, key: &str, value: Bytes, options: SetOptions) -> CacheResult<SetResult> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.set(&key, value, options).await })
}
/// Delete multiple keys and return the number removed.
pub fn del(&self, keys: &[String]) -> CacheResult<u64> {
let runtime = Arc::clone(&self.runtime);
let keys = keys.to_vec();
self.executor.run(async move { runtime.del(&keys).await })
}
/// Read multiple keys while preserving input order.
pub fn mget(&self, keys: &[String]) -> CacheResult<Vec<Option<Bytes>>> {
let runtime = Arc::clone(&self.runtime);
let keys = keys.to_vec();
self.executor.run(async move { runtime.mget(&keys).await })
}
/// Store multiple values.
pub fn mset(&self, entries: Vec<(String, Bytes)>) -> CacheResult<()> {
let runtime = Arc::clone(&self.runtime);
self.executor
.run(async move { runtime.mset(entries).await })
}
/// Increment one integer value by one.
pub fn incr(&self, key: &str) -> CacheResult<i64> {
self.incr_by(key, 1)
}
/// Increment one integer value by `delta`.
pub fn incr_by(&self, key: &str, delta: i64) -> CacheResult<i64> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.incr_by(&key, delta).await })
}
/// Decrement one integer value by one.
pub fn decr(&self, key: &str) -> CacheResult<i64> {
self.incr_by(key, -1)
}
/// Decrement one integer value by `delta`.
pub fn decr_by(&self, key: &str, delta: i64) -> CacheResult<i64> {
let increment = delta.checked_neg().ok_or_else(|| {
CacheError::InvalidArgument("decrement delta is too large".to_string())
})?;
self.incr_by(key, increment)
}
/// Check whether a set contains one member.
pub fn sismember(&self, key: &str, member: &[u8]) -> CacheResult<bool> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
let member = member.to_vec();
self.executor
.run(async move { runtime.sismember(&key, &member).await })
}
/// Return all members of one set in unspecified order.
pub fn smembers(&self, key: &str) -> CacheResult<Vec<Bytes>> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.smembers(&key).await })
}
/// Return the cardinality of one set.
pub fn scard(&self, key: &str) -> CacheResult<u64> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor.run(async move { runtime.scard(&key).await })
}
/// Push values to the head of one list.
pub fn lpush(&self, key: &str, values: Vec<Bytes>) -> CacheResult<u64> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.lpush(&key, values).await })
}
/// Push values to the tail of one list.
pub fn rpush(&self, key: &str, values: Vec<Bytes>) -> CacheResult<u64> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.rpush(&key, values).await })
}
/// Pop values from the head of one list.
pub fn lpop(&self, key: &str, count: Option<u64>) -> CacheResult<Vec<Bytes>> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.lpop(&key, count).await })
}
/// Pop values from the tail of one list.
pub fn rpop(&self, key: &str, count: Option<u64>) -> CacheResult<Vec<Bytes>> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.rpop(&key, count).await })
}
/// Return the length of one list.
pub fn llen(&self, key: &str) -> CacheResult<u64> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor.run(async move { runtime.llen(&key).await })
}
/// Return an inclusive range from one list.
pub fn lrange(&self, key: &str, start: i64, stop: i64) -> CacheResult<Vec<Bytes>> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.lrange(&key, start, stop).await })
}
/// Return one list element by index.
pub fn lindex(&self, key: &str, index: i64) -> CacheResult<Option<Bytes>> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.lindex(&key, index).await })
}
/// Replace one list element by index.
pub fn lset(&self, key: &str, index: i64, value: Bytes) -> CacheResult<()> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.lset(&key, index, value).await })
}
/// Trim one list to an inclusive range.
pub fn ltrim(&self, key: &str, start: i64, stop: i64) -> CacheResult<()> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.ltrim(&key, start, stop).await })
}
/// Remove matching elements from one list.
pub fn lrem(&self, key: &str, count: i64, value: Bytes) -> CacheResult<u64> {
let runtime = Arc::clone(&self.runtime);
let key = key.to_string();
self.executor
.run(async move { runtime.lrem(&key, count, value).await })
}
/// Insert one element relative to a pivot.
pub fn linsert(&self, request: ListInsertRequest) -> CacheResult<i64> {
let runtime = Arc::clone(&self.runtime);
self.executor
.run(async move { runtime.linsert(request).await })
}
/// Atomically move one element between lists.
pub fn lmove(&self, request: ListMoveRequest) -> CacheResult<Option<Bytes>> {
let runtime = Arc::clone(&self.runtime);
self.executor
.run(async move { runtime.lmove(request).await })
}
/// Execute one registered script.
pub fn execute_script(&self, request: ScriptRequest) -> CacheResult<ScriptResult> {
let runtime = Arc::clone(&self.runtime);
self.executor
.run(async move { runtime.execute_script(request).await })
}
/// Check whether the provider is healthy.
pub fn ping(&self) -> CacheResult<()> {
let runtime = Arc::clone(&self.runtime);
self.executor.run(async move { runtime.ping().await })
}
/// Close the shared runtime.
pub fn close(&self) -> CacheResult<()> {
let runtime = Arc::clone(&self.runtime);
self.executor.run(async move { runtime.close().await })
}
}