HTTP Caching skill for Claude Code

#!/usr/bin/env python3
"""Inspect HTTP caching headers for one or more URLs and test revalidation.

For each URL: fetch it, print caching-relevant headers (Cache-Control, ETag,
Last-Modified, Age, Vary, Expires, CDN cache status headers), send a conditional
request with If-None-Match / If-Modified-Since to check for 304, and flag common
mistakes based on what kind of resource it looks like.

Usage:
  python3 check_cache_headers.py URL [URL ...] [--kind auto|html|hashed|asset|api] [--header "Name: value"]

Exit code: 0 no errors (warnings allowed), 1 at least one error, 2 usage/network failure.
Standard library only (Python 3.10+).
"""
from __future__ import annotations

import argparse
import re
import sys
import urllib.error
import urllib.request

CDN_HEADERS = ["cf-cache-status", "x-cache", "x-vercel-cache", "x-served-by", "x-cache-hits",
               "cdn-cache-control", "cloudflare-cdn-cache-control", "surrogate-control", "x-amz-cf-pop",
               "fastly-debug-digest", "akamai-cache-status", "x-nf-request-id"]
SHOW = ["cache-control", "expires", "etag", "last-modified", "age", "vary", "content-type",
        "content-encoding", "set-cookie", "pragma"]
HASHED_RE = re.compile(r"[.\-_][0-9a-f]{8,}[.\-_]|[.\-_][A-Za-z0-9_-]{8,}\.(?:js|css|mjs|woff2?|png|jpe?g|webp|avif|svg)$")
ASSET_RE = re.compile(r"\.(?:js|mjs|css|woff2?|ttf|otf|png|jpe?g|gif|webp|avif|svg|ico|mp4|webm)(?:\?|$)", re.I)


class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, *args, **kwargs):  # report redirects instead of following silently
        return None


def fetch(url: str, extra: dict[str, str]) -> tuple[int, dict[str, str], str]:
    req = urllib.request.Request(url, headers={"User-Agent": "cache-check/1.0", "Accept-Encoding": "gzip, br", **extra})
    opener = urllib.request.build_opener(NoRedirect)
    try:
        with opener.open(req, timeout=20) as resp:
            headers = {k.lower(): v for k, v in resp.headers.items()}
            return resp.status, headers, resp.geturl()
    except urllib.error.HTTPError as err:  # 304, 3xx, 4xx, 5xx land here
        headers = {k.lower(): v for k, v in err.headers.items()} if err.headers else {}
        return err.code, headers, url


def parse_cc(value: str) -> dict[str, str | bool]:
    out: dict[str, str | bool] = {}
    for part in value.split(","):
        part = part.strip()
        if not part:
            continue
        key, _, val = part.partition("=")
        out[key.lower()] = val.strip('"') if val else True
    return out


def guess_kind(url: str, headers: dict[str, str]) -> str:
    path = url.split("?", 1)[0]
    if HASHED_RE.search(path):
        return "hashed"
    if ASSET_RE.search(path):
        return "asset"
    ctype = headers.get("content-type", "")
    if "text/html" in ctype:
        return "html"
    if "json" in ctype:
        return "api"
    return "asset"


def audit(url: str, kind: str, status: int, h: dict[str, str]) -> tuple[list[str], list[str]]:
    errors, warns = [], []
    cc = parse_cc(h.get("cache-control", ""))
    max_age = int(cc["max-age"]) if isinstance(cc.get("max-age"), str) and cc["max-age"].isdigit() else None
    s_maxage = int(cc["s-maxage"]) if isinstance(cc.get("s-maxage"), str) and cc["s-maxage"].isdigit() else None
    has_validator = "etag" in h or "last-modified" in h

    if 300 <= status < 400:
        warns.append(f"redirect {status} -> {h.get('location')}; each hop costs a round trip")
        return errors, warns
    if status >= 400:
        errors.append(f"status {status}: fix the response before auditing caching (check auth/URL)")
        return errors, warns
    if "cache-control" not in h:
        (errors if kind in ("hashed", "html") else warns).append("no Cache-Control header: caches apply heuristic freshness")
    if "public" in cc and "set-cookie" in h:
        errors.append("Cache-Control public with Set-Cookie: shared caches may store and serve one user's cookie")
    if h.get("vary", "").strip() == "*":
        warns.append("Vary: * makes responses effectively uncacheable")
    if "vary" in h and "user-agent" in h["vary"].lower():
        warns.append("Vary: User-Agent fragments CDN caches into thousands of variants")
    if kind == "hashed":
        if max_age is None or max_age < 31536000:
            errors.append("fingerprinted asset should use max-age=31536000 (1 year)")
        if "immutable" not in cc:
            warns.append("fingerprinted asset: add 'immutable' to skip revalidation on reload")
        if "no-cache" in cc or "no-store" in cc:
            errors.append("fingerprinted asset marked no-cache/no-store: wastes the fingerprint")
    elif kind == "html":
        if max_age and max_age > 300 and "must-revalidate" not in cc:
            errors.append(f"HTML cached for {max_age}s in browsers: deploys will not reach users until it expires")
        if not has_validator and "no-store" not in cc:
            warns.append("HTML without ETag/Last-Modified: revalidation downloads the full body")
    elif kind == "asset":
        if max_age is not None and max_age > 86400:
            warns.append("long max-age on a non-fingerprinted URL: users keep stale versions after deploys")
        if not has_validator:
            warns.append("no ETag/Last-Modified: cannot revalidate cheaply")
    elif kind == "api":
        if "private" not in cc and "no-store" not in cc and s_maxage is None and max_age:
            warns.append("API response cacheable by shared caches; confirm it is not user-specific (use private)")
    if "pragma" in h and "cache-control" in h:
        warns.append("Pragma is obsolete for responses; Cache-Control wins")
    return errors, warns


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("urls", nargs="+")
    ap.add_argument("--kind", choices=["auto", "html", "hashed", "asset", "api"], default="auto")
    ap.add_argument("--header", action="append", default=[], help='extra request header, e.g. "Cookie: a=b"')
    args = ap.parse_args()
    extra = {}
    for raw in args.header:
        name, sep, value = raw.partition(":")
        if not sep:
            print(f"bad --header {raw!r}", file=sys.stderr)
            return 2
        extra[name.strip()] = value.strip()

    total_errors = 0
    for url in args.urls:
        print(f"\n=== {url}")
        try:
            status, h, _ = fetch(url, extra)
        except (urllib.error.URLError, TimeoutError, ValueError) as exc:
            print(f"  FETCH FAILED: {exc}")
            return 2
        kind = guess_kind(url, h) if args.kind == "auto" else args.kind
        print(f"  status {status}   kind={kind}")
        for name in SHOW + CDN_HEADERS:
            if name in h:
                print(f"  {name}: {h[name]}")

        cond = {}
        if "etag" in h:
            cond["If-None-Match"] = h["etag"]
        if "last-modified" in h:
            cond["If-Modified-Since"] = h["last-modified"]
        if cond and status == 200:
            try:
                status2, h2, _ = fetch(url, {**extra, **cond})
                verdict = "OK (304 Not Modified)" if status2 == 304 else f"got {status2}, expected 304"
                print(f"  revalidation: {verdict}")
                if status2 != 304:
                    print("    note: a changing ETag per request (e.g. per-server or per-compression) defeats revalidation")
            except (urllib.error.URLError, TimeoutError) as exc:
                print(f"  revalidation request failed: {exc}")

        errors, warns = audit(url, kind, status, h)
        for e in errors:
            print(f"  ERROR: {e}")
        for w in warns:
            print(f"  WARN:  {w}")
        if not errors and not warns:
            print("  no issues found")
        total_errors += len(errors)

    print(f"\n{total_errors} error(s)")
    return 1 if total_errors else 0


if __name__ == "__main__":
    sys.exit(main())