TTFB Optimization skill for Claude Code

#!/usr/bin/env python3
"""Break TTFB into network and server phases over repeated curl requests (stdlib only).

Runs `curl` N times against a URL (or parses saved output), then prints median and
p90 for DNS, TCP connect, TLS, server wait (request sent -> first byte), and
download, aggregates any Server-Timing header entries, shows cache-related headers,
and names the dominant phase.

Usage:
  python3 ttfb_breakdown.py URL [-n 10] [-H "Cookie: session=..."]
  python3 ttfb_breakdown.py --from saved.txt      # output captured earlier by this script's --raw
  python3 ttfb_breakdown.py URL --raw > saved.txt # save raw curl output for later comparison
  python3 ttfb_breakdown.py URL --budget 600      # exit 1 if median TTFB exceeds 600 ms

Each run is a fresh curl process, so DNS (unless OS-cached), TCP and TLS are paid
every time, like a first visit; server_wait isolates backend time from that. Exit: 0 ok, 1 budget
exceeded or all requests failed, 2 usage error.
"""
import argparse
import re
import shutil
import statistics
import subprocess
import sys

MARK = "__TIMING__"  # must not start with "@": curl reads -w @file
FMT = (MARK + " code=%{http_code} dns=%{time_namelookup} connect=%{time_connect} "
       "tls=%{time_appconnect} pre=%{time_pretransfer} ttfb=%{time_starttransfer} "
       "total=%{time_total} size=%{size_download} ip=%{remote_ip}\\n")
CACHE_HDRS = ("cache-control", "age", "x-cache", "cf-cache-status", "x-vercel-cache",
              "x-nextjs-cache", "cdn-cache-control", "vary", "server", "via", "set-cookie")


def run_curl(url, headers, n):
    if not shutil.which("curl"):
        sys.exit("error: curl not found on PATH")
    chunks = []
    for _ in range(n):
        cmd = ["curl", "-s", "-o", "/dev/null", "-D", "-", "-w", FMT, "--compressed"]
        for h in headers:
            cmd += ["-H", h]
        cmd.append(url)
        res = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
        chunks.append(res.stdout)
    return "".join(chunks)


def parse(raw):
    samples, header_sets = [], []
    current = {}
    for line in raw.splitlines():
        if line.startswith(MARK):
            vals = dict(kv.split("=", 1) for kv in line[len(MARK):].split())
            samples.append(vals)
            header_sets.append(current)
            current = {}
        elif ":" in line and not line.startswith("HTTP/"):
            k, v = line.split(":", 1)
            current.setdefault(k.strip().lower(), []).append(v.strip())
        elif line.startswith("HTTP/"):
            current = {}  # redirects or 100-continue: keep only the final header block
    return samples, header_sets


def phases(s):
    f = {k: float(s[k]) for k in ("dns", "connect", "tls", "pre", "ttfb", "total")}
    tls_end = f["tls"] if f["tls"] > 0 else f["connect"]
    return {
        "dns": f["dns"],
        "tcp": max(f["connect"] - f["dns"], 0),
        "tls": max(tls_end - f["connect"], 0) if f["tls"] > 0 else 0.0,
        "server_wait": max(f["ttfb"] - f["pre"], 0),
        "ttfb": f["ttfb"],
        "download": max(f["total"] - f["ttfb"], 0),
        "total": f["total"],
    }


def pct(values, p):
    v = sorted(values)
    if len(v) == 1:
        return v[0]
    k = (len(v) - 1) * p
    lo = int(k)
    hi = min(lo + 1, len(v) - 1)
    return v[lo] + (v[hi] - v[lo]) * (k - lo)


def server_timing(header_sets):
    agg = {}
    for hs in header_sets:
        for value in hs.get("server-timing", []):
            for entry in value.split(","):
                name = entry.split(";")[0].strip()
                m = re.search(r"dur=([\d.]+)", entry)
                if name and m:
                    agg.setdefault(name, []).append(float(m.group(1)))
    return agg


def main():
    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    ap.add_argument("url", nargs="?")
    ap.add_argument("-n", type=int, default=10, help="number of requests (default 10)")
    ap.add_argument("-H", action="append", default=[], help="extra request header")
    ap.add_argument("--from", dest="src", help="parse saved raw output instead of running curl")
    ap.add_argument("--raw", action="store_true", help="print raw curl output and exit")
    ap.add_argument("--budget", type=float, help="median TTFB budget in ms")
    a = ap.parse_args()

    if a.src:
        with open(a.src, encoding="utf-8") as fh:
            raw = fh.read()
    elif a.url:
        raw = run_curl(a.url, a.H, a.n)
        if a.raw:
            print(raw, end="")
            return 0
    else:
        ap.print_usage(sys.stderr)
        return 2

    samples, header_sets = parse(raw)
    ok = [(s, h) for s, h in zip(samples, header_sets) if s.get("code", "000") != "000"]
    if not ok:
        print("error: no successful responses (code 000 = connection failed)", file=sys.stderr)
        return 1
    codes = sorted({s["code"] for s, _ in ok})
    ph = [phases(s) for s, _ in ok]
    print(f"requests: {len(ok)}/{len(samples)} ok  status: {', '.join(codes)}  ip: {ok[-1][0].get('ip', '?')}")
    print(f"{'phase':<13}{'median ms':>10}{'p90 ms':>9}")
    for key in ("dns", "tcp", "tls", "server_wait", "ttfb", "download", "total"):
        vals = [p[key] * 1000 for p in ph]
        print(f"{key:<13}{statistics.median(vals):>10.1f}{pct(vals, 0.9):>9.1f}")

    st = server_timing([h for _, h in ok])
    if st:
        print("\nServer-Timing (median ms):")
        for name, vals in sorted(st.items(), key=lambda kv: -statistics.median(kv[1])):
            print(f"  {name:<20}{statistics.median(vals):>8.1f}  (n={len(vals)})")

    last = ok[-1][1]
    shown = [(k, last[k]) for k in CACHE_HDRS if k in last]
    if shown:
        print("\nCache/edge headers (last response):")
        for k, v in shown:
            print(f"  {k}: {' | '.join(v)}")

    med = {k: statistics.median([p[k] for p in ph]) for k in ph[0]}
    net = med["dns"] + med["tcp"] + med["tls"]
    ttfb_ms = med["ttfb"] * 1000
    print(f"\nmedian TTFB {ttfb_ms:.0f} ms (network setup ~{net * 1000:.0f} ms + server wait ~{med['server_wait'] * 1000:.0f} ms)")
    if med["server_wait"] >= net:
        print("dominant: server wait -> profile the request path (app, DB, upstream calls) or cache the response")
    else:
        print("dominant: connection setup -> serve from an edge/CDN closer to users, enable HTTP/2+/3, check TLS and DNS")
    if a.budget is not None and ttfb_ms > a.budget:
        print(f"FAIL: median TTFB {ttfb_ms:.0f} ms exceeds budget {a.budget:.0f} ms")
        return 1
    return 0


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