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>
113 lines
5.7 KiB
Markdown
113 lines
5.7 KiB
Markdown
# Plan: hxprobe-specific usage doc (case-by-case) + hxprobe-specific Makefile
|
||
|
||
## Context
|
||
|
||
`hxprobe` is a fully standalone project (own `pyproject.toml`, `uv.lock`,
|
||
`README.md` — see `docs/summaries/2026-07-02-09-32-hxprobe-standalone-project.md`
|
||
and `...-toolchain-modernization.md`). Two gaps remain versus the other
|
||
Python implementations and versus hxprobe's own "could be `cp -r`'d to its
|
||
own repo" design goal:
|
||
|
||
1. **Docs**: `latprobe`/`phases.py`/`simple.py` each have two usage docs —
|
||
the CLAUDE.md-mandated `docs/usage/py-<name>.md` (what/flags/one example)
|
||
_and_ a much richer `python/configs/usage-<name>.md` "Runnable Usage
|
||
Reference" walking through a full set of concrete cases with real
|
||
captured output (confirmed by reading `python/configs/usage-latprobe.md`,
|
||
313 lines: basic, verbose × 4 variants, sampling, multi-URL, `--fail`,
|
||
JSON × 2, timeout, exit-codes table, Makefile shortcuts). `hxprobe` only
|
||
has the first kind. User confirmed: add the second kind, placed _inside_
|
||
`hxprobe/` itself (not under `python/configs/`, since hxprobe no longer
|
||
lives there) so the doc travels with the project if extracted.
|
||
2. **Makefile**: hxprobe currently has no `Makefile` of its own — the only
|
||
way to run/test/lint it is through the parent repo's root `Makefile`.
|
||
Extracted to its own repo, there'd be no `make` interface left. User
|
||
confirmed: add `hxprobe/Makefile`, fully independent from the root
|
||
Makefile's existing `hx-*` targets (no delegation either direction —
|
||
both keep their own complete logic, at the cost of some duplication).
|
||
|
||
Confirmed: neither `latprobe` nor `hxprobe` accept a config file (both take
|
||
URLs as positional CLI args — only `simple.py`/`phases.py` read the
|
||
`python/configs/*.txt` files), so no `.txt`-config-file equivalent is needed
|
||
for hxprobe; this is a docs+Makefile-only task.
|
||
|
||
## Changes
|
||
|
||
**`hxprobe/USAGE.md`** (new) — modeled directly on
|
||
`python/configs/usage-latprobe.md`'s structure and tone (concrete `sh`
|
||
command blocks immediately followed by real captured output, real IPs/certs/
|
||
timings, brief explanatory notes, `---` section separators). Cases, in order:
|
||
|
||
1. Basic — single URL
|
||
2. Verbose — HTTPS site (shows `Protocol: HTTP/2`, TLS, cert)
|
||
3. Verbose — plain HTTP (no TLS block)
|
||
4. Verbose — redirect followed by default (`http://github.com` → 200,
|
||
`Protocol: HTTP/2 (1 redirect)`) — **hxprobe-specific**, latprobe has no
|
||
equivalent
|
||
5. `--no-follow-redirects` — same URL, raw `301` instead — **hxprobe-specific**
|
||
6. `--no-http2` — forces `Protocol: HTTP/1.1` — **hxprobe-specific**
|
||
7. Verbose — TLS failure (expired cert, badssl.com)
|
||
8. Verbose — DNS failure (empty verbose block, suppressed)
|
||
9. Sampling (`-n`) — min/avg/max table, plus verbose+sampling
|
||
10. Multiple URLs (parallel probing)
|
||
11. `--fail` flag — exit 6 on HTTP 4xx
|
||
12. JSON output
|
||
13. JSON + verbose (includes `http_version`/`redirect_count` keys)
|
||
14. Timeout
|
||
15. Exit codes table (same 0–6 scheme as `latprobe`/Go)
|
||
16. Makefile shortcuts — both the new `hxprobe/Makefile` (`make run`,
|
||
`make test`, etc., run from inside `hxprobe/`) and the parent repo's
|
||
root shortcuts (`make hx-run`, run from the repo root)
|
||
|
||
Cases 1, 2, 3, 4, 5, 6, 8, 11 can reuse real output already captured earlier
|
||
in this session (still accurate — no code changed since). Cases 7, 9, 10,
|
||
12, 13, 14 need fresh live runs during implementation to get real numbers
|
||
(same standard the other `usage-*.md` docs hold themselves to — no
|
||
fabricated timings).
|
||
|
||
**`docs/usage/hxprobe.md`** (edit) — add a one-line pointer near the top:
|
||
"For a full case-by-case runnable reference, see `hxprobe/USAGE.md`." No
|
||
other changes; it stays the CLAUDE.md-mandated summary doc.
|
||
|
||
**`hxprobe/Makefile`** (new) — fully self-sufficient, same auto-generated
|
||
`## comment` help style as the root Makefile, short target names (no `hx-`
|
||
prefix needed since it's already scoped by being inside `hxprobe/`):
|
||
|
||
```makefile
|
||
PYTHON ?= python3.14
|
||
ARGS ?=
|
||
.DEFAULT_GOAL := help
|
||
|
||
help # auto-generated from ## comments, same style as root Makefile
|
||
deps # uv sync
|
||
run # uv run python -m hxprobe $(ARGS) (deps: deps)
|
||
lint # uv run ruff check . (deps: deps)
|
||
fmt # uv run ruff format . (deps: deps)
|
||
test # uv run pytest tests -m "not integration" -v $(ARGS) (deps: deps)
|
||
test-integration # uv run pytest tests -m integration -v $(ARGS) (deps: deps)
|
||
check # lint + test
|
||
clean # remove __pycache__/*.pyc/*.egg-info/.pytest_cache/.ruff_cache
|
||
```
|
||
|
||
No changes to the root `Makefile` — its existing `hx-*` targets are left
|
||
exactly as-is per the "keep both independent" decision.
|
||
|
||
**Docs housekeeping** (per CLAUDE.md convention): save this plan to
|
||
`docs/plans/<timestamp>-hxprobe-usage-doc-and-makefile.md`, write a summary
|
||
to `docs/summaries/<timestamp>-hxprobe-usage-doc-and-makefile.md` after
|
||
implementation, and append a `CHANGELOG.md` entry.
|
||
|
||
## Verification
|
||
|
||
1. `cd hxprobe && make help` — lists all targets with descriptions, works
|
||
with zero dependency on the parent repo's Makefile.
|
||
2. `cd hxprobe && make run ARGS="-v https://example.com"` — same output as
|
||
`make hx-run ARGS="-v https://example.com"` from the repo root (proves
|
||
the two Makefiles agree, without one calling the other).
|
||
3. `cd hxprobe && make check` — lint + hermetic tests pass (28 tests).
|
||
4. `cd hxprobe && make test-integration` — 9 live tests pass.
|
||
5. Re-run every command block in `hxprobe/USAGE.md` and confirm the
|
||
captured output matches what's printed in the doc (structure must be
|
||
stable even if exact millisecond timings drift).
|
||
6. Confirm the root `Makefile`'s `hx-*` targets are byte-for-byte unchanged
|
||
(`git diff Makefile` shows no `hx-*` section changes from this task).
|