http-latency-prober/docs/summaries/2026-07-02-10-22-hxprobe-usage-doc-and-makefile.md

Summary: hxprobe usage reference doc + standalone Makefile

Plan: docs/plans/2026-07-02-10-22-hxprobe-usage-doc-and-makefile.md

What was built

• hxprobe/USAGE.md (new): a "Runnable Usage Reference" matching the depth/format of python/configs/usage-latprobe.md (concrete sh command → real captured output, brief explanatory notes, --- section separators). 16 cases: basic, verbose (HTTPS, plain HTTP, redirect followed, --no-follow-redirects, --no-http2, TLS failure, DNS failure), sampling, multi-URL, --fail, JSON, JSON+verbose, timeout, exit-codes table, Makefile shortcuts (both hxprobe/Makefile's own and the parent repo's hx-* ones). Placed inside hxprobe/ per the user's explicit choice, so the doc travels with the project if it's ever extracted to its own repo.
• docs/usage/hxprobe.md (edit): one-line pointer added at the top to hxprobe/USAGE.md. No other changes.
• hxprobe/Makefile (new): standalone, help/deps/run/lint/ fmt/test/test-integration/check/clean, same auto-generated ## comment help style as the root Makefile. Deliberately independent from the root Makefile's hx-* targets (neither calls into the other) — explicit user decision over the "delegate" alternative.

Key design decisions

• Every output in USAGE.md is real, freshly captured this session — 10 of 16 cases were run live during implementation specifically for this doc (TLS failure, sampling ×2, multi-URL, --fail, JSON ×2, timeout, basic, plain-HTTP), the rest reused real captures from earlier in the same session (redirect-follow, --no-follow-redirects, --no-http2, DNS failure) since the code hadn't changed since those were taken. No numbers were fabricated or extrapolated.
• Timeout example uses 192.0.2.1, not 10.255.255.1. Tested both: 10.255.255.1 resolves to an immediate connect: Connection refused in this dev sandbox (the sandbox's network layer actively rejects the packet rather than dropping it silently), which would misrepresent the timeout path. 192.0.2.1 (RFC 5737 TEST-NET-1, reserved/unreachable) reliably produces a genuine ~500ms timeout here, so that's what the doc uses and explains.
• No delegation between the two Makefiles, per explicit user instruction — both have complete, independent implementations of the same uv sync/uv run pytest/ruff commands. This is deliberate duplication: a change to one Makefile's command flags won't silently break the other, at the cost of needing to update both if the underlying uv run ... invocations ever change.
• hxprobe/Makefile target names have no hx- prefix (run, test, not hx-run, hx-test) since the prefix's whole purpose — disambiguating from go-*/py-* targets in the same file — doesn't apply once you're already inside hxprobe/'s own Makefile.

Deviations from the plan

One, driven by what the live network in this sandbox actually does: the plan didn't anticipate the timeout target needing to change from 10.255.255.1 (used in latprobe's own timeout example) to 192.0.2.1. Discovered and resolved by testing both live before writing the doc, rather than assuming latprobe's example target would work identically for hxprobe.

Verification

• cd hxprobe && make help — lists all 9 targets, no dependency on the root Makefile
• cd hxprobe && make run ARGS="-v https://example.com" — matches make hx-run ARGS="-v https://example.com" output shape from the repo root (both Makefiles agree independently)
• cd hxprobe && make check — 28 hermetic tests pass (lint + test)
• cd hxprobe && make test-integration — 9 live tests pass
• Every command block in USAGE.md was actually executed during authoring; output pasted directly from the terminal, not hand-edited beyond JSON float-precision rounding (documented as such in the doc)
• git diff Makefile — confirms the root Makefile's hx-* section is unchanged by this task