tracerate 0.1.0__tar.gz

tracerate-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: tracerate
+Version: 0.1.0
+Summary: A no-nonsense CLI internet speed tester
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Requires-Dist: rich
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# tracerate
+
+A no-nonsense CLI internet speed tester.
+
+## What it measures
+- Download / upload speed (Mbps)
+- Ping and packet loss
+- Bufferbloat grade (A+ to F)
+- DNS resolution time
+- ISP and location detection
+- Regional latency to 7 global servers
+
+## Install
+pip install tracerate
+
+## Usage
+
+| Command | Description |
+|---|---|
+| `tracerate` | Full test (download, upload, bufferbloat, regional latency) |
+| `tracerate --quick` | Fast test (download only, skips upload and extras) |
+| `tracerate --bytes 50` | Custom download size in MB (default: 25) |
+| `tracerate --output json` | Machine readable output |

tracerate-0.1.0/README.md

@@ -0,0 +1,23 @@
+# tracerate
+
+A no-nonsense CLI internet speed tester.
+
+## What it measures
+- Download / upload speed (Mbps)
+- Ping and packet loss
+- Bufferbloat grade (A+ to F)
+- DNS resolution time
+- ISP and location detection
+- Regional latency to 7 global servers
+
+## Install
+pip install tracerate
+
+## Usage
+
+| Command | Description |
+|---|---|
+| `tracerate` | Full test (download, upload, bufferbloat, regional latency) |
+| `tracerate --quick` | Fast test (download only, skips upload and extras) |
+| `tracerate --bytes 50` | Custom download size in MB (default: 25) |
+| `tracerate --output json` | Machine readable output |

tracerate-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tracerate"
+version = "0.1.0"
+description = "A no-nonsense CLI internet speed tester"
+requires-python = ">=3.10"
+readme = "README.md"
+license = { text = "MIT" }
+dependencies = [
+    "httpx",
+    "typer",
+    "rich",
+]
+
+[project.scripts]
+tracerate = "tracerate.cli:app"

tracerate-0.1.0/tracerate/bufferbloat.py

@@ -0,0 +1,105 @@
+import socket
+import threading
+import time
+
+import httpx
+
+from tracerate.tester import SERVER
+
+
+def _saturate_download(stop_flag: threading.Event, url: str) -> None:
+    """Stream a large download until told to stop. Discards bytes."""
+    try:
+        with httpx.stream("GET", url, timeout=60, follow_redirects=True) as response:
+            for _ in response.iter_bytes():
+                if stop_flag.is_set():
+                    break
+    except Exception:
+        pass
+
+
+def _sample_ping(host: str, port: int) -> float | None:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.settimeout(2)
+    try:
+        start = time.perf_counter()
+        sock.connect((host, port))
+        return (time.perf_counter() - start) * 1000
+    except (socket.timeout, socket.error):
+        return None
+    finally:
+        try:
+            sock.close()
+        except Exception:
+            pass
+
+
+def measure_bufferbloat(duration: float = 5.0, baseline_attempts: int = 8) -> dict:
+    """
+    Saturate the link with a download in a background thread,
+    sample ping repeatedly during the saturation, compare to idle.
+
+    Why this matters: bufferbloat is when your modem queues
+    packets under load. Throughput stays high but latency
+    explodes — exactly what kills video calls and gaming.
+
+    Idle and loaded both use min-of-samples — the floor is
+    the true RTT, higher samples are jitter.
+
+    Grade scale follows the Waveform bufferbloat test convention.
+    """
+
+    idle_samples = []
+    for _ in range(baseline_attempts):
+        ms = _sample_ping(SERVER["host"], SERVER["port"])
+        if ms is not None:
+            idle_samples.append(ms)
+        time.sleep(0.05)
+
+    if not idle_samples:
+        return {"idle_ms": 0.0, "loaded_ms": 0.0, "delta_ms": 0.0, "grade": "?"}
+
+    idle = min(idle_samples)
+
+    url = SERVER["down"].format(bytes=200_000_000)
+    stop = threading.Event()
+    worker = threading.Thread(target=_saturate_download, args=(stop, url), daemon=True)
+    worker.start()
+
+    time.sleep(0.5)
+
+    samples = []
+    end_time = time.time() + duration
+    while time.time() < end_time:
+        ms = _sample_ping(SERVER["host"], SERVER["port"])
+        if ms is not None:
+            samples.append(ms)
+        time.sleep(0.2)
+
+    stop.set()
+    worker.join(timeout=2)
+
+    if not samples:
+        return {
+            "idle_ms": round(idle, 2),
+            "loaded_ms": 0.0,
+            "delta_ms": 0.0,
+            "grade": "?",
+        }
+
+    loaded = min(samples)
+    delta = max(0.0, loaded - idle)
+
+    if   delta < 5:    grade = "A+"
+    elif delta < 30:   grade = "A"
+    elif delta < 60:   grade = "B"
+    elif delta < 200:  grade = "C"
+    elif delta < 400:  grade = "D"
+    else:              grade = "F"
+
+    return {
+        "idle_ms": round(idle, 2),
+        "loaded_ms": round(loaded, 2),
+        "delta_ms": round(delta, 2),
+        "grade": grade,
+    }

tracerate-0.1.0/tracerate/cli.py

@@ -0,0 +1,248 @@
+import json
+
+import typer
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    TextColumn,
+    TransferSpeedColumn,
+)
+
+from tracerate.bufferbloat import measure_bufferbloat
+from tracerate.info import get_ip_info, measure_dns
+from tracerate.regional import measure_regions
+from tracerate.tester import (
+    SERVER,
+    measure_download,
+    measure_ping,
+    measure_upload,
+)
+from tracerate.verdict import analyze
+
+
+app = typer.Typer(help="tracerate — a no-nonsense CLI internet speed tester")
+console = Console()
+
+
+@app.command()
+def run(
+    quick: bool = typer.Option(
+        default=False,
+        help="Skip upload + bufferbloat + regional probes; use 10MB download.",
+    ),
+    bytes_mb: int = typer.Option(
+        default=25,
+        help="Download size in MB.",
+    ),
+    output: str = typer.Option(
+        default="pretty",
+        help="Output format: pretty or json.",
+    ),
+):
+    if output not in ("pretty", "json"):
+        typer.echo("--output must be 'pretty' or 'json'", err=True)
+        raise typer.Exit(code=1)
+
+    download_bytes = (10 if quick else bytes_mb) * 1024 * 1024
+    test_upload = not quick
+    test_extras = not quick
+
+    if output == "pretty":
+        console.print()
+        console.print("  [bold]tracerate[/bold] [dim]· network diagnostics[/dim]")
+        console.print()
+
+    with console.status("[dim]Looking up your ISP...[/dim]", spinner="dots"):
+        info = get_ip_info()
+        dns_ms = measure_dns(SERVER["host"])
+
+    with console.status("[dim]Measuring latency...[/dim]", spinner="dots"):
+        ping_ms, loss_pct, jitter_ms = measure_ping(SERVER["host"], SERVER["port"])
+
+    download_mbps = _run_download(download_bytes, quiet=(output == "json"))
+
+    upload_mbps = None
+    if test_upload:
+        with console.status("[dim]Uploading 10 MB...[/dim]", spinner="dots"):
+            upload_mbps = measure_upload(SERVER["up"])
+
+    bufferbloat = None
+    if test_extras:
+        with console.status("[dim]Probing bufferbloat (saturating link)...[/dim]", spinner="dots"):
+            bufferbloat = measure_bufferbloat()
+
+    regions = []
+    if test_extras:
+        with console.status("[dim]Pinging regional servers...[/dim]", spinner="dots"):
+            regions = measure_regions()
+
+    result = {
+        "name": SERVER["name"],
+        "ping_ms": ping_ms,
+        "packet_loss_pct": loss_pct,
+        "jitter_ms": jitter_ms,
+        "download_mbps": download_mbps,
+        "upload_mbps": upload_mbps,
+        "error": None,
+    }
+    summary = analyze(result, bufferbloat=bufferbloat)
+
+    if output == "json":
+        print(json.dumps({
+            "info": info,
+            "dns_ms": dns_ms,
+            "result": result,
+            "bufferbloat": bufferbloat,
+            "regions": regions,
+            "summary": summary,
+        }, indent=2))
+        return
+
+    _render(info, dns_ms, result, bufferbloat, regions, summary)
+
+
+def _run_download(download_bytes: int, quiet: bool) -> float:
+    """Run the main download with a live progress bar."""
+
+    if quiet:
+        return measure_download(SERVER["down"], download_bytes)
+
+    with Progress(
+        TextColumn("  [dim]Downloading[/dim]"),
+        BarColumn(bar_width=30, complete_style="cyan", finished_style="cyan"),
+        DownloadColumn(),
+        TransferSpeedColumn(),
+        console=console,
+        transient=True,
+    ) as progress:
+        task = progress.add_task("dl", total=download_bytes)
+
+        def on_progress(total: int) -> None:
+            progress.update(task, completed=total)
+
+        return measure_download(SERVER["down"], download_bytes, on_progress=on_progress)
+
+
+# ────────────────────────── rendering ──────────────────────────
+
+_DIVIDER = "[dim]" + "─" * 56 + "[/dim]"
+
+
+def _bar(value: float, max_value: float, width: int = 20,
+         filled: str = "▰", empty: str = "▱") -> str:
+    if max_value <= 0:
+        return empty * width
+    ratio = min(value, max_value) / max_value
+    n = int(round(ratio * width))
+    return filled * n + empty * (width - n)
+
+
+def _section(title: str) -> None:
+    console.print(f"  [bold cyan]{title}[/bold cyan]")
+    console.print(f"  {_DIVIDER}")
+
+
+def _render(info, dns_ms, r, bb, regions, summary):
+    _render_connection(info, dns_ms)
+    _render_speed(r)
+
+    if bb is not None:
+        _render_bufferbloat(bb)
+
+    if regions:
+        _render_regions(regions)
+
+    _render_verdict(summary["verdict"])
+
+
+def _render_connection(info: dict, dns_ms: float) -> None:
+    isp       = info.get("isp")       or "unknown"
+    asn       = info.get("asn")       or ""
+    city      = info.get("city")      or "?"
+    country   = info.get("country")   or "?"
+    colo      = info.get("colo")      or "?"
+    colo_city = info.get("colo_city")
+    ip        = info.get("ip")        or "?"
+
+    dns_color = "dim" if dns_ms < 50 else ("yellow" if dns_ms < 150 else "red")
+    edge = f"Cloudflare [bold]{colo}[/bold]" + (f" [dim]({colo_city})[/dim]" if colo_city else "")
+
+    console.print(f"  [dim]ISP    [/dim]  [bold]{isp}[/bold]   [dim]{asn}[/dim]")
+    console.print(f"  [dim]Where  [/dim]  {city}, {country}  [dim]→[/dim]  {edge}")
+    console.print(f"  [dim]IP     [/dim]  {ip}   [dim]·  DNS[/dim] [{dns_color}]{dns_ms} ms[/{dns_color}]")
+    console.print()
+
+
+def _render_speed(r: dict) -> None:
+    _section("Speed")
+
+    dl = r.get("download_mbps") or 0.0
+    ul = r.get("upload_mbps") or 0.0
+    ping = r.get("ping_ms") or 0.0
+    jitter = r.get("jitter_ms") or 0.0
+    loss = r.get("packet_loss_pct") or 0.0
+
+    scale = max(dl, ul, 100.0)
+
+    console.print(f"   [dim]Download[/dim]  [cyan]{_bar(dl, scale)}[/cyan]   [bold]{dl:>7.2f}[/bold] [dim]Mbps[/dim]")
+    if r.get("upload_mbps") is not None:
+        console.print(f"   [dim]Upload  [/dim]  [cyan]{_bar(ul, scale)}[/cyan]   [bold]{ul:>7.2f}[/bold] [dim]Mbps[/dim]")
+
+    loss_part = f"[red]· {loss}% loss[/red]" if loss > 0 else "[dim]· 0% loss[/dim]"
+    console.print(f"   [dim]Ping    [/dim]  [bold]{ping}[/bold] [dim]ms[/dim]   {loss_part}")
+    console.print(f"   [dim]Jitter  [/dim]  [bold]{jitter}[/bold] [dim]ms[/dim]")
+    console.print()
+
+
+_GRADE_COLOR = {
+    "A+": "green", "A": "green",
+    "B": "cyan",
+    "C": "yellow", "D": "yellow",
+    "F": "red", "?": "dim",
+}
+
+
+def _render_bufferbloat(bb: dict) -> None:
+    _section("Bufferbloat")
+    grade = bb["grade"]
+    color = _GRADE_COLOR.get(grade, "dim")
+    console.print(f"   [dim]Idle  [/dim]  [bold]{bb['idle_ms']}[/bold] [dim]ms[/dim]")
+    console.print(
+        f"   [dim]Loaded[/dim]  [bold]{bb['loaded_ms']}[/bold] [dim]ms[/dim]"
+        f"   [dim]Δ[/dim] [bold]+{bb['delta_ms']}[/bold] [dim]ms[/dim]"
+        f"   [dim]Grade[/dim] [{color}][bold]{grade}[/bold][/{color}]"
+    )
+    console.print()
+
+
+def _render_regions(regions: list[dict]) -> None:
+    _section("Regional latency")
+    reachable = [r for r in regions if r["ms"] > 0]
+    scale = max((r["ms"] for r in reachable), default=200.0)
+
+    ordered = sorted(regions, key=lambda r: r["ms"] if r["ms"] > 0 else 1e9)
+    for r in ordered:
+        ms = r["ms"]
+        if ms == 0:
+            bar = "[dim]" + "▱" * 12 + "[/dim]"
+            ms_str = "[dim]timeout[/dim]"
+        else:
+            color = "cyan" if ms < 80 else ("yellow" if ms < 180 else "red")
+            bar = f"[{color}]{_bar(ms, scale, width=12)}[/{color}]"
+            ms_str = f"[bold]{ms:>6.0f}[/bold] [dim]ms[/dim]"
+        console.print(f"   [dim]{r['code']}[/dim]  {r['city']:<11}  {bar}   {ms_str}")
+    console.print()
+
+
+def _render_verdict(verdict: str) -> None:
+    if verdict == "Connection is healthy":
+        mark, color = "✔", "green"
+    elif verdict in ("ISP bandwidth is just low",):
+        mark, color = "⚠", "yellow"
+    else:
+        mark, color = "✘", "red"
+
+    console.print(f"  [{color}]{mark}[/{color}]  [bold]{verdict}[/bold]")
+    console.print()

tracerate-0.1.0/tracerate/info.py

@@ -0,0 +1,92 @@
+import socket
+import time
+import httpx
+
+
+def get_ip_info() -> dict:
+    """
+    Best-effort ISP / IP / location lookup.
+
+    Combines ipinfo.io (city precision, friendly ISP name) with
+    Cloudflare's /meta endpoint (ASN, edge PoP code) so we can
+    show "you hit Cloudflare BOM via Jio" in one line.
+    """
+
+    info = {
+        "ip": None,
+        "isp": None,
+        "city": None,
+        "country": None,
+        "asn": None,
+        "colo": None,
+        "colo_city": None,
+    }
+
+    try:
+        r = httpx.get("https://ipinfo.io/json", timeout=5)
+        if r.status_code == 200:
+            data = r.json()
+            info["ip"] = data.get("ip")
+            info["city"] = data.get("city")
+            info["country"] = data.get("country")
+            org = data.get("org") or ""
+            if org.startswith("AS") and " " in org:
+                asn, _, name = org.partition(" ")
+                info["asn"] = asn
+                info["isp"] = name
+            elif org:
+                info["isp"] = org
+    except Exception:
+        pass
+
+    try:
+        # Cloudflare blocks bare httpx requests; needs browser-ish headers.
+        r = httpx.get(
+            "https://speed.cloudflare.com/meta",
+            timeout=5,
+            headers={
+                "User-Agent": "Mozilla/5.0",
+                "Accept": "application/json",
+                "Referer": "https://speed.cloudflare.com/",
+            },
+        )
+        if r.status_code == 200:
+            data = r.json()
+            colo = data.get("colo")
+            if isinstance(colo, dict):
+                info["colo"] = colo.get("iata")
+                info["colo_city"] = colo.get("city")
+            elif isinstance(colo, str):
+                info["colo"] = colo
+            if not info["isp"]:
+                info["isp"] = data.get("asOrganization")
+            if not info["asn"] and data.get("asn"):
+                info["asn"] = f"AS{data['asn']}"
+            if not info["city"]:
+                info["city"] = data.get("city")
+            if not info["country"]:
+                info["country"] = data.get("country")
+            if not info["ip"]:
+                info["ip"] = data.get("clientIp")
+    except Exception:
+        pass
+
+    return info
+
+
+def measure_dns(hostname: str = "speed.cloudflare.com") -> float:
+    """
+    DNS lookup time in ms via getaddrinfo.
+
+    Note: OS-level DNS cache (systemd-resolved, nscd) may
+    return a stale near-zero value on subsequent runs.
+    First call after a cache flush is the honest one.
+    """
+
+    try:
+        start = time.perf_counter()
+        socket.getaddrinfo(hostname, None)
+        elapsed = (time.perf_counter() - start) * 1000
+        return round(elapsed, 2)
+    except socket.gaierror:
+        return 0.0

tracerate-0.1.0/tracerate/regional.py

@@ -0,0 +1,55 @@
+import socket
+import time
+
+
+# Linode publishes public speedtest endpoints in each region.
+# Stable hostnames, anycast-free, good proxies for "real" geo distance.
+REGIONS = [
+    ("IN", "Mumbai",     "speedtest.mumbai1.linode.com"),
+    ("SG", "Singapore",  "speedtest.singapore.linode.com"),
+    ("JP", "Tokyo",      "speedtest.tokyo2.linode.com"),
+    ("DE", "Frankfurt",  "speedtest.frankfurt.linode.com"),
+    ("UK", "London",     "speedtest.london.linode.com"),
+    ("US", "Newark",     "speedtest.newark.linode.com"),
+    ("US", "Fremont",    "speedtest.fremont.linode.com"),
+]
+
+
+def _tcp_ping(host: str, port: int = 443, attempts: int = 3, timeout: float = 2.0) -> float:
+    """
+    TCP-connect latency in ms, returns the minimum of N attempts.
+    Min is more representative of true RTT than mean — high samples
+    are jitter, the floor is the actual round-trip.
+    """
+
+    samples = []
+    for _ in range(attempts):
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(timeout)
+            start = time.perf_counter()
+            sock.connect((host, port))
+            samples.append((time.perf_counter() - start) * 1000)
+        except (socket.timeout, socket.error):
+            pass
+        finally:
+            try:
+                sock.close()
+            except Exception:
+                pass
+
+    if not samples:
+        return 0.0
+    return round(min(samples), 2)
+
+
+def measure_regions() -> list[dict]:
+    out = []
+    for code, city, host in REGIONS:
+        out.append({
+            "code": code,
+            "city": city,
+            "host": host,
+            "ms": _tcp_ping(host),
+        })
+    return out

tracerate-0.1.0/tracerate/tester.py

@@ -0,0 +1,118 @@
+import os
+import socket
+import time
+from typing import Callable
+
+import httpx
+
+
+SERVER = {
+    "name": "Cloudflare",
+    "down": "https://speed.cloudflare.com/__down?bytes={bytes}",
+    "up": "https://speed.cloudflare.com/__up",
+    "host": "speed.cloudflare.com",
+    "port": 443,
+}
+
+
+def measure_ping(host: str, port: int, attempts: int = 5) -> tuple[float, float]:
+    """
+    Measures latency and packet loss to a host using TCP connect time.
+
+    Why TCP and not ICMP?
+    ICMP (what 'ping' command uses) requires root on Linux.
+    TCP connect to port 443 works without any special permissions.
+
+    Returns: (average_latency_ms, packet_loss_percent)
+    """
+
+    results = []
+
+    for _ in range(attempts):
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(3)
+            start = time.perf_counter()
+            sock.connect((host, port))
+            elapsed = (time.perf_counter() - start) * 1000
+            results.append(elapsed)
+        except (socket.timeout, socket.error):
+            pass
+        finally:
+            try:
+                sock.close()
+            except Exception:
+                pass
+
+    if not results:
+        return 0.0, 0.0
+
+    average_latency = sum(results) / len(results)
+    packet_loss = ((attempts - len(results)) / attempts) * 100
+    jitter = round(max(results) - min(results), 2)
+
+    return round(average_latency, 2), round(packet_loss, 1), round(jitter, 2)
+
+
+def measure_download(
+    url: str,
+    bytes_to_download: int,
+    on_progress: Callable[[int], None] | None = None,
+) -> float:
+    """
+    Downloads a file in chunks and measures speed in Mbps.
+
+    We stream the response and discard each chunk —
+    bytes are never held in memory.
+
+    `on_progress(total_bytes)` is called per chunk if provided,
+    so the caller can drive a progress bar.
+
+    Returns: speed in Mbps, or 0.0 if it failed.
+    """
+
+    url = url.format(bytes=bytes_to_download)
+    try:
+        total_bytes = 0
+        start = time.perf_counter()
+
+        with httpx.stream("GET", url, timeout=30, follow_redirects=True) as response:
+            for chunk in response.iter_bytes():
+                total_bytes += len(chunk)
+                if on_progress is not None:
+                    on_progress(total_bytes)
+
+        elapsed = time.perf_counter() - start
+
+        if elapsed == 0 or total_bytes == 0:
+            return 0.0
+
+        speed_mbps = (total_bytes * 8) / elapsed / 1_000_000
+        return round(speed_mbps, 2)
+
+    except Exception:
+        return 0.0
+
+
+def measure_upload(url: str, bytes_to_upload: int = 10_000_000) -> float:
+    """
+    Uploads random bytes to a server and measures speed in Mbps.
+
+    Why random bytes?
+    Some servers or network equipment compress data in transit.
+    Random bytes can't be compressed — gives an honest measurement.
+
+    Returns: speed in Mbps, or 0.0 if it failed.
+    """
+
+    data = os.urandom(bytes_to_upload)
+    try:
+        start = time.perf_counter()
+        httpx.post(url, content=data, timeout=30)
+        elapsed = time.perf_counter() - start
+        if elapsed == 0:
+            return 0.0
+        speed_mbps = (bytes_to_upload * 8) / elapsed / 1_000_000
+        return round(speed_mbps, 2)
+    except Exception:
+        return 0.0

tracerate-0.1.0/tracerate/verdict.py

@@ -0,0 +1,49 @@
+def analyze(result: dict, bufferbloat: dict | None = None) -> dict:
+    """
+    Takes a single test result (+ optional bufferbloat data)
+    and returns a summary with averages and a verdict string.
+
+    Verdict priority: worst-condition first, healthy last.
+    """
+
+    download = result.get("download_mbps") or 0.0
+    upload = result.get("upload_mbps")
+    ping = result.get("ping_ms") or 0.0
+    jitter = result.get("jitter_ms") or 0.0
+    loss = result.get("packet_loss_pct") or 0.0
+
+    verdict = _diagnose(
+        download=download,
+        ping=ping,
+        jitter=jitter,
+        loss=loss,
+        bufferbloat_delta=(bufferbloat or {}).get("delta_ms", 0.0),
+    )
+
+    return {
+        "download_mbps": download,
+        "upload_mbps": upload,
+        "ping_ms": ping,
+        "jitter_ms": jitter,
+        "packet_loss_pct": loss,
+        "verdict": verdict,
+    }
+
+
+def _diagnose(download: float, ping: float, jitter: float, loss: float, bufferbloat_delta: float) -> str:
+    if loss > 5:
+        return "Packet loss detected"
+
+    if bufferbloat_delta > 200:
+        return "Severe bufferbloat — calls and gaming will lag"
+
+    if ping > 100 and download >= 10:
+        return "Congestion detected"
+
+    if jitter > 30:
+        return "High jitter — calls may drop out"
+
+    if download < 10:
+        return "ISP bandwidth is just low"
+
+    return "Connection is healthy"