Skip to content

armgit / plexo

Public Imported from GitHub
0

Speed up downloads by combining multiple network connections in parallel

Add MIT license and rewrite README for public release

Anmol Kapil49dba9f247d5
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..de30b65
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anmol Kapil
+
+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.
diff --git a/README.md b/README.md
index d9b2e90..1651ac9 100644
--- a/README.md
+++ b/README.md
@@ -1,34 +1,60 @@
-# plexo
+# Plexo
-An Electron application with React and TypeScript
+Plexo is a macOS download manager that speeds up downloads by splitting a file into blocks and pulling them in parallel across your available network interfaces — Wi-Fi, Ethernet, a USB-tethered phone, whatever you've got connected at once.
-## Recommended IDE Setup
+<!-- Demo video coming soon -->
-- [VSCode](https://code.visualstudio.com/) + [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) + [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+## Why
-## Project Setup
+A single TCP connection rarely saturates your real bandwidth, and if your Mac has more than one network path available (say, Wi-Fi + a phone tethered over USB), most download tools only ever use one of them at a time. Plexo probes the URL, splits the file into range-addressed blocks, and downloads them in parallel over every interface you select — binding each connection to a specific interface's IP — then reassembles the file once every block lands.
-### Install
+## Features
+
+- **Multi-connection, multi-interface downloads** — splits the file into ~64 blocks (min. 4 MB each) and fans them out across worker connections bound to the network interfaces you pick, with up to 8 parallel connections per interface
+- **Real interface detection** — reads actual macOS hardware ports (`networksetup`) so a tethered iPhone or Thunderbolt Bridge shows up labeled correctly, not as a bare `en0`/`en6`
+- **Dynamic work-stealing** — blocks are leased from a shared pending queue, so a faster connection just keeps pulling more blocks instead of sitting idle while a slower one catches up
+- **Resumable** — pausing aborts in-flight connections without losing progress; resuming re-verifies the remote file's ETag/Last-Modified first and refuses to resume (rather than silently corrupt the file) if the server-side content changed
+- **Resilient** — per-block retry with exponential backoff, stall detection on dead-but-open connections, mid-download redirect following, and an upfront disk-space check before writing anything
+- **Per-network customization** — rename and recolor each physical network, with preferences persisted across runs
+- **Live per-connection stats** — throughput, ETA, and a visual map of which blocks are being pulled by which interface
+- **Dark mode**
+
+## How it works
+
+1. Plexo sends a 1-byte ranged GET to the URL to check whether the server supports byte ranges (`Accept-Ranges`) and to read its size, filename, and ETag/Last-Modified.
+2. If ranges are supported, the file is split into fixed-size blocks; if not, it falls back to a single-connection download.
+3. One worker per requested connection binds its outgoing socket to a chosen network interface's local IP and pulls blocks from a shared queue until none remain.
+4. Finished blocks are concatenated in order into the destination file once every block completes.
+
+This is all plain Node `http`/`https` requests bound via `localAddress` — no native networking dependencies.
+
+## Running it
+
+No prebuilt releases yet — clone and run it locally, or build the app yourself.
+
+Requirements: Node.js, npm, macOS (interface detection relies on macOS's `networksetup`, so other platforms aren't supported yet).
```bash
-$ npm install
+git clone https://github.com/anmolkapil/plexo.git
+cd plexo
+npm install
+npm run dev
```
-### Development
+### Building the app
```bash
-$ npm run dev
+npm run build:mac
```
-### Build
+This builds `dist/mac/Plexo.app` locally, unsigned (no Apple Developer certificate). Since you built it yourself, macOS won't quarantine it and Gatekeeper won't complain — Gatekeeper only checks signatures on files that were downloaded via a browser/curl/etc., which is what sets the quarantine flag in the first place. A locally built app never gets that flag.
-```bash
-# For windows
-$ npm run build:win
+Windows and Linux build scripts exist (`build:win`, `build:linux`) but are untested — Plexo has only been developed and verified on macOS.
-# For macOS
-$ npm run build:mac
+## Tech stack
-# For Linux
-$ npm run build:linux
-```
+Electron, React 19, TypeScript, Zustand, built with `electron-vite`/`electron-builder`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
diff --git a/package.json b/package.json
index c831e36..d5a08b1 100644
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
"version": "1.0.0",
"description": "Speed up downloads by combining multiple network connections in parallel",
"main": "./out/main/index.js",
- "author": "example.com",
+ "author": "Anmol Kapil",
"scripts": {
"format": "prettier --write .",
"lint": "eslint --cache .",