debscout 0.1.0__tar.gz

debscout-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manish Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

debscout-0.1.0/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: debscout
+Version: 0.1.0
+Summary: Find the fastest up-to-date Debian mirrors and configure apt to use them, with automatic fallback
+Author: Manish Sharma
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/iam-super-user/debscout
+Project-URL: Issues, https://github.com/iam-super-user/debscout/issues
+Keywords: debian,apt,mirror,fastest,sources.list
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+debscout - find the fastest up-to-date Debian mirrors for apt
+=============================================================
+
+debscout tests Debian's official mirrors and CDNs from your own
+connection, skips any that are out of date, measures real download
+speed, and ranks them. If you ask it to, it points apt at the fastest
+ones using apt's mirror list feature, so apt falls back to the next
+mirror on its own if one fails. Every change is backed up and can be
+undone with one command.
+
+It needs Python 3.9 or newer and apt 1.6 or newer. Nothing else.
+
+
+Synopsis
+--------
+
+    debscout [options]                  test mirrors, print a ranking
+    debscout --apply [--dry-run] [-y]   switch apt to the fastest mirrors
+    debscout --status                   show what debscout has configured
+    debscout --undo                     put your original apt sources back
+
+
+Why
+---
+
+deb.debian.org is a good default, but on some networks the route to
+its CDN is very slow. On one machine in India it ran at 85-350 kB/s,
+while other official mirrors on the same connection gave 10-22 MB/s.
+A cold "apt-get update" took 116 seconds before debscout and 2.9
+seconds after.
+
+Picking a mirror by hand, or by ping time alone, goes wrong easily:
+
+  - A mirror can answer pings quickly and still download slowly.
+  - Some mirrors are hours, days or even months out of date.
+  - A single fast test can be luck. Some mirrors swing between fast
+    and slow from one minute to the next.
+
+debscout checks all three.
+
+
+Installation
+------------
+
+From the debscout apt repository (Debian 11 or newer, Ubuntu 22.04
+or newer). Upgrades then come with the rest of your system:
+
+    sudo curl -fsSLo /usr/share/keyrings/debscout.gpg \
+        https://iam-super-user.github.io/debscout/debscout.gpg
+    echo "deb [signed-by=/usr/share/keyrings/debscout.gpg] https://iam-super-user.github.io/debscout stable main" \
+        | sudo tee /etc/apt/sources.list.d/debscout-repo.list
+    sudo apt update
+    sudo apt install debscout
+
+The repository is signed with this key:
+
+    pub   rsa4096 2026-11-07 [SC] [expires: 2031-11-06]
+          5D2B C8E3 028B 5D62 39C6  416E A08C 17C2 1C69 04A9
+    uid   debscout apt repository <manish.sharma@owasp.org>
+
+To check the key you downloaded:
+
+    gpg --show-keys /usr/share/keyrings/debscout.gpg
+
+From a .deb file, downloaded from the GitHub releases page:
+
+    sudo apt install ./debscout_0.1.0-1_all.deb
+
+From PyPI, with pipx. sudo does not search ~/.local/bin, so give it
+the full path:
+
+    pipx install debscout
+    debscout
+    sudo "$(command -v debscout)" --apply
+
+From source, without installing anything:
+
+    git clone https://github.com/iam-super-user/debscout.git
+    cd debscout
+    ./debscout
+    sudo ./debscout --apply
+
+
+Quick start
+-----------
+
+    debscout                    # test mirrors and print the ranking
+    debscout --apply --dry-run  # show exactly what would change
+    sudo debscout --apply       # switch apt to the fastest mirrors
+    sudo debscout --undo        # put everything back
+
+Testing needs no root and changes nothing. A full run takes about a
+minute and a half.
+
+Example run:
+
+    $ debscout
+    debscout 0.1.0: testing mirrors for Debian trixie (amd64)
+    Debian mirror list: 351 mirrors (downloaded)
+    Checked 353 mirrors in 16s: 345 up to date, 3 out of date, 5 unreachable
+    Speed-testing 12 mirrors, 2 round(s) each (up to 8 MB or 5s per test)...
+
+     #      Speed  Latency  Behind  Where  Mirror
+     1  15.0 MB/s    14 ms    <1 h  BD     https://mirror.xeonbd.com/debian/
+     2   9.3 MB/s    38 ms    <1 h  CDN    https://cdn-aws.deb.debian.org/debian/
+     3   7.6 MB/s    76 ms    <1 h  SG     http://mirror.sg.gs/debian/
+     4   5.8 MB/s    82 ms    <1 h  MY     http://debian.tuxuri.com/debian/
+     ...
+     7   1.6 MB/s    44 ms    <1 h  IN     http://debian.mirror.net.in/debian/  unstable
+    12   118 kB/s    64 ms    <1 h  CDN    http://deb.debian.org/debian/
+
+    Skipped because they are out of date (closest first):
+      http://mirror.realcompute.io/debian/  18 h behind
+      http://mirror.sjtu.edu.cn/debian/  2 days behind
+
+    To switch apt to the top 3: sudo debscout --apply
+
+"Speed" is total bytes over total time across all rounds. "Latency"
+is the TCP connect time. "Behind" is how far the mirror lags the
+newest mirror seen. "unstable" means the speed changed more than
+four times between rounds.
+
+
+Options
+-------
+
+Actions (pick one; the default is to test and print a ranking):
+
+    --apply             switch apt to the fastest mirrors (needs root)
+    --undo              restore the apt sources debscout changed
+    --status            show what debscout has configured
+
+Testing:
+
+    -c, --country CC,...  only test mirrors in these countries, by ISO
+                          code (e.g. IN,SG,HK); the CDNs are always tested
+    -t, --test N          speed-test the N closest mirrors (default 10)
+    --rounds N            speed-test rounds per mirror (default 2)
+    --sample-mb MB        most MB to download per test (default 8)
+    --time-limit SEC      most seconds per test download (default 5)
+    --max-age HOURS       skip mirrors more than HOURS behind (default 12)
+    --timeout SEC         timeout when checking mirrors (default 4)
+    --suite SUITE         suite to test with (default: from your sources)
+    --arch ARCH           architecture to test with (default: from dpkg)
+    --no-cdn              don't consider Debian's CDNs
+
+Applying:
+
+    -n, --top N           put the N fastest mirrors in apt's list
+                          (default 3); deb.debian.org is always added
+                          last as a fallback
+    --dry-run             with --apply: show the changes, make none
+    --no-update           don't run "apt-get update" afterwards
+    -y, --yes             don't ask for confirmation
+
+Output:
+
+    --json                print the ranking as JSON
+    -v, --verbose         show every speed test
+    -q, --quiet           only print results and errors
+    -V, --version         print the version
+
+
+How it works
+------------
+
+1. Candidates. Every mirror in Debian's official list
+   (https://mirror-master.debian.org/status/Mirrors.masterlist) that
+   carries your architecture, plus Debian's two CDNs: deb.debian.org
+   (Fastly) and cdn-aws.deb.debian.org (Amazon CloudFront). The list
+   is cached for a day.
+
+2. Freshness. It reads each mirror's project/trace/master file, 32 at
+   a time, and skips mirrors more than 12 hours behind the newest one.
+   If a mirror redirects (often http to https), debscout keeps the
+   final address, so apt doesn't pay for a redirect on every request.
+
+3. Shortlist. It measures the TCP connect time to each up-to-date
+   mirror, the best of two tries, and keeps the 10 closest plus the
+   CDNs.
+
+4. Speed test. It downloads up to 8 MB of your suite's Packages.xz
+   from each shortlisted mirror, one mirror at a time so the tests
+   don't compete, in two interleaved rounds.
+
+5. Apply. It writes the 3 fastest mirrors, with deb.debian.org last
+   as a fallback, to an apt mirror list. Before writing, it checks
+   that each chosen mirror carries every suite you use.
+
+
+What --apply changes
+--------------------
+
+  - It creates /etc/apt/sources.list.d/debscout.sources with the same
+    suites, components and options as your Debian entries, pointing at
+    mirror+file:/etc/apt/mirrors/debscout-debian.list.
+
+  - It switches off your original Debian entries. Lines in .list files
+    are commented out, and "Enabled: no" is added to .sources files.
+    Other repositories (Chrome, Node.js, and so on) are never touched.
+
+  - It backs up every file before changing it.
+
+  - It runs "apt-get update". If that fails, everything is restored
+    automatically.
+
+Security updates only ever come from Debian's own hosts
+(cdn-aws.deb.debian.org, security.debian.org, deb.debian.org), never
+from third-party mirrors. Whichever mirror serves a file, apt still
+checks Debian's signatures, so a mirror cannot change packages.
+
+To re-rank later, run "sudo debscout --apply" again. The first backup
+is kept, so "--undo" always returns you to where you started.
+
+"sudo debscout --undo" restores every file exactly as it was. If you
+edited one of those files after applying, your edited copy is saved
+next to it as <name>.debscout-saved.
+
+
+Files
+-----
+
+    /etc/apt/sources.list.d/debscout.sources
+                            apt sources written by debscout
+    /etc/apt/mirrors/debscout-debian.list
+    /etc/apt/mirrors/debscout-debian-security.list
+                            mirror lists, fastest first
+    /var/lib/debscout/state.json
+                            what was changed, for --status and --undo
+    /var/lib/debscout/backup/
+                            original copies of changed files
+    /var/cache/debscout/Mirrors.masterlist
+                            cached mirror list (~/.cache/debscout/
+                            when not run as root)
+
+
+Exit status
+-----------
+
+    0     success
+    1     error (message on stderr)
+    2     bad command-line usage
+    130   interrupted with Ctrl-C
+
+
+Troubleshooting
+---------------
+
+"--apply needs root"
+    Run it with sudo. Use --apply --dry-run to preview without root.
+
+apt is slow or failing after --apply
+    Run "sudo debscout --apply" again to re-rank, or
+    "sudo debscout --undo" to go back.
+
+Behind a proxy
+    debscout honours the http_proxy and https_proxy environment
+    variables. sudo usually drops them, so use "sudo -E". apt's own
+    proxy settings are not read.
+
+A mirror you expected is missing
+    Only mirrors in Debian's official list are tested. Mirrors more
+    than --max-age hours behind are skipped and listed separately.
+
+
+Uninstalling
+------------
+
+    sudo debscout --undo        # first, if you used --apply
+    sudo apt remove debscout
+    sudo rm /etc/apt/sources.list.d/debscout-repo.list \
+            /usr/share/keyrings/debscout.gpg
+
+
+Development
+-----------
+
+Run the tests (standard library only, no network needed):
+
+    PYTHONPATH=src python3 -m unittest discover -s tests
+
+Source layout:
+
+    src/debscout/cli.py        command line and output
+    src/debscout/mirrors.py    mirror list, freshness checks, speed tests
+    src/debscout/sources.py    reading and writing apt sources
+    src/debscout/apply.py      backups, apply, undo, rollback
+    src/debscout/net.py        small HTTP helpers on urllib
+    tests/                     unit and end-to-end tests
+    debian/                    Debian packaging
+    scripts/build-apt-repo.sh  builds the signed apt repository
+
+Making a release:
+
+    1. Bump __version__ in src/debscout/__init__.py.
+    2. Add a debian/changelog entry with the same version.
+    3. Commit, then tag and push: git tag v0.1.1 && git push --tags
+
+The release workflow runs the tests, builds the .deb and the Python
+package, and publishes to PyPI, GitHub releases and the apt
+repository.
+
+
+Reporting bugs
+--------------
+
+Open an issue at https://github.com/iam-super-user/debscout/issues
+and include:
+
+  - the output of "debscout --version" and "debscout -v"
+  - your release (cat /etc/os-release)
+  - the files in /etc/apt/sources.list.d/, if --apply went wrong
+
+
+See also
+--------
+
+apt-transport-mirror(1), sources.list(5), netselect-apt(1).
+
+debscout was inspired by Manjaro's "pacman-mirrors --fasttrack" and
+Arch Linux's reflector. It is an independent implementation and
+shares no code with them.
+
+
+Author
+------
+
+Manish Sharma <manish.sharma@owasp.org>
+
+
+License
+-------
+
+MIT. See the LICENSE file.