CDN Caching skill for Codex

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

interface:
  display_name: "CDN Caching"
  short_description: "High hit ratios without leaking anyone's page"
  default_prompt: "$cdn-caching Our Cloudflare cache hit ratio is 20 percent, find out why and fix the headers"

#!/usr/bin/env python3
"""Probe a URL through its CDN and explain what the cache did.

Requests the URL several times, prints the caching-relevant headers from each
response, recognises common CDN status headers (Cloudflare, CloudFront, Fastly,
Vercel, Netlify, Akamai, RFC 9211 Cache-Status) and flags configurations that
prevent shared caching.

Usage:
  python3 cache_probe.py https://example.com/assets/app.js
  python3 cache_probe.py https://example.com/ --count 3 --expect-hit
  python3 cache_probe.py https://example.com/api/x -H "Accept-Language: de"

Needs network access. Exit codes: 0 ok, 1 --expect-hit set but no hit seen
(or blocking problems found), 2 request failed.
"""
from __future__ import annotations

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

SHOW = [
    "cache-control", "cdn-cache-control", "surrogate-control", "cloudflare-cdn-cache-control",
    "vercel-cdn-cache-control", "netlify-cdn-cache-control", "age", "expires", "etag",
    "last-modified", "vary", "cache-status", "cf-cache-status", "x-cache", "x-cache-hits",
    "x-vercel-cache", "x-served-by", "x-amz-cf-pop", "cache-tag", "surrogate-key",
]
HIT = re.compile(r"\bhit\b|^hit|revalidated|stale", re.I)


def fetch(url: str, headers: dict[str, str], timeout: float):
    req = urllib.request.Request(url, headers={"User-Agent": "cache-probe/1.0", **headers})
    start = time.monotonic()
    try:
        resp = urllib.request.urlopen(req, timeout=timeout)
    except urllib.error.HTTPError as err:  # 4xx/5xx still carry cache headers
        resp = err
    body = resp.read()
    ms = (time.monotonic() - start) * 1000
    return resp.status, {k.lower(): v for k, v in resp.headers.items()}, resp.headers.get_all("set-cookie") or [], len(body), ms


def cache_state(h: dict[str, str]) -> str:
    for key in ("cf-cache-status", "x-vercel-cache", "x-cache", "cache-status"):
        if key in h:
            return f"{key}={h[key]}"
    if "age" in h:
        return f"age={h['age']} (no vendor status header)"
    return "unknown (no CDN status header)"


def is_hit(h: dict[str, str]) -> bool:
    for key in ("cf-cache-status", "x-vercel-cache", "x-cache", "cache-status"):
        if key in h and HIT.search(h[key]):
            return True
    try:
        return int(h.get("age", "0")) > 0
    except ValueError:
        return False


def problems(h: dict[str, str], cookies: list[str]) -> list[str]:
    out = []
    cc = ",".join(h.get(k, "") for k in ("cache-control", "cdn-cache-control", "surrogate-control")).lower()
    if not cc.strip(","):
        out.append("no Cache-Control: the CDN falls back to its defaults (often: do not cache HTML)")
    if "no-store" in cc or "private" in cc:
        out.append("private/no-store: shared caches must not store this response")
    if "max-age=0" in cc and "s-maxage" not in cc and "stale-while-revalidate" not in cc:
        out.append("max-age=0 without s-maxage: caches without an edge TTL override revalidate every request")
    if cookies:
        out.append(f"Set-Cookie present ({len(cookies)}): many CDNs bypass the cache for these by default")
    vary = h.get("vary", "").lower()
    if "*" in vary or "cookie" in vary or "user-agent" in vary:
        out.append(f"Vary: {h.get('vary')}: fragments the cache (near-zero hit ratio)")
    return out


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("url")
    p.add_argument("--count", type=int, default=2, help="number of requests (default 2)")
    p.add_argument("--delay", type=float, default=1.0, help="seconds between requests")
    p.add_argument("--timeout", type=float, default=15.0)
    p.add_argument("-H", "--header", action="append", default=[], help="extra request header 'Name: value'")
    p.add_argument("--expect-hit", action="store_true", help="exit 1 unless a later request is a cache hit")
    a = p.parse_args()

    extra = {}
    for item in a.header:
        if ":" not in item:
            print(f"error: bad header {item!r}", file=sys.stderr)
            return 2
        k, v = item.split(":", 1)
        extra[k.strip()] = v.strip()

    hits_after_first = False
    last_h: dict[str, str] = {}
    last_cookies: list[str] = []
    for i in range(1, a.count + 1):
        try:
            status, h, cookies, size, ms = fetch(a.url, extra, a.timeout)
        except (urllib.error.URLError, TimeoutError, OSError) as exc:
            print(f"error: request {i} failed: {exc}", file=sys.stderr)
            return 2
        print(f"--- request {i}: HTTP {status}, {size} bytes, {ms:.0f} ms, cache: {cache_state(h)}")
        for key in SHOW:
            if key in h:
                print(f"    {key}: {h[key]}")
        if cookies:
            print(f"    set-cookie: {len(cookies)} cookie(s)")
        if i > 1 and is_hit(h):
            hits_after_first = True
        last_h, last_cookies = h, cookies
        if i < a.count:
            time.sleep(a.delay)

    issues = problems(last_h, last_cookies)
    print("\nfindings:")
    for msg in issues or ["no blocking cache headers found"]:
        print(f"  - {msg}")
    print(f"  - later requests served from cache: {'yes' if hits_after_first else 'no'}")

    if a.expect_hit and not hits_after_first:
        print("\nFAIL: expected a cache hit after the first request")
        return 1
    return 0


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