Jan Novak
16fff2f964
- Rename python/configs/usage.md → usage-simple.md so both scripts have a parallel runnable reference file in the same directory - Add python/configs/usage-phases.md: runnable sh commands + real expected output for phases.py against every error-path config, including a note on the key difference from simple.py (HTTP 4xx exits 0 in phases.py vs 1 in simple.py because phases.py completes at the network level) - Update doc cross-links in docs/usage/py-simple.md and py-phases.md Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
80 lines
2.3 KiB
Markdown
80 lines
2.3 KiB
Markdown
# `simple.py` — Site Reachability Checker
|
|
|
|
## What it does
|
|
|
|
Reads a plain-text list of URLs, issues an HTTP GET to each one, and reports
|
|
whether the site responded and how long it took (full wall-clock time including
|
|
body download). This is the simplest possible latency check — one line of
|
|
output per site, nothing more.
|
|
|
|
## Flags / arguments
|
|
|
|
```
|
|
python simple.py [sites.txt]
|
|
```
|
|
|
|
| Argument | Default | Meaning |
|
|
|----------|---------|---------|
|
|
| `sites.txt` | `sites.txt` in the current directory | Path to the plain-text config file |
|
|
|
|
**Config file format:**
|
|
- One URL per line.
|
|
- Lines starting with `#` are comments and are ignored.
|
|
- Blank lines are ignored.
|
|
- Future `key=value` tokens after the URL (e.g. `https://x.com budget=200ms`)
|
|
are silently ignored, so the file format is forward-compatible.
|
|
|
|
**Exit codes:**
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| 0 | All sites responded |
|
|
| 1 | One or more sites failed, or a usage/config error |
|
|
|
|
## Example
|
|
|
|
**Config (`sites.txt`):**
|
|
```
|
|
https://example.com
|
|
https://www.google.com
|
|
# https://httpbin.org/get # uncomment to include
|
|
```
|
|
|
|
**Run:**
|
|
```sh
|
|
python simple.py sites.txt
|
|
```
|
|
|
|
**Expected output (latencies vary):**
|
|
```
|
|
OK 147.11 ms https://example.com
|
|
OK 83.42 ms https://www.google.com
|
|
```
|
|
|
|
**With an unreachable host:**
|
|
```
|
|
OK 147.11 ms https://example.com
|
|
FAIL (nodename nor servname provided, or not known) https://nonexistent.invalid
|
|
```
|
|
Exit code: `1`
|
|
|
|
## Example config files
|
|
|
|
`python/configs/` contains purpose-built config files targeting every distinct
|
|
failure class (DNS, connection-refused, timeout, TLS-cert errors, HTTP 4xx/5xx,
|
|
and a mixed scenario). Each file includes a comment explaining what it exercises.
|
|
|
|
See [`python/configs/usage-simple.md`](../../python/configs/usage-simple.md) for the runnable
|
|
shell commands and expected output for each file.
|
|
|
|
## Limitations
|
|
|
|
- Measures total wall-clock time (DNS + TCP + TLS + server + transfer) as a
|
|
single number. Use `phases.py` for a per-phase breakdown.
|
|
- Always uses GET; no auth, no custom headers, no redirect control.
|
|
- Timeout is hard-coded at 10 s. Use `phases.py` or `latprobe/` for a `--timeout`
|
|
flag.
|
|
- HTTP error statuses (4xx, 5xx) are reported as `FAIL` — `urllib.request.urlopen`
|
|
raises `HTTPError` for non-2xx responses, so a 404 is treated as a failure,
|
|
not a success.
|