Speed up downloads by combining multiple network connections in parallel
TypeScript bandwidth-aggregationcross-platformdesktop-appdownloaderdownloadmanagerlinuxmacosmulticonnectionparallel-downloadswindows
feat: add Windows compatibility and installer CI
Sahil Dabhi9cc4db54d627
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 4e7fd64..4f0727a 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -39,3 +39,20 @@ jobs:- name: Check formattingrun: npm run format:check++ windows:+ name: Windows build+ runs-on: windows-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version: 22+ cache: npm+ - name: Install dependencies+ run: npm ci++ - name: Build Windows installer+ run: npm run build:win -- --publish never+ env:+ CSC_IDENTITY_AUTO_DISCOVERY: 'false'diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 295d1f8..caca03d 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -11,7 +11,7 @@ npm installnpm run dev```-Requires macOS — interface detection relies on macOS's `networksetup` command, so the app won't run correctly on other platforms yet (see [README.md](README.md#requirements)).+Requires Windows 10/11 or macOS and Node.js 22.12+. See [requirements](README.md#requirements).## Before opening a PR@@ -21,11 +21,11 @@ npm run typechecknpm run format```-CI runs the same three checks on every pull request, with formatting checked rather than applied — if it flags something, `npm run format` fixes it.+CI runs these checks on every pull request, with formatting checked rather than applied — if it flags something, `npm run format` fixes it.`main` takes changes by pull request only: direct pushes and force-pushes are rejected, and CI has to be green before a PR can merge.-There's no test suite yet, so please describe how you tested your change manually (which URL/file size/interfaces you tried) in the PR description.+CI also builds the Windows installer. Please describe how you checked your change manually (which URL/file size/interfaces you tried) in the PR description.## Making changes@@ -38,7 +38,7 @@ There's no test suite yet, so please describe how you tested your change manuallOpen a GitHub issue with:-- macOS version+- Operating system and version- What you were downloading (URL if it's public, or roughly: file size, server type)- Which network interfaces were involved- Console/error output if there was a crashdiff --git a/README.md b/README.mdindex b19e224..2922080 100644--- a/README.md+++ b/README.md@@ -1,8 +1,8 @@# Plexo-A fast download manager for macOS that speeds up downloads by pulling chunks in parallel across **multiple network connections at the same time**.+A fast download manager for Windows and macOS that speeds up downloads by pulling chunks in parallel across **multiple network connections at the same time**.-For example, if your Mac has:+For example, if your computer has:- Wi-Fi- Ethernet@@ -16,7 +16,7 @@ https://github.com/user-attachments/assets/e57728f4-fb63-441f-839c-174eef954b17## ⚠️ Before you start-### Using Android USB tethering?+### Using Android USB tethering on macOS?macOS does not natively provide an RNDIS driver, so Android phones with USB tethering enabled won't appear as network interfaces out of the box (this is also why legacy kernel extensions like `HoRNDIS` stopped working on Apple Silicon and modern macOS).@@ -24,13 +24,13 @@ To use your Android phone's connection over USB, install **TetherKit** — a kexSee [Using a USB-tethered Android phone](#using-a-usb-tethered-android-phone) for setup instructions.-> Plexo can only route traffic through connections that macOS recognizes as network interfaces.+> Plexo can only route traffic through connections that your operating system recognizes as network interfaces.---## Why Plexo?-A single TCP connection rarely saturates your actual bandwidth. Even when your Mac has multiple active networks — such as Wi-Fi and a tethered mobile phone — the operating system routes all traffic through a single default gateway, leaving the other interfaces completely idle.+A single TCP connection rarely saturates your actual bandwidth. Even when your computer has multiple active networks — such as Wi-Fi and a tethered mobile phone — the operating system routes all traffic through a single default gateway, leaving the other interfaces completely idle.Plexo changes that: it splits the file into independent byte ranges and downloads them simultaneously through distinct physical network interfaces.@@ -49,7 +49,7 @@ File ──→ Split ─────┼── Ethernet (IP: 10.0.0.12) ───## Features- 🚀 **Multi-interface, multi-connection downloads** — splits files into fixed 8 MB chunks and fans them out across worker connections bound to specific network interfaces (up to 8 parallel connections per interface, 32 total).-- 🔌 **Hardware interface detection** — queries macOS hardware ports via `networksetup` so Wi-Fi, Ethernet, tethered iPhones, and Thunderbolt bridges are labeled by real device names instead of bare BSD names (`en0`, `en6`).+- 🔌 **Hardware interface detection** — queries Windows adapters via PowerShell `Get-NetAdapter` and macOS hardware ports via `networksetup` so Wi-Fi, Ethernet, tethered iPhones, and Thunderbolt bridges are labeled by real device names instead of bare BSD names (`en0`, `en6`).- ⚖️ **Dynamic work-stealing queue** — chunks are leased from a shared pending queue; faster networks pull more chunks instead of waiting for slower connections to finish.- ⏸️ **Resumable downloads** — pausing cleanly aborts in-flight socket connections while preserving downloaded `part-N` chunk files on disk.- 💾 **Relaunch recovery** — interrupted downloads are restored as paused after Plexo restarts, with progress and part files preserved in application data.@@ -91,7 +91,7 @@ Before starting a multi-connection download, Plexo sends a **1-byte ranged GET**### 2. Multi-interface socket binding via `localAddress`-Every active network interface on your Mac has its own local IP address — Wi-Fi might be `192.168.1.40`, while a USB-tethered phone is `172.20.10.3`.+Every active network interface on your computer has its own local IP address — Wi-Fi might be `192.168.1.40`, while a USB-tethered phone is `172.20.10.3`.A standard TCP socket leaves interface selection to the operating system's routing table. However, Node.js allows outbound HTTP/HTTPS requests to explicitly bind to a specific local IP using the `localAddress` option:@@ -214,8 +214,8 @@ Plexo currently doesn't have pre-built releases, so you'll need to run it from s## Requirements-- **macOS**: Plexo relies on macOS networking utilities (`networksetup`) for physical network interface discovery.-- **Node.js**: v18+ recommended.+- **Windows 10/11 or macOS**: Windows uses its built-in Windows PowerShell for adapter metadata; macOS uses `networksetup`. If metadata is unavailable, Plexo falls back to interface names.+- **Node.js**: 22.12+ (Node 22 LTS recommended).- **npm**: v9+ recommended.---@@ -259,7 +259,34 @@ dist/mac/Plexo.app> **Note on Gatekeeper:** The app is unsigned because it is not distributed with a paid Apple Developer certificate. However, because you compile it locally on your machine, macOS will not apply the quarantine flag (`com.apple.quarantine`). Gatekeeper only quarantines files downloaded from the web (via browsers, curl, etc.), so your locally built `Plexo.app` will launch cleanly without quarantine warnings.-_(Build scripts for Windows and Linux exist in `package.json`, but multi-interface routing and hardware detection have only been verified on macOS.)_+## Build the Windows app++Run these commands from PowerShell in the project directory:++```powershell+npm install+npm run build:win+```++The installer is generated at `dist/plexo-1.0.0-setup.exe`. For an unpacked app, run+`npm run build:unpack` and launch `dist/win-unpacked/plexo.exe`.+Local builds are unsigned.++Windows uses native window controls, Ctrl+V hints, File Explorer integration, and Windows+Network Settings. Download filenames are normalized to Windows filename rules.++### USB tethering on Windows++Enable USB tethering on your phone and check that its adapter appears in Windows Network+Settings. Install the phone manufacturer's Windows driver if Windows does not recognize it.+TetherKit is only needed for the macOS setup below.++Each selected network needs a working IPv4 connection and a route to the download server.+Adapter detection does not guarantee Internet access: VPN, virtual, and isolated adapters may+also appear. Check per-network latency and transfer stats. Combined throughput depends on the+networks, Windows routing, and the server; it needs testing with your particular connections.++Linux packaging remains available but has not been validated.---@@ -296,7 +323,7 @@ Contributions are welcome! Whether you're optimizing download concurrency, impro- 🐛 Fix bugs & edge cases- 🚀 Improve download engine & socket throughput-- 🌐 Expand multi-interface detection to other platforms (Linux / Windows)+- 🌐 Expand multi-interface detection to other platforms (Linux)- 🎨 Enhance UI/UX and dark mode styling- 🧪 Test diverse multi-network environments (5G tethering, Wi-Fi 6, 10GbE)- 📖 Improve documentation & guidesdiff --git a/electron-builder.yml b/electron-builder.ymlindex 39ddc96..ffb97d1 100644--- a/electron-builder.yml+++ b/electron-builder.yml@@ -13,6 +13,7 @@ asarUnpack:- resources/**win:executableName: plexo+ target: nsisnsis:artifactName: ${name}-${version}-setup.${ext}shortcutName: ${productName}diff --git a/package-lock.json b/package-lock.jsonindex 601a6bd..ffea37c 100644--- a/package-lock.json+++ b/package-lock.json@@ -1725,9 +1725,6 @@"x64"],"dev": true,- "libc": [- "glibc"- ],"license": "MIT","optional": true,"os": [@@ -1917,9 +1914,6 @@"arm"],"dev": true,- "libc": [- "glibc"- ],"license": "MIT","optional": true,"os": [@@ -1934,9 +1928,6 @@"arm"],"dev": true,- "libc": [- "musl"- ],"license": "MIT","optional": true,"os": [@@ -1951,9 +1942,6 @@"arm64"],"dev": true,- "libc": [- "glibc"- ],"license": "MIT","optional": true,"os": [@@ -1968,9 +1956,6 @@"arm64"],"dev": true,- "libc": [- "musl"- ],"license": "MIT","optional": true,"os": [@@ -1985,9 +1970,6 @@"loong64"],"dev": true,- "libc": [- "glibc"- ],"license": "MIT","optional": true,"os": [@@ -2002,9 +1984,6 @@"loong64"],"dev": true,- "libc": [- "musl"- ],"license": "MIT","optional": true,"os": [@@ -2019,9 +1998,6 @@"ppc64"],"dev": true,- "libc": [- "glibc"- ],"license": "MIT","optional": true,"os": [@@ -2036,9 +2012,6 @@"ppc64"],"dev": true,- "libc": [- "musl"- ],"license": "MIT","optional": true,"os": [@@ -2053,9 +2026,6 @@"riscv64"],"dev": true,- "libc": [- "glibc"- ],"license": "MIT","optional": true,"os": [@@ -2070,9 +2040,6 @@"riscv64"],"dev": true,- "libc": [- "musl"- ],"license": "MIT","optional": true,"os": [@@ -2087,9 +2054,6 @@"s390x"],"dev": true,- "libc": [- "glibc"- ],"license": "MIT","optional": true,"os": [@@ -2104,9 +2068,6 @@"x64"],"dev": true,- "libc": [- "glibc"- ],"license": "MIT","optional": true,"os": [@@ -2121,9 +2082,6 @@"x64"],"dev": true,- "libc": [- "musl"- ],"license": "MIT","optional": true,"os": [diff --git a/src/main/download/chunkDownloader.ts b/src/main/download/chunkDownloader.tsindex 14fda18..f2fe29a 100644--- a/src/main/download/chunkDownloader.ts+++ b/src/main/download/chunkDownloader.ts@@ -88,8 +88,13 @@ export function downloadChunk(options: ChunkDownloadOptions): Promise<void> {// resume has already reconciled that file's length. Discarding those// writes is safe: what survives on disk is what the next attempt// resumes from.- currentFileStream?.destroy()- reject(error)+ const stream = currentFileStream+ if (stream && !stream.closed) {+ stream.once('close', () => reject(error))+ stream.destroy()+ } else {+ reject(error)+ }})const onAbort = (): void => fail(new DOMException('Aborted', 'AbortError'))@@ -211,7 +216,9 @@ export function downloadChunk(options: ChunkDownloadOptions): Promise<void> {)return}- fileStream.end(() => finish(resolve))+ // Windows cannot reliably reopen/remove a file until its handle closes.+ fileStream.once('close', () => finish(resolve))+ fileStream.end()})})diff --git a/src/main/download/downloadManager.ts b/src/main/download/downloadManager.tsindex 1d673db..597c0a4 100644--- a/src/main/download/downloadManager.ts+++ b/src/main/download/downloadManager.ts@@ -12,6 +12,7 @@ import {writeFile} from 'node:fs/promises'import { basename, join } from 'node:path'+import { finished } from 'node:stream/promises'import type { BrowserWindow } from 'electron'import { app } from 'electron'import { IpcChannels } from '../../shared/ipc-channels'@@ -206,7 +207,7 @@ function appendFileToStream(sourcePath: string, output: NodeJS.WritableStream):output.once('drain', () => input.resume())}})- input.on('end', resolve)+ input.on('close', resolve)})}@@ -899,14 +900,8 @@ export class DownloadManager {bytesWritten += actualBytes}- await new Promise<void>((resolve, reject) => {- if (outputErrors.length > 0) {- reject(outputErrors[0])- return- }- output.on('error', reject)- output.end(resolve)- })+ output.end()+ await finished(output)if (outputErrors.length > 0) throw outputErrors[0]if (runtime.state.totalBytes > 0 && bytesWritten !== runtime.state.totalBytes) {@@ -916,6 +911,7 @@ export class DownloadManager {}} catch (error) {output.destroy()+ await finished(output).catch(() => {})// Leaving a half-written file where the user expects their download is// worse than leaving nothing: it looks like the download they asked for.await rm(runtime.state.destinationPath, { force: true })diff --git a/src/main/download/paths.ts b/src/main/download/paths.tsindex 01c7a96..af05b36 100644--- a/src/main/download/paths.ts+++ b/src/main/download/paths.ts@@ -14,6 +14,16 @@ export function getHomeDir(): string {// (or if something outside the app is creating them as fast as we try).const MAX_NAME_ATTEMPTS = 10_000+function sanitizeFileName(fileName: string): string {+ // A server-provided name is one component, never a path or NTFS data stream.+ let safe = fileName.replace(/[\\/]/g, '_').replace(/\p{Cc}/gu, '_')+ if (process.platform === 'win32') {+ safe = safe.replace(/[<>:"|?*]/g, '_').replace(/[ .]+$/, '')+ if (/^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(safe)) safe = `_${safe}`+ }+ return !safe || /^\.+$/.test(safe) ? 'download' : safe+}+/*** Claims <directory>/<fileName>, or <directory>/<fileName> (1), (2), ... if it* already exists, by creating an empty file at that path.@@ -29,6 +39,7 @@ const MAX_NAME_ATTEMPTS = 10_000* download doesn't end up producing a file.*/export async function reserveDestinationPath(directory: string, fileName: string): Promise<string> {+ fileName = sanitizeFileName(fileName)const ext = extname(fileName)const base = basename(fileName, ext)diff --git a/src/main/index.ts b/src/main/index.tsindex 1dcb858..077f88a 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -21,7 +21,7 @@ function createWindow(): void {// Matches the renderer's dark-mode background so a live window resize// (which briefly exposes the raw window background) doesn't flash white.backgroundColor: nativeTheme.shouldUseDarkColors ? '#1c1c1e' : '#ffffff',- ...(process.platform === 'linux' ? { icon } : {}),+ ...(process.platform !== 'darwin' ? { icon } : {}),// Design v2 draws its own logo + status readout where the title normally sits — on macOS,// keep the real traffic lights (still native, still draggable) but let the renderer's own// title bar occupy the rest of the strip instead of an OS-drawn title.diff --git a/src/main/ipc/handlers.ts b/src/main/ipc/handlers.tsindex e2d06c7..20dfee1 100644--- a/src/main/ipc/handlers.ts+++ b/src/main/ipc/handlers.ts@@ -12,7 +12,10 @@ import { measureLatencies } from '../network/latency'import { listActiveInterfaces } from '../network/interfaces'import { loadNetworkPreferences, saveNetworkPreference } from '../network/preferences'-const NETWORK_SETTINGS_URL = 'x-apple.systempreferences:com.apple.preference.network'+const NETWORK_SETTINGS_URL =+ process.platform === 'win32'+ ? 'ms-settings:network-status'+ : 'x-apple.systempreferences:com.apple.preference.network'export function registerIpcHandlers(getWindow: () => BrowserWindow | null): DownloadManager {let cachedInterfaces: NetworkInterfaceInfo[] = []diff --git a/src/main/network/interfaces.ts b/src/main/network/interfaces.tsindex 830583a..9d4c4b9 100644--- a/src/main/network/interfaces.ts+++ b/src/main/network/interfaces.ts@@ -4,6 +4,13 @@ import { promisify } from 'node:util'import type { NetworkInterfaceInfo, NetworkInterfaceKind } from '../../shared/types'const execFileAsync = promisify(execFile)+const DISCOVERY_TIMEOUT_MS = 5000++interface WindowsAdapter {+ Name: string+ InterfaceDescription: string+ NdisPhysicalMedium: number+}/*** macOS device names (en0, en1, ...) don't say what they are. `networksetup`@@ -11,10 +18,13 @@ const execFileAsync = promisify(execFile)* Thunderbolt Bridge, ...), which is what lets us label a USB-tethered phone* as such instead of just "en6".*/-async function getHardwarePortNames(): Promise<Map<string, string>> {+async function getMacHardwarePortNames(): Promise<Map<string, string>> {const deviceToName = new Map<string, string>()+ if (process.platform !== 'darwin') return deviceToNametry {- const { stdout } = await execFileAsync('networksetup', ['-listallhardwareports'])+ const { stdout } = await execFileAsync('networksetup', ['-listallhardwareports'], {+ timeout: DISCOVERY_TIMEOUT_MS+ })const blocks = stdout.split(/\n\s*\n/)for (const block of blocks) {const portMatch = /Hardware Port:\s*(.+)/.exec(block)@@ -31,35 +41,72 @@ async function getHardwarePortNames(): Promise<Map<string, string>> {function classifyInterface(hardwarePortName: string): NetworkInterfaceKind {const name = hardwarePortName.toLowerCase()- if (name.includes('wi-fi') || name.includes('airport')) return 'wifi'+ if (/wi-?fi|wireless|wlan|802\.11|airport/.test(name)) return 'wifi'+ if (/rndis|remote ndis|tether|apple mobile device/.test(name)) return 'usb'if (name.includes('iphone') || name.includes('ipad') || name.includes('usb')) return 'usb'if (name.includes('bridge')) return 'bridge'if (name.includes('ethernet') || name.includes('lan')) return 'ethernet'return 'other'}+/** Adapter aliases match Node's interface names; metadata identifies renamed or localized adapters. */+async function getWindowsAdapters(): Promise<Map<string, WindowsAdapter>> {+ if (process.platform !== 'win32') return new Map()+ try {+ const { stdout } = await execFileAsync(+ 'powershell.exe',+ [+ '-NoLogo',+ '-NoProfile',+ '-NonInteractive',+ '-Command',+ '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; Get-NetAdapter -ErrorAction Stop | Select-Object Name, InterfaceDescription, NdisPhysicalMedium | ConvertTo-Json -Compress'+ ],+ { windowsHide: true, timeout: DISCOVERY_TIMEOUT_MS, encoding: 'utf8' }+ )+ const parsed = JSON.parse(stdout.trim().replace(/^\uFEFF/, ''))+ const adapters: WindowsAdapter[] = Array.isArray(parsed) ? parsed : parsed ? [parsed] : []+ return new Map(+ adapters+ .filter((adapter) => typeof adapter.Name === 'string')+ .map((adapter) => [adapter.Name, adapter])+ )+ } catch {+ // Restricted PowerShell or unavailable metadata must not prevent downloads.+ return new Map()+ }+}+/**- * Active, externally-routable IPv4 interfaces on this Mac. Each one has its+ * Active non-loopback IPv4 interfaces. Each one has its* own local IP, which is what lets us bind a download's outgoing connection* to a specific interface (see chunkDownloader's `localAddress` option).*/export async function listActiveInterfaces(): Promise<NetworkInterfaceInfo[]> {- const hardwarePorts = await getHardwarePortNames()+ const hardwarePorts = await getMacHardwarePortNames()+ const windowsAdapters = await getWindowsAdapters()const all = networkInterfaces()const result: NetworkInterfaceInfo[] = []for (const [device, addresses] of Object.entries(all)) {if (!addresses) continue- const ipv4 = addresses.find((addr) => addr.family === 'IPv4' && !addr.internal)+ const ipv4 = addresses.find(+ (addr) => addr.family === 'IPv4' && !addr.internal && !addr.address.startsWith('169.254.')+ )if (!ipv4) continueconst hardwareName = hardwarePorts.get(device)+ const adapter = windowsAdapters.get(device)+ let kind = classifyInterface(adapter?.InterfaceDescription ?? hardwareName ?? device)+ // NDIS media: 1 = wireless LAN, 9 = native 802.11, 14 = Ethernet (802.3).+ if (adapter?.NdisPhysicalMedium === 1 || adapter?.NdisPhysicalMedium === 9) kind = 'wifi'+ else if (kind === 'other' && adapter?.NdisPhysicalMedium === 14) kind = 'ethernet'result.push({id: device,device,displayName: hardwareName ?? device,address: ipv4.address,- kind: classifyInterface(hardwareName ?? ''),+ kind,mac: ipv4.mac && ipv4.mac !== '00:00:00:00:00:00' ? ipv4.mac : undefined})}diff --git a/src/renderer/src/screens/CompleteScreen.tsx b/src/renderer/src/screens/CompleteScreen.tsxindex debc283..e204639 100644--- a/src/renderer/src/screens/CompleteScreen.tsx+++ b/src/renderer/src/screens/CompleteScreen.tsx@@ -301,7 +301,7 @@ export function CompleteScreen({New Download</button><button type="button" onClick={handleReveal} style={primaryButtonStyle}>- Reveal in Finder+ {window.plexo.platform === 'darwin' ? 'Reveal in Finder' : 'Show in folder'}</button></div></div>diff --git a/src/renderer/src/screens/IdleScreen.tsx b/src/renderer/src/screens/IdleScreen.tsxindex bfe1cf9..9dd234b 100644--- a/src/renderer/src/screens/IdleScreen.tsx+++ b/src/renderer/src/screens/IdleScreen.tsx@@ -205,7 +205,7 @@ export function IdleScreen(): React.JSX.Element {flexShrink: 0}}>- PASTE ⌘V+ PASTE {window.plexo.platform === 'darwin' ? '⌘V' : 'Ctrl+V'}</button></div><buttondiff --git a/src/renderer/src/utils/format.ts b/src/renderer/src/utils/format.tsindex 23dafdf..e1b3e23 100644--- a/src/renderer/src/utils/format.ts+++ b/src/renderer/src/utils/format.ts@@ -30,7 +30,7 @@ export function formatPercent(bytesDownloaded: number, totalBytes: number): numb}export function fileNameFromPath(path: string): string {- return path.split('/').pop() ?? path+ return path.split(/[\\/]/).pop() ?? path}/** Short uppercase file-type badge from a name's extension, e.g. "Xcode_16.2.xip" -> "XIP". */@@ -57,8 +57,10 @@ export function splitFormattedBytes(bytes: number): { value: string; unit: strin}export function dirnameOf(path: string): string {- const index = path.lastIndexOf('/')- return index <= 0 ? '/' : path.slice(0, index)+ const index = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))+ if (index < 0) return '.'+ if (index === 0 || (index === 2 && path[1] === ':')) return path.slice(0, index + 1)+ return path.slice(0, index)}export interface NetworkGroup {@@ -102,8 +104,16 @@ export function groupChunksByInterface(chunks: ChunkState[]): NetworkGroup[] {/** Shortens an absolute path under the user's home directory to a "~/..." form for display. */export function toDisplayPath(path: string, homeDir: string): string {- if (homeDir && (path === homeDir || path.startsWith(`${homeDir}/`))) {- return `~${path.slice(homeDir.length)}`+ const normalize = (value: string): string => {+ const normalized = value.replace(/\\/g, '/').replace(/\/$/, '')+ return /^[a-z]:/i.test(normalized) || normalized.startsWith('//')+ ? normalized.toLowerCase()+ : normalized+ }+ const home = normalize(homeDir)+ const target = normalize(path)+ if (home && (target === home || target.startsWith(`${home}/`))) {+ return `~${path.slice(home.length)}`}return path}