# yslow

A command-line tool that diagnoses why your network connection is slow (or feels slow).

Instead of just reporting numbers, yslow isolates *where* the problem is — your local network (wifi/router), your ISP, or the broader internet — and tells you in plain language.

## What it checks

- **Gateway latency** — how fast your machine can talk to your router. High latency or jitter here points to wifi congestion, a bad cable, or an overloaded router.
- **Internet latency** — TCP handshake time to multiple well-known servers (Cloudflare, Google, OpenDNS).
- **Packet loss** — at both the local and internet level.
- **Jitter** — variance in latency, which causes buffering, choppy calls, and inconsistent page loads.

By comparing gateway vs internet results, yslow isolates the problem:

| Gateway | Internet | Diagnosis |
|---------|----------|-----------|
| Fast | Fast | Connection is healthy |
| Slow | Slow | Local network is the bottleneck (router/wifi) |
| Fast | Slow | ISP or internet routing issue |
| Unreachable | Slow | Unusual setup, but internet works |

## Usage

```
uv run yslow
```

Requires Python 3.10+ and Linux. No dependencies beyond the standard library.

## How it works

yslow uses **TCP handshake timing** rather than ICMP ping. A TCP connect to port 443 measures the same network round-trip as ping, but works without root privileges and inside containers where ICMP is often blocked.

For the gateway, it tries common TCP ports (80, 443, 53) and falls back to ICMP ping if needed.

## Development

```
uv sync                  # install deps
./check.sh               # run all checks (format, lint, typecheck, tests)
uv run pytest            # run tests only
uv run ty check          # type check only
uv run ruff check --fix  # lint
uv run ruff format       # format
```

## Documentation

See [`docs/metrics.md`](docs/metrics.md) for details on what yslow measures (RTT, packet loss, jitter), how each metric is calculated, and the thresholds used for diagnosis.

## Planned

- DNS resolution timing
- Bandwidth / throughput estimation
- Bufferbloat detection (latency under load)
- Route analysis (where along the path is the bottleneck)
