windscout 0.5.7 → 0.6.0

package/README.md

@@ -13,6 +13,7 @@ WindScout drives the official `windscribe-cli`: it connects to each country × p
 - Linux, macOS or Windows 10/11
 - Node.js 20+
 - The [Windscribe desktop app](https://windscribe.com/download) installed, running and logged in. It includes `windscribe-cli`, which WindScout uses to control the app. Check with `windscribe-cli status`, which should show `Logged in`. On Windows the app doesn't put the CLI on `PATH`, so run `"C:\Program Files\Windscribe\windscribe-cli.exe" status` instead. WindScout finds it there on its own.
+- Optional, for [parallel scans](#parallel-scan-with-docker): Docker. WindScout offers to install it.
 
 ## Install
 
@@ -52,6 +53,8 @@ Run `windscout` with no arguments to open the interactive picker:
 | `1`–`6` | toggle a protocol (`1`–`5` on Linux, which has no IKEv2) |
 | `s` | toggle the speed test (off = connect-only mode) |
 | `f` | toggle "block internet while scanning" (firewall) |
+| `r` | toggle random order: scan the selected countries shuffled, a new order each run |
+| `d` | toggle the [parallel scan in docker containers](#parallel-scan-with-docker) (installs or starts docker first, after asking) |
 | `u` | update to the newer version and restart (only when the picker shows one is out) |
 | `enter` | start scanning |
 | `q` | quit (during a scan: stop and show partial results; press again to force quit) |
@@ -60,7 +63,7 @@ Run `windscout` with no arguments to open the interactive picker:
 
 Your selection is saved to `~/.config/windscout/config.json` (`%USERPROFILE%\.config\windscout\config.json` on Windows) and preselected next time.
 
-While scanning, WindScout shows a progress bar, elapsed time and remaining time. It also shows what it's doing right now (connecting, measuring latency or measuring speed). The table of working locations refreshes after each country. When the scan finishes, the final report is printed to your normal terminal. It ends with the best connection and the other working ones, each with its `windscribe-cli connect` command; type a number at the prompt to connect to it.
+While scanning, WindScout shows a progress bar, elapsed time and remaining time. It also shows what it's doing right now (connecting, measuring latency or measuring speed). The table of working locations refreshes after each country. When the scan finishes, the final report is printed to your normal terminal. It ends with the best connection and the other working ones, each with its `windscribe-cli connect` command. At the prompt, press enter to connect to the best one, type another one's number to connect to that, or `q` to quit.
 
 ### Non-interactive
 
@@ -80,6 +83,8 @@ windscout -t 40 -a                          # longer connect timeout, also list
 | `-a, --all` | include failed attempts in the final table | off |
 | `-n, --no-speed` | connect-only mode: skip the download test, rank by latency | picker: saved, or connect-only on first run; with `-c`: speed test on |
 | `-f, --firewall` | block internet while scanning, except through the VPN | picker: saved, or off; with `-c`: off |
+| `-r, --random` | scan the countries in a random order | picker: saved, or off; with `-c`: off |
+| `-d, --docker` | [scan in parallel, in docker containers](#parallel-scan-with-docker) | picker: saved, or off; with `-c`: off |
 | `-v, --version` | print the installed version; if a newer one is on npm, show the update command (with `sudo` when needed) and ask (y/n) to run it | |
 
 ## Connect-only mode
@@ -107,6 +112,48 @@ While scanning, press `tab` to switch between the availability grid and the spee
 
 Between attempts the VPN is disconnected for a moment, and apps on your computer (browser, messengers, updates) can go online over your real connection. Turn on **block internet while scanning** with `f` in the picker or `--firewall`, and WindScout switches on the Windscribe app's firewall for the scan: nothing gets online except through the VPN. When the scan ends or you stop it, the firewall goes back off (if you already had it on, WindScout leaves it on). While a scan is paused, the firewall keeps blocking.
 
+## Parallel scan with Docker
+
+A normal scan tries one location at a time, because your computer has one VPN connection. Turn on **parallel scan** with `d` in the picker or `--docker`, and each attempt runs in its own docker container instead. Each container has its own Windscribe app (Windscribe's Linux CLI app) and so its own VPN connection, and several locations are tried at once. The results come back to the scan screen, which shows a line per container.
+
+**How many containers:** one per attempt, as many as docker's CPUs allow and three quarters of its memory (at 250 MB each), at most 8. The picker shows the number (`8 at a time`) and the estimate that goes with it.
+
+**First time:** if docker isn't installed or isn't running, `d` (or a scan with `--docker`) opens a dialog that says what WindScout will do, and does it once you agree:
+
+- **macOS:** downloads Docker Desktop from docker.com (about 600 MB), installs it in `/Applications` with its license accepted, and starts it.
+- **Linux:** runs Docker's install script from get.docker.com (or, where docker.com refuses, installs your distribution's own docker package), adds you to the `docker` group and starts docker. The group takes effect in a new login session: log out and back in (or run `newgrp docker`), then start WindScout again. Members of the `docker` group can control docker, which is as good as root.
+- **Windows:** installs Docker Desktop with winget, with its license accepted and its WSL 2 engine, and starts it. Windows asks for permission, and may want a restart. Docker Desktop may also ask to install or update WSL: do what it asks, then try again. If Docker Desktop is set to Windows containers, switch it to Linux containers (right-click its icon by the clock).
+
+Steps that need root ask for your password in the dialog. WindScout checks it with `sudo` once, so a typo counts as one failed try. It keeps the password in memory until the steps are done and never saves it. Docker Desktop is free for personal use, education and small businesses; bigger companies need a [paid plan](https://www.docker.com/pricing/).
+
+Then the first parallel scan builds a local image, `windscout-worker`, with Node and Windscribe's Linux CLI app (the latest stable release on [GitHub](https://github.com/Windscribe/Desktop-App/releases)). That takes a few minutes. Later scans reuse it until WindScout updates.
+
+**In Iran (and other places docker.com refuses):** Docker Hub and docker.com refuse Iranian addresses (US sanctions), so every download falls back to mirrors in Iran when the official source refuses or doesn't answer. Everywhere else, the official sources are used as before:
+
+- **The image's base** (`node:22-bookworm-slim`) comes from Docker Hub, else from the first mirror of it that answers: `registry.docker.ir`, `docker.iranserver.com`, `docker.kernel.ir`, `mirror2.chabokan.net`, `docker-mirror.liara.ir`, `hub.hamdocker.ir`, `docker.arvancloud.ir`, `focker.ir`, `docker.mobinhost.com`, `mirror-docker.runflare.com`. It's pinned by digest, so a mirror can only hand over that exact image. To try other mirrors first, list them in `WINDSCOUT_REGISTRY_MIRRORS` (comma-separated hosts).
+- **Debian's packages** in the image come from deb.debian.org, else `mirror.shatel.ir`, `mirror.iranserver.com`, `mirror.mobinhost.com` or `mirror2.chabokan.net`. apt checks Debian's signatures, whichever mirror serves them.
+- **Windscribe's app** in the image comes from GitHub, which Iran can reach.
+- **Docker on Linux:** where get.docker.com refuses, your distribution's own docker package is installed instead, from the mirrors your system already uses.
+- **Docker Desktop on macOS and Windows** has no mirror anywhere: when docker.com refuses the download, the dialog says so. Connect a VPN (Windscribe will do), then press Retry. That's needed once, for the install.
+
+The mirrors come from [Mirava](https://github.com/MiravaOrg/Mirava)'s list of mirrors in Iran; they come and go, and that's where to look for new ones.
+
+**Kernel check:** each container first checks that docker's Linux kernel gives it what Windscribe needs: a tunnel device (tun) and a firewall (nftables). If not, the scan stops and says so, rather than showing every location as blocked. Windscribe's WireGuard also needs nftables' `fib` in its firewall table, which Docker Desktop's own Linux VM lacks (on macOS, and on Windows without WSL 2). There, WireGuard runs on this computer instead (see below).
+
+**Login:** each container's Windscribe app logs in once. WindScout asks for your Windscribe username and password (and a 2FA code or captcha when Windscribe asks for one) and passes them to the containers, one at a time. Each login is kept in that container's docker volume (`windscout-1`, `windscout-2`, …), so later scans don't ask.
+
+**Remember username and password** is ticked to start with (tab to it and press space, or click it). Once the login works, WindScout saves both in `~/.config/windscout/login.json`, as plain text that only you can read. Then containers that are new next time (a scan with more attempts) log in by themselves, with no terminal too; a 2FA code is never saved, so with 2FA they still ask. Untick it and nothing is saved, and a login saved before is forgotten. Deleting that file forgets it too. With `-c` and no terminal, only containers that are logged in already, or can log in with the remembered login, take part.
+
+**Measuring:** the containers share your internet connection, so they take turns measuring latency and speed while the connecting happens in parallel. Numbers stay comparable with a normal scan. Most of the time saved comes from attempts that hang until the timeout, which overlap now.
+
+**Differences from a normal scan:**
+
+- IKEv2, and WireGuard when the kernel check finds it can't run in the containers, are tried on this computer once the containers are done, one at a time like a normal scan. The scan screen shows them on a line of their own (`this computer`), and the picker's estimate counts them. Windscribe's Linux app has no IKEv2.
+- This computer's own Windscribe connection is disconnected at the start and stays off while the containers scan, since it would carry their traffic too.
+- No firewall: "block internet while scanning" isn't used, since it would block the containers' traffic too.
+
+The containers are removed after the scan. To remove the logins too, run `docker volume rm windscout-1 windscout-2 …`. To remove the image, run `docker rmi windscout-worker`.
+
 ## Output
 
 While scanning:
@@ -142,7 +189,7 @@ At the end, the results, a per-protocol summary and the best pick are printed to
 - **The country list is built in.** On v2.24, `windscribe-cli locations` returns nothing, so WindScout uses a fixed list of country codes. Codes Windscribe doesn't serve are skipped quickly.
 - **A full scan takes a while.** The worst case is countries × protocols × timeout. Narrow it with `-c` and `-p`.
 - **No flags in macOS Terminal.** Terminal.app draws flag emoji wider than their space, which pushes table borders out of line, so WindScout leaves them out there (as on Windows). iTerm2 and other terminals show them.
-- **Your connection changes during the scan.** WindScout connects and disconnects the VPN repeatedly, so don't run it while you need a stable connection.
+- **Your connection changes during the scan.** WindScout connects and disconnects the VPN repeatedly, so don't run it while you need a stable connection. A [parallel scan](#parallel-scan-with-docker) does that inside its containers instead, and your computer's own VPN stays off.
 
 ## Development
 
@@ -151,6 +198,7 @@ The source is TypeScript in `src/`. It compiles to `dist/`, which is what gets p
 ```sh
 npm install
 npm run build       # compile src/ to dist/ (the windscout command is dist/cli.js)
+npm test            # build, then check the scan's scheduling (no VPN, no docker)
 node dist/cli.js    # run your build; takes the same options as windscout
 ./publish.sh        # build, install the packed tarball to check it runs, publish to npm (bump the version first)
 ```

package/dist/cli.js

@@ -5,8 +5,11 @@
 import { createInterface } from "node:readline";
 import { spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
-import { CONFIG, DEFAULT_TIMEOUT, loadConfig, MIN_TIMEOUT } from "./config.js";
+import { CONFIG, DEFAULT_TIMEOUT, loadConfig, loadDockerWireGuard, MIN_TIMEOUT, saveDockerWireGuard } from "./config.js";
+import { notInContainers, stopWorkers } from "./docker.js";
+import { probe } from "./probe.js";
 import { Scan } from "./scan.js";
+import { startParallel } from "./tui/docker.js";
 import { pick } from "./tui/picker.js";
 import { logProgress, showProgress } from "./tui/progress.js";
 import { command, report, target } from "./tui/report.js";
@@ -15,6 +18,7 @@ import { cyan, green, yellow } from "./tui/text.js";
 import { now, sleep } from "./time.js";
 import { canUpdate, checkUpdate, runUpdate, updateNotice, versionLines } from "./update.js";
 import { blockInternet, CLI, connectState, isFirewallOn, PROTOCOLS, restoreFirewall, waitForLogin, windscribe } from "./windscribe.js";
+import { worker } from "./worker.js";
 const HELP = `Usage: windscout [options]
 
 Find which Windscribe locations and protocols work from your network, ranked by speed.
@@ -27,6 +31,8 @@ Options:
   -a, --all             also show failed attempts in the final table
   -n, --no-speed        connect-only: skip the download test, rank by latency (faster scan)
   -f, --firewall        block internet while scanning, except through the VPN (turned back off afterwards)
+  -r, --random          scan the countries in a random order
+  -d, --docker          scan in parallel, in docker containers (as many as docker's CPUs and memory allow, up to 8)
   -v, --version         show the installed version (and offer to update if a newer one is out)
   -h, --help            show this help
 
@@ -36,18 +42,18 @@ Example: windscout -c DE,NL,TR -p stealth,tcp:443`;
 const list = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
 const ask = (question) => new Promise((resolve) => {
     const rl = createInterface({ input: process.stdin, output: out });
-    rl.on("SIGINT", () => rl.close()); // Ctrl-C / Ctrl-D: same as enter
-    rl.on("close", () => resolve(""));
+    rl.on("SIGINT", () => rl.close()); // Ctrl-C / Ctrl-D: no answer, null
+    rl.on("close", () => resolve(null));
     rl.question(question, (a) => (resolve(a.trim()), rl.close()));
 });
-/** Asks which numbered connection to make, then runs its command and waits for it to connect */
+/** Asks which numbered connection to make (enter: the best), then runs its command and waits for it to connect */
 async function offerConnect(choices, timeout) {
-    const others = choices.length > 1 ? `, 1-${choices.length - 1} = other` : "";
+    const others = choices.length > 2 ? `, 1-${choices.length - 1} = other` : choices.length > 1 ? ", 1 = other" : "";
     for (;;) {
-        const a = await ask(`\nconnect to # (0 = best${others}, enter to quit): `);
-        if (!a)
+        const a = await ask(`\nconnect to # (enter or 0 = best${others}, q = quit): `);
+        if (a === null || /^q(uit)?$/i.test(a))
             return;
-        const r = /^\d+$/.test(a) ? choices[Number(a)] : undefined;
+        const r = a === "" ? choices[0] : /^\d+$/.test(a) ? choices[Number(a)] : undefined;
         if (!r) {
             console.log(yellow(`no #${a} in the tables`));
             continue;
@@ -83,15 +89,22 @@ async function main() {
             version: { type: "boolean", short: "v", default: false },
             "no-speed": { type: "boolean", short: "n", default: false },
             firewall: { type: "boolean", short: "f", default: false },
+            random: { type: "boolean", short: "r", default: false },
+            docker: { type: "boolean", short: "d", default: false },
+            worker: { type: "boolean", default: false }, // in a parallel scan's container
         },
     });
+    if (a.worker) {
+        await worker();
+        process.exit(); // its stdin may still be open: it has no login to scan with
+    }
     if (a.help)
         return console.log(HELP);
     checkUpdate(); // runs while the app starts and the user picks, before the VPN starts switching
     if (a.version) {
         await checkUpdate();
         console.log(versionLines().join("\n"));
-        if (canUpdate() && process.stdin.isTTY && out.isTTY && /^y(es)?$/i.test(await ask("update now? (y/n) ")))
+        if (canUpdate() && process.stdin.isTTY && out.isTTY && /^y(es)?$/i.test((await ask("update now? (y/n) ")) ?? ""))
             process.exitCode = runUpdate();
         return;
     }
@@ -104,6 +117,8 @@ async function main() {
     let protocols = a.protocols ? list(a.protocols) : undefined;
     let speedTest = !a["no-speed"];
     let firewall = a.firewall;
+    let random = a.random;
+    let docker = a.docker;
     if (!countries) {
         if (!tty)
             throw new Error("no terminal for the picker: pass countries with -c");
@@ -115,6 +130,8 @@ async function main() {
             speedTest: speedTest && (saved?.speed ?? false), // first run: connect-only
             // already on in the app: show it on, since the scan won't turn it off
             firewall: firewall || isFirewallOn(status) || (saved?.firewall ?? false),
+            random: random || (saved?.random ?? false),
+            docker: docker || (saved?.docker ?? false),
         });
         if (!choice)
             return;
@@ -124,16 +141,37 @@ async function main() {
         protocols ??= choice.protocols;
         speedTest = choice.speed;
         firewall = choice.firewall;
+        random = choice.random;
         timeout = choice.timeout;
+        docker = choice.docker;
     }
     protocols ??= PROTOCOLS;
     timeout ??= DEFAULT_TIMEOUT;
-    const scan = new Scan(countries, protocols, { timeout, speedTest });
-    const blocking = firewall && (await blockInternet());
+    if (random)
+        countries = countries.map((c) => [Math.random(), c]).sort(([x], [y]) => x - y).map(([, c]) => c);
+    let probers = [probe], after; // after: what runs here once the containers are done
+    const later = notInContainers(protocols, loadDockerWireGuard()); // as far as the last parallel scan knows
+    const inContainers = countries.length * protocols.filter((p) => !later.has(p)).length;
+    if (docker && inContainers) {
+        const started = await startParallel(inContainers);
+        if (!started)
+            return leaveScreen();
+        saveDockerWireGuard(started.wireguard);
+        probers = started.probers;
+        after = { prober: probe, protocols: notInContainers(protocols, started.wireguard), name: "this computer" };
+        await windscribe("disconnect"); // a VPN connection here would carry the containers' traffic too
+    }
+    const scan = new Scan(countries, protocols, { timeout, speedTest }, probers, after);
+    // not with containers: their traffic goes out through this computer, and the firewall would block it
+    const blocking = firewall && !after && (await blockInternet());
     const view = tty ? showProgress(scan, blocking) : logProgress(scan);
     await scan.run(view);
+    if (after)
+        await stopWorkers();
     await restoreFirewall();
     view.close();
+    for (const e of new Set(scan.errors))
+        console.error(yellow(e));
     if (scan.stopping)
         console.log(yellow("interrupted, showing partial results"));
     const choices = report(scan.results, protocols, { all: a.all, speedTest });

package/dist/config.js

@@ -1,11 +1,14 @@
-// The picker's selection, remembered between runs.
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+// The picker's selection, and the docker containers' Windscribe login if wanted, remembered between runs.
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { COUNTRIES, PROTOCOLS } from "./windscribe.js";
 export const DEFAULT_TIMEOUT = 15;
 export const MIN_TIMEOUT = 10; // seconds; shorter cuts off connections that would have worked
 export const CONFIG = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "windscout", "config.json");
+// ponytail: plain text that only this user can read, like git's credential store; the OS keychain if that's not enough
+export const LOGIN_FILE = join(dirname(CONFIG), "login.json");
+const DOCKER_FILE = join(dirname(CONFIG), "docker.json"); // what the last parallel scan found its containers can do
 /** The saved choice, minus anything this version doesn't offer; null on first run or an unreadable file */
 export function loadConfig() {
     try {
@@ -15,7 +18,9 @@ export function loadConfig() {
             protocols: (c.protocols ?? []).filter((x) => PROTOCOLS.includes(x)),
             speed: c.speed !== false,
             firewall: c.firewall === true,
+            random: c.random === true,
             timeout: c.timeout >= MIN_TIMEOUT ? c.timeout : DEFAULT_TIMEOUT,
+            docker: c.docker === true,
         };
     }
     catch {
@@ -29,3 +34,40 @@ export function saveConfig(c) {
     }
     catch { } // not being able to remember isn't worth failing the scan
 }
+/** Whether WireGuard worked in the docker containers last time (yes until a scan finds otherwise), for the picker's estimate */
+export function loadDockerWireGuard() {
+    try {
+        return JSON.parse(readFileSync(DOCKER_FILE, "utf8")).wireguard !== false;
+    }
+    catch {
+        return true;
+    }
+}
+export function saveDockerWireGuard(wireguard) {
+    try {
+        mkdirSync(dirname(DOCKER_FILE), { recursive: true });
+        writeFileSync(DOCKER_FILE, JSON.stringify({ wireguard }) + "\n");
+    }
+    catch { } // not being able to remember isn't worth failing the scan
+}
+/** The Windscribe login remembered for the docker containers; null when there's none */
+export function loadLogin() {
+    try {
+        const { username, password } = JSON.parse(readFileSync(LOGIN_FILE, "utf8"));
+        return typeof username === "string" && typeof password === "string" ? { username, password } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Remembers the login, or forgets it (null) */
+export function saveLogin(c) {
+    try {
+        rmSync(LOGIN_FILE, { force: true }); // a new file gets the mode below; an old one would keep its own
+        if (!c)
+            return;
+        mkdirSync(dirname(LOGIN_FILE), { recursive: true });
+        writeFileSync(LOGIN_FILE, JSON.stringify(c) + "\n", { mode: 0o600 });
+    }
+    catch { } // not being able to remember isn't worth failing the scan
+}