Skip to content

HydraCache 0.36.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 13 Jul 16:00
· 1366 commits to main since this release
v0.36.0
8089ca4

HydraCache 0.36.0

0.36.0 is a database production-rollout release. It builds on the 0.35.0
database production-readiness work by adding rollout playbooks, review
guardrails, adapter matrix clarity, freshness-budget guidance, macro ergonomics,
and repeatable soak/load validation.

Highlights

  • Database-cache rollout playbook for feature-flagged adoption, canaries,
    bypass mode, rollback, and dashboards.
  • Repository transaction/invalidation guardrails that keep invalidation after
    commit and away from rollback paths.
  • Cache-policy review checklist for tenant, authorization, filters,
    pagination, sorting, locale, region, feature flags, and time windows.
  • Freshness budget guidance for stale-on-loader-error, refresh-ahead,
    read-mostly catalog data, negative caching, and security-sensitive reads.
  • Macro ergonomics work to reduce entity, key, tag, policy, and prepared-query
    boilerplate while keeping cache boundaries explicit.
  • Honest SQLx, Diesel, and SeaORM adapter support matrix.
  • Deterministic DB-cache soak/load validation for miss, hit, write,
    invalidation, reload, rollback, loader failure, stale fallback, and
    diagnostics behavior.
  • Release-gate updates that keep Windows validation stable and make DB rollout
    confidence visible.

Changes

  • Track the implementation plan under
    docs/plans/V0_36_DATABASE_PRODUCTION_ROLLOUT_PLAN.md.
  • Add HydraCacheEntity id-field inference so named structs can use
    #[hydracache(id)] on the id field instead of repeating id = Type on the
    struct attribute.
  • Add query_cache_policy! preset = ... and freshness-budget options for
    refresh_ahead_secs, stale_while_revalidate_secs, and
    stale_on_loader_error_secs.
  • Add query_cache_policy! key_segments = [...] and
    tag_segments = [[...], [...]] for escaped, reviewable dimension-based
    keys and invalidation tags.
  • Add prepared_query_policy! for reusable repository-method cache metadata
    while keeping DbCache::prepare and loader execution explicit.
  • Breaking macro cleanup: cacheable!(...) is now cacheable_loader!(...),
    and #[cacheable(...)] is the explicit async-function attribute macro for
    ordinary non-database cached work.
  • Add sandbox ergonomics examples at /demo/ergonomics/examples so verbose
    implementations and equivalent release-36 sugar can be reviewed side by
    side.
  • Add sandbox rollout comparison at /demo/rollout/compare so canaries can
    compare uncached backing-store reads with cached reads and avoided loader
    calls.
  • Add sandbox DB soak validation at /demo/db/soak/run with short and long
    request shapes for release gates and manual pre-release checks; the JSON
    summary reports requests, hit ratio, avoided loader calls, single-flight
    joins, invalidations, stale fallback/discard counters, loader failures,
    retries, writes, rollbacks, reloads, and latency distribution.
  • Add InvalidationPlan for staging key/tag invalidations during repository
    writes and executing them only after the database commit succeeds.
  • Add a pre-rollout cache-key review checklist for tenant, authorization,
    filters, pagination, sort, locale, region, feature flag, and time-window
    dimensions.
  • Add a freshness-budget decision table and observability notes for negative
    caching, refresh-ahead, stale-while-revalidate, stale-on-loader-error, and
    security-sensitive reads.
  • Document the adapter runtime matrix: hydracache-db repository loaders,
    SQLx SQLite, Diesel SQLite, and SeaORM SQLite are deterministic local-gate
    coverage; SQLx Postgres and sandbox Postgres are optional Docker smoke checks;
    Diesel/SeaORM Postgres/MySQL remain adapter-contract-only.
  • Extend docs/DB_PRODUCTION_READINESS.md with rollout and rollback guidance.
  • Extend docs/POLICY_GUIDE.md with freshness-budget examples.
  • Extend docs/OBSERVABILITY_CONTRACT.md with rollout dashboard and alert
    interpretations.
  • Improve macro ergonomics for:
    • HydraCacheEntity id-field inference;
    • query_cache_policy! presets and freshness options;
    • safe key_segments and tag_segments DSLs;
    • a prepared_query_policy! macro for hot repository methods;
    • a carefully scoped function attribute macro for ordinary non-database
      expensive async work.
  • Add and document a DB rollout/soak validation command.
  • Add the short DB soak route test to
    scripts/verify-release-readiness.ps1 -RunGate and document the Windows
    CARGO_BUILD_JOBS=1 workaround for intermittent MSVC LNK1104 locks.
  • Add tests for staged repository invalidation, key-review examples, and
    freshness policy intent where implementation work requires new code.
  • Add unit, trybuild, runtime, and re-export tests for every new macro
    feature.

Verification

This release should pass:

  • cargo fmt --all -- --check
  • cargo check --workspace --all-targets --locked
  • cargo test --workspace --all-targets --locked
  • cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
  • cargo test --doc --workspace --locked
  • RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --locked
  • .\scripts\verify-release-readiness.ps1 -Version 0.36.0 -RunGate
  • cargo test -p hydracache-sandbox db_soak_route_reports_release_validation_counters --locked
  • macro-specific tests for every implemented macro ergonomics item
Assets 2
Loading