HydraCache 0.24.0

HydraCache 0.24.0

Status: ready for release. Validated locally on 2026-06-11.

0.24.0 focuses on cluster-aware read-through over the peer-fetch routing layer
introduced in 0.23.0.

Highlights

• Public HydraCache::put_encoded for encoded-byte hydration.
• PeerFetchReadThrough in hydracache-cluster-transport-axum.
• Near-cache hydration on remote owner hits through the existing cache codec
  boundary.
• Explicit LocalThenOwner, OwnerThenLocal, and OwnerOnly policies without
  remote loader execution.
• Read-through diagnostics for local hits, local misses, remote hits,
  remote misses,
  hydrations, router errors, and future fallback loader counts.
• Sandbox route for local miss -> owner hit -> hydration -> local hit.
• README, testing notes, post-publish coverage, and rustdoc examples.

Intended Shape

use hydracache::{CacheOptions, ClusterCandidate, ClusterGeneration, InMemoryCluster};
use hydracache_cluster_transport_axum::{PeerFetchReadThrough, PeerFetchReadThroughStatus};

# async fn example() -> hydracache::CacheResult<()> {
let near_cache = hydracache::HydraCache::local().build();
let cluster = InMemoryCluster::new("orders");
cluster.join_member(
    ClusterCandidate::member("member-a")
        .generation(ClusterGeneration::new(1))
        .peer_fetch_base_url("http://127.0.0.1:3000"),
)?;

let read_through = PeerFetchReadThrough::new(near_cache);
let outcome = read_through
    .fetch_encoded(
        cluster.owner_for_key("user:42"),
        CacheOptions::new().tag("user:42"),
    )
    .await?;
assert!(matches!(
    outcome.status,
    PeerFetchReadThroughStatus::RemoteHit
        | PeerFetchReadThroughStatus::RemoteMiss
        | PeerFetchReadThroughStatus::TransportError
));
# let _ = outcome;
# Ok(())
# }

Boundaries

Read-through fetches only bytes already cached by the owner member. It can
hydrate the caller's local cache on remote hit, but it does not ask the owner to
execute loaders or database queries. TLS, authentication, replication, backup
ownership, and failover repair remain future work.

The sandbox route POST /demo/cluster/read-through/run starts two temporary
owner HTTP peer-fetch services, stores encoded bytes on the selected owner,
performs a read-through first read, verifies near-cache hydration, and performs
a second read that should be local.

Validation

cargo test -p hydracache --lib --locked put_encoded
cargo test -p hydracache-cluster-transport-axum --locked read_through
cargo test --doc -p hydracache-cluster-transport-axum --locked
cargo test -p hydracache-sandbox --locked swagger_api_exercises_library_features_and_reports
cargo fmt --all -- --check
cargo check --workspace --all-targets --locked
cargo test --workspace --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
$env:RUSTDOCFLAGS='-D warnings'; cargo doc --workspace --no-deps --locked

See the 0.24.0 plan for the
implementation checklist.