linux-mirror-bench 0.1.2__tar.gz → 0.3.0__tar.gz

{linux_mirror_bench-0.1.2 → linux_mirror_bench-0.3.0}/.github/workflows/ci.yml

@@ -23,8 +23,8 @@ jobs:
     name: Pre-commit
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ env.PYTHON_VERSION }}
       - uses: astral-sh/setup-uv@v7
@@ -38,13 +38,13 @@ jobs:
     name: Lint + format
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
           cache-dependency-glob: pyproject.toml
-      - run: uv sync --frozen --all-extras || uv sync --all-extras
+      - run: uv sync --frozen --all-extras
       - name: Ruff check
         run: uv run ruff check --output-format=github .
       - name: Ruff format check
@@ -54,13 +54,13 @@ jobs:
     name: Mypy (strict)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
           cache-dependency-glob: pyproject.toml
-      - run: uv sync --frozen --all-extras || uv sync --all-extras
+      - run: uv sync --frozen --all-extras
       - name: mypy
         run: uv run mypy src tests
 
@@ -72,8 +72,8 @@ jobs:
       matrix:
         python: ["3.14"]
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python }}
       - uses: astral-sh/setup-uv@v7
@@ -81,7 +81,7 @@ jobs:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
           cache-dependency-glob: pyproject.toml
-      - run: uv sync --frozen --all-extras || uv sync --all-extras
+      - run: uv sync --frozen --all-extras
       - name: pytest
         run: uv run pytest -v --tb=short
       - name: Smoke-test the built CLI
@@ -93,13 +93,13 @@ jobs:
     name: Security scan (bandit + pip-audit)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           version: ${{ env.UV_VERSION }}
           enable-cache: true
           cache-dependency-glob: pyproject.toml
-      - run: uv sync --frozen --all-extras || uv sync --all-extras
+      - run: uv sync --frozen --all-extras
       - name: Bandit
         run: uv run --with "bandit[toml]" bandit -c pyproject.toml -r src
       - name: pip-audit (runtime deps)
@@ -114,7 +114,7 @@ jobs:
       contents: read
       security-events: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: docker/setup-buildx-action@v4
       - name: Build image
         uses: docker/build-push-action@v7

linux_mirror_bench-0.3.0/.github/workflows/integration.yml

@@ -0,0 +1,42 @@
+---
+# Runs the opt-in integration tests against real mirror infrastructure.
+# Mirror lists, file paths, and release names change upstream without notice;
+# this is the only job that sees it. It is not a PR gate, because a failure
+# here is usually upstream drift, not a defect in the change under review.
+
+name: Integration
+
+on:
+  schedule:
+    - cron: "17 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+env:
+  PYTHON_VERSION: "3.14"
+  UV_VERSION: "0.11.7"
+
+jobs:
+  integration:
+    name: Live mirrors
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+      - run: uv sync --frozen --all-extras
+      - name: pytest (integration)
+        run: make test-integration

{linux_mirror_bench-0.1.2 → linux_mirror_bench-0.3.0}/.github/workflows/release.yml

@@ -31,8 +31,8 @@ jobs:
     outputs:
       version: ${{ steps.version.outputs.value }}
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ env.PYTHON_VERSION }}
       - uses: astral-sh/setup-uv@v7
@@ -94,7 +94,7 @@ jobs:
       id-token: write
       attestations: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: docker/setup-qemu-action@v4
       - uses: docker/setup-buildx-action@v4
       - uses: docker/login-action@v4
@@ -143,7 +143,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/download-artifact@v8
         with:
           name: dist

{linux_mirror_bench-0.1.2 → linux_mirror_bench-0.3.0}/.pre-commit-config.yaml

@@ -44,6 +44,7 @@ repos:
       - id: mypy
         additional_dependencies:
           - httpx
+          - aioquic
           - typer
           - rich
           - pytest

{linux_mirror_bench-0.1.2 → linux_mirror_bench-0.3.0}/.release-please-config.json

@@ -1,5 +1,6 @@
 {
   "release-type": "python",
+  "bump-minor-pre-major": true,
   "packages": {
     ".": {}
   }

linux_mirror_bench-0.3.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.0"
+}

{linux_mirror_bench-0.1.2 → linux_mirror_bench-0.3.0}/AGENTS.md

@@ -9,21 +9,26 @@ this repo. Humans should read `README.md` + `CONTRIBUTING.md` instead.
 src/mirror_bench/
   cli.py              typer app, subcommands `bench`, `list`, `completion`
   distro.py           /etc/os-release parsing + derivative alias table +
-                      structured exceptions (UnsupportedDistroError, etc.)
+                      default codenames + structured exceptions
+                      (UnsupportedDistroError, etc.)
   models.py           Mirror, ProbeResult, Score, Weights, BenchConfig, HostInfo
   discovery/          per-distro mirror fetchers (ABC + 5 impls +
-                      UnknownDiscovererError)
+                      DiscoveryError, UnknownDiscovererError)
   benchmark/
     transport.py      shared httpx.AsyncClient factory
     probe.py          two-phase async orchestration (TaskGroup + semaphore)
     tls.py            TLS version / cert inspection via response.extensions
+    h3.py             HTTP/3 discovery from the Alt-Svc header + optional
+                      QUIC probe orchestration (--http3)
+    h3_quic.py        aioquic client; imported only through h3.py (optional
+                      `http3` extra, not a runtime dependency)
     scorer.py         weighted composite ranking
   display.py          rich.Table + JSON/CSV emitters
 
 tests/
   fixtures/           captured mirror-list bodies per distro
   test_*.py           respx-mocked units + @pytest.mark.integration opt-ins
-                      (45 tests, 2 integration-gated)
+                      (integration.yml runs the opt-ins each week)
 ```
 
 ## Commands (use these, not ad-hoc ones)
@@ -87,6 +92,9 @@ Run a single test: `uv run pytest tests/test_scorer.py::test_weights_shift_ranki
 ## Adding a new discoverer
 
 1. `src/mirror_bench/discovery/<name>.py` implementing `MirrorDiscoverer`.
+   `probe_path` must name a small file that upstream rewrites as packages
+   change, and `sync_time` must read its generation time, or stale mirrors
+   cannot be detected.
 2. Register in `discovery/__init__.py::DISCOVERERS`.
 3. Add ID aliases in `distro.py::_ALIASES`.
 4. Respx-mocked test in `tests/test_discovery.py` + fixture file under
@@ -100,7 +108,8 @@ Run a single test: `uv run pytest tests/test_scorer.py::test_weights_shift_ranki
 - Don't skip hooks (`--no-verify`), nor add `# type: ignore` / `# noqa` /
   `# nosec` without a one-line reason at the call site.
 - Don't introduce new runtime dependencies without a strong reason — three
-  (`httpx[http2]`, `typer`, `rich`) is the budget.
+  (`httpx[http2]`, `typer`, `rich`) is the budget. `aioquic` is an optional
+  extra (`http3`): import it only in `benchmark/h3_quic.py`.
 - Don't expand `[tool.ruff.lint] select` without a concrete bug class in mind.
 - Don't emit rich output to stdout when `--json` or `--csv` is set.
 - Don't rely on network access in unit tests. Network-touching tests must be
@@ -111,6 +120,9 @@ Run a single test: `uv run pytest tests/test_scorer.py::test_weights_shift_ranki
 - **Mypy error.** Fix the types. `# type: ignore` is not allowed in this
   codebase — if you think you need one, you're probably modelling something
   wrong.
+- **Scheduled integration run fails.** First check for upstream drift: a
+  moved file, a renamed list field, an end-of-life default release. Fix the
+  path or default and refresh the fixture to match the live format.
 - **Integration test flaky.** Real mirrors come and go. If reproducible,
   tighten the assertion or bump tolerance. Don't add retries to runtime code
   just to paper over a test.

linux_mirror_bench-0.3.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0](https://github.com/MysticRyuujin/mirror-bench/compare/v0.2.0...v0.3.0) (2026-11-13)
+
+
+### Features
+
+* measure mirror freshness and drop stale mirrors ([#18](https://github.com/MysticRyuujin/mirror-bench/issues/18)) ([462ac42](https://github.com/MysticRyuujin/mirror-bench/commit/462ac42017f1026c6892701aaa0452b791a0c498))
+
+
+### Bug Fixes
+
+* make completion work without click, and reject error pages as probes ([#19](https://github.com/MysticRyuujin/mirror-bench/issues/19)) ([0c2427d](https://github.com/MysticRyuujin/mirror-bench/commit/0c2427dcb949f394e0118a386407d215d732465b))
+* try https for mirrors listed as http, and write plain output with no TTY ([#17](https://github.com/MysticRyuujin/mirror-bench/issues/17)) ([07d38ee](https://github.com/MysticRyuujin/mirror-bench/commit/07d38eec00a0c5669a728723a13a9d805f6113c8))
+
+
+### Dependencies
+
+* **actions:** match action versions in integration.yml ([#15](https://github.com/MysticRyuujin/mirror-bench/issues/15)) ([35da73d](https://github.com/MysticRyuujin/mirror-bench/commit/35da73d052acf4f1ea67c2f14f4df0b09a8b8c98))
+
+## [0.2.0](https://github.com/MysticRyuujin/mirror-bench/compare/v0.1.2...v0.2.0) (2026-11-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* follow redirects in probes and require a 2xx response; reject an https mirror that redirects to http
+* report throughput from phase 2 only; throughput_bps is null when phase 2 fails or is skipped
+* remove the certificate point from the security score; the maximum is 2.5
+* change default releases to Debian trixie, Mint zena, and Fedora 45
+* reject --json together with --csv
+* stop mapping distros with their own mirror network (rocky, almalinux, centos, rhel, ol, manjaro, kali, parrot, devuan, raspbian) to another distro
+
+### Features
+
+* add --http3 to confirm HTTP/3 with a QUIC probe (optional http3 extra) ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* add throughput_error to JSON and CSV output ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* report mirrors that advertise HTTP/3 (HTTP/3 column, h3_advertised) ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+
+
+### Bug Fixes
+
+* add a time limit to both probe phases ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* change default releases to Debian trixie, Mint zena, and Fedora 45 ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* correct probe and throughput paths for Ubuntu, Mint, Arch, and Fedora ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* **docker:** remove pip from the runtime image ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* drop rsync entries from Arch discovery ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* exit with code 1 and a message when discovery fails ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* follow redirects in probes and require a 2xx response; reject an https mirror that redirects to http ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* handle Debian records with no Country, and try https and http for each Debian site ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* reject --concurrency 0 and --top 0 ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* reject --json together with --csv ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* remove the certificate point from the security score; the maximum is 2.5 ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* report throughput from phase 2 only; throughput_bps is null when phase 2 fails or is skipped ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* run bench when no subcommand is given ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* stop mapping distros with their own mirror network (rocky, almalinux, centos, rhel, ol, manjaro, kali, parrot, devuan, raspbian) to another distro ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+
+
+### Dependencies
+
+* **actions:** bump actions/checkout ([#9](https://github.com/MysticRyuujin/mirror-bench/issues/9)) ([be49743](https://github.com/MysticRyuujin/mirror-bench/commit/be49743112ba6001b022bd3daec9c442a5925a66))
+* **actions:** bump actions/setup-python in the actions group ([#12](https://github.com/MysticRyuujin/mirror-bench/issues/12)) ([930680d](https://github.com/MysticRyuujin/mirror-bench/commit/930680da12de59dc3171385bcb3672399586f66f))
+* bump anyio, certifi, h2, hpack ([9977a7c](https://github.com/MysticRyuujin/mirror-bench/commit/9977a7c439590741123af2dec31548917d265186))
+* bump idna to 3.18 (fixes PYSEC-2026-215) ([#10](https://github.com/MysticRyuujin/mirror-bench/issues/10)) ([690565c](https://github.com/MysticRyuujin/mirror-bench/commit/690565cc1669320eded4faaa175eb8ae85d739e4))
+
+## [0.1.2](https://github.com/MysticRyuujin/mirror-bench/compare/v0.1.1...v0.1.2) (2026-04-23)
+
+
+### Bug Fixes
+
+* **docs:** lowercase ghcr.io references (docker pull requires lowercase) ([#8](https://github.com/MysticRyuujin/mirror-bench/issues/8)) ([31fcf57](https://github.com/MysticRyuujin/mirror-bench/commit/31fcf57239fc98eecb6df9fe8fed06400cb55dc7))
+
+
+### Documentation
+
+* add shields.io badges at top of README ([#6](https://github.com/MysticRyuujin/mirror-bench/issues/6)) ([c25c12b](https://github.com/MysticRyuujin/mirror-bench/commit/c25c12bdc36aa6af67cbbb1b8b7ec65c000d7a53))
+
+## [0.1.1](https://github.com/MysticRyuujin/mirror-bench/compare/v0.1.0...v0.1.1) (2026-04-23)
+
+
+### Bug Fixes
+
+* **ci:** pin aquasecurity/trivy-action to a version that exists ([#2](https://github.com/MysticRyuujin/mirror-bench/issues/2)) ([9984cd0](https://github.com/MysticRyuujin/mirror-bench/commit/9984cd018aaaa6de34b5cdf8261752f563187858))
+
+
+### Dependencies
+
+* **actions:** bump the actions group across 1 directory with 11 updates ([#4](https://github.com/MysticRyuujin/mirror-bench/issues/4)) ([4aba2a6](https://github.com/MysticRyuujin/mirror-bench/commit/4aba2a68079d2029bf5cc387d9a6eae459d9ff2a))
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-23
+
+### Added
+
+- Cross-distribution mirror benchmarking for **Ubuntu, Debian, Fedora,
+  Linux Mint, and Arch**.
+- Two-phase probe: async latency screen (ranged GET on each distro's canonical
+  metadata file; median of 3 samples) followed by a throughput test on the
+  top-N candidates.
+- Weighted composite scoring across latency, throughput, and security (HTTPS +
+  TLS 1.3 + valid cert + HTTP/2). Weights adjustable via
+  `--weights lat=…,thr=…,sec=…`.
+- `bench` and `list` subcommands with `--json` / `--csv` / `--https-only` /
+  `--tls13-only` / `--no-throughput` / `--country` / `--top` / `--concurrency`.
+- Host auto-detection via `/etc/os-release`, with derivative alias support
+  (Pop!\_OS, Kali, Rocky, etc.). `--distro` override for containers and macOS.
+- Shell completion via typer (`--install-completion` / `--show-completion`).
+- Multi-stage Dockerfile (`python:3.14-slim-bookworm`, non-root uid 65532).
+- GitHub Actions CI + release pipelines with OIDC PyPI publishing, multi-arch
+  container image, SLSA build provenance, and Trivy image scanning.
+- Pre-commit hooks: ruff, mypy, bandit, gitleaks, hadolint, shellcheck,
+  yamllint, markdownlint, commitizen.
+- `SECURITY.md` with responsible-disclosure workflow and supply-chain notes.
+- Licensed under **GNU AGPL-3.0-or-later** — users of hosted/network-facing
+  modified versions must receive the modified source.
+
+[Unreleased]: https://github.com/MysticRyuujin/mirror-bench/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/MysticRyuujin/mirror-bench/releases/tag/v0.1.0

{linux_mirror_bench-0.1.2 → linux_mirror_bench-0.3.0}/CONTRIBUTING.md

@@ -66,7 +66,7 @@ walks you through the format interactively.
 1. Create `src/mirror_bench/discovery/<name>.py` implementing
    `MirrorDiscoverer` (`discover`, `probe_path`, `throughput_path`).
 2. Register it in `src/mirror_bench/discovery/__init__.py`'s `DISCOVERERS` map.
-3. Add the distro's `ID` / `ID_LIKE` aliases to
+3. Add the distro's `ID` aliases to
    `src/mirror_bench/distro.py::_ALIASES`.
 4. Add a respx-mocked test with a realistic fixture under
    `tests/fixtures/<name>_*`.

{linux_mirror_bench-0.1.2 → linux_mirror_bench-0.3.0}/Dockerfile

@@ -8,7 +8,7 @@ ARG UV_VERSION=0.11.7
 FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv
 
 FROM python:${PYTHON_VERSION}-slim-bookworm AS builder
-ARG VERSION=0.1.0
+ARG VERSION=dev
 
 # Minimal build deps; nothing compiled lands in the final image.
 ENV PYTHONDONTWRITEBYTECODE=1 \
@@ -20,20 +20,26 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
 COPY --from=uv /uv /usr/local/bin/uv
 
 WORKDIR /app
-COPY pyproject.toml README.md LICENSE ./
+COPY pyproject.toml uv.lock README.md LICENSE ./
 COPY src ./src
 
-# Build the wheel, then install it (+ runtime deps) into a self-contained venv
-# under /opt/venv. No dev deps, no sources, no uv binary in the final image.
+# Build the wheel, then install it into a self-contained venv under /opt/venv.
+# Runtime deps come from uv.lock, so the image runs the same versions that CI
+# tests; resolving at build time would pull whatever is newest that day.
+# No dev deps, no sources, no uv binary in the final image.
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv venv /opt/venv \
+ && uv export --frozen --no-dev --no-emit-project --format requirements.txt \
+      --output-file /tmp/requirements.txt \
+ && VIRTUAL_ENV=/opt/venv uv pip install --no-cache --require-hashes \
+      -r /tmp/requirements.txt \
  && uv build --wheel \
  && wheel=$(find dist -maxdepth 1 -name '*.whl' -print -quit) \
- && VIRTUAL_ENV=/opt/venv uv pip install --no-cache "${wheel}"
+ && VIRTUAL_ENV=/opt/venv uv pip install --no-cache --no-deps "${wheel}"
 
 # ---- Runtime stage -------------------------------------------------------
 FROM python:${PYTHON_VERSION}-slim-bookworm AS runtime
-ARG VERSION=0.1.0
+ARG VERSION=dev
 
 LABEL org.opencontainers.image.title="mirror-bench" \
       org.opencontainers.image.description="Cross-distribution Linux package mirror benchmarking." \
@@ -46,11 +52,14 @@ LABEL org.opencontainers.image.title="mirror-bench" \
 # We deliberately do not pin ca-certificates: the whole point of this package
 # is to ship the latest Debian-security-vetted CA list at build time. Pinning
 # a specific version would freeze trust material and defeat the upgrade path.
+# The runtime never installs anything, so pip goes too: its vendored copies of
+# urllib3, msgpack, and setuptools are what image scanners report.
 # hadolint ignore=DL3008
 RUN apt-get update \
  && apt-get install -y --no-install-recommends ca-certificates \
  && apt-get clean \
  && rm -rf /var/lib/apt/lists/* \
+ && python -m pip uninstall --yes --no-cache-dir pip \
  && groupadd --system --gid 65532 app \
  && useradd --system --uid 65532 --gid app \
         --home-dir /home/app --create-home --shell /usr/sbin/nologin app

{linux_mirror_bench-0.1.2 → linux_mirror_bench-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: linux-mirror-bench
-Version: 0.1.2
+Version: 0.3.0
 Summary: Cross-distribution Linux package mirror benchmarking tool
 Project-URL: Homepage, https://github.com/MysticRyuujin/mirror-bench
 Project-URL: Issues, https://github.com/MysticRyuujin/mirror-bench/issues
@@ -21,6 +21,8 @@ Requires-Python: >=3.14
 Requires-Dist: httpx[http2]>=0.27
 Requires-Dist: rich>=13
 Requires-Dist: typer>=0.12
+Provides-Extra: http3
+Requires-Dist: aioquic>=1.2; extra == 'http3'
 Description-Content-Type: text/markdown
 
 # mirror-bench
@@ -35,7 +37,7 @@ Description-Content-Type: text/markdown
 
 A cross-distribution Linux package mirror benchmarking tool.
 
-Ranks mirrors by **latency**, **throughput**, and **security** (HTTPS / TLS 1.3 / cert validity / HTTP/2).
+Ranks mirrors by **latency**, **throughput**, and **security** (HTTPS / TLS 1.3 / HTTP/2).
 
 `mirror-bench` is **read-only**: it discovers mirrors, probes them, prints a
 ranked table, and exits. It never touches `/etc/apt/sources.list`,
@@ -131,19 +133,21 @@ Running `mirror-bench` with no subcommand is equivalent to `mirror-bench bench`.
 
 ### Common flags
 
-| Flag                          | Description                                                                                 |
-| ----------------------------- | ------------------------------------------------------------------------------------------- |
-| `--distro, -d NAME`           | One of `ubuntu`, `debian`, `fedora`, `mint`, `arch`.                                        |
-| `--release, -r VALUE`         | Release override: codename for apt (noble, bookworm, wilma) or numeric for Fedora (41, 42). |
-| `--country, -c US,CA,GB`      | ISO 3166-1 alpha-2 country codes to filter on.                                              |
-| `--top, -n N`                 | How many mirrors to include in phase 2 / display (default 15).                              |
-| `--concurrency N`             | Max parallel HTTP probes (default 20).                                                      |
-| `--https-only`                | Hard-exclude mirrors without HTTPS.                                                         |
-| `--tls13-only`                | Hard-exclude mirrors that don't negotiate TLS 1.3.                                          |
-| `--weights lat=…,thr=…,sec=…` | Override scoring weights (auto-normalized).                                                 |
-| `--no-throughput`             | Skip phase 2. Phase-1 latency screen only.                                                  |
-| `--json`                      | Emit JSON to stdout. Suppresses the table + progress.                                       |
-| `--csv`                       | Emit CSV to stdout. Suppresses the table + progress.                                        |
+| Flag                          | Description                                                                              |
+| ----------------------------- | ---------------------------------------------------------------------------------------- |
+| `--distro, -d NAME`           | One of `ubuntu`, `debian`, `fedora`, `mint`, `arch`.                                     |
+| `--release, -r VALUE`         | Release override: codename for apt (noble, trixie, zena) or numeric for Fedora (44, 45). |
+| `--country, -c US,CA,GB`      | ISO 3166-1 alpha-2 country codes to filter on.                                           |
+| `--top, -n N`                 | How many mirrors to include in phase 2 / display (default 15).                           |
+| `--concurrency N`             | Max parallel HTTP probes (default 20).                                                   |
+| `--https-only`                | Hard-exclude mirrors without HTTPS.                                                      |
+| `--tls13-only`                | Hard-exclude mirrors that don't negotiate TLS 1.3.                                       |
+| `--weights lat=…,thr=…,sec=…` | Override scoring weights (auto-normalized).                                              |
+| `--no-throughput`             | Skip phase 2. Phase-1 latency screen only.                                               |
+| `--max-age HOURS`             | Drop mirrors more than this far behind the newest mirror (default 36). `0` keeps all.    |
+| `--http3`                     | Probe over QUIC the mirrors that advertise HTTP/3. Needs the `http3` extra.              |
+| `--json`                      | Emit JSON to stdout. Suppresses the table + progress.                                    |
+| `--csv`                       | Emit CSV to stdout. Suppresses the table + progress.                                     |
 
 ## Running in Docker
 
@@ -161,8 +165,9 @@ directly.
 > The image renders a colored, properly-widened table even without `-it`.
 > If you want **rich to use your host terminal's exact width** (and react to
 > resizes), add `-it`; otherwise the image falls back to a sensible 120-col
-> table. Set `NO_COLOR=1` if you'd rather have plain text — e.g. when
-> redirecting to a file.
+> table. Set `NO_COLOR=1` if you'd rather have plain text with no escape
+> codes — e.g. when redirecting to a file. Progress bars show only when
+> stderr is a terminal.
 
 ### Basic invocation
 
@@ -277,7 +282,7 @@ All arguments are optional; defaults match what CI ships.
 | ---------------- | -------- | ------------------------------------------------------------------- |
 | `PYTHON_VERSION` | `3.14`   | Base image tag (`python:<PYTHON_VERSION>-slim-bookworm`).           |
 | `UV_VERSION`     | `0.11.7` | uv release pulled from `ghcr.io/astral-sh/uv:<UV_VERSION>`.         |
-| `VERSION`        | `0.1.0`  | Value embedded in the `org.opencontainers.image.version` OCI label. |
+| `VERSION`        | `dev`    | Value embedded in the `org.opencontainers.image.version` OCI label. |
 
 Example:
 
@@ -369,6 +374,26 @@ $ mirror-bench bench --<TAB>
 --distro  --country  --top  --concurrency  --https-only  --tls13-only  …
 ```
 
+## Supported distributions
+
+| `--distro` | Auto-detected from `/etc/os-release` `ID`      |
+| ---------- | ---------------------------------------------- |
+| `ubuntu`   | `ubuntu`, `pop`, `elementary`, `zorin`, `neon` |
+| `debian`   | `debian`                                       |
+| `fedora`   | `fedora`, `nobara`                             |
+| `mint`     | `linuxmint`                                    |
+| `arch`     | `arch`, `archlinux`, `endeavouros`             |
+
+Another Ubuntu remix is detected when its `os-release` has `ID_LIKE=ubuntu`
+and `UBUNTU_CODENAME`.
+
+Distributions with their own mirror network (RHEL family, Kali, Devuan,
+Raspberry Pi OS, Manjaro) are not supported. Ranking the mirrors of a
+different distribution for them gives a wrong answer.
+
+The Ubuntu, Mint, and Arch throughput tests always fetch the x86_64 file.
+The mirror lists for those distributions cover x86_64 mirrors only.
+
 ## How it works
 
 1. **Discover** — fetch the canonical mirror list for the target distribution:
@@ -376,23 +401,92 @@ $ mirror-bench bench --<TAB>
      set (`mirrors.ubuntu.com/mirrors.txt` returns a geo-selected _single_
      mirror, not a full list — so we don't rely on it alone).
    - Debian: `mirror-master.debian.org/status/Mirrors.masterlist` (RFC822
-     multi-record format).
+     multi-record format). The list does not say which sites serve HTTPS, so
+     each site is tried as an `https://` and an `http://` candidate.
    - Fedora: `mirrors.fedoraproject.org/mirrorlist?repo=&arch=&country=`.
+   - The Ubuntu and Fedora lists name one scheme for each mirror, often
+     `http://` for a host that also serves HTTPS. Each `http://` entry is
+     also tried as `https://`.
    - Linux Mint: scraped from `linuxmint.com/mirrors.php`.
-   - Arch: `archlinux.org/mirrors/status/json/` (JSON, filtered to active).
-2. **Phase 1 — latency screen.** Concurrent ranged GET (`bytes=0-1023`) on the
-   distro's canonical small metadata file (`InRelease`, `repomd.xml`,
-   `lastsync`). Three samples per mirror, **median TTFB** used for ranking.
-3. **Phase 2 — throughput test.** Full streaming GET of a representative file
-   (`Contents-<arch>.gz` for apt, `core.db` for Arch, etc.) on the top N from
-   phase 1, capped at 5 MiB. `bytes_per_sec` is measured from first-byte to
-   end-of-stream so steady-state bandwidth isn't polluted by connect/TLS
-   overhead.
+   - Arch: `archlinux.org/mirrors/status/json/` (JSON, filtered to active
+     HTTP and HTTPS entries).
+
+   If the list cannot be fetched, the command prints the reason and exits
+   with code 1.
+
+2. **Phase 1 — latency screen.** Concurrent ranged GET (`bytes=0-1023`) on a
+   small metadata file that the distribution rewrites as packages change:
+   `InRelease` of the `-updates` suite for Ubuntu and Debian, `Release` for
+   Mint, `repomd.xml` of the updates repository for Fedora, `lastupdate` for
+   Arch. Three samples per mirror, **median TTFB** used for ranking.
+3. **Phase 2 — throughput test.** Streaming GET of a large file
+   (`Contents-<arch>.gz` for apt, `images/install.img` for Fedora, `extra.db`
+   for Arch) on the top N from phase 1, capped at 5 MiB and 30 seconds.
+   `bytes_per_sec` is measured from first-byte to last-byte so steady-state
+   bandwidth isn't polluted by connect/TLS overhead.
+
+   A mirror that answers a missing file with status 200 and an HTML error
+   page fails phase 1 with `soft_404`. A complete phase 2 body under 256 KiB
+   fails with `short_body`. If no mirror passes phase 1, a line on stderr
+   gives the most common failure; a wrong `--release` is the usual cause.
+
+   Both phases follow redirects, so the timing includes the extra hop that a
+   package manager also pays. Only a 2xx final response counts. An `https://`
+   mirror that redirects to `http://` fails with `https_downgrade`. An
+   `http://` mirror gets no TLS credit, even when it redirects to HTTPS.
+
 4. **Score.** Weighted composite of normalized latency (inverse), throughput,
-   and security (HTTPS + TLS 1.3 + cert-valid + HTTP/2, max 3.5). Weights
+   and security (HTTPS 1 + TLS 1.3 1 + HTTP/2 0.5, max 2.5). Weights
    default to `lat=0.4, thr=0.4, sec=0.2` and are user-overridable.
+   - Throughput is the phase 2 measurement only. A mirror whose phase 2 probe
+     fails shows `-`, scores 0 for throughput, and reports the cause in the
+     `throughput_error` field of the JSON and CSV output.
+   - With `--no-throughput`, the throughput weight is 0 and the other weights
+     are normalized again.
+   - When a site answers on `https://` and `http://`, only the `https://` row
+     is kept.
 5. **Render.** A `rich.Table`, or JSON / CSV for scripting.
 
+### Freshness
+
+A fast mirror that stopped syncing serves old packages. The phase 1 file
+carries the time its content was generated, so each run also reads that
+time, with no extra request.
+
+- The `Age` column shows how far a mirror is behind the newest mirror in the
+  run: `0`, `23h`, `12d`, or `-` when the file gave no time. JSON and CSV
+  carry it as `sync_age_s`.
+- Age is relative to the other mirrors, not to your clock. If the
+  distribution published nothing for a week, every current mirror still
+  shows `0`.
+- Mirrors more than 36 hours behind are dropped before ranking, and a line on
+  stderr says how many. Change the limit with `--max-age HOURS`; `0` keeps
+  all mirrors.
+- Age does not change the score. A stale mirror is wrong, not slow.
+
+### HTTP/3
+
+Phase 1 reads the `Alt-Svc` response header. The `HTTP/3` column shows `adv`
+when a mirror advertises HTTP/3 (`h3`) for its own host; JSON and CSV carry
+the same fact as `h3_advertised`. This has no effect on the score: apt, dnf,
+and pacman do not use HTTP/3 today.
+
+To confirm the advertisement with a real QUIC request, install the optional
+extra and add `--http3`:
+
+```sh
+uv tool install "linux-mirror-bench[http3]"
+mirror-bench bench --distro arch --http3
+```
+
+- Each ranked mirror that advertises HTTP/3 gets one ranged GET over QUIC.
+- The `HTTP/3` column shows `yes` when that request succeeds. JSON and CSV
+  gain `h3_latency_ms` and `h3_error`.
+- If UDP is blocked on your network, the probes fail after about 8 seconds
+  and the column stays at `adv`.
+- Without the extra, `--http3` exits with code 2 and names the extra.
+- The container image does not include the extra.
+
 ## Development
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full dev loop.