http-latency-prober/docs/summaries/2026-07-02-14-05-hxprobe-run-summary-footer.md

hxprobe: end-of-run summary footer — summary

Plan: docs/plans/2026-07-02-14-05-hxprobe-run-summary-footer.md.

Trigger: a follow-up to docs/explanations/2026-07-02-13-25-hxprobe-worst-exit-code-and-render-loop.md — does a single worst-code exit even make sense across multiple URLs with different possible errors? The answer landed on: keep the scalar exit code (it's a documented cross-implementation contract with latprobe/Go — see hxprobe/USAGE.md's Exit codes table, asserted by 13 existing tests), and instead add the missing visibility as an end-of-run summary footer.

What changed

All in hxprobe/hxprobe/cli.py unless noted, matching the plan exactly (no deviations):

1. _EXIT_LABELS (new, next to _PHASE_EXIT): inverse mapping from exit code → short label (ok, dns, connect, timeout, tls, http), used to render the footer's → exit N (label) line.

2. Accumulation loop refactor: previously computed a single running worst directly inside the per-URL loop via two different idioms (if c > worst: worst = c for network failures, max(worst, EXIT_HTTP) for --fail). Now each URL first gets its own code (EXIT_OK folded up via max() across its failed samples and, if --fail, its ≥400 successes), appended to a new url_codes: list[int] (index-aligned with urls), and then folded into worst = max(worst, code). Unifies both idioms into one.

3. _print_run_summary(urls, url_codes, worst, out) (new helper, next to _print_failure_summary): writes a separator line, an N URLs — X ok[, Y failed] header, one ✗ {label:<8}: {count} line per non-OK class present (first-seen order, same dedup style as _summarize_failures), and the closing → exit N (label) line.

4. Call site: elif len(urls) > 1: _print_run_summary(urls, url_codes, worst, stdout) — added after the per-URL loop, in the else branch of the existing if ns.json_out: check (so it's text-mode-only), right before return worst. JSON path (json.dumps(json_items, ...)) is completely untouched — still a bare array, no top-level summary object, preserving the documented "same shape as latprobe's JSON" contract.

Design decisions (confirmed with user before implementing)

• Exit code stays a scalar (worst/highest severity across URLs) — not count-of-failed-URLs, not binary 0/1. Both alternatives were presented and rejected because they'd break the documented 0–6 table, Go/latprobe parity, and the 13 existing exit-code tests.
• Summary is a text footer, multi-URL only (len(urls) > 1) — not always shown, and not also duplicated into JSON as a top-level object (which would turn the JSON array into an object and break the documented array-shape parity). Single-URL text output is untouched; JSON output is untouched.

Tests

hxprobe/tests/test_cli.py: new TestCLIRunSummary class, 3 tests, reusing the existing _OKHandler/_start_server/_free_port/_invoke harness:

• test_multi_url_mixed_shows_summary — one OK URL + one connection-refused URL: asserts EXIT_CONNECT, and the footer strings ("Summary: 2 URLs", "1 ok", "1 failed", "connect : 1", "→ exit 3").
• test_multi_url_all_ok_summary — two OK URLs: asserts EXIT_OK, "Summary: 2 URLs — 2 ok", and no "✗" anywhere in output.
• test_single_url_has_no_summary — one OK URL: asserts "Summary:" is absent (locks the multi-URL-only rule).

All 33 pre-existing tests pass unedited (33 + 3 new = 36 total).

Verification

• hxprobe/.venv/bin/python -m pytest tests/test_cli.py tests/test_probe.py -q → 36 passed.
• hxprobe/.venv/bin/ruff check hxprobe/ tests/ → all checks passed.
• Manual smoke tests, all matching the plan's expected behavior exactly:
  • hxprobe https://example.com https://example.org → footer Summary: 2 URLs — 2 ok / → exit 0 (ok).
  • hxprobe https://example.com http://no.such.host.invalid → footer Summary: 2 URLs — 1 ok, 1 failed / ✗ dns : 1 / → exit 2 (dns); process exit code confirmed 2 via echo $?.
  • hxprobe https://example.com (single URL) → no footer, output byte-for-byte the same shape as before this change.
  • hxprobe --json https://example.com https://example.org → still a bare JSON array, no summary object.
  • Also captured a 3-URL mixed run (example.com ok, DNS failure, TLS failure against self-signed.badssl.com) to confirm severity ordering in the footer: DNS (2) and TLS (5) both counted, exit reported as 5 (tls) — the higher-severity class correctly wins the scalar while the footer still shows the DNS failure that the scalar alone would hide.

Docs updated (per CLAUDE.md conventions)

• hxprobe/USAGE.md: new "Multi-URL summary footer" section with a real 3-URL mixed-outcome capture; refreshed the pre-existing "Multiple URLs" and -f configs/all-ok.txt / -f configs/dns-failure.txt examples, which were captured before this feature existed and were now stale (missing the footer) — replaced with fresh live captures; added a sentence to the Exit codes section pointing at the new section.
• docs/usage/hxprobe.md: one-line addition to the exit-codes bullet pointing at hxprobe/USAGE.md's new section.
• docs/explanations/2026-07-02-13-25-hxprobe-worst-exit-code-and-render-loop.md: appended an "Update (2026-07-02)" paragraph pointing forward to this work, per the plan's "optional — pointer instead of a new file" option.
• CHANGELOG.md: new entry at the top.
• This file.

No deviations from the approved plan.