feat: Add Legacy Header Support (#8)

Author: bartventer

helpers.go

@@ -14,7 +14,7 @@ func make504Response(req *http.Request) (*http.Response, error) {
 	buf.WriteString("Cache-Control: no-cache\r\n")
 	buf.WriteString("Content-Length: 0\r\n")
 	buf.WriteString(
-		internal.CacheStatusHeader + ": " + internal.CacheStatusBypass.String() + "\r\n",
+		internal.CacheStatusHeader + ": " + internal.CacheStatusBypass.Value + "\r\n",
 	)
 	buf.WriteString("Connection: close\r\n")
 	buf.WriteString("\r\n")

internal/header.go

@@ -0,0 +1,36 @@
+package internal
+
+import (
+	"net/http"
+)
+
+const (
+	CacheStatusHeader       = "X-Httpcache-Status"
+	CacheStatusHeaderLegacy = "X-Cache-Status" // Deprecated: use [CacheStatusHeader] instead
+)
+
+type CacheStatus struct {
+	Value string
+	// Value for compatibility with github.com/gregjones/httpcache:
+	// 	"1" means served from cache (less specific "HIT")
+	// 	"" means not served from cache (less specific "MISS")
+	//
+	// Deprecated: only used for compatibility with unmaintained (still widely
+	// used) github.com/gregjones/httpcache; use Value instead.
+	Legacy string
+}
+
+func (s CacheStatus) ApplyTo(header http.Header) {
+	header.Set(CacheStatusHeader, s.Value)
+	if s.Legacy != "" {
+		header.Set(CacheStatusHeaderLegacy, s.Legacy)
+	}
+}
+
+var (
+	CacheStatusHit         = CacheStatus{"HIT", "1"}         // served from cache
+	CacheStatusMiss        = CacheStatus{"MISS", ""}         // served from origin
+	CacheStatusStale       = CacheStatus{"STALE", "1"}       // served from cache but stale
+	CacheStatusRevalidated = CacheStatus{"REVALIDATED", "1"} // revalidated with origin server
+	CacheStatusBypass      = CacheStatus{"BYPASS", ""}       // cache bypassed
+)

internal/normalization.go

@@ -151,6 +151,7 @@ func normalizeOrderInsensitiveWithQValues(value string) string {
 	}
 	parts := slices.Collect(TrimmedCSVSeq(value))
 	qualityParts := make([]qualityValue, 0, len(parts))
+outer:
 	for i := range parts {
 		part := parts[i]
 		main, allParamsRaw, found := strings.Cut(part, ";")
@@ -164,7 +165,7 @@ func normalizeOrderInsensitiveWithQValues(value string) string {
 				case len(param) > 2 && strings.EqualFold(param[:2], "q="):
 					qRaw := param[2:]
 					if qRaw == "0" || qRaw == "0.0" {
-						goto skipQualityPart // skip this part, as it has q=0
+						continue outer // skip this part, as it has q=0
 					}
 					if qVal, err := strconv.ParseFloat(qRaw, 64); err == nil {
 						q = unique.Make(
@@ -182,10 +183,6 @@ func normalizeOrderInsensitiveWithQValues(value string) string {
 			q:      q,
 			params: params,
 		})
-		continue
-
-	skipQualityPart:
-		continue
 	}
 
 	// Sort by quality value, then by number of wildcards in main,

internal/validationresponsehandler.go

@@ -5,22 +5,6 @@ import (
 	"time"
 )
 
-const CacheStatusHeader = "X-Httpcache-Status"
-
-type CacheStatus string
-
-// ApplyTo sets the cache status header on the provided HTTP header.
-func (s CacheStatus) ApplyTo(header http.Header) { header.Set(CacheStatusHeader, s.String()) }
-func (s CacheStatus) String() string             { return string(s) }
-
-const (
-	CacheStatusHit         CacheStatus = "HIT"         // Response was served from cache
-	CacheStatusMiss        CacheStatus = "MISS"        // Response was not found in cache, and was served from origin
-	CacheStatusStale       CacheStatus = "STALE"       // Response was served from cache but is stale
-	CacheStatusRevalidated CacheStatus = "REVALIDATED" // Response was revalidated with the origin server
-	CacheStatusBypass      CacheStatus = "BYPASS"      // Response was not served from cache due to cache bypass
-)
-
 type ValidationResponseHandler interface {
 	HandleValidationResponse(
 		ctx RevalidationContext,

roundtripper.go

@@ -283,12 +283,8 @@ func (r *transport) handleCacheHit(
 		return r.serveFromCache(stored, freshness, isRespNoCacheQualified, respNoCacheFieldsSeq)
 	}
 
-	if freshness.IsStale && ccResp.MustRevalidate() {
-		goto revalidate
-	}
-
-	// Unqualified no-cache: must revalidate before serving from cache
-	if hasRespNoCache && !isRespNoCacheQualified {
+	if (freshness.IsStale && ccResp.MustRevalidate()) ||
+		(hasRespNoCache && !isRespNoCacheQualified) { // Unqualified no-cache: must revalidate before serving from cache
 		goto revalidate
 	}
 
@@ -337,6 +333,8 @@ func (r *transport) serveFromCache(
 	return stored.Data, nil
 }
 
+// handleStaleWhileRevalidate serves a stale cached response immediately and triggers
+// background revalidation in a separate goroutine (RFC 5861, §3).
 func (r *transport) handleStaleWhileRevalidate(
 	req *http.Request,
 	stored *internal.Response,
@@ -346,6 +344,12 @@ func (r *transport) handleStaleWhileRevalidate(
 ) (*http.Response, error) {
 	req2 := req.Clone(req.Context())
 	req2 = withConditionalHeaders(req2, stored.Data.Header)
+	// Background revalidation is "best effort"; it is not guaranteed to complete
+	// if the program exits before the goroutine finishes. This design choice was
+	// made to keep the API simple and avoid requiring explicit shutdown coordination.
+	//
+	// Open a discussion at github.com/bartventer/httpcache/issues if your use case requires
+	// guaranteed completion.
 	go r.performBackgroundRevalidation(req2, stored, urlKey, freshness, ccReq)
 	internal.CacheStatusStale.ApplyTo(stored.Data.Header)
 	return stored.Data, nil

roundtripper_test.go

@@ -61,7 +61,7 @@ func mockTransport(fields func(rt *transport)) *transport {
 func assertCacheStatus(t *testing.T, resp *http.Response, expectedStatus internal.CacheStatus) {
 	t.Helper()
 	status := resp.Header.Get(internal.CacheStatusHeader)
-	if status != expectedStatus.String() {
+	if status != expectedStatus.Value {
 		t.Errorf("expected cache status %s, got %s", expectedStatus, status)
 	}
 }

store/memcache/memcache.go

@@ -1,4 +1,4 @@
-// Package memcache provides an in-memory implementation of store.Cache.
+// Package memcache implements an in-memory cache backend.
 //
 // It is suitable for testing or ephemeral caching needs, but does not persist data
 // across process restarts.