redesign

adlist/cache.py

@@ -0,0 +1,34 @@
+"""HTTP cache policy of the completed converted representation."""
+import config
+
+def cache_headers(content_sha256: str, *, debug_mode: bool = False) -> dict[str, str]:
+    """Cache headers for a fully validated, byte-identical converted representation.
+
+    The ETag must describe the actual converted bytes, never the source ETag:
+    different sources, target IPs and debug output can have different bodies.
+    """
+    headers = {
+        "Content-Type": "text/plain; charset=utf-8",
+        "X-Content-Type-Options": "nosniff",
+    }
+    if debug_mode:
+        # Debug output contains request-specific information and timestamps.
+        headers["Cache-Control"] = "private, no-store"
+        headers["X-Debug-Mode"] = "1"
+    elif not config.CACHE_ENABLED or config.CACHE_S_MAXAGE == 0:
+        headers["Cache-Control"] = "no-store"
+    else:
+        headers["ETag"] = f'"{content_sha256}"'
+        directives = [
+            "public",
+            f"max-age={config.CACHE_MAX_AGE}",
+            f"s-maxage={config.CACHE_S_MAXAGE}",
+        ]
+        if config.CACHE_STALE_WHILE_REVALIDATE:
+            directives.append(
+                f"stale-while-revalidate={config.CACHE_STALE_WHILE_REVALIDATE}"
+            )
+        if config.CACHE_STALE_IF_ERROR:
+            directives.append(f"stale-if-error={config.CACHE_STALE_IF_ERROR}")
+        headers["Cache-Control"] = ", ".join(directives)
+    return headers