versionedcache: a cache that reloads when a Redis version key moves by aaron-wego · Pull Request #253 · wego/pkg

aaron-wego · 2026-09-12T02:18:30Z

A new module, github.com/wego/pkg/versionedcache.

Holds a dataset in memory and reloads it only when a small version published beside that dataset says the data changed. A cycle that finds the version unchanged costs one read of a short string instead of reading the whole dataset.

It is for config that is read constantly, changes rarely, and is expensive to fetch whole.

cache := versionedcache.New(
    versionedcache.VersionInHashField(client, "myservice:versions", "rates"),
    loadRates,
    30*time.Second,
    versionedcache.Options{
        WhenRefreshed: func(o versionedcache.RefreshOutcome, err error) { /* your metric */ },
    },
)

rates, err := cache.Get(ctx)

Notes for review

Where the version lives is a ReadVersion function, not a client plus a key. VersionInKey and VersionInHashField cover the two Redis shapes; a dataset with no version passes nil and reloads every interval. Only those two helpers mention Redis, so a caller could version off a DynamoDB attribute or an ETag without a third constructor.
Versions are compared as exact text, never as an ordering. Any different value counts as changed, so a publisher only has to make the value change, not increase. A value restored from a backup is handled for free.
The version is read before the data. A refresh overlapping a writer is then stamped with the older version and repairs itself next cycle. The reverse order can pin a stale value forever: data read before a writer's update, paired with a version read after it, makes the held version match the published one permanently.
Get returns an error only when it has never loaded. After a first success, a failed read of either the version or the data keeps the previous value and returns it with a nil error. The failure reaches the caller through Options.WhenRefreshed, so an outage does not empty a warm cache.
The outcome says what happened; the error is only detail. Six values, so a caller's metric tag is string(outcome) with nothing to branch on: version_unchanged, reloaded_after_change, reloaded_without_version, reloaded_at_max_staleness, refresh_failed, first_load_failed.
No metrics dependency. WhenRefreshed lets the calling service emit its own metric, which is what keeps observability libraries out of this repo.
An Options struct rather than functional options: Go cannot infer the type parameter for a standalone generic option, so WhenRefreshed[T](...) would make every call site spell the type out.

The store underneath is otter

Holding the value, timing the interval and running one refresh at a time are otter v2's. This package adds the version comparison and the outcome. An earlier revision hand-rolled all of it; the library replaced about a hundred lines of atomics and a compare-and-swap election.

Two caller-visible consequences:

A refresh runs on a background goroutine. The call that finds the interval elapsed is answered from memory and starts the refresh; a changed dataset reaches a later call. Worst-case staleness is the interval plus one refresh. That refresh also runs with the caller's cancellation stripped, so a deadline on the Get that started it does not cut it short — the client's own timeouts bound it.
A caller arriving during the very first load waits for it and gets what it produced, rather than being turned away.

Two otter behaviours this package deliberately overrides, both worth a look:

Its refresh calculators leave a failed reload still due, which would send the very next call back to a source already known to be down. refreshEvery puts the entry back on the clock after every cycle, failed ones included.
Reload is handed the value the cache held when that call's Get ran. For a cycle queued behind another one that value is out of date, so the cycle decides the version moved, re-reads a dataset the cycle in front just read, and writes its result over the newer one. The cycle therefore compares against the newest entry it produced. This surfaced as a flaky test, not in review; it reproduces 17 times in 40 runs under -race.

A floor under how long a version is trusted

Options.MaxStaleness, six hours by default. A version that stops moving is not proof the data is unchanged — a writer can change rows and die before publishing, and a bulk import publishes once at the very end. Data kept on an unchanged version for that long is read again anyway and reports reloaded_at_max_staleness. Only a read restarts that clock; a skipped cycle does not.

Release

Not tagged yet. Once this merges, ./auto_version on main tags versionedcache/v0.1.0.

lei-wego

Four blocking items, all inline. The one that decides timing rather than content: New has no error return and the six RefreshOutcome strings are already Datadog tag values in flight-cerberus, so the input-validation and enum decisions freeze the moment ./auto_version cuts versionedcache/v0.1.0.