plexo-cli 0.1.0__tar.gz

plexo_cli-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+out
+.DS_Store
+.eslintcache
+*.log*
+test-results
+playwright-report
+*.tsbuildinfo

plexo_cli-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: plexo-cli
+Version: 0.1.0
+Summary: Multi-network bandwidth bonding download engine & CLI
+Author-email: Jagjot Singh <gotogether@gmail.com>
+License-Expression: MIT
+Keywords: bandwidth-aggregation,download-accelerator,multi-interface,network-bonding,proxy,torrent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: urllib3>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Plexo CLI (`plexo-cli`)
+
+> **Multi-network bandwidth bonding download accelerator in your terminal.**
+
+Combines multiple active internet connections (e.g. **Hostel Wi-Fi + Mobile 5G via USB Tethering + Ethernet**) into a single parallel stream to boost download speeds for direct files and developer tools.
+
+---
+
+## Features
+- **Parallel HTTP Range Slicing**: Binds concurrent download workers to distinct physical network interfaces (source IP socket binding).
+- **Zero-Touch Local Proxy (`plexo proxy`)**: Run a local forward proxy (`127.0.0.1:8899`) to automatically accelerate `pip install`, `git clone`, `curl`, and browser downloads.
+- **Rich Terminal UI**: Live dashboard showing real-time throughput per individual network adapter.
+- **Dynamic Failover**: Auto-detects lagging or disconnected hotspots and re-routes pending chunks to healthy connections without corrupting files.
+- **Sparse File Allocation**: Instant zero-overhead pre-allocation on disk with non-blocking multi-threaded byte writes.
+
+---
+
+## Installation
+
+```bash
+pip install plexo-cli
+```
+
+Or install in editable mode from source:
+```bash
+git clone https://github.com/Jagjotkarhu/plexo.git
+cd plexo/packages/plexo-cli
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+### 1. Scan Network Adapters
+```bash
+plexo adapters
+```
+Lists all discovered network interfaces (Wi-Fi, USB cellular tether, Ethernet), their local IPs, and connectivity status.
+
+### 2. Download a File with Aggregated Bandwidth
+```bash
+plexo download https://example.com/largefile.zip -o largefile.zip
+```
+
+### 3. Accelerate `pip` or Terminal Tools
+Start the local proxy:
+```bash
+plexo proxy --port 8899
+```
+Then run any tool using the proxy:
+```bash
+pip install torch --proxy http://127.0.0.1:8899
+```
+
+---
+
+## License
+MIT © Anmol Kapil & Jagjot Singh

plexo_cli-0.1.0/README.md

@@ -0,0 +1,59 @@
+# Plexo CLI (`plexo-cli`)
+
+> **Multi-network bandwidth bonding download accelerator in your terminal.**
+
+Combines multiple active internet connections (e.g. **Hostel Wi-Fi + Mobile 5G via USB Tethering + Ethernet**) into a single parallel stream to boost download speeds for direct files and developer tools.
+
+---
+
+## Features
+- **Parallel HTTP Range Slicing**: Binds concurrent download workers to distinct physical network interfaces (source IP socket binding).
+- **Zero-Touch Local Proxy (`plexo proxy`)**: Run a local forward proxy (`127.0.0.1:8899`) to automatically accelerate `pip install`, `git clone`, `curl`, and browser downloads.
+- **Rich Terminal UI**: Live dashboard showing real-time throughput per individual network adapter.
+- **Dynamic Failover**: Auto-detects lagging or disconnected hotspots and re-routes pending chunks to healthy connections without corrupting files.
+- **Sparse File Allocation**: Instant zero-overhead pre-allocation on disk with non-blocking multi-threaded byte writes.
+
+---
+
+## Installation
+
+```bash
+pip install plexo-cli
+```
+
+Or install in editable mode from source:
+```bash
+git clone https://github.com/Jagjotkarhu/plexo.git
+cd plexo/packages/plexo-cli
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+### 1. Scan Network Adapters
+```bash
+plexo adapters
+```
+Lists all discovered network interfaces (Wi-Fi, USB cellular tether, Ethernet), their local IPs, and connectivity status.
+
+### 2. Download a File with Aggregated Bandwidth
+```bash
+plexo download https://example.com/largefile.zip -o largefile.zip
+```
+
+### 3. Accelerate `pip` or Terminal Tools
+Start the local proxy:
+```bash
+plexo proxy --port 8899
+```
+Then run any tool using the proxy:
+```bash
+pip install torch --proxy http://127.0.0.1:8899
+```
+
+---
+
+## License
+MIT © Anmol Kapil & Jagjot Singh

plexo_cli-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "plexo-cli"
+version = "0.1.0"
+description = "Multi-network bandwidth bonding download engine & CLI"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Jagjot Singh", email = "gotogether@gmail.com" },
+]
+keywords = [
+    "download-accelerator",
+    "network-bonding",
+    "bandwidth-aggregation",
+    "multi-interface",
+    "torrent",
+    "proxy",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "urllib3>=2.0.0",
+    "rich>=13.7.0",
+    "click>=8.1.0",
+    "psutil>=5.9.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+plexo = "plexo.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/plexo"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

plexo_cli-0.1.0/src/plexo/__init__.py

@@ -0,0 +1,4 @@
+"""Plexo CLI: Multi-network bandwidth bonding download accelerator."""
+
+__version__ = "0.1.0"
+__author__ = "Jagjot Singh"

plexo_cli-0.1.0/src/plexo/cli.py

@@ -0,0 +1,190 @@
+"""Command Line Interface for Plexo.
+
+Exposes subcommands: download, adapters, proxy, info.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+# Ensure UTF-8 output on Windows consoles
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from . import __version__
+from .core.adapter import discover_adapters, get_bonded_pool
+from .core.engine import BondingDownloadEngine, ProgressUpdate
+from .proxy.server import run_proxy
+from .ui.dashboard import TerminalDashboard
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="plexo")
+def main():
+    """Plexo: Multi-Network Bandwidth Bonding Download Engine."""
+    pass
+
+
+@main.command(name="adapters")
+@click.option("--all", "show_all", is_flag=True, help="Show all adapters including offline/internal.")
+def list_adapters(show_all: bool):
+    """Scan and benchmark active network adapters."""
+    console.print("\n[bold cyan]Scanning Network Interfaces...[/bold cyan]")
+    adapters = discover_adapters(verify_online=True)
+
+    table = Table(title="[bold green]Network Interfaces[/bold green]")
+    table.add_column("Interface Name", style="bold white")
+    table.add_column("Type", style="magenta")
+    table.add_column("IPv4 Address", style="cyan")
+    table.add_column("Link Speed", style="yellow")
+    table.add_column("Internet Route", style="bold")
+
+    display_list = adapters if show_all else [a for a in adapters if a.is_online]
+
+    for a in display_list:
+        status_text = "[bold green]ONLINE[/bold green]" if a.is_online else "[dim red]OFFLINE[/dim red]"
+        speed_str = f"{a.speed_mbps} Mbps" if a.speed_mbps > 0 else "Unknown"
+        table.add_row(a.name, a.kind.upper(), a.ip_address, speed_str, status_text)
+
+    console.print(table)
+    online_count = sum(1 for a in adapters if a.is_online)
+
+    if online_count >= 2:
+        console.print(
+            f"\n[bold green][OK] Ready for bonding:[/bold green] [yellow]{online_count}[/yellow] independent connections detected.\n"
+        )
+    elif online_count == 1:
+        console.print(
+            "\n[yellow][INFO] 1 connection active.[/yellow] Plug in Phone 5G USB tethering or Ethernet to enable multi-network bonding.\n"
+        )
+    else:
+        console.print("\n[bold red][X] No online connections found.[/bold red]\n")
+
+
+@main.command(name="download")
+@click.argument("url")
+@click.option("-o", "--output", "output_path", type=click.Path(), default=None, help="Output destination path.")
+@click.option("--chunk-size", default=8, type=int, help="Chunk size in MB (default: 8 MB).")
+@click.option("--workers", default=2, type=int, help="Workers per network adapter (default: 2).")
+def download_file(url: str, output_path: Optional[str], chunk_size: int, workers: int):
+    """Download a file using bonded multi-network connections."""
+    adapters = get_bonded_pool()
+    if not adapters:
+        console.print("[bold red]Error: No active online network adapters detected.[/bold red]")
+        raise click.Abort()
+
+    dashboard = TerminalDashboard(console=console)
+    chunk_bytes = chunk_size * 1024 * 1024
+
+    engine = BondingDownloadEngine(
+        url=url,
+        output_path=output_path,
+        adapters=adapters,
+        chunk_size=chunk_bytes,
+        workers_per_adapter=workers,
+    )
+
+    probe = engine._prepare()
+    dashboard.setup(probe.filename, probe.total_bytes, adapters)
+
+    start_time = time.time()
+    with dashboard.progress:
+        final_path = engine.execute(progress_callback=dashboard.update)
+
+    elapsed = time.time() - start_time
+    total_bytes = final_path.stat().st_size
+
+    # Calculate checksum
+    from .core.sparse import SparseFileWriter
+    with SparseFileWriter(final_path, total_bytes) as writer:
+        checksum = writer.calculate_checksum()
+
+    dashboard.finish(final_path.name, total_bytes, elapsed, checksum)
+
+
+@main.command(name="proxy")
+@click.option("--host", default="127.0.0.1", help="Proxy listening host (default: 127.0.0.1).")
+@click.option("--port", default=8899, type=int, help="Proxy listening port (default: 8899).")
+def start_proxy(host: str, port: int):
+    """Launch local acceleration proxy for pip, git, and curl."""
+    run_proxy(host=host, port=port)
+
+
+@main.command(name="torrent")
+@click.argument("source")
+@click.option("-o", "--output-dir", default=".", help="Directory to save downloaded files.")
+def download_torrent(source: str, output_dir: str):
+    """Download a torrent or magnet link across bonded network adapters."""
+    from .torrent.metadata import parse_magnet, parse_torrent_file
+    from .torrent.client import TorrentBondingEngine
+
+    adapters = get_bonded_pool()
+    if not adapters:
+        console.print("[bold red]Error: No active online network adapters detected.[/bold red]")
+        raise click.Abort()
+
+    if source.startswith("magnet:?"):
+        meta = parse_magnet(source)
+    else:
+        meta = parse_torrent_file(source)
+
+    console.print(
+        Panel.fit(
+            f"[bold cyan]Plexo Torrent Swarm Engine[/bold cyan]\n"
+            f"Name: [bold yellow]{meta.name}[/bold yellow]\n"
+            f"Info Hash: [dim]{meta.info_hash_hex}[/dim]\n"
+            f"Active Network Links: [bold green]{len(adapters)}[/bold green]",
+            border_style="cyan",
+        )
+    )
+
+    dashboard = TerminalDashboard(console=console)
+    dashboard.setup(meta.name, meta.total_length, adapters)
+
+    engine = TorrentBondingEngine(metadata=meta, output_dir=output_dir, adapters=adapters)
+
+    start_time = time.time()
+    with dashboard.progress:
+        final_path = engine.download(progress_callback=dashboard.update)
+
+    elapsed = time.time() - start_time
+    total_bytes = final_path.stat().st_size
+
+    from .core.sparse import SparseFileWriter
+    with SparseFileWriter(final_path, total_bytes) as writer:
+        checksum = writer.calculate_checksum()
+
+    dashboard.finish(final_path.name, total_bytes, elapsed, checksum)
+
+
+@main.command(name="info")
+def show_info():
+    """Display Plexo environment and bonding capabilities."""
+    adapters = get_bonded_pool()
+    console.print(
+        Panel.fit(
+            f"[bold cyan]Plexo CLI v{__version__}[/bold cyan]\n"
+            f"Bonding Engine: [bold green]Active[/bold green]\n"
+            f"Verified Online Adapters: [bold yellow]{len(adapters)}[/bold yellow]\n"
+            f"Default Proxy Port: [bold magenta]8899[/bold magenta]",
+            border_style="cyan",
+            title="System Capabilities",
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

plexo_cli-0.1.0/src/plexo/core/__init__.py

@@ -0,0 +1 @@
+"""Core multi-adapter bonding and download engine."""

plexo_cli-0.1.0/src/plexo/core/adapter.py

@@ -0,0 +1,139 @@
+"""Network interface discovery and binding module.
+
+Detects active network adapters (Wi-Fi, USB cellular tether, Ethernet),
+filters internal/virtual networks, and verifies outward internet reachability.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import platform
+import socket
+import subprocess
+from dataclasses import dataclass
+from typing import List, Optional
+import psutil
+import urllib3
+
+
+@dataclass
+class NetworkAdapter:
+    """Represents a discovered physical or virtual network interface."""
+    name: str
+    ip_address: str
+    netmask: str
+    kind: str  # "wifi", "usb", "ethernet", "other"
+    is_up: bool
+    speed_mbps: int = 0
+    gateway: Optional[str] = None
+    is_online: bool = False
+
+    @property
+    def display_name(self) -> str:
+        kind_label = self.kind.upper()
+        return f"{self.name} [{kind_label}] ({self.ip_address})"
+
+
+def classify_interface(name: str) -> str:
+    """Classifies interface type based on OS naming conventions."""
+    name_lower = name.lower()
+    if any(k in name_lower for k in ("wi-fi", "wifi", "wireless", "wlan", "802.11")):
+        return "wifi"
+    if any(k in name_lower for k in ("rndis", "tether", "remote ndis", "apple mobile", "usb", "enx")):
+        return "usb"
+    if any(k in name_lower for k in ("ethernet", "lan", "eth", "en0", "en1")):
+        return "ethernet"
+    return "other"
+
+
+def is_usable_ip(ip_str: str) -> bool:
+    """Checks if an IPv4 address is routable and not loopback/link-local."""
+    try:
+        ip = ipaddress.IPv4Address(ip_str)
+        if ip.is_loopback:
+            return False
+        if ip.is_link_local:  # 169.254.x.x
+            return False
+        if ip.is_unspecified:  # 0.0.0.0
+            return False
+        return True
+    except (ValueError, ipaddress.AddressValueError):
+        return False
+
+
+def test_adapter_connectivity(ip_address: str, timeout: float = 2.0) -> bool:
+    """Verifies that an outgoing connection bound to this source IP can reach the internet."""
+    test_hosts = [("1.1.1.1", 53), ("8.8.8.8", 53)]
+    for host, port in test_hosts:
+        sock = None
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(timeout)
+            # Bind specifically to this adapter's source IP
+            sock.bind((ip_address, 0))
+            sock.connect((host, port))
+            return True
+        except (socket.error, OSError):
+            continue
+        finally:
+            if sock:
+                sock.close()
+    return False
+
+
+def discover_adapters(verify_online: bool = True) -> List[NetworkAdapter]:
+    """Discovers all active, routable network adapters."""
+    adapters: List[NetworkAdapter] = []
+    seen_ips = set()
+
+    if_addrs = psutil.net_if_addrs()
+    if_stats = psutil.net_if_stats()
+
+    # Exclude common internal virtual switches unless they provide genuine routes
+    virtual_keywords = ("vEthernet", "Hyper-V", "VirtualBox", "VMware", "Loopback", "WSL")
+
+    for iface_name, addrs in if_addrs.items():
+        if any(v.lower() in iface_name.lower() for v in virtual_keywords):
+            continue
+
+        stats = if_stats.get(iface_name)
+        is_up = stats.isup if stats else True
+        if not is_up:
+            continue
+
+        for addr in addrs:
+            # We focus on IPv4 for multi-adapter bonding
+            if addr.family == socket.AF_INET:
+                ip = addr.address
+                if ip in seen_ips or not is_usable_ip(ip):
+                    continue
+
+                seen_ips.add(ip)
+                kind = classify_interface(iface_name)
+                speed = stats.speed if stats else 0
+
+                online = False
+                if verify_online:
+                    online = test_adapter_connectivity(ip)
+
+                adapter = NetworkAdapter(
+                    name=iface_name,
+                    ip_address=ip,
+                    netmask=addr.netmask or "255.255.255.0",
+                    kind=kind,
+                    is_up=is_up,
+                    speed_mbps=speed,
+                    is_online=online if verify_online else is_up,
+                )
+                adapters.append(adapter)
+
+    # Sort so online adapters appear first, prioritized by speed/type
+    adapters.sort(key=lambda a: (not a.is_online, a.kind == "other", a.name))
+    return adapters
+
+
+def get_bonded_pool(min_adapters: int = 1) -> List[NetworkAdapter]:
+    """Returns all verified online adapters ready for bonding."""
+    adapters = discover_adapters(verify_online=True)
+    online = [a for a in adapters if a.is_online]
+    return online if online else adapters