Turn repeated requests for unhashed URLs into 304 Not Modified

Unhashed URL responses now include an ETag header derived from the
content hash already computed at startup. When a browser sends
If-None-Match with a matching ETag, the server responds with 304
and an empty body instead of re-sending the file. Hashed URLs are
unaffected since they already use Cache-Control: immutable.

Key design decisions:
- ETags are pre-computed as quoted byte strings in _hash_files()
  alongside file_map and _reverse, so serving adds zero computation.
- Only unhashed URLs get ETags. Hashed URLs have the hash baked
  into the filename itself, making ETags redundant.

Author: audreyfeldroy

src/staticware/middleware.py

@@ -65,6 +65,8 @@ def __init__(
         self.file_map: dict[str, str] = {}
         # hashed relative path -> original relative path
         self._reverse: dict[str, str] = {}
+        # original relative path -> ETag value (quoted hash)
+        self._etags: dict[str, bytes] = {}
 
         self._hash_files()
 
@@ -100,6 +102,7 @@ def _hash_files(self) -> None:
 
             self.file_map[relative] = hashed
             self._reverse[hashed] = relative
+            self._etags[relative] = f'"{hash_val}"'.encode('latin-1')
 
     def url(self, path: str) -> str:
         """Return the cache-busted URL for a static file path.
@@ -155,7 +158,18 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
             await _send_text(send, 404, b"Not Found")
             return
         if file_path.exists() and file_path.is_file():
-            await _send_file(send, file_path)
+            etag = self._etags.get(relative_path)
+            if etag:
+                # Check for conditional request (If-None-Match)
+                for hdr_name, hdr_value in scope.get("headers", []):
+                    if hdr_name == b"if-none-match" and hdr_value == etag:
+                        await _send_text(send, 304, b"")
+                        return
+                await _send_file(
+                    send, file_path, extra_headers=[(b"etag", etag)]
+                )
+            else:
+                await _send_file(send, file_path)
             return
 
         await _send_text(send, 404, b"Not Found")

tests/test_staticware.py

@@ -461,3 +461,70 @@ async def test_serve_with_mismatched_mount_and_prefix(static_dir: Path) -> None:
     await static(scope, receive, resp)
     assert resp.status == 200
     assert resp.text == "body { color: red; }"
+
+
+# ── HashedStatic: ETag and conditional requests ──────────────────────
+
+
+def make_scope_with_headers(
+    path: str, headers: list[tuple[bytes, bytes]] | None = None
+) -> dict[str, Any]:
+    scope: dict[str, Any] = {"type": "http", "path": path, "method": "GET"}
+    if headers:
+        scope["headers"] = headers
+    return scope
+
+
+async def test_etag_on_unhashed_response(
+    static: HashedStatic, static_dir: Path
+) -> None:
+    """Original filename response includes an ETag header with the content hash."""
+    resp = ResponseCollector()
+    await static(make_scope("/static/styles.css"), receive, resp)
+    assert resp.status == 200
+
+    css_content = (static_dir / "styles.css").read_bytes()
+    h = expected_hash(css_content)
+    assert b"etag" in resp.headers, "Response should include an etag header"
+    assert resp.headers[b"etag"] == f'"{h}"'.encode("latin-1")
+
+
+async def test_conditional_request_returns_304(
+    static: HashedStatic, static_dir: Path
+) -> None:
+    """If-None-Match with matching ETag returns 304 and empty body."""
+    css_content = (static_dir / "styles.css").read_bytes()
+    h = expected_hash(css_content)
+    etag_value = f'"{h}"'.encode("latin-1")
+
+    scope = make_scope_with_headers(
+        "/static/styles.css",
+        headers=[(b"if-none-match", etag_value)],
+    )
+    resp = ResponseCollector()
+    await static(scope, receive, resp)
+    assert resp.status == 304
+    assert resp.body == b""
+
+
+async def test_conditional_request_mismatched_etag_returns_200(
+    static: HashedStatic,
+) -> None:
+    """If-None-Match with wrong ETag returns 200 with full body."""
+    scope = make_scope_with_headers(
+        "/static/styles.css",
+        headers=[(b"if-none-match", b'"wronghash"')],
+    )
+    resp = ResponseCollector()
+    await static(scope, receive, resp)
+    assert resp.status == 200
+    assert resp.text == "body { color: red; }"
+
+
+async def test_hashed_url_no_etag(static: HashedStatic) -> None:
+    """Hashed URL responses use immutable caching and should not include an ETag."""
+    hashed_name = static.file_map["styles.css"]
+    resp = ResponseCollector()
+    await static(make_scope(f"/static/{hashed_name}"), receive, resp)
+    assert resp.status == 200
+    assert b"etag" not in resp.headers, "Hashed URL should not include an etag header"