Mark cached responses with X-Cache and Age

A stale fallback is byte-identical to a fresh response, so a client has
no way to tell it is holding data pdbmux served only because every
backend was down; the sole signal is a log line and a /healthz counter.

Set X-Cache to hit, miss or stale and Age to whole seconds since the
served copy was stored on every response from a cached path. Neither
header is emitted by OpenVoxDB, so nothing upstream is shadowed.

cache_test.go

@@ -11,6 +11,7 @@ import (
 	"os"
 	"path/filepath"
 	"slices"
+	"strconv"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -776,6 +777,48 @@ func TestFlightGroup_AllCallersAbandon(t *testing.T) {
 	}
 }
 
+func TestServeCached_CacheStatusHeaders(t *testing.T) {
+	stored := `[` + fact("h1", "role", "web", "") + `]`
+	a := newCountingBackend(t, map[string]string{factsPath: stored})
+	b := newCountingBackend(t, map[string]string{factsPath: `[]`})
+	srv, clk := newCachedServer(t, cacheTestConfig(a.srv.URL, b.srv.URL))
+	h := srv.Handler()
+
+	rec := doGet(t, h, factsPath, "")
+	if got := rec.Header().Get(cacheStatusHeader); got != "miss" {
+		t.Errorf("first request %s = %q, want miss", cacheStatusHeader, got)
+	}
+	if got := rec.Header().Get(ageHeader); got != "0" {
+		t.Errorf("first request %s = %q, want 0", ageHeader, got)
+	}
+
+	rec = doGet(t, h, factsPath, "")
+	if got := rec.Header().Get(cacheStatusHeader); got != "hit" {
+		t.Errorf("cached request %s = %q, want hit", cacheStatusHeader, got)
+	}
+	if _, err := strconv.Atoi(rec.Header().Get(ageHeader)); err != nil {
+		t.Errorf("cached request %s = %q, want whole seconds", ageHeader, rec.Header().Get(ageHeader))
+	}
+
+	// Past the TTL with every backend down, the stale fallback must say so.
+	clk.advance(31 * time.Second)
+	a.setFail(true)
+	b.setFail(true)
+	rec = doGet(t, h, factsPath, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("stale fallback status %d (%s)", rec.Code, rec.Body.String())
+	}
+	if got := rec.Header().Get(cacheStatusHeader); got != "stale" {
+		t.Errorf("stale fallback %s = %q, want stale", cacheStatusHeader, got)
+	}
+	if got := rec.Header().Get(ageHeader); got == "" {
+		t.Errorf("stale fallback must carry an %s header", ageHeader)
+	}
+	if got := strings.TrimSpace(rec.Body.String()); got != stored {
+		t.Errorf("stale body = %s, want %s", got, stored)
+	}
+}
+
 func TestHandler_HealthzReportsCacheState(t *testing.T) {
 	a := newCountingBackend(t, map[string]string{factsPath: `[` + fact("h1", "role", "web", "") + `]`})
 	b := newCountingBackend(t, map[string]string{factsPath: `[]`})