HTTP Caching Headers skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "HTTP Caching Headers"
  short_description: "Cache assets for a year, HTML for zero seconds"
  default_prompt: "$http-caching Users keep getting old JavaScript after deploys, fix our Cache-Control headers"

#!/usr/bin/env python3
"""Check HTTP caching headers for a list of URLs and flag policy problems.

Standard library only. For each URL it fetches the response headers, classifies the
resource (hashed static asset, other static asset, HTML document, API/other), checks
Cache-Control against the expected policy, and optionally sends a conditional request
to prove revalidation returns 304.

Usage:
  python3 check_cache_headers.py URL [URL ...] [--revalidate] [--header 'Name: value']
  python3 check_cache_headers.py --file urls.txt --revalidate

Exit code: 0 when no problems, 1 when any URL has a problem, 2 on usage errors.
"""
from __future__ import annotations

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

HASHED = re.compile(r"[.\-_][0-9a-zA-Z_-]{8,}\.(?:js|mjs|css|woff2?|png|jpe?g|webp|avif|svg|gif|ico|wasm)$")
STATIC = re.compile(r"\.(?:js|mjs|css|woff2?|ttf|png|jpe?g|webp|avif|svg|gif|ico|wasm|mp4|webm)$")


def parse_cc(value: str) -> dict[str, str | None]:
    out: dict[str, str | None] = {}
    for part in value.split(","):
        part = part.strip()
        if not part:
            continue
        k, _, v = part.partition("=")
        out[k.strip().lower()] = v.strip().strip('"') or None
    return out


def fetch(url: str, headers: dict[str, str]):
    req = urllib.request.Request(url, headers={"User-Agent": "cache-check/1.0", **headers})
    try:
        with urllib.request.urlopen(req, timeout=15) as r:
            r.read(1024)
            return r.status, r.headers
    except urllib.error.HTTPError as e:  # 304 and 4xx/5xx arrive here
        return e.code, e.headers


def classify(url: str, ctype: str) -> str:
    path = url.split("?", 1)[0]
    if HASHED.search(path):
        return "hashed-asset"
    if STATIC.search(path):
        return "static-asset"
    if "text/html" in ctype:
        return "html"
    return "other"


def check(url: str, extra: dict[str, str], revalidate: bool) -> list[str]:
    status, h = fetch(url, extra)
    cc_raw = h.get("Cache-Control", "")
    cc = parse_cc(cc_raw)
    kind = classify(url, h.get("Content-Type", ""))
    etag, lm = h.get("ETag"), h.get("Last-Modified")
    print(f"\n{url}\n  status={status} kind={kind}")
    for name in ("Cache-Control", "CDN-Cache-Control", "Surrogate-Control", "ETag",
                 "Last-Modified", "Vary", "Age", "Expires", "Set-Cookie"):
        if h.get(name):
            val = h.get(name) if name != "Set-Cookie" else "(present)"
            print(f"  {name}: {val}")

    problems: list[str] = []
    max_age = int(cc["max-age"]) if (cc.get("max-age") or "").isdigit() else None
    if status >= 400:
        print(f"  PROBLEM: HTTP {status} (cache policy not checked; pass auth with --header)")
        return [f"HTTP {status}"]
    if not cc_raw:
        problems.append("no Cache-Control: browsers apply heuristic freshness")
    if kind == "hashed-asset":
        if "no-store" in cc or "no-cache" in cc:
            problems.append("hashed asset is not cacheable; use public, max-age=31536000, immutable")
        elif max_age is None or max_age < 31536000:
            problems.append(f"hashed asset max-age={max_age}; expected 31536000")
        elif "immutable" not in cc:
            problems.append("hashed asset lacks immutable (reload triggers revalidation)")
    if kind == "static-asset" and max_age and max_age > 86400 and not (etag or lm):
        problems.append("un-hashed asset cached > 1 day with no validator; users may keep stale files")
    if kind == "html":
        if max_age and max_age > 600 and "s-maxage" not in cc:
            problems.append(f"HTML browser max-age={max_age}s; deploys will not reach users quickly")
    if h.get("Set-Cookie") and "public" in cc:
        problems.append("Set-Cookie on a public response: a shared cache may store a user's cookie")
    if "no-store" not in cc and not (etag or lm) and kind != "hashed-asset":
        problems.append("no ETag or Last-Modified: revalidation impossible, full re-download")

    if revalidate and (etag or lm):
        cond = dict(extra)
        if etag:
            cond["If-None-Match"] = etag
        if lm:
            cond["If-Modified-Since"] = lm
        rstatus, _ = fetch(url, cond)
        print(f"  conditional request -> {rstatus}")
        if rstatus != 304:
            problems.append(f"conditional request returned {rstatus}, expected 304")

    for p in problems:
        print(f"  PROBLEM: {p}")
    if not problems:
        print("  ok")
    return problems


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("urls", nargs="*")
    ap.add_argument("--file", help="file with one URL per line")
    ap.add_argument("--revalidate", action="store_true", help="send a conditional request and expect 304")
    ap.add_argument("--header", action="append", default=[], help="extra request header, 'Name: value'")
    a = ap.parse_args()
    urls = list(a.urls)
    if a.file:
        with open(a.file, encoding="utf-8") as f:
            urls += [ln.strip() for ln in f if ln.strip() and not ln.startswith("#")]
    if not urls:
        ap.print_usage(sys.stderr)
        return 2
    extra = {}
    for hv in a.header:
        k, _, v = hv.partition(":")
        extra[k.strip()] = v.strip()
    bad = 0
    for u in urls:
        try:
            if check(u, extra, a.revalidate):
                bad += 1
        except (urllib.error.URLError, OSError) as e:
            print(f"\n{u}\n  PROBLEM: request failed: {e}")
            bad += 1
    print(f"\n{len(urls)} URL(s) checked, {bad} with problems")
    return 1 if bad else 0


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