# Custom Usage Examples

All examples assume the binary has been built first:

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

**Concurrency note:** Since Step 7, `latprobe` probes URLs in parallel by default
(`min(numURLs, 8)` workers). Estimated runtimes below reflect this — they are
roughly _slowest-single-URL × samples_ rather than the sum across all URLs.
Use `-c 1` to restore serial execution for the most accurate per-phase numbers.

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: ~5–8 s — all 10 sites measured in parallel; 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: ~20–30 s — 8 workers run in parallel; wall time ≈ slowest single URL × 10 samples.*

---

## 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: ~20–30 s.*

---

## 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: ~20–30 s — DNS failures resolve near-instantly; 8 workers run in parallel.*

---

## 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: ~20–30 s — refused connections fail immediately; 8 workers run in parallel.*

---

## 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: ~35–40 s — all 10 URLs measured in parallel; the 2 timeout IPs each add 3 s × 10 samples = 30 s and are the bottleneck.*

---

## 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: ~20–30 s — full timing captured even for error responses; all 10 URLs measured in parallel.*

---

## 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: ~20–30 s — TLS failures surface DNS + connect timing; all 10 URLs measured in parallel.*

---

## 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: ~35–45 s — 15 URLs measured with 8 workers; the 2 timeout IPs (30 s × each) are the bottleneck.*

---

## 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: ~4–6 s — 15 URLs probed in parallel with `-n 1`; only the 2 s timeout IPs add meaningful delay.*

---

## Example 11 — 3 working sites, one of each error kind (exit code 6)

Minimal URL set that exercises every failure class simultaneously.
Three real sites succeed; five targets each trigger a distinct error.
`--fail` is required to surface the HTTP 4xx as an exit code.
**Expected exit code: 6** (highest code wins; HTTP error = 6 > TLS = 5 > timeout = 4 > refused = 3 > DNS = 2).

```sh
./go/latprobe -n 5 --fail --timeout 3s \
  https://www.cloudflare.com \
  https://www.github.com \
  https://www.wikipedia.org \
  https://nonexistent-host.invalid \
  http://127.0.0.1:1 \
  https://192.0.2.1 \
  https://self-signed.badssl.com \
  https://httpbin.org/status/404
```

| URL | Expected outcome | Exit-code contribution |
| --- | --------------- | ---------------------- |
| cloudflare.com | success | — |
| github.com | success | — |
| wikipedia.org | success | — |
| nonexistent-host.invalid | DNS failure | 2 |
| 127.0.0.1:1 | connection refused | 3 |
| 192.0.2.1 | timeout (3 s × 5 samples) | 4 |
| self-signed.badssl.com | TLS handshake failure | 5 |
| httpbin.org/status/404 | HTTP 404 (with --fail) | 6 |

_Estimated runtime: ~18–22 s — 8 workers cover all URLs in parallel; the non-routable IP (192.0.2.1) drives the wall time at 3 s × 5 samples = 15 s._

---

## 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.