amalgam/
lib.rs

1//! `amalgam` — a robust, multi-level, fail-safe cache for Rust.
2//!
3//! An *amalgam* is a fusion of metals; this crate is a faithful, idiomatic Rust
4//! port of the resiliency model pioneered by .NET's
5//! [FusionCache](https://github.com/ZiggyCreatures/FusionCache). It fuses an
6//! in-memory L1 cache with an optional distributed L2 cache and gives you the
7//! features that make a cache *robust* rather than merely fast:
8//!
9//! * **Cache-stampede protection** — only one factory runs per key (single-flight).
10//! * **Fail-safe** — serve a stale value when the factory fails, instead of erroring.
11//! * **Soft / hard timeouts** — a slow factory can return a stale value immediately
12//!   and finish in the background.
13//! * **Eager refresh** — refresh proactively before expiration, off the hot path.
14//! * **Adaptive caching** — the factory can change the entry's options per call.
15//! * **Conditional refresh** — HTTP-style `NotModified` reuse of a stale value.
16//! * **Tagging** — invalidate many entries at once, lazily, by tag.
17//! * **L1 + L2 + backplane** — pluggable distributed cache and multi-node sync.
18//!
19//! See `PORTING.md` for the C#→Rust translation methodology and `docs/PARITY.md`
20//! for the feature-by-feature mapping to FusionCache.
21
22#![forbid(unsafe_code)]
23#![warn(missing_docs)]
24
25pub mod backplane;
26pub mod cache;
27pub mod circuit;
28pub mod distributed;
29pub mod distributed_lock;
30pub mod entry;
31pub mod error;
32pub mod events;
33pub mod factory;
34pub mod locking;
35pub mod maybe;
36pub mod memory;
37pub mod observability;
38pub mod options;
39pub mod plugins;
40pub mod recovery;
41pub mod registry;
42pub mod serializers;
43pub mod tags;
44pub mod time;
45
46#[cfg(feature = "opentelemetry")]
47pub mod otel;
48
49#[cfg(feature = "redis")]
50pub mod redis_backend;
51
52pub use backplane::{Backplane, BackplaneAction, BackplaneMessage, InProcessBackplane};
53pub use cache::{Cache, CacheBuilder};
54pub use circuit::CircuitBreaker;
55pub use distributed::{
56    DistributedCache, DistributedEntry, DistributedSerializer, InMemoryDistributedCache,
57    JsonSerializer,
58};
59pub use distributed_lock::{DistributedLocker, InMemoryDistributedLocker};
60pub use error::{Error, FactoryError, Result};
61pub use events::{CacheEvent, CircuitComponent, Events};
62pub use factory::{FactoryContext, FactoryProduct, ModifiedBuilder};
63pub use maybe::MaybeValue;
64pub use options::{EagerThreshold, EntryOptions, KeyModifierMode, Priority, RemoveByTagBehavior};
65pub use plugins::{Plugin, PluginHost};
66pub use recovery::{
67    AutoRecoveryService, RecoveryAction, RecoveryConfig, RecoveryExecutor, RecoveryItem,
68};
69pub use registry::{CacheRegistry, DefaultEntryOptionsProvider};
70pub use tags::Tag;
71pub use time::{Clock, ManualClock, SystemClock, Timeout, Timestamp};
72
73#[cfg(feature = "messagepack")]
74pub use serializers::MessagePackSerializer;
75
76#[cfg(feature = "postcard")]
77pub use serializers::PostcardSerializer;
78
79#[cfg(feature = "metrics")]
80pub use observability::MetricsPlugin;
81
82#[cfg(feature = "opentelemetry")]
83pub use otel::{OtelGuard, init_otlp};
84
85#[cfg(feature = "redis")]
86pub use redis_backend::{RedisBackplane, RedisDistributedCache, RedisDistributedLocker};
amalgam/lib.rs

amalgam/
lib.rs
