Caching · XB Field Notes

A bloom filter answers maybe at low cost

Wed, 15 Dec 2027 00:00:00 +0000

A Bloom filter can cheaply rule out membership in the set it represents, while a positive answer means only “possibly present.” That asymmetry depends on correct updates and unchanged hash rules. A stale or corrupted filter can reject a key that exists in the underlying database, even though the ordinary append-only algorithm has no false negatives for inserted items.

Bits represent candidates, not records

Start with a zeroed array of m bits and k hash-derived positions per key. Insertion sets all those positions. Lookup returns negative if any required bit is zero; otherwise it returns maybe. Different keys can share positions, so a positive answer is not proof that the queried key was inserted.

Inserting an existing key again leaves its bits unchanged. The filter does not retain the original keys or values, and cannot enumerate them. An exact set or database remains authoritative when a false positive would affect correctness. Do not use “maybe” alone to grant access, charge a customer, or discard required work.

Size for an expected population

Under the usual approximately uniform, independent-hashing model, n inserted distinct items give an approximate false-positive probability of p = (1 − exp(−kn/m))^k. For fixed m and n, k near (m/n) ln(2) minimizes that approximation. More hash operations are not always better: they also fill bits faster.

With an optimal hash count, a one-percent target needs roughly 9.6 bits per item, before implementation overhead. Ten million items therefore need about twelve million bytes of bitmap, not merely a few million bits. State whether a size is bits, bytes, payload alone, or total process memory.

The false-positive rate concerns queries for absent items. It is not the fraction of all positive answers that are wrong; that fraction also depends on how often callers ask about present items. Measure against known nonmembers, and do not interpret a finite sample as an exact probability guarantee.

Keep the represented set synchronized

For a negative answer to justify skipping the database, the filter must include all relevant database insertions. Publishing a new row before updating the filter creates a visibility gap. Rebuilds likewise need a defined snapshot and update handoff. A successful filter lookup does not establish that those application-level steps were atomic.

Keep the bit count, hash construction, seeds or domain prefixes, and byte encoding consistent across writers and readers. Changing those inputs changes positions. Ordinary filters cannot safely delete by clearing an item’s bits, because other items may depend on the same bits. Counting or other deletion-capable structures have different contracts.

When it breaks

Overfilling a fixed bitmap raises false positives and can erase the benefit of avoiding expensive lookups. Negatives remain sound for correctly inserted items, but fewer queries return negative. Enlarging a fixed bitmap requires rebuilding or a suitable growth design; merely changing its modulus makes existing bits meaningless.

Product behavior is not identical to this fixed-size model. Redis BF.RESERVE can create additional subfilters when scaling is enabled, while its nonscaling mode rejects insertion beyond capacity. Subfilters cost memory and lookup work. Consult the configured implementation instead of assuming it silently saturates like an unbounded insertion loop.

Lost updates, inconsistent encoding, stale snapshots, and unsafe deletion can violate the application’s expected negative-answer safety. Track insertion failures and filter freshness as well as observed false positives. The filter is an optimization whose maintenance belongs in the data lifecycle.

Bloom: maybe is not proof. Source-based mechanism illustration. Model values and source-reported observations are not a new runtime test.

Check it quickly

Save the block as bloom_check.py and run python3 bloom_check.py with Python 3.10 or newer. It ran with Python 3.14.4 and uses only the standard library. Seven domain-prefixed SHA-256 digests, explicit UTF-8, and fixed key sequences make the test repeatable. No external service, network access, or file writing is required.

from hashlib import sha256
from math import exp


M, K, N = 10000, 7, 1000


def offsets(value):
 data = value.encode("utf-8")
 return tuple(int.from_bytes(sha256(index.to_bytes(2, "big") + data).digest(), "big") % M
 for index in range(K))


def add(bits, value):
 for position in offsets(value):
 bits[position // 8] |= 1 << (position % 8)


def maybe(bits, value):
 return all(bits[position // 8] & (1 << (position % 8)) for position in offsets(value))


bits = bytearray((M + 7) // 8)
inserted = [f"item:{index}" for index in range(N)]
truth = set(inserted)
for value in inserted:
 add(bits, value)
assert all(maybe(bits, value) for value in inserted)
before = bytes(bits)
add(bits, inserted[0])
assert bytes(bits) == before

absent = [f"absent:{index}" for index in range(10000)]
assert truth.isdisjoint(absent)
false_positives = [value for value in absent if maybe(bits, value)]
assert 0 < len(false_positives) < len(absent)
estimate = (1 - exp(-K * N / M)) ** K
print(f"{N} inserted; bitmap={len(bits)} bytes; estimate={estimate:.4%}")
print(f"absent probes: {len(false_positives)}/{len(absent)} false positives")
assert false_positives[0] not in truth
print("a maybe still needs exact lookup:", false_positives[0])

victim = inserted[0]
victim_offsets = set(offsets(victim))
retained = next(value for value in inserted[1:] if victim_offsets.intersection(offsets(value)))
broken = bytearray(bits)
for position in victim_offsets:
 broken[position // 8] &= ~(1 << (position % 8))
assert retained in truth and maybe(bits, retained) and not maybe(broken, retained)
print("clearing bits for", victim, "incorrectly rejects retained", retained)

new_value = next(f"new:{index}" for index in range(1000) if not maybe(bits, f"new:{index}"))
truth.add(new_value)
assert new_value in truth and not maybe(bits, new_value)
add(bits, new_value)
assert maybe(bits, new_value)
print("an origin insertion is invisible until the filter is also updated")

# Use a separate fixed bitmap so the capacity experiment has exactly 5000 items.
overfull = bytearray((M + 7) // 8)
for index in range(5000):
 add(overfull, f"item:{index}")
overfull_positives = sum(maybe(overfull, value) for value in absent)
assert overfull_positives > len(false_positives)
assert all(maybe(overfull, f"item:{index}") for index in range(5000))
print(f"5000 inserted in the same bit budget: {overfull_positives}/{len(absent)} false positives")

The 10,000-bit array occupies 1,250 payload bytes. After 1,000 insertions, all inserted items test positive, repeated insertion changes nothing, and 73 of 10,000 known-absent probes return maybe. The approximation predicts about 0.8194 percent; this finite fixture observes 0.73 percent.

Clearing item:0’s bits incorrectly rejects retained item:79. A new origin item is also invisible until its filter update. A separate bitmap filled with 5,000 items returns 8,016 false positives on the same absent probes, while still recognizing every inserted item.

These assertions distinguish algorithmic false positives from maintenance-induced false negatives. They are not a production memory benchmark, concurrency test, serialization-compatibility test, or execution of Redis Bloom commands.

Sources

Redis Bloom filters, probabilistic membership and authoritative follow-up lookups, checked 2026-09-08.
Redis BF.RESERVE, sizing formulas, capacity, and scaling behavior, checked 2026-09-08.
Python hashlib, deterministic SHA-256 digest construction, checked 2026-09-08.

Cache freshness is judged against a clock

Fri, 03 Dec 2027 00:00:00 +0000

A cache does not receive a new freshness allowance every time another cache forwards a response. It must account for age already accumulated along the delivery path, then add its own residence time. Otherwise a chain of individually plausible sixty-second caches can keep old content reusable much longer than the origin intended.

A received Age of 20 reaches the shared freshness boundary at 30 and the private boundary at 60. A separate stale window permits a response with asynchronous validation, not fresh reuse. Source illustration only; no new fixture execution.

Count the age

Age estimates seconds since generation or successful validation, including time in caches and transit. The received Age field is therefore an input to current age, not a counter that stays frozen while the response sits locally. Date supplies the response’s origination timestamp. Clock synchronization and measured request/response timing matter when relating those values.

RFC 9111 describes an apparent age from response receipt minus Date, clamped at zero, and a corrected age value from received Age plus response delay. Its conservative calculation takes the larger value, then adds residence time. For request time 100, receipt 102, Date 95, received Age 10, and current time 107, those values are 7, 12, and finally 17 seconds. Reading only the original Age would miss seven seconds.

Freshness lifetime has a precedence order: shared caches use s-maxage when present; otherwise max-age takes precedence over Expires minus Date. Private caches ignore s-maxage. Without explicit expiration, a permitted heuristic might apply, but its duration is not universally fixed. A response is fresh only while its applicable lifetime is greater than current age; equality is already the stale boundary.

When it breaks

Fresh does not mean usable for every request. Storage permission, URL and Vary matching, and validation requirements still apply. No-cache requires validation before reuse even when an explicit lifetime looks generous. An ETag supplies a validator, not permission to skip validation. Successfully revalidating can update stored metadata without transferring the body; simply receiving a cached response cannot reset its age.

Stale delivery is a separate permission, not an automatic response to an outage. Must-revalidate prohibits reuse once stale until validation succeeds, including when disconnected. Stale-while-revalidate permits a bounded stale interval while validation proceeds, subject to applicable restrictions. It does not turn stale content fresh. RFC 9111 also obsoletes Warning, so absence of the old Warning: 110 field is not evidence of freshness.

Do not confuse storage retention with freshness. Keeping bytes after expiration can be useful for validation or an allowed stale window. A backend’s eviction TTL may therefore exceed the direct-reuse lifetime. If the caller treats that TTL as permission to serve, it can deliver stale responses outside the intended policy.

Check it quickly

Use Node.js and npm; the tested versions are Node 26.0.0 and http-cache-semantics 4.2.0. Install the library below, then execute the JavaScript with NODE_PATH="$freshness_lab/node_modules" node. The test overrides the library’s clock, not the system clock. It uses synthetic metadata, performs no requests, and needs no sleeping; only installation requires the network.

freshness_lab=$(mktemp -d)
npm install --prefix "$freshness_lab" --ignore-scripts --no-audit --no-fund --package-lock=false http-cache-semantics@4.2.0

const assert = require("node:assert/strict");
const CachePolicy = require("http-cache-semantics");

const start = Date.parse("2026-09-07T00:00:00Z");
let clock = start;
class TestPolicy extends CachePolicy {
 now() { return clock; }
}
const request = { url: "https://example.test/news", method: "GET", headers: {} };
const headers = {
 date: new Date(start).toUTCString(),
 age: "20",
 expires: new Date(start + 3600000).toUTCString(),
 "cache-control": "public, max-age=60, s-maxage=30",
};
const shared = new TestPolicy(request, { headers }, { shared: true });
const single = new TestPolicy(request, { headers }, { shared: false });
assert.equal(shared.maxAge(), 30);
assert.equal(single.maxAge(), 60);
for (const [elapsed, sharedHit, privateHit] of [
 [0, true, true], [9, true, true], [10, false, true], [40, false, false],
]) {
 clock = start + elapsed * 1000;
 assert.equal(shared.age(), 20 + elapsed);
 assert.equal(shared.responseHeaders().age, String(20 + elapsed));
 assert.equal(shared.satisfiesWithoutRevalidation(request), sharedHit);
 assert.equal(single.satisfiesWithoutRevalidation(request), privateHit);
 console.log("elapsed:", elapsed, "age:", shared.age(), "reuse:", sharedHit, privateHit);
}

clock = start;
const background = new TestPolicy(request, { headers: {
 age: "20", "cache-control": "public, max-age=30, stale-while-revalidate=20",
} });
clock += 15000;
const decision = background.evaluateRequest(request);
assert.equal(background.timeToLive(), 15000);
assert.equal(background.satisfiesWithoutRevalidation(request), false);
assert(decision.response);
assert.equal(decision.revalidation.synchronous, false);
console.log("stale window: retain 15000 ms, serve and revalidate");
clock += 15000;
assert.equal(background.evaluateRequest(request).response, undefined);
assert.equal(background.evaluateRequest(request).revalidation.synchronous, true);

clock = start;
const oldDate = new TestPolicy(request, { headers: {
 date: new Date(start - 3600000).toUTCString(),
 "cache-control": "public, max-age=60",
} });
assert.equal(oldDate.age(), 0);
assert.equal(oldDate.satisfiesWithoutRevalidation(request), true);
console.log("library limitation: old Date alone does not increase age");

At elapsed times zero, nine, ten, and forty seconds, the calculated ages are twenty, twenty-nine, thirty, and sixty. Both modes initially reuse the response. Shared reuse stops exactly at age thirty; private reuse stops at sixty. The future Expires date does not override either explicit lifetime. Updated outgoing Age is checked as well as the reuse decision.

The separate stale-window fixture reaches age thirty-five, five seconds beyond freshness. Its remaining retention allowance is fifteen thousand milliseconds, but validation is still required. The library permits a response together with asynchronous revalidation; it does not perform that network operation itself. At age fifty, that permission ends and validation becomes synchronous.

The final check exposes an important implementation limit: this library deliberately ignores server Date when calculating age. An hour-old Date with no Age still starts at zero here. Its documented model adds received Age and local residence, not measured response delay or the conservative apparent-age branch above. Consequently, these passing assertions establish the pinned library’s decisions, not complete RFC age-calculation conformance. Test actual intermediary timing and header propagation separately before using a measured cache lifetime as a delivery guarantee.

Sources

RFC 9111: freshness, lifetime precedence, current age, and stale-response restrictions, checked 2026-09-07.
MDN: Cache-Control, freshness and stale-while-revalidate directives, checked 2026-09-07.
http-cache-semantics 4.2.0, retention TTL, revalidation decisions, and the documented server-Date limitation, checked 2026-09-07.

A cache stampede hits when expiry syncs

Mon, 22 Nov 2027 00:00:00 +0000

A cache stampede occurs when concurrent misses cause redundant work against the same dependency. Synchronized expiration is one trigger, but eviction, a cold deployment, or cache unavailability can create the same burst. A single popular key can be enough. The useful question is how many rebuilds reach the source while one result is still being computed.

The article’s overlapping-call fixture counts work within explicit Group boundaries. One Group coalesces an in-flight wave, two independent Groups each load, and a later wave starts again. Completed-value storage remains the application’s responsibility.

Coalesce work within its actual boundary

Go’s singleflight Group gives one key at most one in-flight function execution within that Group. Duplicate callers receive the same result, including the same error. Separate Groups do not coordinate, even within one process, and separate service instances normally have separate Groups. It is neither a distributed lock nor a cache of completed values.

Keep the Group shared across requests, and make its key identify equivalent work. Mixing tenants, permissions, currencies, or representations under one key can share the wrong result. In a cache-backed loader, check the cache again inside the shared function, fetch only if still necessary, and publish a successful value before returning. Singleflight itself does none of those storage operations.

Spread deadlines without changing the promise

Jitter spreads expiration across different entries or independently maintained copies. It does not prevent all callers of one expired hot key from colliding. If a maximum TTL is a freshness requirement, randomly shortening lifetimes within a chosen bound avoids silently exceeding it; adding arbitrary positive jitter changes that requirement. There is no universally correct percentage or number of seconds.

Early refresh and permitted stale responses can keep callers from waiting, but they require explicit application rules. A last-known public catalog may be acceptable temporarily; a revoked permission or current balance may not be. Coalescing reduces duplicate work without deciding whether old data is safe, and a cold cache still needs a source response.

When it breaks

A stuck shared loader can hold many waiters. Bound the loader’s dependency calls and give callers their own waiting deadlines. DoChan returns a result channel, not a cancellation mechanism: one caller abandoning its wait does not automatically stop the underlying work. Forget allows a new execution for the key; it does not cancel the old execution, so it can reintroduce overlapping loads.

Errors are shared only while that execution is in flight. Immediate retries after it finishes can create successive waves against a failing dependency. Use a retry and admission policy matched to that dependency; cacheable absence and transient failure need different treatment. Likewise, a fleet of one hundred local Groups can still create one hundred rebuilds. Do not describe one-process suppression as a global origin-load bound.

Check it quickly

Use Go 1.25 or newer; this exercise was run with Go 1.27.0 and x/sync v0.22.0. Create an isolated module below, put the Go block in main.go there, and run go run -race main.go. Dependency installation requires the network. The experiment starts at the cold-miss boundary and invokes counted loader functions, not a real database, cache server, or timed TTL implementation.

stampede_lab=$(mktemp -d)
cd "$stampede_lab"
go mod init example.invalid/stampede-lab
go get golang.org/x/sync@v0.22.0

package main

import (
 "errors"
 "fmt"
 "sync"
 "sync/atomic"

 "golang.org/x/sync/singleflight"
)

const callers = 12

func require(ok bool) {
 if !ok {
 panic("unexpected result")
 }
}

func wave(groups []*singleflight.Group, failure error) int32 {
 var calls atomic.Int32
 gate := make(chan struct{})
 results := make([]<-chan singleflight.Result, callers)
 load := func() (any, error) {
 calls.Add(1)
 <-gate
 if failure != nil {
 return nil, failure
 }
 return "catalog-v1", nil
 }
 for i := range results {
 results[i] = groups[i%len(groups)].DoChan("catalog", load)
 }
 close(gate)
 for _, result := range results {
 r := <-result
 require(r.Shared && r.Err == failure)
 if failure == nil {
 require(r.Val == "catalog-v1")
 } else {
 require(r.Val == nil)
 }
 }
 return calls.Load()
}

func main() {
 var plain atomic.Int32
 var workers sync.WaitGroup
 gate := make(chan struct{})
 for range callers {
 workers.Add(1)
 go func() {
 defer workers.Done()
 plain.Add(1)
 <-gate
 }()
 }
 close(gate)
 workers.Wait()
 require(plain.Load() == callers)
 fmt.Println("without coalescing: 12 loader calls")

 group := new(singleflight.Group)
 require(wave([]*singleflight.Group{group}, nil) == 1)
 require(wave([]*singleflight.Group{group}, nil) == 1)
 fmt.Println("one Group: 1 call per wave; completed results are not cached")
 other := new(singleflight.Group)
 require(wave([]*singleflight.Group{group, other}, nil) == 2)
 fmt.Println("two independent Groups: 2 loader calls")

 failure := errors.New("origin unavailable")
 require(wave([]*singleflight.Group{group}, failure) == 1)
 require(wave([]*singleflight.Group{group}, nil) == 1)
 fmt.Println("one error reaches 12 callers; next wave starts a new load")
}

The baseline executes twelve loaders. Each single-Group wave executes one, and running a second wave on the same Group executes another: finished results are not retained. Splitting the twelve callers between two Groups produces two executions. A failing wave sends the same error to all twelve callers; the next successful wave starts fresh rather than retrieving a cached failure.

The gate keeps the shared load pending until every DoChan call has registered, so the test does not depend on sleeps or favorable scheduling. Shared is true for all results in these joined waves, including the initiating caller’s result. Receive exactly one result from each channel; DoChan does not close those channels, so ranging over one would wait indefinitely.

For a service-level follow-up, measure loader executions, waiting callers, latency, and failures during a deliberately cold test in an isolated environment. Include multiple instances and source timeouts, not just a high warm-cache hit ratio. The race-detector run validates this program’s observed execution, not every possible race in a production cache implementation.

Sources

Go x/sync v0.22.0: singleflight, Group scope, DoChan, shared errors, and Forget, checked 2026-09-07.
AWS Builders’ Library: caching challenges and strategies, cold caches, request coalescing, failure behavior, and empirical expiration choices, checked 2026-09-07.

An LRU cache evicts the least recently used entry

Fri, 12 Nov 2027 00:00:00 +0000

LRU chooses a victim by recency, not by popularity, age, or business importance. When a bounded cache needs space, an exact least-recently-used policy removes the entry whose last qualifying access occurred longest ago. That rule can exploit temporal locality, but it neither guarantees useful hits nor keeps cached data fresh.

Follow the access order

Imagine a three-entry cache, listed from oldest to newest. Loading A, B, and C produces A–B–C. Reading A moves it to the newest position, producing B–C–A. Loading D then evicts B, leaving C–A–D. A plain insertion-ordered dictionary does not automatically move an entry when it is read.

An implementation must define which operations count as touches. A common exact design combines a lookup table with a doubly linked recency order, supporting efficient lookup, promotion, and removal. Maintaining that order also consumes metadata and turns cache hits into state updates. Concurrent implementations must coordinate those changes.

Exact and sampled policies differ

Redis uses approximate LRU: it samples candidates and maintains a pool of good eviction candidates instead of keeping an exact order of every key. The configurable sample count trades additional CPU work for a closer approximation. It does not promise the exact victim sequence of the small model below or universally constant eviction latency.

Candidate eligibility matters too. Redis allkeys-lru can evict any key, while volatile-lru considers keys with expiration metadata. A TTL is not protection against eviction before its deadline. If no eligible expiring keys exist, a volatile policy behaves like noeviction for memory-pressure decisions.

Capacity is not freshness

A limit of three entries is not a limit of three kilobytes. Values, keys, and bookkeeping have different sizes; a count-bounded cache can still retain large objects. Python’s lru_cache retains references to arguments and results until eviction or clearing. Choose a capacity unit that matches the resource you need to control.

Recency also says nothing about whether a source value changed. Frequently reading an obsolete cached answer can keep it resident indefinitely. Expiration, explicit invalidation, and versioned keys address freshness separately. An eviction rule is neither a consistency protocol nor a backup policy.

When it breaks

A scan through one-time entries can displace a useful working set. Cycling through four distinct keys with capacity three can miss on every access, even though those keys are repeatedly requested. Historical popularity does not reserve space under LRU. LFU, admission filtering, or a different capacity may help particular workloads, but no policy follows automatically from “read-heavy.”

Measure hits, misses, evictions, retained bytes, and miss cost over representative intervals. A high hit ratio can hide expensive misses; an eviction counter alone does not reveal whether victims were useful. Reconstruct the access trace before changing policies.

A cache hit must also be safe to reuse. Avoid memoizing side effects or results that require a fresh mutable object on each call. Python’s lru_cache keeps its internal state coherent across threads, but simultaneous misses may still execute the wrapped function more than once. Thread safety is not duplicate-work suppression.

Touch A, then evict B. Source-based mechanism illustration. Model values and source-reported observations are not a new runtime test.

Check it quickly

Save the block as lru_check.py and run python3 lru_check.py with Python 3.10 or newer. It ran with Python 3.14.4. Only the standard library is used: an OrderedDict models exact recency, and the real functools decorator separately verifies memoization. No Redis server, network requests, or filesystem writes are involved.

from collections import OrderedDict
from functools import lru_cache


def access(cache, key, capacity):
 assert capacity > 0
 hit = key in cache
 evicted = None
 if hit:
 cache.move_to_end(key)
 else:
 cache[key] = key.lower()
 if len(cache) > capacity:
 evicted, _ = cache.popitem(last=False)
 return hit, evicted, tuple(cache)


cache = OrderedDict()
observed = [access(cache, key, 3) for key in "ABCAD"]
assert observed == [
 (False, None, ("A",)),
 (False, None, ("A", "B")),
 (False, None, ("A", "B", "C")),
 (True, None, ("B", "C", "A")),
 (False, "B", ("C", "A", "D")),
]
print("ABCAD: touching A makes B the victim; final oldest -> newest:", tuple(cache))

for key in "XYZ":
 access(cache, key, 3)
assert tuple(cache) == ("X", "Y", "Z")
assert access(cache, "A", 3)[0] is False
print("a one-time XYZ scan displaces the old working set")

cache.clear()
hits = sum(access(cache, key, 3)[0] for key in "ABCD" * 3)
assert hits == 0
print("capacity 3, repeated ABCD: 0 hits in 12 accesses")

origin = {"A": 1, "B": 2, "C": 3}
loads = []


@lru_cache(maxsize=2)
def read(key):
 loads.append(key)
 return origin[key]


assert [read(key) for key in "ABACB"] == [1, 2, 1, 3, 2]
assert loads == ["A", "B", "C", "B"]
assert tuple(read.cache_info()) == (1, 4, 2, 2)
print("functools trace:", read.cache_info(), "origin reads:", loads)
origin["B"] = 20
assert read("B") == 2
read.cache_clear()
assert read("B") == 20
assert tuple(read.cache_info()) == (0, 1, 2, 1)
print("a recent cached B stays stale until explicit invalidation")

The first assertion checks every intermediate order, not just the final size: touching A makes B the victim. A subsequent XYZ scan displaces the former working set. The repeated ABCD trace then produces zero hits in twelve accesses with capacity three.

The decorated function reads an in-memory origin mapping. Its ABACB trace records one hit, four misses, and two retained entries; the recorded origin reads identify which calls actually recomputed. Changing the origin’s B from two to twenty leaves the cached result at two until cache_clear runs. Clearing also resets the statistics.

These are deterministic correctness checks, not latency or memory benchmarks. They do not exercise Redis sampling, TTL processing, concurrent misses, byte-based capacity, or a production access distribution. Use the measured trace to understand the policy, then validate the actual cache implementation under its own workload.

Sources

Python functools, LRU memoization, cache statistics, references, invalidation, and concurrent-call limits, checked 2026-09-08.
Python collections, OrderedDict reordering and endpoint removal, checked 2026-09-08.
Redis key eviction, approximate LRU, sampling, and candidate eligibility, checked 2026-09-08.

Consistent hashing shrinks the rebalance

Sun, 19 Sep 2027 00:00:00 +0000

Consistent hashing limits placement changes when membership changes; it does not itself move data, make replicas agree, or distribute a hot key’s requests. In the classic clockwise ring, a key belongs to the first node point at or after its hash position, wrapping to the smallest point when necessary.

Get the ownership interval right

A point owns the interval after its predecessor through itself: (predecessor, point]. With points A at 20, B at 50, and C at 80, B owns positions above 20 through 50. A key beyond 80 wraps to A. This is not the arc from B to its successor.

Adding D at 35 takes positions above 20 through 35 from B, the new point’s clockwise successor. Removing B transfers B’s former interval to C. Unaffected points retain their positions and ownership. That preservation is the useful property; saying “only a small arc moves” is insufficient when an existing arc might already cover a large fraction of the ring.

By contrast, directly choosing node index hash(key) modulo node_count changes the divisor when a node is added. Many keys then choose another index. A balanced ring with four equal-capacity nodes expanded to five would ideally move about one fifth of keys, but exact movement depends on the actual points and key distribution, not a universal percentage.

Virtual nodes spread intervals, not individual keys

Assigning many ring points to each physical node usually reduces imbalance from a few randomly placed points. Each physical node owns several smaller intervals, and adding another can take pieces from multiple neighbors. Weights can allocate different point counts for unequal capacity. More points also cost routing-table memory and maintenance work.

One key still resolves to one physical owner in this primary-placement model. If that key receives most requests, increasing virtual-node count does not split those requests across machines. Even equal key counts do not imply equal bytes, request rates, or processing cost. Replication, read distribution, and hot-key handling require additional policies.

Stability alone also does not imply balance. All participants must agree on membership, persistent node identities, key encoding, hash rules, and point counts. A stable digest helps them reproduce positions, but cannot compensate for different membership views or a skewed workload. Rebuilding every node’s points on each membership change would defeat the placement-preservation property.

Placement is not migration or consistency

A new routing answer does not transfer cached or persistent values to the new owner. A cache may experience misses and an origin-load spike; a persistent store needs a migration and ownership protocol. Clients using old and new rings can disagree during rollout. Recovery and synchronization behavior belongs to the surrounding system.

Real products also choose different algorithms and metadata. Redis Cluster uses fixed hash slots whose ownership is reassigned; it is not this example’s direct node-point ring. Cassandra adds replica placement and token-management rules, while Envoy uses hashing to select upstream hosts. Do not infer one product’s failure guarantees from another product’s placement diagram.

When it breaks

A single point per node can be badly unbalanced, and renaming a node can unexpectedly relocate its points. Changing byte encoding or hash configuration can likewise remap keys without any physical machine joining. Record the mapping inputs as part of deployment configuration and compare ownership before rollout.

Measure moved keys separately from moved bytes and real traffic. Virtual nodes improve statistical placement, not a guaranteed maximum load. During membership churn, budget for migration work or cold-cache demand, and verify how clients learn the new view. A placement experiment is not an availability or data-integrity test.

Only the affected interval moves. Source-based mechanism illustration. Model values and source-reported observations are not a new runtime test.

Check it quickly

Save the following as ring_check.py and run python3 ring_check.py with Python 3.10 or newer. This ran with Python 3.14.4. It uses only the standard library, starts no servers, and performs no network or filesystem writes. SHA-256 and explicit UTF-8 inputs make the generated fixture reproducible.

from bisect import bisect_left
from collections import Counter
from hashlib import sha256


def token(value):
 return int.from_bytes(sha256(value.encode("utf-8")).digest(), "big")


def ring(nodes, copies):
 entries = sorted(
 (token(f"node:{node}:{copy}"), node)
 for node in nodes for copy in range(copies)
 )
 positions, owners = zip(*entries)
 assert len(set(positions)) == len(positions), "fixture token collision"
 return positions, owners


def lookup(layout, position):
 positions, owners = layout
 return owners[bisect_left(positions, position) % len(positions)]


simple = ((20, 50, 80), ("A", "B", "C"))
joined = ((20, 35, 50, 80), ("A", "D", "B", "C"))
removed = ((20, 80), ("A", "C"))
assert [lookup(simple, value) for value in (0, 20, 21, 50, 51, 80, 81)] == [
 "A", "A", "B", "B", "C", "C", "A",
]
for value in range(100):
 assert lookup(joined, value) == ("D" if 20 < value <= 35 else lookup(simple, value))
 assert lookup(removed, value) == ("C" if 20 < value <= 50 else lookup(simple, value))
assert lookup(joined, 35) == "D"
assert lookup(removed, 50) == "C"
print("a point owns (predecessor, point]; lookups wrap clockwise")

nodes = ("A", "B", "C", "D")
positions = [token(f"key:{index}") for index in range(20000)]
base = ring(nodes, 256)
expanded = ring(nodes + ("E",), 256)
contracted = ring(tuple(node for node in nodes if node != "B"), 256)
assert base == ring(tuple(reversed(nodes)), 256)
before = [lookup(base, position) for position in positions]
after_add = [lookup(expanded, position) for position in positions]
after_remove = [lookup(contracted, position) for position in positions]
add_count = sum(old != new for old, new in zip(before, after_add))
remove_count = sum(old != new for old, new in zip(before, after_remove))
assert 0 < add_count < len(positions)
assert add_count == after_add.count("E")
assert all(old == new or new == "E" for old, new in zip(before, after_add))
assert remove_count == before.count("B")
assert all(old == new or old == "B" for old, new in zip(before, after_remove))
modulo_count = sum(
 nodes[position % 4] != (nodes + ("E",))[position % 5]
 for position in positions
)
print(f"add E: {add_count}/20000 keys move ({add_count / 200:.2f}%)")
print(f"remove B: {remove_count}/20000 keys move ({remove_count / 200:.2f}%)")
print(f"modulo 4 -> 5: {modulo_count}/20000 keys move ({modulo_count / 200:.2f}%)")

single = ring(nodes, 1)
for label, layout in (("one point", single), ("256 points", base)):
 counts = Counter(lookup(layout, position) for position in positions)
 print(label, {node: counts[node] for node in nodes})

hot_owner = lookup(base, token("key:hot"))
synthetic_requests = Counter(before)
synthetic_requests[hot_owner] += 100000
assert synthetic_requests[hot_owner] == before.count(hot_owner) + 100000
print("100000 extra requests for one hot key all target", hot_owner)
print("synthetic request counts", dict(sorted(synthetic_requests.items())))

The integer example checks both interval endpoints and wraparound across every position from zero through 99. For 20,000 deterministic keys with 256 points per node, adding E moves 4,023 keys, removing B moves 4,895, and modulo resizing moves 16,013. Assertions also require every addition-related move to end at E and every removal-related move to originate at B.

The printed counts show this fixture’s improved balance with 256 points, not a universal bound. Assigning 100,000 extra synthetic requests to one hot key still directs them all to D. These are calculated placement and demand counts, not measured production requests, transferred bytes, or recovery timings.

Sources

Apache Cassandra’s Dynamo architecture, clockwise ownership, token ranges, and virtual nodes, checked 2026-09-08.
Envoy load-balancing algorithms, ring hashing, stable host identity, weights, and distribution, checked 2026-09-08.
Python hashlib, portable SHA-256 digest construction, checked 2026-09-08.
Redis Cluster specification, fixed slot mapping as a distinct placement design, checked 2026-09-08.

Cache invalidation is a push, not a prayer

Thu, 05 Aug 2027 00:00:00 +0000

Changing an origin does not notify every cache that already holds its response. Invalidation is about controlling which stored copies remain eligible for reuse, not merely updating a file. A reliable release distinguishes expiration, validation, targeted removal, and choosing a new URL. These mechanisms have different scopes, and none remotely erases every copy a reader has downloaded.

Two independent private caches make removal scope visible: changing one entry leaves the other usable. Publishing and requesting a new URL creates a separate entry; it does not erase the old URL or update every reader automatically.

Expiration is not a broadcast

A fresh response can remain usable after its source changes. Freshness is calculated from lifetime and current age, accounting for cache metadata and elapsed time; it is not simply a countdown from one origin Date header. Expiration makes direct reuse conditional on the applicable rules. It neither guarantees physical deletion nor automatically causes an idle cache to contact the origin.

Validators are consulted when a request requires validation, not pushed to clients when content changes. A correct ETag lets the origin confirm an unchanged representation or send its replacement. It cannot force a browser holding a still-fresh response to ask. Changing the origin to no-cache or no-store does not retroactively rewrite previously received caching instructions.

Identify the scope before invalidating

RFC 9111 requires a cache receiving a successful or redirect response to an unsafe method to invalidate the target URI. This affects caches on that request’s path; it is not global notification. Application database writes made through another route do not automatically invalidate every derived page, query variant, translated response, or search listing.

A CDN purge similarly controls the provider’s managed copies, not independent browser caches. Identify the affected host, paths, variants, and cache tags using the provider’s actual contract. Publish the replacement before invalidating, track completion, then compare response bodies as well as cache status. An accepted purge request alone proves neither propagation nor that the origin now serves the desired bytes.

When it breaks

Purging before the origin is updated can immediately repopulate an edge with the old response. An in-flight refill can also race with invalidation; its handling depends on the cache implementation. Repeating a broad purge is not evidence that either race is resolved. Prefer a narrowly identified object set, and account for the additional origin load when those objects become cold.

For static assets, publish a new content-fingerprinted filename before switching HTML or a manifest to reference it. Keep the old asset available while previously cached documents can still reference it. The new URL avoids confusion with the old cache entry, but readers must receive the updated document first. Updating only the asset filename without updating its referring document changes nothing for those readers.

Deletion for confidentiality is a different problem. Removing an origin object or purging a CDN cannot revoke bytes already downloaded, and a cache policy is not authorization. Prevent sensitive responses from entering inappropriate caches in the first place. For an urgent repair, define what “visible” means: a fresh visit, an existing tab, or every previously downloaded copy cannot share one guarantee.

Check it quickly

Use Python 3.10 or newer and a POSIX shell. The tested versions are Python 3.14.4, CacheControl 0.14.4, and Requests 2.34.2. Run the Python block with "$invalidation_lab/venv/bin/python" after installing the pinned dependencies. It starts one loopback HTTP server on an allocated port, uses two separate in-memory private caches, disables environment proxies, and closes its resources. Installation alone needs external network access.

invalidation_lab=$(mktemp -d)
python3 -m venv "$invalidation_lab/venv"
"$invalidation_lab/venv/bin/python" -m pip install CacheControl==0.14.4 requests==2.34.2

from collections import Counter
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Thread

import requests
from cachecontrol import CacheControl
from cachecontrol.cache import DictCache

assets = {"/manual.txt": b"A"}
counts = Counter()


class Origin(BaseHTTPRequestHandler):
 def log_message(self, *_):
 pass

 def do_GET(self):
 counts[self.path] += 1
 body = assets.get(self.path, b"missing")
 status = 200 if self.path in assets else 404
 self.send_response(status)
 self.send_header("Cache-Control", "max-age=600" if status == 200 else "no-store")
 self.send_header("Content-Length", str(len(body)))
 self.end_headers()
 self.wfile.write(body)


server = HTTPServer(("127.0.0.1", 0), Origin)
worker = Thread(target=server.serve_forever)
worker.start()
base = f"http://127.0.0.1:{server.server_port}"
caches = [DictCache(), DictCache()]
clients = []
try:
 for cache in caches:
 client = CacheControl(requests.Session(), cache=cache)
 client.trust_env = False
 clients.append(client)

 def check(index, path, status, body, cached):
 response = clients[index].get(base + path, timeout=3)
 assert (response.status_code, response.content, response.from_cache) == (
 status, body, cached
 )

 for index in range(2):
 check(index, "/manual.txt", 200, b"A", False)
 check(index, "/manual.txt", 200, b"A", True)
 assert counts["/manual.txt"] == 2
 print("warm: two independent caches hold A; origin requests=2")

 assets["/manual.txt"] = b"B"
 caches[0].delete(base + "/manual.txt")
 check(0, "/manual.txt", 200, b"B", False)
 check(1, "/manual.txt", 200, b"A", True)
 assert counts["/manual.txt"] == 3
 print("targeted invalidation: cache 0=B; cache 1=A")

 check(1, "/manual.v2.txt", 404, b"missing", False)
 assets["/manual.v2.txt"] = b"B"
 for index in range(2):
 check(index, "/manual.v2.txt", 200, b"B", False)
 check(index, "/manual.v2.txt", 200, b"B", True)
 assert counts["/manual.v2.txt"] == 3
 check(1, "/manual.txt", 200, b"A", True)
 print("new URL: 404 before publication, then both caches=B")
 print("old URL: cache 1 still holds A")
finally:
 for client in clients:
 client.close()
 server.shutdown()
 worker.join()
 server.server_close()

Both clients first receive A from the origin, then hit their own cache. After the origin changes to B, deleting only cache zero’s exact URL makes that client retrieve B; cache one still returns A without another origin request. The old URL has reached the origin three times, demonstrating scoped removal rather than global convergence.

The new filename initially returns 404 with no-store, exposing incorrect publication order. CacheControl 0.14.4 also excludes 404 from its default cacheable statuses, so this fixture does not isolate no-store’s effect on negative caching. After publication, both clients obtain and cache B under that new URL; cache one still retains A at the original URL. This is a real HTTP and cache-storage experiment, not a CDN purge implementation or browser test. CacheControl is a private-cache library and must not be repurposed as a multi-user shared edge.

Sources

RFC 9111: invalidating stored responses, invalidation scope and unsafe methods, checked 2026-09-07.
CloudFront: invalidation and versioned filenames, edge removal does not clear independent caches, checked 2026-09-07.
CacheControl usage, sessions and separate cache stores, checked 2026-09-07.
CacheControl security model, private-cache restrictions, checked 2026-09-07.
CacheControl 0.14.4 controller, default cacheable statuses and storage checks, checked 2026-10-18.

A read-through cache loads on a miss by itself

Wed, 26 May 2027 00:00:00 +0000

Read-through caching gives callers one reading interface: a hit returns a stored value, while a miss invokes a loader and stores its result. The important boundary is who owns that loader. Moving it behind the cache interface can remove duplicated lookup logic, but does not automatically solve concurrency, writes, authorization, or consistency between independent copies.

Identify the loading layer

In cache-aside, application code explicitly checks the cache, queries the source on a miss, and fills the cache. With read-through, the caching component owns that miss path. A library can provide this interface inside an application, or a service can provide it remotely. Those deployment choices still determine which processes need updating when loader behavior changes.

A Redis GET alone is not a read-through loader. For a missing string key it returns nil; it does not discover and query your database. A client library, caching service, or application adapter must supply the loading behavior. The exercise below uses a memoizing function wrapper as that interface, not Redis, and keeps the source as an in-memory fixture.

Loading does not define writing

Read-through says nothing about where writes go. Write-through is a separate arrangement, and even a shared read/write component must define what happens when source updates and cache updates fail independently. Writers that bypass it can leave cached values unchanged. Identify all real update paths instead of assuming the pattern makes every writer participate.

TTL restricts reuse of a particular cached entry; it does not guarantee that a later reload obtains current truth from a lagging replica or buggy loader. Nor does expiration necessarily remove bytes from memory immediately. Choose lifetimes from actual data requirements. A short TTL on user-specific data is not permission isolation, and a high hit ratio cannot establish correctness.

When it breaks

An absent record and an unavailable source are different results. Caching a legitimate absence can reduce repeated misses, but can also hide a record created afterward until expiry or invalidation. Converting a timeout into an empty successful result can therefore create a poisoned entry. Decide which outcomes are cacheable and how callers distinguish absence from failure.

Concurrent loading is another independent contract. Cachetools documents that a lock protects cache access while the wrapped function executes outside it; a lock alone does not suppress duplicate loading. Its condition option addresses same-key concurrent execution. The single-threaded exercise deliberately uses neither and must not be treated as a thread-safe or distributed implementation.

Invalidation can race with a load already reading an older source version. Removing a key does not inherently prevent that pending result from being inserted later. Select coordination appropriate to the real writer and loader protocol, and test their ordering. Avoid broad key-pattern deletion as a default response: it creates cold entries without proving that the underlying defect is fixed.

Historical exact cachetools evidence covers a single-threaded wrapper and manual clock. Loader paths, cached absence and raised errors are distinct; concurrency and distributed consistency were not tested.

Check it quickly

Use Python 3.10+ with assertions enabled, without -O or PYTHONOPTIMIZE: assertions contain required calls. Retained exact-fence records report Python 3.12.14 and cachetools 7.1.8 passing; this review did not rerun them. Install the pinned dependency, then use "$readthrough_lab/venv/bin/python". The library provides storage, expiry and memoization; a manual test clock avoids sleeping or changing system time. No Redis or external database is contacted.

readthrough_lab=$(mktemp -d)
python3 -m venv "$readthrough_lab/venv"
"$readthrough_lab/venv/bin/python" -m pip install cachetools==7.1.8

from collections import Counter

from cachetools import TTLCache, cached

clock = [0]
cache = TTLCache(maxsize=8, ttl=10, timer=lambda: clock[0])
source = {"tea": 100}
failures = set()
loads = Counter()


@cached(cache=cache, info=True)
def price(sku):
 loads[sku] += 1
 if sku in failures:
 raise OSError("source unavailable")
 return source.get(sku)


assert price("tea") == price("tea") == 100
assert loads["tea"] == 1
source["tea"] = 120
clock[0] = 9
assert price("tea") == 100 and loads["tea"] == 1
clock[0] = 10
assert price("tea") == 120 and loads["tea"] == 2
print("hit does not extend TTL: old value at t=9; reload at t=10")

source["tea"] = 130
cache.pop(price.cache_key("tea"))
assert price("tea") == 130 and loads["tea"] == 3
print("explicit eviction: next read loads the updated source")

assert price("coffee") is None
source["coffee"] = 200
assert price("coffee") is None and loads["coffee"] == 1
cache.pop(price.cache_key("coffee"))
assert price("coffee") == 200 and loads["coffee"] == 2
print("None is cached: newly created data needs expiry or invalidation")

cache.pop(price.cache_key("tea"))
failures.add("tea")
for _ in range(2):
 try:
 price("tea")
 except OSError:
 pass
 else:
 raise AssertionError("failure was hidden")
assert loads["tea"] == 5
assert price.cache_key("tea") not in cache
failures.remove("tea")
assert price("tea") == price("tea") == 130
assert loads["tea"] == 6
print("exceptions are not cached: two failed loads, then one recovery load")
print(price.cache_info())

The first two reads execute one loader. Changing the source does not change the still-live cached price: it remains 100 at time nine. At time ten the entry expires, and the wrapper loads 120. This checks expiration after insertion, not sliding expiration after access. Explicitly removing the wrapper’s actual cache key then exposes the next source update, 130.

The missing coffee price is cached as None. Creating the source record alone does not replace that cached absence; explicit removal allows a subsequent load of 200. Two raised source errors each invoke the loader and leave no cached tea entry. After recovery, one successful load supplies two reads. The retained output reports four hits and eight misses, including failed loads; these statistics are printed, not separately asserted.

These assertions prove this wrapper’s observed miss, expiry, absence, and error behavior. They do not prove atomic writes, concurrent miss suppression, eviction under memory pressure, or distributed consistency. For a real service, record loader counts and outcomes alongside cache statistics; two faster HTTP requests or global Redis hit counters cannot identify which application loader actually ran.

Sources

Cachetools documentation, TTLCache, cached, synchronization options, and exception handling, checked 2026-09-07.
Redis GET, missing keys return nil rather than loading another data source, checked 2026-09-07.
AWS Builders’ Library: caching challenges and strategies, cold caches, negative caching, and source-load risks, checked 2026-09-07.
Cachetools 7.1.8, version-matched TTL, synchronization and exception contracts, checked 2026-10-18.
Python assert, optimization removes assertion evaluation, checked 2026-10-18.

Stale cache needs a bounded policy

Mon, 01 Feb 2027 00:00:00 +0000

A stale response can preserve access to a public manual during an origin outage. It can also preserve an obsolete price, revoked permission, or misleading status. Availability is not automatically more important than correctness. Choose the information that may remain usable, the conditions that permit reuse, and the maximum tolerable age before enabling this behavior.

The historical Node/http-cache-semantics fixture checks a bounded policy and caller-selected bytes using synthetic responses. Age 35 and 89 allow eligible-error reuse; 91 does not. Failures never restart the window. The offline pass is not a real-network or outage test, and no new execution occurred.

The trade is availability over freshness

Expiration and eviction are different events. An expired response can remain stored for conditional validation or permitted stale delivery. But a cold or evicted cache has no old body to return. Stale directives cannot create one, and retaining bytes does not by itself authorize reuse. The selected response must still match the request, including relevant Vary dimensions and any access boundary.

How it is signaled

Stale-while-revalidate permits a bounded stale response while validation is attempted without blocking that response. Stale-if-error instead permits using a stale response when the attempted origin interaction encounters an eligible error. These are different triggers. Neither extension mandates storage or guarantees that every cache implements the feature. A response arriving after the allowed window cannot rely on the earlier permission indefinitely.

For max-age=30, stale-if-error=60, the extra sixty seconds begin after freshness ends, not after each failed attempt. The response can be a candidate for error-time reuse for roughly ninety seconds of total age. RFC 5861 identifies errors that would produce 500, 502, 503, or 504. Authentication failures and missing resources must not casually be relabeled as availability failures to hide them behind an old success response.

A successful conditional validation need not download a replacement body. A 304 can update the stored response using its validation metadata while retaining the representation bytes. Log that outcome separately from a replacement 200 and an error-time stale hit; all three can deliver the same-looking page for different reasons.

When it breaks

Resetting Age after every failed revalidation turns a bounded exception into unlimited stale delivery. So does replacing the entry’s stored timestamp while keeping the old body. Preserve age on failure; only a legitimate new response or successful validation supplies the basis for updating freshness. Background validation is usually demand-triggered, so an idle cache does not necessarily refresh itself before traffic returns.

Read-only or idempotent does not mean safe to serve stale. A GET can reveal permissions or prices whose age matters. RFC 9111 prohibits stale reuse when an applicable directive such as no-cache or must-revalidate forbids it. Avoid contradictory policies and test the deployed cache’s treatment of restrictions. The old Warning-field advice in RFC 5861 is superseded by RFC 9111, which obsoletes that field.

Observe stale responses separately from fresh hits. Record total age, the failure category, and whether validation succeeded without logging secrets. A healthy HTTP success rate can conceal a failing origin if every response is old. Recovery requires verifying actual replacement or successful validation, not merely noticing that the origin process has started again.

Check it quickly

Use Node.js and npm. The retained historical result reports Node 24.19.0 and http-cache-semantics 4.2.0; this revision does not rerun it. Install the pinned package, then execute the JavaScript with NODE_PATH="$stale_lab/node_modules" node. This is a deterministic policy-and-body-selection experiment with synthetic responses and a controlled clock. It makes no requests and causes no outage; only installation needs network access.

stale_lab=$(mktemp -d)
npm install --prefix "$stale_lab" --ignore-scripts --no-audit --no-fund --package-lock=false http-cache-semantics@4.2.0

const assert = require("node:assert/strict");
const CachePolicy = require("http-cache-semantics");

const start = Date.parse("2026-09-07T00:00:00Z");
let clock = start;
class TestPolicy extends CachePolicy {
 now() { return clock; }
}
const request = { url: "https://example.test/manual", method: "GET", headers: {} };
const policy = new TestPolicy(request, { status: 200, headers: {
 "cache-control": "public, max-age=30, stale-if-error=60",
 etag: '"revision-a"', age: "0",
} });
const oldBody = Buffer.from("manual revision A");
clock = start + 35000;
const decision = policy.evaluateRequest(request);
assert.equal(decision.response, undefined);
assert.equal(decision.revalidation.synchronous, true);
assert.equal(decision.revalidation.headers["if-none-match"], '"revision-a"');
console.log("age 35: validate before using stale-if-error");

for (const status of [500, 502, 503, 504]) {
 const result = policy.revalidatedPolicy(request, { status, headers: { "cache-control": "no-store" } });
 assert.equal(result.modified, false);
 assert.equal(result.policy, policy);
 assert.equal(result.policy.responseHeaders().age, "35");
 const body = result.modified ? Buffer.from("origin error") : oldBody;
 assert.equal(body.toString(), "manual revision A");
 console.log(status, "uses old body without resetting Age");
}
const denied = policy.revalidatedPolicy(request, { status: 403, headers: { "cache-control": "no-store" } });
assert.equal(denied.modified, true);
assert.equal(denied.policy.storable(), false);
console.log("403 does not use the stale success response");

clock = start + 89000;
assert.equal(policy.revalidatedPolicy(request, { status: 503, headers: {} }).modified, false);
clock = start + 91000;
const expired = policy.revalidatedPolicy(request, { status: 503, headers: { "cache-control": "no-store" } });
assert.equal(expired.modified, true);
assert.equal(expired.policy.storable(), false);
console.log("age 89: stale allowed; age 91: error must be surfaced");

const recovered = policy.revalidatedPolicy(request, { status: 200, headers: {
 "cache-control": "public, max-age=30, stale-if-error=60",
 etag: '"revision-b"', age: "0",
} });
assert.equal(recovered.modified, true);
assert.equal(recovered.policy.age(), 0);
assert.equal(recovered.policy.satisfiesWithoutRevalidation(request), true);
const newBody = Buffer.from("manual revision B");
const delivered = recovered.modified ? newBody : oldBody;
assert.equal(delivered.toString(), "manual revision B");
console.log("recovery 200: replace the body and start the new policy");

At age thirty-five the normal decision requires synchronous validation; stale-if-error alone does not authorize an immediate stale hit. Each eligible simulated error then keeps revision A and its original policy. Outgoing Age remains thirty-five rather than resetting to zero. The 403 branch does not reuse that success body and its no-store response is ineligible for storage.

The same old entry survives an eligible error at age eighty-nine but not ninety-one. Repeated failures have not extended the window. A subsequent successful 200 with revision B produces a fresh policy and selects the new body. The fixture verifies both metadata decisions and which bytes the caller retains or replaces.

The library does not fetch, retry, schedule background work, or retain bodies for the caller. These assertions cover one matching warm entry and this nonconflicting policy, not network timeout handling, all directive combinations, or a complete CDN. Deployment acceptance still needs cold-cache, exhausted-window, and recovery tests through the real path, alongside evidence that stale delivery stays within the resource’s correctness requirements.

Sources

RFC 5861: stale controls, extension windows and eligible error statuses, checked 2026-09-07.
RFC 9111: serving stale responses, restrictions on stale reuse, checked 2026-09-07.
http-cache-semantics 4.2.0, revalidation decisions and caller-owned body storage, checked 2026-09-07.

Immutable assets and fingerprints

Wed, 25 Nov 2026 00:00:00 +0000

A fingerprinted asset puts a digest of its bytes into its URL. Changing a stylesheet produces a different address, so a page can request the new representation without depending on every existing cache expiring simultaneously. The useful guarantee comes from the publishing process: once an address is released, its contents must remain consistent with that digest.

Publish a new digest URL for changed bytes, expose the new HTML references only after its files are available, and retain older referenced files. Overwriting an old URL can split old and new clients. Filename hashes are not browser integrity checks; no example was rerun for this illustration.

Names support a freshness contract

A build can calculate SHA-256 for each generated file and rewrite the HTML references from logical names to those addresses. Unchanged bytes retain their name; changed bytes normally produce a different name. A short digest introduces additional collision risk, so choose its length deliberately. Browsers do not recalculate a filename’s hash as an integrity check. HTTP cache keys also include request context and potentially Vary fields; naming a file does not replace HTTP caching rules.

For public fingerprinted assets, Cache-Control: public, max-age=31536000, immutable combines a freshness lifetime with a promise that the representation will not change during that lifetime. RFC 8246 discourages unnecessary conditional requests while it remains fresh. Expiration, eviction, user overrides, and unsupported directives still exist. The RFC recommends ignoring immutable outside an authenticated context such as HTTPS. Neither permanent storage nor unlimited trust follows from this header.

HTML needs a separate policy because it selects the current asset names. A short lifetime or suitable revalidation can expose a new release while old assets remain available. Publish referenced files before exposing their manifest or HTML. Retain earlier assets long enough for old pages and rollback references to work. Fingerprinting does not make a collection of files an atomic release.

The public directive is appropriate only for representations that may be shared. A personalized download does not become suitable for shared caching because its filename contains a digest. Authorization and confidentiality requirements still determine its response policy.

When it breaks

Overwriting an old fingerprinted path creates two incompatible realities: an existing browser may reuse its cached red stylesheet while a fresh client retrieves blue bytes at the same address. Purging one CDN cannot remove every private browser copy. A deployment check should compare actual artifact bytes with their recorded digest and reject this mutation before release.

Deleting old assets immediately causes another failure. A cached page can still reference yesterday’s script, and a rollback can restore HTML whose dependencies no longer exist. Keeping the source commit alone does not preserve these artifacts. Likewise, publishing HTML before its new files reach every serving location introduces transient missing resources despite correct hashes.

Check it quickly

Save the following as immutable.py and run python3 immutable.py with Python 3. It starts a loopback server, verifies the CSS digest and cache header, deliberately changes bytes behind the old URL, detects the mismatch, restores the original, and shuts down. Expect three successful contract flags and browser_cache_tested_by_cli false. This command checks real HTTP responses; it does not implement a browser cache.

from hashlib import sha256
from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Event, Lock, Thread
from urllib.parse import urlsplit
import json
import sys

styles = {'one': b'body{background:rgb(127,29,29);color:white;font-family:sans-serif;margin:3rem}',
 'two': b'body{background:rgb(30,64,175);color:white;font-family:sans-serif;margin:3rem}'}
paths = {name: '/assets/' + sha256(data).hexdigest() + '.css' for name, data in styles.items()}
state = {'tampered': False, 'requests': []}
lock = Lock()


class Handler(BaseHTTPRequestHandler):
 def do_POST(self):
 if self.path not in ('/tamper', '/restore'):
 self.send_error(404)
 return
 with lock:
 state['tampered'] = self.path == '/tamper'
 self.send_response(204)
 self.end_headers()

 def do_GET(self):
 path = urlsplit(self.path).path
 cache = 'no-store'
 if path in ('/one', '/two'):
 name = path[1:]
 data = f'<!doctype html><html><head><meta name="viewport" content="width=device-width,initial-scale=1"><title>Immutable asset lab</title><link rel="icon" href="data:,"><link rel="stylesheet" href="{paths[name]}"></head><body><h1>Release {name}</h1><p>The background comes from the referenced CSS artifact.</p></body></html>'.encode()
 kind = 'text/html; charset=utf-8'
 elif path in paths.values():
 with lock:
 state['requests'].append(path)
 data = styles['two'] if path == paths['two'] or state['tampered'] else styles['one']
 kind, cache = 'text/css', 'public, max-age=31536000, immutable'
 elif path == '/events':
 with lock:
 data = json.dumps(state).encode()
 kind = 'application/json'
 else:
 self.send_error(404)
 return
 self.send_response(200)
 self.send_header('Content-Type', kind)
 self.send_header('Cache-Control', cache)
 self.send_header('Content-Length', str(len(data)))
 self.end_headers()
 self.wfile.write(data)

 def log_message(self, *args):
 pass


server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
thread = Thread(target=server.serve_forever)
thread.start()
try:
 origin = f'http://127.0.0.1:{server.server_port}'
 if '--serve' in sys.argv:
 print(json.dumps({'origin': origin, 'assets': paths}), flush=True)
 try:
 Event().wait()
 except KeyboardInterrupt:
 pass
 else:
 def request(method, path):
 connection = HTTPConnection('127.0.0.1', server.server_port, timeout=5)
 try:
 connection.request(method, path)
 response = connection.getresponse()
 return response.status, response.getheader('Cache-Control'), response.read()
 finally:
 connection.close()

 status, cache, original = request('GET', paths['one'])
 assert status == 200 and cache == 'public, max-age=31536000, immutable'
 assert sha256(original).hexdigest() in paths['one']
 assert request('POST', '/tamper')[0] == 204
 changed = request('GET', paths['one'])[2]
 assert sha256(changed).hexdigest() not in paths['one']
 assert request('GET', paths['two'])[2] == styles['two']
 assert request('POST', '/restore')[0] == 204
 assert request('GET', paths['one'])[2] == original
 print(json.dumps({'hash_name_contract_checked': True,
 'changed_old_url_detected': True, 'original_restored': True,
 'browser_cache_tested_by_cli': False}))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

For the separate browser experiment, run python3 immutable.py --serve and copy the printed origin into a terminal variable named ASSET_ORIGIN. With a fresh browser profile and normal caching enabled, visit its /one page. Then run curl -X POST "$ASSET_ORIGIN/tamper", navigate to /one?after=mutation, and finally visit /two. Inspect /events to count asset requests. Stop the server with Ctrl-C when finished.

In Chrome 152.0.7977.83, the initial page was red. After mutation, the second navigation stayed red and the old stylesheet had only one server request. The new fingerprinted URL produced blue and one request for the second stylesheet. This demonstrates cache separation and the danger of rewriting fresh resources. Ordinary max-age freshness is sufficient for the observed reuse; the experiment does not isolate immutable’s effect on reload validation, test HTTPS, or prove behavior across browsers. A previously cached new URL may also be reused, so a changed reference does not guarantee a network transfer every time.

Sources

RFC 8246: HTTP Immutable Responses, freshness lifetime and authenticated-context guidance, checked 2026-09-13.
MDN: HTTP caching, versioned URLs, cache freshness and validation, checked 2026-09-13.

The Age header tells how long a cached copy has been around

Fri, 06 Nov 2026 00:00:00 +0000

Age is an estimate of elapsed seconds since an origin generated or successfully validated a response. It includes time in caches and in transit. It is not the object’s creation timestamp, a count of requests, or simply the time spent on the last proxy’s disk. Reading it correctly requires the response’s freshness policy and the request context.

Take the larger receipt estimate, then add local residence. Freshness is a strict age comparison, not permission to reuse.

Combine estimates without counting time twice

RFC 9111 defines two age estimates at receipt. Apparent age compares the receiving cache’s clock with Date, clamping a negative result to zero. Corrected age starts with the received Age value and adds the interval between sending the request and receiving the response. A missing Age supplies zero to this calculation; it does not erase the Date-based estimate.

The RFC permits using corrected age alone where the cache chain supports the relevant HTTP behavior. Its more conservative calculation takes the maximum of apparent age and corrected age, then adds local residence time. The exercise uses that conservative option. Adding both estimates would count overlapping time twice, while resetting Age to zero at every cache hop would lose upstream history.

Receipt time, request time, and elapsed residence must be measured consistently. Date comparison also depends on clock synchronization, so the result remains an estimate rather than an exact stopwatch measurement. Production implementations need appropriate clock handling and integer serialization. The small calculation below uses fixed whole-second UTC timestamps and valid header values, not a complete HTTP cache implementation.

Freshness is a separate decision

A current age of 45 seconds is fresh under a 60-second lifetime, but stale under a 30-second lifetime. Equality is already stale: freshness requires age to be less than the lifetime. This comparison does not independently authorize reuse. Request restrictions, cache keys, Vary, storage rules, and directives requiring validation still matter even for a young response.

For a shared cache, s-maxage overrides max-age; its value can shorten or lengthen the applicable lifetime. Stale-while-revalidate does not make an old response fresh. It permits specified stale reuse while validation happens, subject to the policy and implementation. Treat allowed stale service as a distinct state, rather than extending the freshness label until every grace period is exhausted.

When it breaks

A large Age is not automatically evidence of a broken deployment. A year-lived, fingerprinted asset can be old and still fresh. An unchanged representation can also be successfully validated later, refreshing its metadata without replacing its bytes. Age then describes the newer validation history, not necessarily the time when those bytes were first authored.

Nor must Age increase monotonically across every request to one URL. Requests may reach different edge locations, select different representations, encounter an eviction, or follow successful revalidation. Age zero can occur for a newly cached response, and an absent header alone does not establish that the origin answered directly. Compare matching requests, body identity, validators, Date, policy, and provider diagnostics together.

If a response is incorrectly reused, first distinguish wrong identity from wrong lifetime. A perfect age calculation cannot repair a currency or authorization value omitted from the cache key. Likewise, shortening origin max-age does not retroactively inform already-fresh copies. Inspect the headers on the actual GET path; a HEAD probe can have different implementation behavior and does not show which body was delivered.

Check it quickly

Run this block with Python 3.11 or newer; it was executed with Python 3.14.4. It needs only the standard library. HTTP dates are parsed and formatted by email.utils, and all timestamps are synthetic. No network requests are made, no system clock changes are needed, and no sleeping is involved. The input timestamps are ordered and the Age inputs are valid nonnegative integers.

from datetime import timedelta
from email.utils import format_datetime, parsedate_to_datetime

base = parsedate_to_datetime("Thu, 01 Jan 2026 00:00:00 GMT")


def at(seconds):
 return base + timedelta(seconds=seconds)


def current_age(headers, request_time, response_time, now):
 date_value = parsedate_to_datetime(headers["Date"])
 age_value = int(headers.get("Age", "0"))
 assert request_time <= response_time <= now and age_value >= 0
 apparent_age = max(0, (response_time - date_value).total_seconds())
 response_delay = (response_time - request_time).total_seconds()
 corrected_age_value = age_value + response_delay
 corrected_initial_age = max(apparent_age, corrected_age_value)
 resident_time = (now - response_time).total_seconds()
 return corrected_initial_age + resident_time


def headers(date_seconds, age=None):
 result = {"Date": format_datetime(at(date_seconds), usegmt=True)}
 if age is not None:
 result["Age"] = str(age)
 return result


cases = [
 ("Date estimate dominates", headers(0, 5), 10, 12, 20, 20),
 ("upstream Age dominates", headers(0, 50), 10, 12, 20, 60),
 ("future Date is clamped", headers(30, 5), 10, 12, 20, 15),
 ("Age absent means zero input", headers(0), 10, 12, 20, 20),
 ("after modeled validation", headers(100, 0), 100, 102, 105, 5),
]
for name, fields, sent, received, now, expected in cases:
 age = current_age(fields, at(sent), at(received), at(now))
 assert age == expected
 print(f"{name}: {age:g} seconds")

freshness_lifetime = 60
assert 45 < freshness_lifetime
assert not 60 < freshness_lifetime
print("lifetime=60: age 45 is fresh; age 60 is stale")

With receipt at second twelve and inspection at second twenty, the first case returns twenty, not twenty-seven: the Date-based and corrected estimates overlap. Raising upstream Age to fifty produces sixty after request delay and residence are included. A future Date contributes zero apparent age, but the upstream age and elapsed intervals still produce fifteen.

The missing-Age case still obtains twenty from Date. The modeled successful validation uses new response metadata and yields five, rather than the 105 seconds since the earlier generation timestamp. Finally, the lifetime assertions distinguish fresh age 45 from stale age 60. These results verify the stated arithmetic and boundary, not a particular browser’s or CDN’s header generation, routing, or malformed-field handling.

Sources

RFC 9111: calculating age, independent estimates, response delay, residence, and conservative correction, checked 2026-09-07.
MDN: Age, header syntax and nonnegative seconds, checked 2026-09-07.

Cache-Control private versus shared

Fri, 23 Oct 2026 00:00:00 +0000

Storage scope is not an identity system. Cache-Control: private tells a conforming shared cache not to store a response; it does not teach a browser which application account owns the bytes. This distinction matters when a person logs out, another account logs in, and the same browser requests the same URL again.

The article’s fresh-response fixture separates storage eligibility from reuse without validation. A second boundary shows why a private cache can still match an old account response. Header matching does not establish current authorization.

Not all cacheable should be shared

An unqualified private directive permits storage by a single-user cache, subject to other caching requirements. Browsers are a common example, not the only implementation. public explicitly permits caching in circumstances that might otherwise prohibit it, including some responses to authorized requests. Public is not required on every already-cacheable response, and it never means that every possible cache must store the response.

The unqualified forms of no-cache and no-store answer different questions. No-cache allows storage but requires successful validation before reuse. No-store prohibits HTTP cache storage and subsequent reuse, for both shared and private caches. Neither is encryption, an access-control check, or a guarantee that application logs and previously saved copies have disappeared. This article uses unqualified directives, not the less widely implemented forms listing individual field names.

Freshness is separate again. A five-second shared lifetime still permits five seconds of incorrect disclosure if the wrong person’s response is stored under a shared key. Shortening max-age cannot repair an identity boundary. Conversely, s-maxage controls shared-cache freshness only; it is not a synonym for private.

When it breaks

Cookies do not automatically prohibit shared caching under HTTP’s general rules. Authorization has specific shared-cache restrictions, but directives such as public can explicitly permit storage. Adding public to improve a hit ratio can therefore undo a protection the application was relying on. Review the actual response body and authentication path before changing that directive.

Vary refines request matching; it does not grant permission to store. Adding Vary: Cookie cannot make a private response eligible for a shared cache. Within a private cache it can distinguish differing Cookie fields, but that is still field matching, not an authorization decision. A token that remains unchanged while permissions change illustrates why matching headers alone cannot establish current access rights.

For sensitive account data, select an explicit response policy and test account transitions. Include logout, switching accounts in one browser profile, and changes in permissions. Keep actual secrets out of diagnostic captures. An origin header inspection alone cannot prove that every proxy on the deployed path honored the policy.

Check it quickly

Use Node.js and npm; this experiment was run with Node 26.0.0 and http-cache-semantics 4.2.0. Install the pinned policy library in a temporary directory, then execute the JavaScript block with NODE_PATH="$cache_lab/node_modules" node. Installation needs the network; the fixture itself makes no requests and contains only invented cookie and authorization values.

cache_lab=$(mktemp -d)
npm install --prefix "$cache_lab" --ignore-scripts --no-audit --no-fund --package-lock=false http-cache-semantics@4.2.0

const assert = require("node:assert/strict");
const CachePolicy = require("http-cache-semantics");

const request = {
 url: "https://example.test/account",
 method: "GET",
 headers: { cookie: "account=alpha" },
};
const cases = [
 ["private, max-age=300", [false, false], [true, true]],
 ["public, max-age=300", [true, true], [true, true]],
 ["no-cache, max-age=300", [true, false], [true, false]],
 ["no-store, max-age=300", [false, false], [false, false]],
];
for (const [directive, sharedResult, privateResult] of cases) {
 for (const shared of [true, false]) {
 const policy = new CachePolicy(request, {
 status: 200,
 headers: { "cache-control": directive },
 }, { shared });
 const result = [policy.storable(),
 policy.storable() && policy.satisfiesWithoutRevalidation(request)];
 assert.deepEqual(result, shared ? sharedResult : privateResult);
 console.log(shared ? "shared" : "private", directive, result);
 }
}

const authorized = { ...request, headers: { authorization: "Bearer example" } };
for (const [directive, expected] of [
 ["max-age=300", false], ["public, max-age=300", true],
]) {
 const policy = new CachePolicy(authorized, {
 headers: { "cache-control": directive },
 }, { shared: true });
 assert.equal(policy.storable(), expected);
 console.log("authorized shared:", directive, expected);
}

const otherAccount = { ...request, headers: { cookie: "account=beta" } };
for (const vary of [false, true]) {
 const headers = { "cache-control": "private, max-age=300" };
 if (vary) headers.vary = "Cookie";
 const policy = new CachePolicy(request, { headers }, { shared: false });
 assert.equal(policy.satisfiesWithoutRevalidation(otherAccount), !vary);
 console.log("different cookie, Vary enabled:", vary, "reuse:", !vary);
}

Each result pair means storage eligibility followed by reuse without validation. Private yields false/false in shared mode and true/true in private mode. Public yields true/true in both. No-cache yields true/false, while no-store yields false/false. The storage check deliberately comes first: callers must not insert forbidden entries into a cache and rely on a later lookup to repair that mistake.

The Authorization checks show the explicit public opt-in changing shared storage eligibility from false to true. They do not establish that any real personalized response is safe to share. Finally, changing the synthetic cookie still matches the private entry without Vary, but stops matching with Vary. That is the concrete counterexample to treating private as account isolation.

This is a policy-library experiment, not a browser, CDN, or logout implementation. Production evidence still needs two distinct accounts, observable origin requests, and body assertions through the real delivery path. Choose that acceptance test before tuning freshness or measuring the hit ratio.

Sources

RFC 9111: response cache directives, storage scope, authorization exceptions, and qualified directives, checked 2026-09-07.
MDN: Cache-Control, private, public, no-cache, and no-store, checked 2026-09-07.
http-cache-semantics 4.2.0, shared/private options, storage checks, and request matching, checked 2026-09-07.

Negative DNS answers preserve absence until their cache lifetime expires

Thu, 22 Oct 2026 00:00:00 +0000

DNS can return useful information by saying that data is absent. NXDOMAIN reports a name error; NODATA describes a successful response without the requested record type. In a direct query without aliases, these distinguish a nonexistent name from an existing name that lacks the requested data. Caching those results avoids repeating the same unsuccessful upstream lookup for every client request.

Classify the response before interpreting its cache. The source’s SOA TTL/MINIMUM pairs 8/4 and 2/9 yield four and two seconds. Existing negative entries can outlive authoritative publication. SERVFAIL, timeout and validation failure use different failure-caching rules. The historical resolver example was not rerun.

When it breaks

A deployment can create a correct record and still appear broken to clients whose resolver previously cached its absence. The authority returns the new data, while the cache continues returning the earlier negative result until its lifetime ends. Repeatedly recreating the record does not invalidate that remote cache. This is especially visible when applications query a planned hostname before provisioning completes.

An empty answer section alone is not enough to classify a DNS result. Examine the response code, authority section, and any alias chain. A referral is different from an authoritative negative answer, and an NXDOMAIN can concern a terminal CNAME target rather than the originally requested alias. Reporting every empty result as “the domain does not exist” can send investigation toward the wrong record.

For authoritative NXDOMAIN and NODATA covered by RFC 2308, negative lifetime comes from the smaller of SOA.MINIMUM and the SOA record’s TTL. That value is carried on the SOA in the negative response and aged by caches. The MINIMUM field is not a universal floor for all positive record TTLs, and changing only a future positive record’s TTL does not shorten an already cached absence.

Check it quickly

The historical resolver integration remains unrerun. This review preserves its existing Docker/listener hold; no new environment or listener test was attempted.

Save this as check-negative-dns.py and run python3 check-negative-dns.py with Docker. The pinned environment uses BIND 9.18.49 and dnsmasq 2.90 on isolated loopback networking. The first zone has SOA TTL 8, SOA minimum 4, and one existing A record. The example checks actual responses and authoritative query counts before and after creating the missing data:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid
recipe='FROM python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84\nRUN apt-get update && apt-get install -y --no-install-recommends bind9=1:9.18.49-1~deb12u2 bind9-dnsutils=1:9.18.49-1~deb12u2 dnsmasq-base=2.90-4~deb12u2 python3-dnspython=2.3.0-1 && rm -rf /var/lib/apt/lists/*\nCMD ["/usr/bin/python3"]\n'
program=r"""
from contextlib import ExitStack,contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import json,re,signal,subprocess,time
import dns.exception,dns.message,dns.query,dns.rcode,dns.rdatatype

def run(*args,check=True):
 result=subprocess.run(args,capture_output=True,text=True,timeout=15)
 if check:assert result.returncode==0,(args,result.returncode,result.stdout,result.stderr)
 return result
def query(name,kind='A',port=1053):
 return dns.query.udp(dns.message.make_query(name,kind),'127.0.0.1',port=port,timeout=1)
def values(response,kind='A'):
 wanted=dns.rdatatype.from_text(kind)
 return [item.to_text() for rrset in response.answer if rrset.rdtype==wanted for item in rrset]
def show(response):
 def section(records):return [{'name':str(rr.name),'type':dns.rdatatype.to_text(rr.rdtype),'ttl':rr.ttl,'data':[item.to_text() for item in rr]} for rr in records]
 return {'rcode':dns.rcode.to_text(response.rcode()),'answer':section(response.answer),'authority':section(response.authority)}
def wait(predicate,timeout=15):
 deadline=time.monotonic()+timeout
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except (OSError,dns.exception.Timeout):pass
 time.sleep(.05)
 raise AssertionError('DNS fixture condition did not become true')
def stop(process):
 if process.poll() is None:
 process.terminate()
 try:process.wait(timeout=5)
 except subprocess.TimeoutExpired:process.kill();process.wait(timeout=5)

@contextmanager
def lab(records,soa_ttl=8,minimum=4,extra=''):
 with TemporaryDirectory(prefix='xbcatm-dns-') as directory,ExitStack() as stack:
 root=Path(directory);zone=root/'zone';conf=root/'named.conf';log=root/'named.log';serial=1
 def save(body):
 zone.write_text(f'$ORIGIN lab.test.\n$TTL 30\n@ {soa_ttl} IN SOA ns.lab.test. hostmaster.lab.test. ({serial} 60 60 3600 {minimum})\n@ IN NS ns.lab.test.\nns IN A 127.0.0.1\n'+body+'\n')
 run('named-checkzone','lab.test',str(zone))
 save(records)
 conf.write_text(f'''options {{ directory "{root}"; listen-on port 1053 {{127.0.0.1;}}; listen-on-v6 {{none;}};
recursion no; dnssec-validation no; notify no; querylog yes; max-cache-size 8m; pid-file "{root}/named.pid"; session-keyfile none;
{extra} }};
controls {{}};
zone "lab.test" {{ type primary; file "{zone}"; }};
''')
 run('named-checkconf',str(conf))
 output=stack.enter_context(log.open('w'))
 authority=subprocess.Popen(['named','-g','-c',str(conf),'-n','1','-U','1'],stdout=output,stderr=subprocess.STDOUT)
 stack.callback(stop,authority)
 def ready():
 assert authority.poll() is None,log.read_text()
 response=query('lab.test.','SOA');return response.rcode()==0 and response.answer[0][0].serial==serial
 wait(ready)
 def update(body):
 nonlocal serial
 serial+=1;save(body);authority.send_signal(signal.SIGHUP);wait(ready)
 def cache(port=1054,upstream=1053,size=150,options=()):
 logfile=root/('cache-'+str(port)+'.log');stream=stack.enter_context(logfile.open('w'))
 command=['dnsmasq','--no-daemon','--conf-file=/dev/null','--no-resolv','--no-hosts','--bind-interfaces',
 '--listen-address=127.0.0.1','--port='+str(port),'--server=127.0.0.1#'+str(upstream),
 '--cache-size='+str(size),'--log-queries','--log-facility=-',*options]
 process=subprocess.Popen(command,stdout=stream,stderr=subprocess.STDOUT);stack.callback(stop,process)
 def cache_ready():
 assert process.poll() is None,logfile.read_text()
 return query('lab.test.','SOA',port).rcode()==0
 wait(cache_ready);return process,logfile
 def queries(name,kind='A'):
 return sum(bool(re.search(r'query: '+re.escape(name.rstrip('.'))+r' IN '+kind+r'\b',line)) for line in log.read_text().splitlines())
 yield root,update,cache,queries
with lab('exists 30 IN A 127.0.0.2',soa_ttl=8,minimum=4) as (_,update,cache,queries):
 cache();missing=query('new.lab.test.',port=1054);nodata=query('exists.lab.test.','AAAA',1054)
 assert missing.rcode()==dns.rcode.NXDOMAIN and not missing.answer
 assert nodata.rcode()==dns.rcode.NOERROR and not nodata.answer
 for answer in (missing,nodata):assert len(answer.authority)==1 and answer.authority[0].rdtype==dns.rdatatype.SOA and answer.authority[0].ttl==4
 wait(lambda: queries('new.lab.test')==1 and queries('exists.lab.test','AAAA')==1)
 again=query('new.lab.test.',port=1054);again_nodata=query('exists.lab.test.','AAAA',1054)
 assert again.rcode()==dns.rcode.NXDOMAIN and again_nodata.rcode()==0 and not again_nodata.answer
 assert queries('new.lab.test')==1 and queries('exists.lab.test','AAAA')==1
 positive=query('exists.lab.test.','A',1054);assert values(positive)==['127.0.0.2']
 update('exists 30 IN A 127.0.0.2\nexists 30 IN AAAA ::1\nnew 30 IN A 127.0.0.3')
 assert values(query('new.lab.test.'))==['127.0.0.3'] and values(query('exists.lab.test.','AAAA'),'AAAA')==['::1']
 stale_missing=query('new.lab.test.',port=1054);stale_nodata=query('exists.lab.test.','AAAA',1054)
 assert stale_missing.rcode()==dns.rcode.NXDOMAIN and stale_nodata.rcode()==0 and not stale_nodata.answer
 wait(lambda: values(query('new.lab.test.',port=1054))==['127.0.0.3'],timeout=7)
 wait(lambda: values(query('exists.lab.test.','AAAA',1054),'AAAA')==['::1'],timeout=7)
 result={'NXDOMAIN':show(missing),'NODATA':show(nodata),'repeat_upstream_queries':{'NXDOMAIN':1,'NODATA':1},'existing_A_unaffected':show(positive),
 'immediately_after_creation':{'NXDOMAIN':show(stale_missing),'NODATA':show(stale_nodata)},'new_records_observed_after_expiry':True}
with lab('exists 30 IN A 127.0.0.2',soa_ttl=2,minimum=9) as (_,update,cache,queries):
 smaller=query('new.lab.test.');assert smaller.rcode()==dns.rcode.NXDOMAIN and smaller.authority[0].ttl==2
 result['smaller_SOA_TTL']=show(smaller)
print(json.dumps(result,sort_keys=True))
"""
name='xbcatm-dns-'+uuid.uuid4().hex[:10]
def docker(*args,**kwargs):return subprocess.run(['docker',*args],capture_output=True,text=True,timeout=300,**kwargs)
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'Dockerfile').write_text(recipe)
 built=docker('build','-t',name,str(root));assert built.returncode==0,built.stderr
 result=docker('run','--rm','-i','--name',name,'--network','none','--memory','384m','--pids-limit','128',name,
 '/usr/bin/python3','-',input=program)
 assert result.returncode==0,result.stderr
 print(json.dumps(json.loads(result.stdout),sort_keys=True))
finally:
 docker('rm','-f',name);docker('image','rm',name)

An A query for new.lab.test returns NXDOMAIN. An AAAA query for exists.lab.test, which already has A 127.0.0.2, returns NOERROR with no answer data. Both negative responses contain an SOA with TTL 4. The program repeats both queries through the cache and confirms that each has generated only one upstream query, proving reuse rather than merely observing two identical responses.

Querying the existing name’s A record still succeeds. This shows that the cached absence of AAAA does not mean every type at that name is absent. The script next adds A for the new name and AAAA for the existing name, reloads the authoritative zone, and verifies the new records directly. The authority now returns 127.0.0.3 and ::1, respectively.

Immediately querying through dnsmasq still returns the earlier NXDOMAIN and NODATA results. After the negative entries expire, those queries return the new positive data. A second isolated zone reverses the limiting values: SOA TTL 2 and minimum 9 produce a negative response with TTL 2. Together the cases verify both sides of the minimum rule instead of only one convenient configuration.

Separate authoritative absence from resolution failure

SERVFAIL, timeout, and DNSSEC validation failure do not establish that a name is absent. They describe failure to obtain or accept an answer. They are not categorically uncacheable, however: RFC 9520 updates the requirements for caching DNS resolution failures, including validation failures. Its failure-cache lifetime rules differ from the SOA-derived lifetime used for the authoritative negative answers in this experiment.

Do not assume a resolver implements every current recommendation merely because it caches NXDOMAIN correctly. This fixture does not test failure caching or DNSSEC validation. Inspect the deployed resolver’s version, configuration, and diagnostics for those behaviors. Preserve response codes and extended error information when available so a cached validation problem is not mistaken for a recently deleted hostname.

Before publishing a new service, consider whether its names have already been queried while absent. Create required records early when the deployment permits, and allow any known negative cache window to drain before requiring successful discovery. An operator can clear a cache they control, but cannot normally purge every independent resolver used by clients. Verify both authoritative publication and the affected resolver’s current response.

Choose negative lifetime with recovery and repeated-miss load in mind. Repeated queries for one absent name can benefit from caching; a stream of unique names behaves differently and still consumes resources. Keep positive and negative query metrics distinguishable. The operational question is which fact was cached, under which name and type, for how long, and what evidence now shows that the client’s view has changed.

Sources

RFC 2308 negative DNS caching, NXDOMAIN, NODATA, cache keys, and the SOA-derived lifetime, checked 2026-09-12.
RFC 9520 caching DNS resolution failures, updated requirements for resolution and validation failure caching, checked 2026-09-12.
dnsmasq manual, negative caching behavior and related options, checked 2026-09-12.

Content-Type and Vary work together

Mon, 12 Oct 2026 00:00:00 +0000

One URL can return JSON to an API client and plain text to another reader. Content-Type identifies the selected representation; Vary identifies request fields relevant to selecting it. A correct body label cannot prevent a cache from choosing the wrong stored response when the request-matching information is missing.

Content-Type describes the selected body; Vary constrains request matching. The article’s stated CacheControl example shows plain-text requests receiving cached JSON when Vary is omitted. This illustration adds no execution or production-cache verification.

Separate format, selection, and reuse

For negotiation driven by the request’s Accept field, return Vary: Accept alongside the actual response type. Vary: Content-Type would instead nominate the request’s Content-Type field, which does not describe the desired response. A cache cannot reconstruct the selection rule merely by inspecting the stored response’s media type. Its normal key already includes the target URI and relevant method semantics; Vary adds request-header matching requirements.

Compression introduces another distinction. Gzipped JSON still has the JSON media type, with Content-Encoding: gzip describing a content coding of the representation. This is not Transfer-Encoding or message framing. When the server selects that coding from Accept-Encoding, that request field is a relevant Vary dimension. Include only dimensions actually involved in selection; a browser’s physical viewport is not automatically a request header.

Vary neither grants permission to cache nor makes a stored response fresh. Storage and reuse must also satisfy status, method, authorization, and cache-directive rules. It is not an access-control boundary: adding Vary: Cookie does not establish that private account data is safe in a shared cache. Decide storage policy and audience independently, then describe the variation of representations that may legitimately be reused.

When it breaks

With an otherwise cacheable, fresh response, omitting Vary can let the first request determine what later readers receive. The origin works correctly when contacted directly, but a later client receives an incompatible representation without reaching it. A successful status and a perfectly honest Content-Type do not reveal that the response belongs to a different request preference. Compare the requested Accept value, returned type, and evidence of cache reuse.

Another failure is emitting Vary only for the nondefault representation. The default response then remains eligible for unrelated preferences. Generate consistent selection metadata for every representation of the route. When middleware adds a separate dimension, retain the existing dimensions instead of overwriting them. Large, unnecessary dimensions can fragment cache reuse, so investigate actual selection inputs rather than adding every available header.

Check it quickly

Use Python 3.11 or newer and a POSIX shell. These commands create a temporary environment and install the tested CacheControl and Requests versions. Installation uses the network; the following experiment talks only to loopback and disables environment proxy and netrc settings. These are experiment dependencies, not website dependencies.

vary_lab=$(mktemp -d)
python3 -m venv "$vary_lab/venv"
"$vary_lab/venv/bin/python" -m pip install CacheControl==0.14.4 requests==2.34.2

Run this program with "$vary_lab/venv/bin/python" in the same shell. The server recognizes exactly two Accept values; it is a fixture, not a general negotiator supporting wildcards or quality weights. CacheControl supplies the actual cache implementation.

from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread

import requests
from cachecontrol import CacheControl

representations = {
 "application/json": b'{"format":"json"}\n',
 "text/plain": b"format=plain\n",
}
hits = {"/vary": 0, "/no-vary": 0, "/star": 0}


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 media = self.headers.get("Accept")
 if self.path not in hits or media not in representations:
 self.send_error(400)
 return
 hits[self.path] += 1
 body = representations[media]
 self.send_response(200)
 self.send_header("Content-Type", media)
 self.send_header("Content-Length", str(len(body)))
 self.send_header("Cache-Control", "public, max-age=300")
 if self.path != "/no-vary":
 self.send_header("Vary", "*" if self.path == "/star" else "Accept")
 self.end_headers()
 self.wfile.write(body)

 def log_message(self, *args):
 pass


server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
worker = Thread(target=server.serve_forever)
worker.start()
session = CacheControl(requests.Session())
session.trust_env = False
try:
 base = f"http://127.0.0.1:{server.server_port}"
 for route in hits:
 for index, accept in enumerate([
 "application/json", "application/json", "text/plain", "text/plain"
 ]):
 response = session.get(base + route, headers={"Accept": accept}, timeout=3)
 response.raise_for_status()
 expected = "application/json" if route == "/no-vary" else accept
 assert response.headers["Content-Type"] == expected
 assert response.content == representations[expected]
 cached = index > 0 if route == "/no-vary" else index in (1, 3)
 if route == "/star":
 cached = False
 assert response.from_cache == cached
 print(route, accept, "->", expected, "cached=", response.from_cache)
 assert hits == {"/vary": 2, "/no-vary": 1, "/star": 4}
 print("origin hits:", hits)
finally:
 session.close()
 server.shutdown()
 server.server_close()
 worker.join()

For /vary, cache flags are false, true, false, true: each preference reaches the origin once and its immediate repeat is cached. For /no-vary, flags are false, true, true, true; both plain-text requests incorrectly receive JSON. The assertions deliberately verify this failure rather than pretending it is acceptable application behavior. Origin counts are respectively two and one, independently confirming which requests reached the server.

For /star, all four requests reach the origin. A Vary value containing * always fails cache matching; the standard does not equate that rule with a universal prohibition on storage. This CacheControl version declines to store those responses. The test also does not assert that a cache keeps multiple variants simultaneously: an implementation can replace its single entry and still respect matching requirements.

Run requests in both preference orders when testing a deployed cache, using an isolated test URL or approved invalidation procedure. A newly corrected origin header does not automatically repair an already fresh, incorrectly keyed entry. Check the real proxy or CDN separately: this experiment establishes the mechanism in a client cache, not the configuration or privacy guarantees of your production shared cache.

Sources

RFC 9110: Vary, selection fields and representation metadata, checked 2026-09-07.
RFC 9111: Vary cache matching, matching requirements, wildcard behavior, and storage rules, checked 2026-09-07.
CacheControl 0.14.4, the Requests caching wrapper used in the experiment, checked 2026-09-07.

ETags and conditional requests avoid work

Sat, 26 Sep 2026 00:00:00 +0000

A 304 is useful only when the old representation really remains an acceptable substitute. ETag supplies the origin’s version claim; it does not independently verify that claim. An incorrect tag can make conditional requests efficiently preserve wrong content. Test both unchanged data and meaningful changes before counting reduced transfers as a performance improvement.

Strong validators distinguish changed bytes; weak validators may preserve semantic equivalence. A fixed incorrect tag can return false 304 after the object changes. Source illustration only; no new fixture execution.

Validators identify the version

Entity tags are opaque, quoted identifiers. Clients should return them as received rather than interpreting them as timestamps or removing the weak marker. The generator might use a revision identifier or a collision-resistant digest. A digest is convenient when the final bytes already exist; repeatedly rendering and hashing an expensive document merely to return 304 can still consume substantial origin work.

Strong and weak are different promises

A strong validator must change when the selected representation’s data changes. Pretty-printed and compact JSON have different bytes even when they decode into the same object. Gzip and unencoded forms also have different representation data. Their strong validators must preserve that distinction. Identical lengths or a database timestamp with coarse resolution do not establish byte identity.

A weak tag, marked with W/, can group representations that the origin considers interchangeable. For a JSON endpoint whose contract ignores formatting, one semantic revision can cover both compact and indented serialization. A change to the actual field values requires a new revision when the old object is no longer an acceptable substitute. Weak validation is an explicit equivalence policy, not permission to leave a tag unchanged indefinitely.

If-None-Match uses weak comparison for cache validation. A matching conditional GET receives 304 without content; a nonmatching tag normally receives 200 with the selected representation. If-Match uses strong comparison, which matters for update preconditions. Weak tags are not valid client validators for If-Range. These fields have different contracts, so stripping W/ and applying one generic string comparison everywhere is incorrect.

When it breaks

A fixed tag on changing data can produce false 304 responses. The opposite mistake, issuing a new tag for identical data on every request, causes needless body transfers. Neither is repaired by adding a long max-age. Freshness decides when validation is needed; validation decides whether an existing response remains usable. A successful 304 also does not guarantee that application parsing or rendering work disappears.

Comparison must follow representation selection and normal access checks. A matching validator is not authorization. For negotiated responses, preserve the relevant Vary dimensions and distinguish representation data correctly. Header lists require a real parser: a quoted entity tag can itself contain a comma, so splitting the header text on commas corrupts valid identifiers.

Check it quickly

Use Python 3.11 or newer and Werkzeug 3.1.8. Create the temporary environment, then run the Python block with "$etag_lab/venv/bin/python". The test client exercises the WSGI application in-process without binding a port or making network requests. Installation requires the network. The deliberately broken endpoint is a negative fixture, not an implementation to deploy.

etag_lab=$(mktemp -d)
python3 -m venv "$etag_lab/venv"
"$etag_lab/venv/bin/python" -m pip install Werkzeug==3.1.8

import hashlib
import json

from werkzeug.http import parse_etags
from werkzeug.test import Client
from werkzeug.wrappers import Request, Response

state = {"value": 1, "revision": 1, "indent": None}


def body():
 return json.dumps({"value": state["value"]}, indent=state["indent"]).encode()


@Request.application
def application(request):
 if request.path not in {"/strong", "/weak", "/broken"}:
 return Response(status=404)
 response = Response(body(), mimetype="application/json")
 response.headers["Cache-Control"] = "no-cache"
 if request.path == "/strong":
 response.set_etag(hashlib.sha256(response.data).hexdigest())
 elif request.path == "/weak":
 response.set_etag(f"record-{state['revision']}", weak=True)
 else:
 response.set_etag("fixed") # Deliberately incorrect failure fixture.
 return response.make_conditional(request)


client = Client(application)


def get(route, tag=None):
 response = client.get(route, headers={"If-None-Match": tag} if tag else {})
 print(route, response.status_code, "bytes:", len(response.data))
 return response


first = get("/strong")
assert first.status_code == 200 and first.json == {"value": 1}
same = get("/strong", first.headers["ETag"])
assert same.status_code == 304 and same.data == b""
state["indent"] = 2
formatted = get("/strong", first.headers["ETag"])
assert formatted.status_code == 200 and formatted.json == first.json
assert formatted.data != first.data and formatted.headers["ETag"] != first.headers["ETag"]

weak = get("/weak")
state["indent"] = None
assert body() != weak.data and json.loads(body()) == weak.json
equivalent = get("/weak", weak.headers["ETag"])
assert equivalent.status_code == 304 and equivalent.data == b""
state.update(value=2, revision=2)
changed = get("/weak", weak.headers["ETag"])
assert changed.status_code == 200 and changed.json == {"value": 2}
assert changed.headers["ETag"] != weak.headers["ETag"]

tags = parse_etags('"unrelated", W/"record-2", "a,b"')
assert tags.contains_weak("record-2") and not tags.contains("record-2")
assert tags.contains("a,b")
print("weak match: True; strong match: False; quoted comma preserved")

broken = get("/broken")
state.update(value=3, revision=3)
assert json.loads(body()) != broken.json
false_confirmation = get("/broken", broken.headers["ETag"])
assert false_confirmation.status_code == 304 and false_confirmation.data == b""
print("broken validator: changed content was incorrectly confirmed")

The strong endpoint returns 200, 304, then 200. Formatting changes the body from twelve to sixteen bytes and changes its digest, even though the parsed object remains equal. The weak endpoint returns 200, 304, then 200 too, but for different reasons: formatting alone is equivalent; changing the value and revision is not. Both 304 responses contain no body.

The parser check accepts the weak revision for weak comparison but rejects it for strong comparison, while preserving the quoted comma. Finally, the broken endpoint returns 200 followed by 304 even though its current object has changed. That assertion intentionally documents incorrect origin behavior. The framework trusted the supplied tag; it did not detect that the application had attached the wrong version claim.

The fixture does not test range assembly, concurrent writes, authorization, or a shared cache. Production revision changes must be coupled to the represented data, and write preconditions need atomic checking with the update. Retain the changed-content counterexample in tests: a high 304 ratio alone cannot distinguish correct savings from persistent stale answers.

Sources

RFC 9110: validators, strong and weak representation claims, checked 2026-09-07.
MDN: ETag, opaque identifiers and validator use, checked 2026-09-07.
Werkzeug entity-tag collections, strong and weak membership tests, checked 2026-09-07.
Werkzeug test client, in-process WSGI request testing, checked 2026-09-07.

Freshness and validation in the two-clock cache model

Fri, 14 Aug 2026 00:00:00 +0000

Caching has two separate decisions: may a stored response be reused without contacting the server, and how can the client check whether that response still represents the resource? Calling them “two clocks” is a mnemonic. Freshness really is an age calculation; validation is a comparison, not another timer. A response can be fresh by policy while already differing from a newly deployed origin, without the cache violating HTTP.

Simplified age example: matching variant, no overriding request directive. no-cache still requires validation; must-revalidate forbids unvalidated stale reuse. Validator matching does not prove byte identity.

Freshness: how long to reuse without asking

Cache-Control: max-age=60 gives a response a freshness lifetime of 60 seconds. A cache compares that lifetime with the response’s current age, accounting for Date, Age, transit time, and time stored. At exactly 60 seconds it is stale, not fresh for one more second. Shared caches prefer s-maxage when present; absent explicit freshness, some responses can receive heuristic freshness.

A fresh response is usually reusable, but matching the cache key and Vary fields and obeying request/response directives still matters. no-cache requires successful validation before reuse even when the response could otherwise be fresh. no-store prohibits storage; it is not a synonym for revalidate. public permits shared-cache storage in cases otherwise restricted; it does not specify a duration.

For mutable HTML, a short explicit lifetime plus validation is often useful. It intentionally permits updates to take up to that lifetime to become visible through a compliant cache. A whole-tree deployment does not invalidate existing browser or CDN entries. Content-addressed assets can instead use a long lifetime when the URL changes with the bytes.

Validation: ask whether the stored representation still matches

An ETag is an opaque validator, not a checksum the client should decode. Last-Modified is a timestamp validator. Neither header specifies an explicit freshness lifetime, and a server need not supply both. When heuristic freshness is permitted, however, a cache can use Last-Modified to estimate a lifetime. For example, these illustrative headers express a lifetime and a validator separately:

Cache-Control: max-age=60, must-revalidate
ETag: "release-a"

After expiry, If-None-Match: "release-a" lets a GET receive 304 Not Modified if the selected representation still matches, or a new 200 with a body if it changed. The cache updates applicable metadata from the 304 and reuses its stored body. A 304 is not useful without a corresponding stored representation. If-None-Match uses weak comparison, so successful validation does not necessarily prove byte-for-byte identity; If-Range and combining partial responses have stronger requirements.

The server can compute an ETag from bytes or other reliably changing metadata. A strong tag must distinguish representations whose data differs, including content codings where applicable. Sending the same strong ETag for different gzip and identity bytes is not fixed by adding a short lifetime. Vary: Accept-Encoding also tells a cache which request header affected selection.

A small exercise that separates the decisions

This Python model deliberately excludes heuristic freshness, network delay, and variant selection. age stands for the already calculated current age; the conditional request uses a server validator that has not changed. The model compares two fixed tag strings; it does not implement HTTP entity-tag parsing, tag lists, or the full weak-comparison rules.

lifetime = 60
stored_etag = '"release-a"'
server_etag = '"release-a"'
for age in (59, 60, 61):
 fresh = age < lifetime
 action = "reuse without validation" if fresh else (
 "validate: 304, reuse body" if stored_etag == server_etag
 else "validate: 200, replace body"
 )
 print(age, action)

The first line reuses without validation; the other two validate and reuse after a 304. Set server_etag to "release-b": the stale cases become 200, while the 59-second case still reuses the stored response. That is the permitted visibility delay the freshness policy buys in exchange for lower latency and origin load.

The contract worth asserting

Test matching and changed validators, freshness at the boundary, and the selected encoding. Also decide what should happen during an origin outage. HTTP can permit stale reuse under defined conditions or extensions; must-revalidate prohibits reusing the response once stale without successful validation, even when disconnected. This increases correctness pressure at the cost of availability. A validator alone makes no such promise.

A useful release record therefore states the cache policy, selected representation, observed conditional status, and tolerated update delay. Requiring two validator headers and one 304 cannot prove that every cache has current bytes, prevent all bandwidth waste, or replace testing the actual intermediary configuration.

Sources

RFC 9111: HTTP Caching, sections 4.1–4.3 and 5.2 on variants, age, validation, and directives, checked 2026-10-15.
RFC 9110: HTTP Semantics, sections 8.8, 13.1.2, and 13.1.5 on validators and comparison, checked 2026-10-15.

Cache headers are a two-way contract with browsers

Wed, 15 Jul 2026 00:00:00 +0000

An origin defines storage and freshness policy; a cache decides whether its stored response can satisfy the next request. When it cannot reuse that response directly, validators can make checking cheaper. These are separate decisions. Finding Cache-Control and ETag in one successful response does not prove that the next request follows the intended path.

A validator checks whether a stored representation still matches. A 304 refreshes metadata while the cache retains its body.

Who is allowed to reuse and for how long

Private restricts storage to single-user caches, while public explicitly permits caching subject to other requirements. Max-age supplies a freshness lifetime; s-maxage overrides it for shared caches. No-cache permits storage but requires successful validation before reuse. No-store prohibits HTTP cache storage, not application logging or every possible saved copy. None of these directives substitutes for authorization or transport security.

For a content-fingerprinted asset, public, max-age=31536000, immutable can be appropriate when changing the bytes always changes the URL. That duration is one year, not one month. A mutable document at a stable URL needs a policy consistent with its update requirements. A short lifetime with a validator permits bounded direct reuse; no-cache instead requires validation for each subsequent cache reuse.

Validators answer a different question

A client can echo an ETag in If-None-Match. For conditional GET, a matching tag produces 304 without content; a nonmatching tag ordinarily produces 200 with the current representation. If-None-Match uses weak comparison, so weak tags are useful for validation too. Last-Modified supports If-Modified-Since, but second-level timestamps can miss rapid changes. When If-None-Match is present, If-Modified-Since is ignored, regardless of whether the supplied entity tag matches.

A cache receiving an applicable 304 retains its stored body and updates metadata according to the caching rules. The origin must include relevant fields such as Date, ETag, and Cache-Control when they would appear on the corresponding 200. A program that only downloads responses does not automatically implement this cache behavior; treating an empty 304 as a replacement document loses the actual content.

When it breaks

An ETag that never changes when meaningful content changes can incorrectly confirm an old response. A tag regenerated for every identical response causes unnecessary transfers instead. Both defects require repeated-request tests. Strong tags must distinguish differing representation data, including content-coded variants. A hash of the actual bytes is one possible implementation, not a requirement to expose the hash algorithm as a client contract.

Changing origin policy does not recall already-fresh copies that have no reason to contact it. Likewise, a short TTL on personalized JSON does not isolate users. Test cache keys and account transitions separately. Browser history restoration and application-managed caches are additional mechanisms, so a passing HTTP test should not be described as proof that every displayed page will refresh immediately.

Check it quickly

Use Python 3.11 or newer and a POSIX shell. Install Werkzeug 3.1.8 below, then run the Python block with "$validation_lab/venv/bin/python". It creates a loopback development server on an automatically allocated port and shuts it down afterward. Installation needs the network; all seven requests remain local. This is an origin-side protocol test, not a production deployment or browser-cache simulation.

validation_lab=$(mktemp -d)
python3 -m venv "$validation_lab/venv"
"$validation_lab/venv/bin/python" -m pip install Werkzeug==3.1.8

import hashlib
from datetime import datetime, timezone
from http.client import HTTPConnection
from threading import Thread

from werkzeug.serving import make_server
from werkzeug.wrappers import Request, Response

state = {"body": b"release A\n", "modified": datetime(2026, 1, 1, tzinfo=timezone.utc)}
directive = "public, max-age=0, must-revalidate"


@Request.application
def application(request):
 if request.path != "/document":
 return Response("not found\n", status=404)
 if request.method != "GET":
 return Response("GET only\n", status=405, headers={"Allow": "GET"})
 body = state["body"]
 response = Response(body, mimetype="text/plain")
 response.headers["Cache-Control"] = directive
 response.set_etag(hashlib.sha256(body).hexdigest())
 response.last_modified = state["modified"]
 return response.make_conditional(request)


server = make_server("127.0.0.1", 0, application)
worker = Thread(target=server.serve_forever)
worker.start()


def get(headers=None):
 connection = HTTPConnection("127.0.0.1", server.server_port, timeout=3)
 try:
 connection.request("GET", "/document", headers=headers or {})
 response = connection.getresponse()
 body = response.read()
 assert response.headers["Cache-Control"] == directive
 assert response.headers["ETag"] and response.headers["Date"]
 print(response.status, "bytes:", len(body))
 return response.status, response.headers, body
 finally:
 connection.close()


try:
 status, first, body = get()
 assert status == 200 and body == b"release A\n"
 status, headers, body = get({"If-None-Match": first["ETag"]})
 assert status == 304 and body == b"" and headers["ETag"] == first["ETag"]
 status, _, body = get({"If-None-Match": '"different"',
 "If-Modified-Since": first["Last-Modified"]})
 assert status == 200 and body == b"release A\n"
 status, _, body = get({"If-None-Match": "W/" + first["ETag"]})
 assert status == 304 and body == b""
 state.update(body=b"release B\n", modified=datetime(2026, 1, 2, tzinfo=timezone.utc))
 status, second, body = get({"If-None-Match": first["ETag"]})
 assert status == 200 and body == b"release B\n"
 assert second["ETag"] != first["ETag"]
 status, _, body = get({"If-None-Match": second["ETag"]})
 assert status == 304 and body == b""
 status, _, body = get({"If-Modified-Since": second["Last-Modified"]})
 assert status == 304 and body == b""
finally:
 server.shutdown()
 server.server_close()
 worker.join()

Expected statuses are 200, 304, 200, 304, 200, 304, and 304. Each 200 carries ten bytes; each 304 carries zero. The conflicting-validator request returns 200 even though its date matches, agreeing with entity-tag precedence for this combination; the reverse combination is not exercised here. The weak-form request still validates the unchanged representation. Both A and B have the same length, so the changed-body test also rules out using length alone as a validator.

The final two requests validate B using its new ETag and then its Last-Modified value alone. Cache-Control, Date, and ETag are checked throughout. Max-age zero with must-revalidate permits storage but requires successful validation once stale; it does not itself cause Python’s HTTP client to cache anything. The client deliberately constructs every request. Werkzeug handles conditional parsing and wire-level body suppression.

Carry the changed-body and conflicting-validator cases into deployment tests. Inspect the actual GET response, not only HEAD, and check that intermediaries preserve the validator for the selected representation. A good result includes both avoided transfers when appropriate and full replacement when the content really changed.

Sources

RFC 9111: cache validation, stored-body reuse and metadata updates, checked 2026-09-07.
RFC 9110: conditional requests, entity-tag comparison and precondition precedence, checked 2026-09-07.
MDN: Cache-Control, storage directives and resource-specific freshness, checked 2026-09-07.
Werkzeug conditional responses, the tested response API and body handling, checked 2026-09-07.

Validators decide whether a cached copy is still the answer

Tue, 30 Jun 2026 00:00:00 +0000

A cache can ask whether its stored copy is still usable without always downloading the body again. It sends a validator; a matching conditional GET can receive 304 Not Modified, while a changed representation normally needs a new 200 response. Validation saves bytes on a hit, not on every request.

Illustrative tags; otherwise successful requests. GET/HEAD use weak comparison. HEAD has no body. Matching is neither byte identity nor freshness. Other methods normally return 412; If-Range cannot use weak ETags.

Validator type and strength are different questions

An ETag is an opaque, quoted value. It can be strong ("release-a") or explicitly weak (W/"release-a"). Strong comparison requires both tags to be strong and equal; weak comparison compares the opaque values regardless of the W/ marker. Weak tags can describe semantic equivalence even when bytes differ.

Last-Modified is a timestamp with one-second HTTP-date resolution. It is usually weak unless the conditions in RFC 9110 section 8.8.2.2 establish it as strong. Do not classify every ETag as strong or every timestamp as unconditionally weak.

The earlier site observation recorded:

etag: "dkx84jwth7nkc9e"
last-modified: Mon, 24 Aug 2026 13:55:23 GMT

These are historical values; the original response log is not retained here and the live result was not rechecked in this review. Caddy’s file server normally sets both fields, subject to file metadata and configuration.

Conditional GET uses weak comparison

Send the ETag exactly as received in If-None-Match, including its quotes and any W/. The original note reported HTTP 304 for the value above but printed an unquoted request value. That request text was not valid entity-tag syntax and should not be copied as a working probe. Obtain a current validator before testing a live endpoint.

This socket-free exercise illustrates the comparison for individual, already-parsed tags; it is not a complete HTTP header parser:

def weak_value(tag):
 return tag[2:] if tag.startswith('W/') else tag

def strong_equal(a, b):
 return not a.startswith('W/') and not b.startswith('W/') and a == b

stored = 'W/"release-a"'
current = '"release-a"'
assert weak_value(stored) == weak_value(current)
assert not strong_equal(stored, current)
assert weak_value(stored) != weak_value('"release-b"')
print("weak match: True; strong match: False; changed tag: no match")

For an otherwise successful GET or HEAD, a matching If-None-Match produces a body-free 304. The same false precondition on another method normally produces 412 Precondition Failed. If both If-None-Match and If-Modified-Since are present, the ETag condition takes precedence. Byte-range validation with If-Range cannot use a weak ETag.

Republish without preserving a misleading validator

An ETag is not necessarily a content hash. Caddy v2.10.2’s default file tag is derived from modification time and size; replacing bytes while preserving both can preserve the tag. Inspect the deployed version and any configured overrides, then make the release process update the validator’s inputs or use content-based versioning.

Keep byte checksums in the release manifest and test both unchanged and changed responses. A checksum does not automatically become the server’s ETag. A 304 also needs the applicable cache metadata so a cache can update its stored response; it is not merely an empty success status.

Sources

RFC 9110 — HTTP Semantics, sections 8.8 and 13 on validator strength and preconditions, checked 2026-10-15.
RFC 9111 — HTTP Caching, section 4.3 on validation and updating stored responses, checked 2026-10-15.
MDN: HTTP conditional requests, conditional-request overview, checked 2026-10-15.
Caddy v2.10.2 file-server source, calculateEtag inputs and default response fields, checked 2026-10-15.

Cache headers are a contract with two clocks

Thu, 25 Jun 2026 00:00:00 +0000

Caching is not a single switch. A response has a freshness decision made by a cache and a validation conversation with the origin. Mixing those two ideas produces either stale content or needless requests.

Storage, freshness, and validation answer separate questions. Match the policy to how the URL changes, preserve validators exactly, and check shared-cache variants.

Pick the change model first

For an HTML document that may change after publication, Cache-Control: no-cache is usually a more accurate starting point than no-store. no-cache permits storage but requires a cache to validate before reuse; no-store asks caches not to store the response at all. The distinction matters when you want conditional requests and a cheap 304 Not Modified response.

For a fingerprinted asset such as app.4f2c.js, the URL changes when the bytes change. A long freshness lifetime can then be reasonable:

Cache-Control: public, max-age=31536000, immutable

That policy is unsafe for a stable URL whose contents can be replaced in place. If the URL is stable, prefer a shorter lifetime and a validator such as an entity tag (ETag) or a meaningful Last-Modified value.

Choose who may store the response as well as how long it stays fresh. Use the unqualified private directive when shared caches must not store user-specific content; a browser’s private cache can still store it. no-cache alone does not provide that restriction. The public example above is for assets safe to share across users, not a default for personalized responses.

Inspect both paths

Make one ordinary request and one conditional request. The exact server flags vary, but the evidence you want is stable:

curl -sS -D - -o /dev/null https://www.example.test/
curl -sS -D - -o /dev/null \
 -H 'If-None-Match: "copy-a-real-etag-from-the-first-response"' \
 https://www.example.test/

Do not paste a made-up validator into a runbook. Copy the value from the first response or use a test fixture. For this conditional GET, a matching If-None-Match can yield 304 using weak comparison: it permits semantic equivalence, not necessarily byte identity. A changed validator normally produces a new 200 response. Keep the ETag’s quotes and any W/ prefix intact.

Keep intermediaries visible

Age, Vary, and the cache-control directives explain why two clients can receive different results. If a response varies by Accept-Encoding, language, or another request field, that dimension belongs in Vary; otherwise a shared cache can reuse the wrong representation.

The useful release check is not “the scanner found a cache header”. It is “the header matches the replacement policy, and a conditional request behaves as documented”.

immutable applies during the advertised freshness lifetime; it is not a permanent ban on revalidation. Keep versioned URLs immutable and older assets reachable while old HTML can still reference them. Changing today’s cache header does not retroactively shorten a previously cached response’s lifetime, so a cache-policy mistake may require a new URL or an explicitly supported cache purge.

Sources

RFC 9111 — HTTP Caching, sections 4–5, checked 2026-10-15.
RFC 9110 — HTTP Semantics, sections 8 and 13, checked 2026-10-15.
MDN: Cache-Control, directive semantics and defaults, checked 2026-10-15.
RFC 8246 — Immutable Responses, freshness-limited immutable semantics, checked 2026-10-15.

Caching · XB Field Notes

A bloom filter answers maybe at low cost

Bits represent candidates, not records

Size for an expected population

Keep the represented set synchronized

When it breaks

Check it quickly

Further reading

Sources

Cache freshness is judged against a clock

Count the age

When it breaks

Check it quickly

Sources

A cache stampede hits when expiry syncs

Coalesce work within its actual boundary

Spread deadlines without changing the promise

When it breaks

Check it quickly

Further reading

Sources

An LRU cache evicts the least recently used entry

Follow the access order

Exact and sampled policies differ

Capacity is not freshness

When it breaks

Check it quickly

Further reading

Sources

Consistent hashing shrinks the rebalance

Get the ownership interval right

Virtual nodes spread intervals, not individual keys

Placement is not migration or consistency

When it breaks

Check it quickly

Further reading

Sources

Cache invalidation is a push, not a prayer

Expiration is not a broadcast

Identify the scope before invalidating

When it breaks

Check it quickly

Further reading

Sources

A read-through cache loads on a miss by itself

Identify the loading layer

Loading does not define writing

When it breaks

Check it quickly

Further reading

Sources

Stale cache needs a bounded policy

The trade is availability over freshness

How it is signaled

When it breaks

Check it quickly

Further reading

Sources

Immutable assets and fingerprints

Names support a freshness contract

When it breaks

Check it quickly

Further reading

Sources

The Age header tells how long a cached copy has been around

Combine estimates without counting time twice

Freshness is a separate decision

When it breaks

Check it quickly

Further reading

Sources

Cache-Control private versus shared

Not all cacheable should be shared

When it breaks

Check it quickly

Sources

Negative DNS answers preserve absence until their cache lifetime expires

When it breaks

Check it quickly

Separate authoritative absence from resolution failure