# Custom Usage Examples

All examples assume the binary has been built first:

```sh
make build
# binary is now at go/latprobe
```

Estimated runtimes assume a typical home broadband connection.
The timeout flag is shortened to `--timeout 3s` wherever non-routable IPs are
used, so each timed-out sample fails in 3 s instead of the default 10 s.

---

## Example 1 — Clean global sweep, text output (single sample)

10 sites distributed across continents, one request each.
**All sites accessible. Exit code: 0.**

```sh
./go/latprobe \
  https://www.google.com \
  https://www.bbc.co.uk \
  https://www.lemonde.fr \
  https://www.spiegel.de \
  https://www.yahoo.co.jp \
  https://www.alibaba.com \
  https://www.globo.com \
  https://www.abc.net.au \
  https://www.thehindu.com \
  https://www.timeslive.co.za
```

*Estimated runtime: ~30 s — shows per-phase breakdown once per site.*

---

## Example 2 — Clean global sweep, 10 samples, text output

Same 10 sites, 10 requests each — reveals real latency distribution (min/avg/max).
**All sites accessible. Exit code: 0.**

```sh
./go/latprobe -n 10 \
  https://www.google.com \
  https://www.bbc.co.uk \
  https://www.lemonde.fr \
  https://www.spiegel.de \
  https://www.yahoo.co.jp \
  https://www.alibaba.com \
  https://www.globo.com \
  https://www.abc.net.au \
  https://www.thehindu.com \
  https://www.timeslive.co.za
```

*Estimated runtime: ~3–5 min — best for spotting jitter and TTFB variance.*

---

## Example 3 — Clean global sweep, 10 samples, JSON output

Same as Example 2, machine-readable. Pipe into `jq` to extract specific phases.
**All sites accessible. Exit code: 0.**

```sh
./go/latprobe -n 10 --json \
  https://www.google.com \
  https://www.bbc.co.uk \
  https://www.lemonde.fr \
  https://www.spiegel.de \
  https://www.yahoo.co.jp \
  https://www.alibaba.com \
  https://www.globo.com \
  https://www.abc.net.au \
  https://www.thehindu.com \
  https://www.timeslive.co.za

# Extract average total latency per site:
./go/latprobe -n 10 --json \
  https://www.google.com https://www.bbc.co.uk https://www.lemonde.fr \
  https://www.spiegel.de https://www.yahoo.co.jp https://www.alibaba.com \
  https://www.globo.com https://www.abc.net.au https://www.thehindu.com \
  https://www.timeslive.co.za \
  | jq '.[] | {url, avg_total_ms: .phases.total.avg_ms}'
```

*Estimated runtime: ~3–5 min.*

---

## Example 4 — DNS failures mixed in (exit code 2)

8 accessible sites + 2 non-existent domains.
The `.invalid` TLD is guaranteed NXDOMAIN by RFC 6761.
**Expected exit code: 2.**

```sh
./go/latprobe -n 10 \
  https://www.google.com \
  https://www.bbc.co.uk \
  https://www.lemonde.fr \
  https://www.spiegel.de \
  https://www.yahoo.co.jp \
  https://www.alibaba.com \
  https://www.globo.com \
  https://www.abc.net.au \
  https://nonexistent-host-one.invalid \
  https://nonexistent-host-two.invalid
```

*Estimated runtime: ~2–3 min — DNS failures resolve near-instantly.*

---

## Example 5 — Connection refused mixed in (exit code 3)

8 accessible sites + 2 localhost ports with nothing listening.
**Expected exit code: 3.**

```sh
./go/latprobe -n 10 \
  https://www.google.com \
  https://www.bbc.co.uk \
  https://www.lemonde.fr \
  https://www.spiegel.de \
  https://www.yahoo.co.jp \
  https://www.alibaba.com \
  https://www.globo.com \
  https://www.abc.net.au \
  http://127.0.0.1:1 \
  http://127.0.0.1:19999
```

*Estimated runtime: ~2–3 min — refused connections fail immediately.*

---

## Example 6 — Timeout failures mixed in (exit code 4)

8 accessible sites + 2 non-routable IPs (RFC 5737 documentation range,
packets are dropped by the network). `--timeout 3s` keeps each failed
sample to 3 s instead of the default 10 s.
**Expected exit code: 4.**

```sh
./go/latprobe -n 10 --timeout 3s \
  https://www.google.com \
  https://www.bbc.co.uk \
  https://www.lemonde.fr \
  https://www.spiegel.de \
  https://www.yahoo.co.jp \
  https://www.alibaba.com \
  https://www.globo.com \
  https://www.abc.net.au \
  https://192.0.2.1 \
  https://203.0.113.1
```

*Estimated runtime: ~3–4 min — timeout IPs add 3 s × 10 samples = 30 s each.*

---

## Example 7 — HTTP error status with `--fail` (exit code 6)

8 accessible sites + 2 URLs that return 4xx/5xx. Without `--fail` these
would exit 0; with it, exit code becomes 6.
**Expected exit code: 6.**

```sh
./go/latprobe -n 10 --fail \
  https://www.google.com \
  https://www.bbc.co.uk \
  https://www.lemonde.fr \
  https://www.spiegel.de \
  https://www.yahoo.co.jp \
  https://www.alibaba.com \
  https://www.globo.com \
  https://www.abc.net.au \
  https://httpbin.org/status/404 \
  https://httpbin.org/status/503
```

*Estimated runtime: ~2–3 min — full timing captured even for error responses.*

---

## Example 8 — TLS failures mixed in (exit code 5)

8 accessible sites + 2 HTTPS servers with bad certificates.
`badssl.com` is a purpose-built TLS testing service.
**Expected exit code: 5.**

```sh
./go/latprobe -n 10 \
  https://www.google.com \
  https://www.bbc.co.uk \
  https://www.lemonde.fr \
  https://www.spiegel.de \
  https://www.yahoo.co.jp \
  https://www.alibaba.com \
  https://www.globo.com \
  https://www.abc.net.au \
  https://self-signed.badssl.com \
  https://expired.badssl.com
```

*Estimated runtime: ~2–3 min — TLS failures surface DNS + connect timing.*

---

## Example 9 — All failure types, full matrix (exit code 5)

10 accessible sites + one of each failure class. Exercises every code path:
DNS (exit 2), connect (exit 3), timeout (exit 4), TLS (exit 5),
HTTP error with `--fail` (exit 6). Highest code wins → **exit 5** (TLS is
5, HTTP error is 6 — but exit 6 if httpbin is reachable).
**Expected exit code: 6 (with --fail).**

```sh
./go/latprobe -n 10 --fail --timeout 3s \
  https://www.google.com \
  https://www.bbc.co.uk \
  https://www.lemonde.fr \
  https://www.spiegel.de \
  https://www.yahoo.co.jp \
  https://www.alibaba.com \
  https://www.globo.com \
  https://www.abc.net.au \
  https://www.thehindu.com \
  https://www.timeslive.co.za \
  https://nonexistent-host.invalid \
  http://127.0.0.1:1 \
  https://192.0.2.1 \
  https://httpbin.org/status/500 \
  https://self-signed.badssl.com
```

*Estimated runtime: ~5–7 min — the comprehensive stress test.*

---

## Example 10 — Quick smoke test, single sample, JSON, all failure types

Same 15 targets as Example 9 but `-n 1` for a fast sanity check.
JSON output lets you pipe results to `jq` for filtering.
**Expected exit code: 6 (with --fail).**

```sh
./go/latprobe -n 1 --fail --timeout 2s --json \
  https://www.google.com \
  https://www.bbc.co.uk \
  https://www.lemonde.fr \
  https://www.spiegel.de \
  https://www.yahoo.co.jp \
  https://www.alibaba.com \
  https://www.globo.com \
  https://www.abc.net.au \
  https://www.thehindu.com \
  https://www.timeslive.co.za \
  https://nonexistent-host.invalid \
  http://127.0.0.1:1 \
  https://192.0.2.1 \
  https://httpbin.org/status/500 \
  https://self-signed.badssl.com

# Show only failed entries:
./go/latprobe -n 1 --fail --timeout 2s --json \
  https://www.google.com \
  https://nonexistent-host.invalid \
  http://127.0.0.1:1 \
  https://192.0.2.1 \
  https://httpbin.org/status/500 \
  https://self-signed.badssl.com \
  | jq '.[] | select(.failed > 0 or .status >= 400)'
```

*Estimated runtime: ~30–60 s — fastest end-to-end check of all error paths.*

---

## Exit code reference

| Code | Meaning |
|------|---------|
| 0 | All probes succeeded |
| 1 | Usage error |
| 2 | DNS resolution failure |
| 3 | Connection failure |
| 4 | Timeout |
| 5 | TLS handshake failure |
| 6 | HTTP status ≥ 400 (only with `--fail`) |

When multiple failure types occur, the process exits with the **highest** code.