http-latency-prober/docs/plans/2026-07-01-00-08-go-latency-tool.md

Plan: Website latency CLI tool (Go first, then Python)

Context

We're building a small CLI tool that measures the latency of one or more websites given their URLs. The point of difference from a naive timer is a full per-phase breakdown of an HTTP request — DNS resolution, TCP connect, TLS handshake, server processing (time-to-first-byte), and content transfer — not just a single total number.

We start simple (total latency only) and grow the tool in clear steps. The Go implementation comes first; once the user is satisfied, we port the same behaviour to Python. This plan also establishes project-wide working conventions (plans, changelog, per-feature docs) up front.

Design decisions confirmed with the user:

• Output: human-readable text by default, with a --json flag for machine output.
• Sampling: a --count/-n flag repeats N requests per URL and reports min/avg/max per phase.
• Input: accept multiple URLs as positional arguments, measured in turn.

Toolchain present: Go 1.26.4, Python 3.14.6.

Proposed layout

tt-excercise/
├── CLAUDE.md                 # working conventions (created first)
├── README.md                 # the assignment + implementation steps
├── CHANGELOG.md              # timestamped completed features
├── docs/
│   ├── plans/                # timestamped plans (this plan copied here)
│   └── usage/                # per-feature user documentation
├── go/
│   ├── go.mod                # module: latprobe (name adjustable)
│   ├── main.go               # CLI: flag parsing, orchestration, output
│   └── internal/probe/
│       └── probe.go          # timing logic via net/http/httptrace
└── python/                   # added later, during the port

Binary/module name proposed: latprobe (easy to change).

Foundation files (created at the start)

CLAUDE.md — working conventions

• Every plan is saved under docs/plans/ with a filename starting with the current timestamp in yyyy-mm-dd-hh-mm format (e.g. 2026-07-01-00-08-go-latency-tool.md).
• Every completed feature is appended to CHANGELOG.md with a timestamp.
• Every feature ships with user documentation under docs/usage/ including a concrete example of how to use it.

README.md — the assignment

• Project purpose: CLI tool to measure website latency, with a full per-request phase breakdown including DNS resolution.
• Two implementations: Go first, then a Python port.
• Usage sketch and the staged implementation roadmap (below).
• Note that Go 1.26 / Python 3.14 are the development versions.

CHANGELOG.md

• Seeded with a header; entries appended per completed feature.

Implementation steps (Go)

Each step is a self-contained, reviewable increment. We pause for the user's sign-off between steps. On completion of each: append to CHANGELOG.md and add its docs/usage/ page.

Step 0 — Scaffold. Create go/go.mod (go mod init latprobe), a minimal main.go that prints usage, and the directory structure. Confirms the toolchain builds.

Step 1 — Simple total latency. Accept a single URL argument, perform an HTTP GET, and print the total wall-clock time of the request. No breakdown yet. Reuse the standard library only (net/http, time).

Step 2 — Full per-phase breakdown (the core feature). Instrument the request with net/http/httptrace.ClientTrace to capture timestamps and derive each phase:

• DNS lookup (DNSStart → DNSDone)
• TCP connect (ConnectStart → ConnectDone)
• TLS handshake (TLSHandshakeStart → TLSHandshakeDone, HTTPS only)
• Server processing / TTFB (WroteRequest → GotFirstResponseByte)
• Content transfer (GotFirstResponseByte → response body fully read)
• Total Print an aligned text breakdown. httptrace is the key reusable stdlib piece — no third-party dependency needed.

Step 3 — Multiple URLs + sampling. Accept multiple positional URLs; add --count/-n (default 1) to repeat each URL N times and report min/avg/max per phase. Group output clearly per URL.

Step 4 — JSON output. Add a --json flag producing structured output (per URL, per phase, with the min/avg/max aggregates and sample count). Keep the human-readable text as the default.

Reasonable extras to consider later (not committed now): --timeout, --method, redirect handling, HTTP/2 vs HTTP/1.1 reporting, exit codes on failure.

Port to Python (after Go is approved)

Mirror the same CLI and output. Python has no direct httptrace equivalent, so the plan will measure phases at a lower level — e.g. custom timing around socket.getaddrinfo (DNS), connection establishment, and TLS wrap, or by using urllib3/httpx connection hooks. The detailed Python design will be drafted as its own plan (saved to docs/plans/) when we reach that stage.

Verification

• cd go && go build ./... succeeds at every step.
• Manual runs against known hosts, e.g.:
  • ./latprobe https://example.com → total only (Step 1), full breakdown (Step 2+).
  • ./latprobe -n 5 https://example.com https://www.google.com → min/avg/max per URL.
  • ./latprobe --json https://example.com → valid JSON (pipe through a JSON validator).
• Sanity-check phase numbers: phases should roughly sum to the total; HTTPS shows a TLS phase, plain HTTP does not.
• go vet ./... clean.

Bookkeeping at execution time

On exiting plan mode, before/with Step 0:

1. Copy this plan to docs/plans/2026-07-01-00-08-go-latency-tool.md.
2. Create CLAUDE.md, README.md, CHANGELOG.md as described above.