Make the KvHandle TTL cap configurable per handle

[eastagiletracker]

This PR proposes making the KvHandle TTL cap configurable per handle, so retention windows longer than a year can be written through named KV stores (Fixes #323). We include this PR work along with a full history of your repo at https://eastagiletracker.com/projects/1008. You can sign in with your GitHub ID to claim ownership of the project.

What changed and why

KvHandle::validate_ttl rejected every TTL above the hard-coded KvHandle::MAX_TTL (365 days), and since KvRegistry::named hands back a KvHandle (BoundKvStore is an alias for it), an app with a multi-year retention policy had no way to write through a named store. This implements option 1 from the issue: KvHandle now carries its own max_ttl, KvHandle::new initialises it to MAX_TTL (so default behaviour is unchanged), and two additive methods expose it: with_max_ttl(self, Duration) -> Self returns the handle with a different cap, and max_ttl(&self) reports the active one. The cap travels with clones. MIN_TTL still applies, and the over-cap error now names the actual cap instead of a fixed "1 year". Usage: kv.named("events").map(|store| store.with_max_ttl(retention)).

No public signature changed or was removed, so existing callers compile and behave as before. The adapters already cope with long TTLs: Axum computes expiry with checked_add and reports overflow as an internal error (covered by its existing put_bytes_with_ttl_propagates_overflow_as_internal_error test), Cloudflare passes whole seconds, and Fastly passes the Duration through. docs/guide/kv.md now mentions the override in the TTL note and the limits table.

Reproduction at current HEAD (f717674)

A throwaway integration test against main, using NoopKvStore, rejected a two-year TTL:

$ cargo test -p edgezero-core --features test-utils --test zz_repro_ttl -- --nocapture
put_with_ttl(2y) -> Err(Validation("TTL 63072000s exceeds maximum of 1 year"))
test repro_two_year_ttl_rejected ... FAILED

Verification

• Six new unit tests in key_value_store.rs: the default cap equals MAX_TTL; a raised cap accepts a two-year TTL through both put_with_ttl and put_bytes_with_ttl and the values read back; writes above a custom cap are still rejected (both paths) and nothing is stored; the cap can be lowered; the 60-second floor still applies; clones keep the cap. Changing the comparison back to Self::MAX_TTL turns three of them red (accepts_ttl_beyond_default_cap, can_lower_the_cap, is_preserved_by_clone) while the controls stay green.
• cargo test -p edgezero-core --all-targets: 485 passed before, 491 passed after (the 6 new tests), 0 failures. cargo test -p edgezero-adapter-axum --all-targets: 119 passed before and after.
• cargo clippy -p edgezero-core --all-targets --all-features -- -D warnings is clean, cargo fmt --all -- --check is clean, and cargo check --workspace --all-targets passes.

How this was managed

This work was tracked as https://eastagiletracker.com/projects/1008/stories/1318615 on https://eastagiletracker.com/projects/1008, a board imported from this repository's 378 issues and pull requests and used to manage this change.

If you'd rather not receive contributions like this, reply no-more-prs on this pull request and we won't open any further ones on your repositories.

---

Lawrence W. Sinclair
CEO / East Agile
linkedin.com/in/lwsinclair/
eastagile.com