Jan Novak
f487a4b1bd
Plans (docs/plans/): - 2026-07-01-23-47-py-hxprobe-httpx.md — initial httpx probe design - 2026-07-02-09-32 through 14-05 — standalone project, toolchain, usage doc + Makefile, file input (-f), simplification pass, run-summary footer Summaries (docs/summaries/): one per completed feature, recording what was actually built, deviations from the plan, and verification steps Explanations (docs/explanations/): two deep-dives written during review — hxprobe concurrency model and worst-exit-code + render-loop analysis Usage (docs/usage/hxprobe.md): overview with pointer to hxprobe/USAGE.md for the full runnable reference Walkthrough (docs/py-latprobe-walkthrough.md): narrative tour of the latprobe Python package for interview / code-review context CHANGELOG.md: entries for all hxprobe features (toolchain, usage doc, file input, simplification, run-summary footer) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
75 lines
4.0 KiB
Markdown
75 lines
4.0 KiB
Markdown
# Summary: hxprobe usage reference doc + standalone Makefile
|
||
|
||
Plan: [docs/plans/2026-07-02-10-22-hxprobe-usage-doc-and-makefile.md](../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
|