http-latency-prober/docs/plans/2026-07-02-11-14-hxprobe-file-input.md

# Plan: read target URLs from a file for hxprobe

## Context

`hxprobe` currently only accepts URLs as positional CLI arguments
(`hxprobe/hxprobe/cli.py:368`, `nargs="+"`). The user wants a file-based
input mode too, matching the existing convention `simple.py`/`phases.py`
already use (`python/simple.py:20-30`'s `load_sites()`: plain text, one URL
per line, `#`-comments and blank lines skipped, first whitespace-separated
token taken per line).

User-confirmed decisions:
- **Mutually exclusive** with positional URL args (either pass URLs on the
  command line, or `-f FILE`, never both).
- **hxprobe only** — `latprobe` is intentionally left untouched.
- **Add example fixture files** (`hxprobe/configs/*.txt`, mirroring
  `python/configs/*.txt`'s exact set: all-ok, dns-failure,
  connection-refused, timeout, tls-errors, http-errors, mixed) plus one new
  section in the existing `hxprobe/USAGE.md` demonstrating the flag.

## Implementation

**`hxprobe/hxprobe/cli.py`:**
- `urls` positional becomes `nargs="*"` (was `nargs="+"`) — no longer
  required on its own, since `-f` is now a second valid source.
- New flag: `-f, --file PATH` — "read URLs from a file, one per line,
  `#` comments allowed (mutually exclusive with positional url args)".
  Placed right after the `urls` positional definition in the argparse
  block, since the two are the two ways of specifying what to probe.
- New helper `_load_urls(path: str) -> list[str]`, duplicating (not
  importing) `simple.py`'s `load_sites()` logic — consistent with hxprobe's
  established "imports nothing outside its own directory" rule from the
  standalone-extraction work.
- After `parser.parse_args()`, manual validation (mirrors the existing
  `--timeout` invalid-value handling style — write to the injected
  `stderr`, `return EXIT_USAGE`, rather than routing through
  `argparse`'s mutually-exclusive-group machinery, which doesn't mix
  cleanly with a variadic positional):
  - both `ns.urls` and `ns.file` given → `parser.error(...)` (usage error,
    consistent with how `_Parser.error()` already handles bad usage)
  - neither given → `parser.error(...)`
  - `ns.file` given but unreadable (`FileNotFoundError`/`OSError`) →
    `stderr.write(...)`; `return EXIT_USAGE`
  - `ns.file` given but yields zero URLs → same treatment
  - otherwise `urls = _load_urls(ns.file)` or `urls = ns.urls`

**`hxprobe/tests/test_cli.py`:** new hermetic tests — successful multi-URL
run from a file, missing-file error, empty-file error, and the
both-sources-given usage error. Uses a temp file (`tempfile`), no network
needed for the parsing-error cases.

**`hxprobe/configs/*.txt`** (new directory) — same 7 fixtures as
`python/configs/`, adapted:
- `all-ok.txt`, `dns-failure.txt`, `connection-refused.txt`,
  `tls-errors.txt` — same URLs, same behavior (DNS/TCP/TLS failures are
  identical regardless of HTTP client sophistication); only the header
  comments change (`hxprobe -f configs/<name>.txt` instead of
  `python3.14 python/simple.py ...`).
- `timeout.txt` — same two targets (`10.255.255.1`, `192.0.2.1`, RFC 5737
  TEST-NET-1) as the original; "expected exit code" documents normal-network
  behavior (exit 4), same caveat the original file already carries about
  network-dependent behavior.
- `http-errors.txt` — same 404 URLs; header comment updated to show the
  demo command with `--fail` (hxprobe treats 4xx as success without
  `--fail`, unlike `simple.py`, which always raises on HTTPError) —
  "expected exit code" becomes 6, not `simple.py`'s blanket 1.
- `mixed.txt` — same mixed set; demo command includes `--fail`; expected
  exit code recalculated as the worst code across the included classes
  (dns=2, connect=3, tls=5, http=6 with `--fail`) → 6.
- Each header's "Expected exit code" will be verified by actually running
  the fixture through `hxprobe -f ...` during implementation, not assumed
  from the `simple.py` originals — hxprobe's worst-code-wins exit scheme
  (`hxprobe/hxprobe/cli.py:455-481`) differs fundamentally from
  `simple.py`'s blanket 0/1.

**`hxprobe/USAGE.md`:** new section "Reading URLs from a file (`-f`)",
placed after the "Multiple URLs" case (same family of "what to probe"
examples) — command + real captured output using `configs/all-ok.txt` or
`configs/mixed.txt`, plus a short list of the other fixture files available
and what each demonstrates.

**Docs housekeeping** (per CLAUDE.md convention): save this plan under
`docs/plans/`, write a summary under `docs/summaries/` after implementation,
append a `CHANGELOG.md` entry.

## Verification

1. `cd hxprobe && uv run python -m hxprobe -f configs/all-ok.txt` — probes
   all 3 URLs, exit 0.
2. `cd hxprobe && uv run python -m hxprobe -f configs/dns-failure.txt` —
   exit 2; `connection-refused.txt` → exit 3; `tls-errors.txt` → exit 5;
   `--fail -f configs/http-errors.txt` → exit 6; `--fail -f configs/mixed.txt`
   → exit 6 (confirms the worst-code documented in each header is accurate).
3. `uv run python -m hxprobe https://example.com -f configs/all-ok.txt` —
   usage error (both sources given).
4. `uv run python -m hxprobe -f /no/such/file` — usage error, clear message.
5. `cd hxprobe && make check` — new hermetic tests pass alongside the
   existing 28.
6. Re-run the new `hxprobe/USAGE.md` section's command and confirm captured
   output matches what's printed in the doc.
7. `grep -n "import" hxprobe/hxprobe/cli.py` — confirm no new import from
   `python/simple.py` or anywhere outside `hxprobe/`.