HydraCache 0.25.0

HydraCache 0.25.0

Status: published.

0.25.0 combines the post-0.24.0 hardening pass with the next product step:
Groupcache-style owner-side loading and distributed single-flight.

0.24.0 can route a client/local miss to an owner member and hydrate the
client near-cache when the owner already has encoded bytes. 0.25.0 should
extend that flow so the owner can execute an explicitly registered loader on
miss, store the encoded value locally, and return it to the caller.

Planned Highlights

• Coverage hardening for sandbox and cluster edge paths, targeting 95%+
  workspace line coverage.
• Transport-neutral owner-load protocol types.
• Explicit owner-side loader registry keyed by stable loader names.
• Owner-load service that checks ownership/generation, local owner cache, and
  owner-side single-flight before running a registered loader.
• HTTP owner-load route/client in hydracache-cluster-transport-axum.
• Read-through load-on-miss helper that can hydrate a client near-cache from an
  owner Hit or Loaded response.
• Diagnostics for owner-load attempts, hits, misses, loader executions,
  single-flight joins, rejections, failures, hydration, and transport errors.
• Sandbox/OpenAPI route for
  client miss -> owner miss -> owner loader -> owner store -> client hydrate.
• README and rustdoc examples for the public owner-load API.

Intended Shape

use std::time::Duration;

use hydracache::{CacheOptions, HydraCache};
use hydracache_cluster_transport_axum::{
    OwnerLoadDescriptor, OwnerLoadRegistry, OwnerLoadValue, PeerFetchReadThrough,
};

# async fn example() -> hydracache::CacheResult<()> {
# let cluster = hydracache::InMemoryCluster::new("users");
# let owner_cache = HydraCache::local().build();
let _registry = OwnerLoadRegistry::new()
    .register("users.by-id", |request| async move {
        let id = request.arg_i64("id").map_err(|error| {
            hydracache::CacheError::Backend(error.to_string())
        })?;
        let user = format!("user-{id}");
        let encoder = HydraCache::local().build();
        encoder.put("value", user, CacheOptions::new()).await?;
        let encoded = encoder.get_encoded("value").await?.expect("encoded value");

        Ok(Some(OwnerLoadValue::encoded(
            encoded,
            CacheOptions::new().tag(format!("user:{id}")),
        )))
    });

let near_cache = HydraCache::local().build();
let read_through = PeerFetchReadThrough::new(near_cache);

let _outcome = read_through
    .get_or_load_encoded(
        cluster.owner_for_key("user:42"),
        OwnerLoadDescriptor::new("users.by-id")
            .key("user:42")
            .tag("user:42")
            .arg("id", 42_i64)
            .ttl(Duration::from_secs(60)),
    )
    .await?;
# let _ = owner_cache;
# Ok(())
# }

The exact API may change during implementation, but the release principle is
fixed: applications register named loaders on members; clients send descriptors,
not closures or raw SQL.

Sandbox Lab

The manual sandbox exposes POST /demo/cluster/owner-load/run. One call runs
the complete owner-load teaching flow:

• client local miss;
• owner cache miss;
• registered owner loader execution;
• owner encoded-value store;
• client near-cache hydration;
• second client read as local hit;
• concurrent same-key remote callers sharing one owner loader;
• structured missing-loader, stale-generation, and wrong-owner rejections.

Boundaries

This release is not a transparent distributed database cache. It does not send
Rust closures, raw SQL, ORM calls, or arbitrary executable code over the
network. It does not add replication, backup ownership, distributed
transactions, TLS/authentication, or durable value storage.

Freshness still comes from explicit key/tag invalidation. Near-cache hydration
is an optimization, not a new consistency model.

Validation

Expected focused checks:

cargo test -p hydracache --lib --locked owner_load
cargo test -p hydracache-cluster-transport-axum --locked owner_load
cargo test -p hydracache-sandbox --locked owner_load
cargo test --doc -p hydracache-cluster-transport-axum --locked

Expected full release gate:

cargo fmt --all -- --check
cargo check --workspace --all-targets --locked
cargo test --workspace --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --doc --workspace --locked
$env:RUSTDOCFLAGS='-D warnings'; cargo doc --workspace --no-deps --locked
cargo llvm-cov --workspace --all-targets --locked --summary-only

Package verification should follow the staged publish order:

.\scripts\package-publishable.ps1 -Set bootstrap
.\scripts\package-publishable.ps1 -Set runtime
.\scripts\package-publishable.ps1 -Set adapters

The runtime and adapters sets can only be verified fully after the earlier
0.25.0 packages are published and the crates.io index sees them.

See
the combined 0.25.0 plan
for the implementation checklist.