feat(store/fscache): add optional mtime update on cache hits (#20)

Author: bartventer

.github/workflows/default.yml

@@ -1,6 +1,7 @@
 name: Test
 on:
   push:
+    branches: [master]
   pull_request:
   workflow_dispatch:
 

README.md

@@ -12,8 +12,8 @@
 ## Features
 
 - **Plug-and-Play**: Just swap in as your HTTP client's transport; no extra configuration needed. [^1]
-- **RFC 9111 Compliance**: Handles validation, expiration, and revalidation ([see details](#rfc-9111-compliance-matrix)).
-- **Cache Control**: Supports all required HTTP cache control directives, as well as extensions like `stale-while-revalidate`, `stale-if-error`, and `immutable` ([view details](#field-definitions-details)).
+- **RFC 9111 Compliance**: Handles validation, expiration, and revalidation (see [details](#rfc-9111-compliance-matrix)).
+- **Cache Control**: Supports all required HTTP cache control directives, as well as extensions like `stale-while-revalidate`, `stale-if-error`, and `immutable` (see [details](#field-definitions-details)).
 - **Cache Backends**: Built-in support for file system and memory caches, with the ability to implement custom backends (see [Cache Backends](#cache-backends)).
 - **Cache Maintenance API**: Optional REST endpoints for listing, retrieving, and deleting cache entries (see [Cache Maintenance API](#cache-maintenance-api-debug-only)).
 - **Extensible**: Options for logging, transport and timeouts (see [Options](#options)).
@@ -264,7 +264,7 @@ Content-Type: application/json
 | 5.2.1.3. | `min-fresh`      |  Optional   |      ✔️      |                                                                |
 | 5.2.1.4. | `no-cache`       |  Optional   |      ✔️      |                                                                |
 | 5.2.1.5. | `no-store`       |  Optional   |      ✔️      |                                                                |
-| 5.2.1.6. | `no-transform`   |  Optional   |      ✔️      | Compliant by default - implementation never transforms content |
+| 5.2.1.6. | `no-transform`   |  Optional   |      ✔️      | See [Content Transformation Compliance](#content-transformation-compliance) |
 | 5.2.1.7. | `only-if-cached` |  Optional   |      ✔️      |                                                                |
 
 </details>
@@ -283,7 +283,7 @@ Content-Type: application/json
 | 5.2.2.3.  | `must-understand`  |  Required   |      ✔️      |                                                                |
 | 5.2.2.4.  | `no-cache`         |  Required   |      ✔️      | Both qualified and unqualified forms supported                 |
 | 5.2.2.5.  | `no-store`         |  Required   |      ✔️      |                                                                |
-| 5.2.2.6.  | `no-transform`     |  Required   |      ✔️      | Compliant by default - implementation never transforms content |
+| 5.2.2.6.  | `no-transform`     |  Required   |      ✔️      | See [Content Transformation Compliance](#content-transformation-compliance) |
 | 5.2.2.7.  | `private`          |     N/A     |     N/A     | Intended for shared caches; not applicable to private caches   |
 | 5.2.2.8.  | `proxy-revalidate` |     N/A     |     N/A     | Intended for shared caches; not applicable to private caches   |
 | 5.2.2.9.  | `public`           |  Optional   |      ✔️      |                                                                |
@@ -310,6 +310,22 @@ The following additional cache control directives are supported, as defined in v
 </details>
 </details>
 
+### Content Transformation Compliance
+
+This implementation maintains RFC 9111 compliance regarding the `no-transform` directive by enforcing a **storage-only** architecture:
+
+```go
+type Conn interface {
+    Get(key string) ([]byte, error)    // Returns byte-identical data
+    Set(key string, data []byte) error // Stores byte-identical data  
+    Delete(key string) error           // Simple deletion
+}
+```
+
+**Storage optimizations** (compression, encryption, serialization) are allowed because they return **byte-identical** HTTP responses. This differs from transformations mentioned in [RFC 9110 §7.7](https://www.rfc-editor.org/rfc/rfc9110#section-7.7), like image format conversion which change actual response content.
+
+**Custom backends:** Must return byte-identical responses. Use the [`store/acceptance`](https://pkg.go.dev/github.com/bartventer/httpcache/store/acceptance) test suite to verify compliance.
+
 ## License
 
 This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). See the [LICENSE](LICENSE) file for details.

helpers.go

@@ -24,14 +24,14 @@ import (
 
 func make504Response(req *http.Request) (*http.Response, error) {
 	var buf bytes.Buffer
-	buf.WriteString("HTTP/1.1 504 Gateway Timeout\r\n")
-	buf.WriteString("Cache-Control: no-cache\r\n")
-	buf.WriteString("Content-Length: 0\r\n")
-	buf.WriteString(
+	_, _ = buf.WriteString("HTTP/1.1 504 Gateway Timeout\r\n")
+	_, _ = buf.WriteString("Cache-Control: no-cache\r\n")
+	_, _ = buf.WriteString("Content-Length: 0\r\n")
+	_, _ = buf.WriteString(
 		internal.CacheStatusHeader + ": " + internal.CacheStatusBypass.Value + "\r\n",
 	)
-	buf.WriteString("Connection: close\r\n")
-	buf.WriteString("\r\n")
+	_, _ = buf.WriteString("Connection: close\r\n")
+	_, _ = buf.WriteString("\r\n")
 	return http.ReadResponse(bufio.NewReader(&buf), req)
 }
 

internal/cachecontrolevaluator.go internal/cacheabilityevaluator.gointernal/cachecontrolevaluator.go renamed to internal/cacheabilityevaluator.go

@@ -281,12 +281,12 @@ func (l *Logger) logCache(ctx context.Context, level slog.Level, msg string, lp
 		attrs = append(attrs, slog.String("trace_id", tracedID))
 	}
 	attrs = append(attrs,
-		groupAttrs("request",
+		slog.GroupAttrs("request",
 			slog.String("method", req.Method),
 			slog.String("url", req.URL.String()),
 			slog.String("host", req.Host),
 		),
-		groupAttrs("cache",
+		slog.GroupAttrs("cache",
 			slog.Any("status", event),
 			slog.String("url_key", cl.URLKey),
 		),
@@ -303,13 +303,3 @@ func (l *Logger) logCache(ctx context.Context, level slog.Level, msg string, lp
 	r.AddAttrs(attrs...)
 	_ = l.handler.Handle(ctx, r)
 }
-
-/*
-	+-------------------------------+
-	| Helpers  						|
-	+-------------------------------+
-*/
-
-func groupAttrs(key string, args ...slog.Attr) slog.Attr {
-	return slog.Attr{Key: key, Value: slog.GroupValue(args...)}
-}

internal/cachecontrolevaluator_test.go internal/cacheabilityevaluator_test.gointernal/cachecontrolevaluator_test.go renamed to internal/cacheabilityevaluator_test.go

@@ -343,8 +343,8 @@ func makeVaryHash(vary map[string]string) uint64 {
 	keys = slices.AppendSeq(keys, maps.Keys(vary))
 	slices.Sort(keys)
 	for _, k := range keys {
-		h.Write([]byte(k))
-		h.Write([]byte(vary[k]))
+		_, _ = h.Write([]byte(k))
+		_, _ = h.Write([]byte(vary[k]))
 	}
 	return h.Sum64()
 }

internal/directives.go internal/ccdirectives.gointernal/directives.go renamed to internal/ccdirectives.go

@@ -41,26 +41,22 @@ func (vm *varyMatcher) VaryHeadersMatch(entries ResponseRefs, reqHdr http.Header
 		bVary := strings.TrimSpace(b.Vary)
 
 		// Responses with Vary: "*" are least preferred
-		aIsStar := aVary == "*"
-		bIsStar := bVary == "*"
-		if aIsStar && !bIsStar {
+		switch aIsStar, bIsStar := aVary == "*", bVary == "*"; {
+		case aIsStar && !bIsStar:
 			return 1 // b preferred
-		}
-		if bIsStar && !aIsStar {
+		case bIsStar && !aIsStar:
 			return -1 // a preferred
 		}
 
 		// Responses with Vary headers are preferred over those without
-		aHasVary := aVary != ""
-		bHasVary := bVary != ""
-		if aHasVary && !bHasVary {
+		switch aHasVary, bHasVary := aVary != "", bVary != ""; {
+		case aHasVary && !bHasVary:
 			return -1 // a preferred
-		}
-		if !aHasVary && bHasVary {
+		case !aHasVary && bHasVary:
 			return 1 // b preferred
 		}
 
-		// If both have Vary headers, sort by Date or ResponseTime
+		// If both have Vary headers, sort by ReceivedAt (earliest first)
 		return a.ReceivedAt.Compare(b.ReceivedAt)
 	})