chore: add HTTP expires header compatibility with "UTC" opt-in via env var

Set HTTPCACHE_ALLOW_UTC_DATETIMEFORMAT=1 to enable parsing of non-standard "UTC" dates.

Author: bartventer

internal/entry.go

@@ -24,6 +24,7 @@ import (
 	"iter"
 	"net/http"
 	"net/http/httputil"
+	"os"
 	"time"
 )
 
@@ -43,8 +44,30 @@ func (r *Response) DateHeader() time.Time {
 	return date
 }
 
-func (r *Response) ExpiresHeader() RawTime {
-	return RawTime(r.Data.Header.Get("Expires"))
+// Deprecated: This function is a workaround for Kubernetes' handling of "UTC" Expires headers.
+func parseHTTPDateCompat(dateStr string) (t time.Time, err error) {
+	if os.Getenv("HTTPCACHE_ALLOW_UTC_DATETIMEFORMAT") == "1" {
+		// TODO(bartventer): PR Kubernetes to emit "GMT" per RFC 9110 §5.6.7.
+		// See k8s.io/kube-openapi/pkg/handler3/handler.go for "UTC" usage.
+		return time.Parse(time.RFC1123, dateStr)
+	}
+	return
+}
+
+func (r *Response) ExpiresHeader() (t time.Time, found bool, valid bool) {
+	expiresStr := r.Data.Header.Get("Expires")
+	if expiresStr == "" {
+		return
+	}
+	found = true
+	if t, valid = RawTime(expiresStr).Value(); valid {
+		return
+	}
+	expires, err := parseHTTPDateCompat(expiresStr)
+	if err != nil || expires.IsZero() {
+		return time.Time{}, false, false
+	}
+	return expires, true, true
 }
 
 func (r *Response) WriteTo(w io.Writer) (int64, error) {

internal/entry_test.go

@@ -162,3 +162,29 @@ func TestParseResponse(t *testing.T) {
 		})
 	}
 }
+
+func TestParseHTTPDateCompat(t *testing.T) {
+	r := Response{
+		Data: &http.Response{
+			Header: http.Header{
+				"Expires": []string{"Mon, 02 Jan 2006 15:04:05 UTC"},
+			},
+		},
+	}
+	t.Run("Not Enabled", func(t *testing.T) {
+		_, err := parseHTTPDateCompat(r.Data.Header.Get("Expires"))
+		testutil.RequireNoError(t, err)
+
+		_, _, valid := r.ExpiresHeader()
+		testutil.AssertTrue(t, !valid)
+	})
+
+	t.Run("Enabled", func(t *testing.T) {
+		t.Setenv("HTTPCACHE_ALLOW_UTC_DATETIMEFORMAT", "1")
+		_, err := parseHTTPDateCompat(r.Data.Header.Get("Expires"))
+		testutil.RequireNoError(t, err)
+
+		_, found, valid := r.ExpiresHeader()
+		testutil.AssertTrue(t, found && valid)
+	})
+}

internal/freshness.go

@@ -119,15 +119,18 @@ func (f *freshnessCalculator) CalculateFreshness(
 	if maxAge, ok := resCC.MaxAge(); ok && maxAge >= 0 {
 		usefulLife = maxAge // Response is fresh for max-age seconds
 	}
+
 	if usefulLife == 0 {
-		if expires, ok := entry.ExpiresHeader().Value(); ok && expires.After(date) {
+		expires, found, valid := entry.ExpiresHeader()
+		switch {
+		case valid && expires.After(date):
+			// Use Expires header if available
 			usefulLife = expires.Sub(date)
+		case !found && (isHeuristicallyCacheableCode(resp.StatusCode) || resCC.Public()):
+			// Heuristic fallback if allowed by RFC9111 §4.2.2 (only if expires is not set)
+			usefulLife = heuristicFreshness(resp.Header, date)
 		}
 	}
-	// Heuristic fallback if allowed by RFC9111 §4.2.2
-	if usefulLife == 0 && (isHeuristicallyCacheableCode(resp.StatusCode) || resCC.Public()) {
-		usefulLife = heuristicFreshness(resp.Header, date)
-	}
 
 	if reqMaxAge, ok := reqCC.MaxAge(); ok && reqMaxAge > 0 {
 		usefulLife = min(usefulLife, reqMaxAge) // Client prefers a response no older than max-age