feat: macros, stores/traits, redis TLS split, runtime decoupling, constructor and ttl consistency

[jaemk]

Summary

Breaking and additive changes across the macros, stores, and traits for the next major release: constructor and ttl-attribute consistency, a sync_writes = "by_key" default, async-runtime decoupling, trait/store ergonomics, redis serialization and connection-string changes, custom hashers on the in-memory stores, and the supporting docs and tests, on top of the redb DiskCache rewrite.

See docs/migrations/2.0-to-unreleased.md and the CHANGELOG for full migration details.

Breaking changes

• Macro ttl attribute now takes a Duration expression (ttl = "core::time::Duration::from_secs(60)"). The old whole-seconds integer form (ttl = 60) is removed and emits a migration error pointing at ttl_secs / ttl_millis.
• RedbCache / RedisCache / AsyncRedisCache drop new() (it returned a builder, not a cache); use builder(...).
• get_or_set_with / try_get_or_set_with (and async variants) return &V instead of &mut V; new *_mut variants preserve the old behavior (Unnecessary &mut V with get_or_set_with and try_get_or_set_with (CachedAsync) #179).
• Redis TLS features split so rustls is selectable; redis_tokio / redis_smol no longer imply native-tls (add *_native_tls or *_rustls) (Rustls support for Redis #231).
• RedisCacheBuilder / AsyncRedisCacheBuilder build() reject an empty namespace+prefix scope (EmptyScope); RedbCacheBuilder::build() rejects an invalid cache_name (InvalidCacheName).
• #[cached] defaults sync_writes = "by_key": concurrent first-calls for the same key dedup through bucketed per-key locks, instead of the previous no-synchronization double-compute (which mirrored Python lru_cache). Opt out with sync_writes = false. #[once] / #[concurrent_cached] defaults unchanged.
• Cached gains an associated type Error; cache_try_set / try_set return Result<_, Self::Error>. Built-ins use Infallible (non-fallible stores) and CacheSetError (TtlCache / LruTtlCache / TtlSortedCache); custom impls must declare it.
• The four CachedAsync shorthand methods get_async / set_async / remove_async / clear_async are renamed to async_cache_get / async_cache_set / async_cache_remove / async_cache_clear, so every CachedAsync method uses the async_cache_* namespace (ConcurrentCachedAsync already did).
• Short method aliases (get / set / remove / clear / len / is_empty / the short get_or_set_with family, etc.) move off the core Cached / ConcurrentCached traits onto blanket extension traits CachedExt / ConcurrentCachedExt (re-exported from the crate root and the prelude). The core traits keep only the cache_-prefixed methods, so a custom store implements a smaller surface. Callers using cached::prelude::* need no change; others add use cached::CachedExt; / use cached::ConcurrentCachedExt;, or use the cache_-prefixed form. Custom impl Cached / impl ConcurrentCached blocks must drop any short-alias methods.
• ShardedCache renamed to ShardedUnboundCache (with ShardedCacheBase / ShardedCacheBuilder renamed to match); the old name only described the unbounded variant. No deprecated alias; rename at the call site.
• TtlSortedCacheError is removed; TtlSortedCache shares the unified CacheSetError with TtlCache / LruTtlCache.
• TTL stores store per-entry expiry: set_ttl now applies to future inserts only (it no longer re-dates existing entries), and set_ttl(0) / unset_ttl() disable expiry for future inserts only. TtlSortedCache now treats a zero ttl as never-expires for future inserts as well (per-entry expiry is Option<Instant>, ordered so never-expiring entries evict last); it previously meant immediate expiry.
• async feature no longer pulls tokio; smol / async-std async users no longer compile it. The async_tokio_rt_multi_thread feature and the RedbCacheError::BackgroundTaskFailed variant are removed. Async RedbCache runs blocking redb work on the blocking crate (runtime-agnostic), and cached::async_sync re-exports async-lock instead of tokio::sync.
• The disk_store cargo feature is renamed to redb_store, and redis_ahash is removed.
• cache_reset (and the concurrent / async variants) no longer preserves the preallocated backing capacity: it now does clear() + shrink_to(initial_capacity), which the allocator may satisfy with a smaller allocation. Recreate the cache instead of resetting it to retain the allocation.
• TimedEntry is now pub(crate) (it was an unused public type after the store() accessors were removed).

Redis store

• Redis values are serialized with MessagePack (rmp-serde) instead of JSON; the redis_store feature pulls rmp-serde (and keeps serde_json only as a read-only fallback). Pre-3.0 JSON entries are read transparently: the store tries MessagePack first, then falls back to serde_json for entries carrying a version key, serving the value without recompute. New writes use MessagePack; old entries are rewritten as MessagePack on their next write. RedisCacheError's serialize/deserialize variants carry rmp_serde error types instead of serde_json::Error.
• Redis TTL uses the millisecond commands PSETEX / PEXPIRE; sub-second TTLs are honored to the millisecond instead of rounded up to the next whole second. Whole-second TTLs are unchanged. Requires Redis 2.6+.
• RedisCache::connection_string() / AsyncRedisCache::connection_string() return a ConnectionString newtype whose Display and Debug both redact credentials; call .reveal() for the raw URL. connection_string_unredacted() is removed.
• Store error enums are now struct variants (named fields); RedbCacheBuildError::Connection is renamed Storage, the serialize/deserialize variants carry MessagePack error types, and CacheDeserialization gains a cached_value: Vec<u8> field. Tuple patterns like CacheSerialization(e) become CacheSerialization { source }.
• disk / redis / map_error on #[cached] / #[once] now emit a guiding error pointing at #[concurrent_cached] (they were never supported on the single-owner macros).

Additive

• new() returning a ready-to-use cache on every in-memory and sharded store, all #[must_use] (LruCache::new(max_size), TtlCache::new(ttl), LruTtlCache::new(max_size, ttl), the Sharded* variants, etc.). new() now consistently returns a usable cache everywhere it exists.
• Custom hash builder on the non-sharded in-memory stores: a S = DefaultHashBuilder type parameter and a .hasher(...) builder method on UnboundCache / LruCache / TtlCache / LruTtlCache / TtlSortedCache / ExpiringCache / ExpiringLruCache. The default keeps existing call sites source-compatible; DefaultHashBuilder is re-exported.
• Concurrent metric accessors (cache_hits / cache_misses / cache_capacity / cache_evictions, plus a default metrics()) on ConcurrentCacheBase, so the sharded stores' aggregated metrics are reachable through a trait bound.
• ttl_secs (whole seconds) and ttl_millis (sub-second) macro attributes; ttl / ttl_secs / ttl_millis are three-way mutually exclusive, and each is mutually exclusive with expires (Feature Request: Floating-Point ttl #149).
• ttl_secs / ttl_millis convenience setters on every TTL builder (non-sharded, sharded, Redis, Redb); last-writer-wins with ttl(Duration).
• force_refresh (per-call cache bypass) on all three macros, with result_fallback interaction and no read side effects on the bypassed entry (Feature Request: bool function argument that forces a cache refresh. #146).
• in_impl to cache methods inside impl blocks; self-receiver methods require it and get a {fn}_no_cache sibling (macro: Not working inside impl blocks #16, Feature request: Skip self field to allow caching methods #140).
• Reference arguments (&T, Option<&T>) form the default key without convert (proc_macro: support args which are &T and Option<&T> #202, Support &T and Option<&T> in input #203).
• SerializeCached / SerializeCachedAsync (cache_set_ref) for serialize-backed stores; #[concurrent_cached] routes its set through them to avoid a value clone (Borrowed keys and values for IOCached::set_cache #196, Borrowed keys and values for IOCached::set_cache #195).
• RedisCache / AsyncRedisCache gain cache_clear / async_cache_clear (Add cache_clear operation #200); LruCache::set_max_size / try_set_max_size with matching LruTtlCache / ExpiringLruCache methods (Feature: Ability to configure (or reconfigure) a SizedCache size based on runtime data #180); ConcurrentCloneCached::cache_peek_with_expiry_status.
• Generated code resolves the crate path via proc-macro-crate (renamed dependency works, Allow reexport #157); macro bindings are hygienic (key argument name collision #230, Cannot use key as a function argument #114); clear error for generic functions without key + convert (How to aproach generics ? #80).
• Unquoted code-valued macro attributes: convert / create / force_refresh / map_error / cache_prefix_block accept bare Rust (convert = { format!("{a}") }, map_error = |e| ...); the quoted-string forms still work. ty / key stay quoted (they hold types).
• map_error optional on disk / redis #[concurrent_cached] when the error type implements From<store error> (the macro generates .map_err(Into::into)?).
• Infallible inherent get / set / remove / remove_entry / delete / reset on the six sharded stores, returning unwrapped values (Option<V>, bool, ()), removing the .expect("...infallible") ceremony. The cache_* trait methods still return Result for generic code.
• companions_vis macro attribute sets the visibility of the generated {fn}_no_cache / {fn}_prime_cache companions independently of the cached fn.
• Expires::expires_at(&self) -> Option<Instant> default method (advisory observability; is_expired() stays the authoritative liveness check).

Documentation

• Docs and examples prefer the short alias method API (get / set / remove / clear / len / ...) over the cache_*-prefixed forms, with a note on when to reach for the cache_* names (collision with another in-scope trait's method). The aliases now live on CachedExt / ConcurrentCachedExt (see Breaking changes); the prelude brings them in.
• The README "Upgrading from 2.x?" banner points to the migration guide rather than enumerating breaking changes inline.
• New specs/ directory documenting the current state and proposed work for the 3.0 effort, each item marked implemented, not implemented, or needs research.
• Float convert guidance (Document how this should work on floats? #78), cache-invalidation and struct-method examples (Examples: cache invalidation #21, Add example of passing dyn trait instance #236), the redis backward-read / connection-string / millisecond-TTL behavior, and a broad accuracy pass across the macro/store docs and the migration guide.
• LRU sharded stores take a write lock on read hits: documented as a known limitation with a planned separate read-optimized store type. Examples modernized to the unquoted attributes, the infallible sharded API, and the optional map_error path.

Tests

• Positive macro coverage for all three ttl spellings across #[cached] / #[once] / #[concurrent_cached], and compile-fail UI goldens for the three-way exclusivity, the ttl = <int> migration error, and the disk / redis / map_error rejection on the single-owner macros.
• Inline store coverage for every new new() constructor and the ttl_secs / ttl_millis builder setters (including override semantics).
• Redis backward-read of pre-3.0 JSON entries, a structured value round-tripped through the MessagePack path, and sub-second TTL precision via PTTL (server-gated); a custom BuildHasher threaded through the non-sharded stores; aggregated cache_hits / cache_misses / cache_capacity / cache_evictions through ConcurrentCacheBase.
• Clone-elision counts, force_refresh + result_fallback / in_impl, _mut trait coverage, redis/redb cache_set_ref round-trips, additional attribute/store combinations, and sharded peek-does-not-renew-TTL.
• sync_writes = "by_key" default dedup, per-entry expiry (set_ttl future-only), the Cached::Error associated type, the infallible sharded inherent methods, unquoted-attribute parsing (positive and UI goldens), the async_cache_* rename and unified CacheSetError, TtlSortedCache never-expires-on-zero-ttl, Expires::expires_at, and async RedbCache under a non-tokio executor (futures::executor::block_on).

Verification

cargo build / clippy --all-features --all-targets clean; full make ci green (check + tests + examples), including redis-backed tests and examples against a local server and the trybuild UI goldens; doctests pass; cargo fmt --check clean; README regenerated from src/lib.rs and in sync. cargo tree confirms redis_smol and the async feature no longer pull tokio (it remains a dev-dependency only).