plexo-cli 0.1.0__py3-none-any.whl

plexo/core/engine.py

@@ -0,0 +1,266 @@
+"""Parallel multi-adapter bonding download engine.
+
+Distributes file chunks across verified network adapters concurrently,
+tracks live per-adapter throughput, and writes to disk via sparse file mapping.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import queue
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, List, Optional
+from .adapter import NetworkAdapter, get_bonded_pool
+from .client import BoundRangeClient, ProbeResult, probe_url
+from .qos import QoSWatchdog
+from .sparse import SparseFileWriter
+
+
+@dataclass
+class DownloadChunk:
+    chunk_id: int
+    start_byte: int
+    end_byte: int
+    retries: int = 0
+
+
+@dataclass
+class ProgressUpdate:
+    total_bytes: int
+    downloaded_bytes: int
+    speed_bytes_sec: float
+    adapter_speeds: dict[str, float]  # ip -> bytes/sec
+    is_completed: bool = False
+    filename: str = ""
+
+
+class BondingDownloadEngine:
+    """Orchestrates multi-adapter parallel downloads."""
+
+    def __init__(
+        self,
+        url: str,
+        output_path: Optional[str | Path] = None,
+        adapters: Optional[List[NetworkAdapter]] = None,
+        chunk_size: int = 8 * 1024 * 1024,  # 8 MB default chunk
+        workers_per_adapter: int = 2,
+    ):
+        self.url = url
+        self.chunk_size = chunk_size
+        self.workers_per_adapter = workers_per_adapter
+        self.adapters = adapters or get_bonded_pool()
+        self.output_path = output_path
+
+        self.probe: Optional[ProbeResult] = None
+        self.watchdog = QoSWatchdog()
+        self._cancel_event = threading.Event()
+        self._completed_bytes = 0
+        self._bytes_lock = threading.Lock()
+        self._start_time = 0.0
+
+    def _prepare(self) -> ProbeResult:
+        """Probes the remote server and sets output path."""
+        self.probe = probe_url(self.url)
+
+        if not self.output_path:
+            self.output_path = Path.cwd() / self.probe.filename
+        else:
+            self.output_path = Path(self.output_path)
+            if self.output_path.is_dir():
+                self.output_path = self.output_path / self.probe.filename
+
+        return self.probe
+
+    def execute(
+        self,
+        progress_callback: Optional[Callable[[ProgressUpdate], None]] = None,
+    ) -> Path:
+        """Executes the bonded download and returns final output file path."""
+        probe = self._prepare()
+        target_path = Path(self.output_path)
+        self._start_time = time.time()
+
+        # If file doesn't support ranges or file size unknown, fall back to single-stream
+        if not probe.accepts_ranges or probe.total_bytes <= 0:
+            return self._execute_single_stream(probe, target_path, progress_callback)
+
+        return self._execute_bonded_parallel(probe, target_path, progress_callback)
+
+    def _execute_single_stream(
+        self,
+        probe: ProbeResult,
+        target_path: Path,
+        progress_callback: Optional[Callable[[ProgressUpdate], None]],
+    ) -> Path:
+        """Fallback for non-range servers."""
+        adapter = self.adapters[0] if self.adapters else None
+        local_ip = adapter.ip_address if adapter else "0.0.0.0"
+        client = BoundRangeClient(local_ip=local_ip)
+
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        downloaded = 0
+
+        with open(target_path, "wb") as f:
+            for chunk in client.fetch_range(probe.url, 0, probe.total_bytes - 1 if probe.total_bytes > 0 else 0):
+                f.write(chunk)
+                downloaded += len(chunk)
+                if progress_callback:
+                    elapsed = max(0.001, time.time() - self._start_time)
+                    progress_callback(
+                        ProgressUpdate(
+                            total_bytes=probe.total_bytes or downloaded,
+                            downloaded_bytes=downloaded,
+                            speed_bytes_sec=downloaded / elapsed,
+                            adapter_speeds={local_ip: downloaded / elapsed},
+                            is_completed=False,
+                            filename=target_path.name,
+                        )
+                    )
+
+        if progress_callback:
+            elapsed = max(0.001, time.time() - self._start_time)
+            progress_callback(
+                ProgressUpdate(
+                    total_bytes=downloaded,
+                    downloaded_bytes=downloaded,
+                    speed_bytes_sec=downloaded / elapsed,
+                    adapter_speeds={local_ip: downloaded / elapsed},
+                    is_completed=True,
+                    filename=target_path.name,
+                )
+            )
+
+        return target_path
+
+    def _execute_bonded_parallel(
+        self,
+        probe: ProbeResult,
+        target_path: Path,
+        progress_callback: Optional[Callable[[ProgressUpdate], None]],
+    ) -> Path:
+        """Executes multi-socket bonded chunk downloading."""
+        total_bytes = probe.total_bytes
+        chunk_queue: queue.Queue[DownloadChunk] = queue.Queue()
+
+        # Split into chunks
+        offset = 0
+        chunk_id = 0
+        while offset < total_bytes:
+            end = min(offset + self.chunk_size - 1, total_bytes - 1)
+            chunk_queue.put(DownloadChunk(chunk_id=chunk_id, start_byte=offset, end_byte=end))
+            offset = end + 1
+            chunk_id += 1
+
+        total_chunks = chunk_id
+
+        # Register adapters in QoS watchdog
+        for a in self.adapters:
+            self.watchdog.register(a.name, a.ip_address, a.kind)
+
+        # Pre-allocate sparse file
+        with SparseFileWriter(target_path, total_bytes) as writer:
+            workers = []
+            with concurrent.futures.ThreadPoolExecutor(
+                max_workers=len(self.adapters) * self.workers_per_adapter
+            ) as executor:
+                for adapter in self.adapters:
+                    for _ in range(self.workers_per_adapter):
+                        future = executor.submit(
+                            self._worker_loop,
+                            adapter,
+                            chunk_queue,
+                            writer,
+                            probe.url,
+                            progress_callback,
+                        )
+                        workers.append(future)
+
+                # Wait for all workers or cancellation
+                for future in concurrent.futures.as_completed(workers):
+                    # Raise any unexpected exceptions
+                    future.result()
+
+        if progress_callback:
+            elapsed = max(0.001, time.time() - self._start_time)
+            progress_callback(
+                ProgressUpdate(
+                    total_bytes=total_bytes,
+                    downloaded_bytes=total_bytes,
+                    speed_bytes_sec=total_bytes / elapsed,
+                    adapter_speeds={a.ip_address: self.watchdog.get(a.ip_address).speed_bytes_per_sec for a in self.adapters},
+                    is_completed=True,
+                    filename=target_path.name,
+                )
+            )
+
+        return target_path
+
+    def _worker_loop(
+        self,
+        adapter: NetworkAdapter,
+        chunk_queue: queue.Queue[DownloadChunk],
+        writer: SparseFileWriter,
+        url: str,
+        progress_callback: Optional[Callable[[ProgressUpdate], None]],
+    ) -> None:
+        """Worker thread dedicated to a specific network adapter."""
+        client = BoundRangeClient(local_ip=adapter.ip_address)
+        metric = self.watchdog.get(adapter.ip_address)
+
+        while not self._cancel_event.is_set():
+            try:
+                chunk = chunk_queue.get_nowait()
+            except queue.Empty:
+                break
+
+            metric.active_chunks += 1
+            chunk_data = bytearray()
+            success = False
+
+            try:
+                def on_bytes(count: int):
+                    metric.record_bytes(count)
+                    with self._bytes_lock:
+                        self._completed_bytes += count
+                    if progress_callback:
+                        elapsed = max(0.001, time.time() - self._start_time)
+                        speeds = {
+                            a.ip_address: self.watchdog.get(a.ip_address).speed_bytes_per_sec
+                            for a in self.adapters
+                        }
+                        progress_callback(
+                            ProgressUpdate(
+                                total_bytes=self.probe.total_bytes,
+                                downloaded_bytes=self._completed_bytes,
+                                speed_bytes_sec=self._completed_bytes / elapsed,
+                                adapter_speeds=speeds,
+                                is_completed=False,
+                                filename=self.output_path.name if self.output_path else "",
+                            )
+                        )
+
+                for block in client.fetch_range(
+                    url, chunk.start_byte, chunk.end_byte, on_bytes=on_bytes
+                ):
+                    chunk_data.extend(block)
+
+                # Write directly into sparse file offset
+                writer.write_chunk(chunk.start_byte, bytes(chunk_data))
+                success = True
+
+            except Exception as err:
+                metric.record_error()
+                chunk.retries += 1
+                if chunk.retries < 5:
+                    # Re-queue for another healthy adapter
+                    chunk_queue.put(chunk)
+                else:
+                    self._cancel_event.set()
+                    raise RuntimeError(f"Chunk {chunk.chunk_id} failed permanently: {err}")
+
+            finally:
+                metric.active_chunks -= 1
+                chunk_queue.task_done()

plexo/core/qos.py

@@ -0,0 +1,76 @@
+"""QoS watchdog and adapter health monitoring.
+
+Tracks real-time throughput, detects hotspot stalls, and triggers
+failover to healthy connections.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Dict
+
+
+@dataclass
+class AdapterMetrics:
+    """Live performance metrics for a specific adapter."""
+    name: str
+    ip_address: str
+    kind: str
+    bytes_transferred: int = 0
+    active_chunks: int = 0
+    last_byte_time: float = field(default_factory=time.time)
+    start_time: float = field(default_factory=time.time)
+    errors: int = 0
+    is_healthy: bool = True
+
+    def record_bytes(self, count: int) -> None:
+        self.bytes_transferred += count
+        self.last_byte_time = time.time()
+
+    def record_error(self) -> None:
+        self.errors += 1
+        if self.errors > 3:
+            self.is_healthy = False
+
+    @property
+    def speed_bytes_per_sec(self) -> float:
+        elapsed = time.time() - self.start_time
+        if elapsed <= 0:
+            return 0.0
+        return self.bytes_transferred / elapsed
+
+    @property
+    def speed_mbps(self) -> float:
+        return (self.speed_bytes_per_sec * 8) / (1024 * 1024)
+
+    @property
+    def is_stalled(self) -> bool:
+        """Returns true if active chunks exist but no data received for > 8 seconds."""
+        if self.active_chunks > 0 and (time.time() - self.last_byte_time > 8.0):
+            return True
+        return False
+
+
+class QoSWatchdog:
+    """Coordinates multi-adapter health and failure detection."""
+
+    def __init__(self):
+        self.adapters: Dict[str, AdapterMetrics] = {}
+
+    def register(self, name: str, ip_address: str, kind: str) -> AdapterMetrics:
+        metric = AdapterMetrics(name=name, ip_address=ip_address, kind=kind)
+        self.adapters[ip_address] = metric
+        return metric
+
+    def get(self, ip_address: str) -> AdapterMetrics:
+        return self.adapters[ip_address]
+
+    def check_health(self) -> Dict[str, bool]:
+        """Audits all adapters and returns active health status."""
+        status = {}
+        for ip, metric in self.adapters.items():
+            if metric.is_stalled:
+                metric.is_healthy = False
+            status[ip] = metric.is_healthy
+        return status

plexo/core/sparse.py

@@ -0,0 +1,92 @@
+"""Sparse file allocation and concurrent chunk writer.
+
+Allows multiple worker threads/tasks to write disjoint byte ranges
+directly into their target offsets concurrently.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import threading
+from pathlib import Path
+from typing import BinaryIO, Optional
+
+
+class SparseFileWriter:
+    """Manages thread-safe random-access writes into a pre-allocated file."""
+
+    def __init__(self, target_path: str | Path, total_bytes: int):
+        self.target_path = Path(target_path).resolve()
+        self.total_bytes = total_bytes
+        self._lock = threading.Lock()
+        self._file: Optional[BinaryIO] = None
+        self._written_bytes = 0
+
+        # Ensure parent directory exists
+        self.target_path.parent.mkdir(parents=True, exist_ok=True)
+        self._allocate()
+
+    def _allocate(self) -> None:
+        """Pre-allocates the file size on disk."""
+        with open(self.target_path, "wb") as f:
+            if self.total_bytes > 0:
+                f.seek(self.total_bytes - 1)
+                f.write(b"\0")
+            f.flush()
+
+        # Open in r+b mode for concurrent random-access writes
+        self._file = open(self.target_path, "r+b")
+
+    def write_chunk(self, offset: int, data: bytes) -> int:
+        """Writes a byte block at the specified offset."""
+        if not self._file:
+            raise RuntimeError("File writer is closed.")
+
+        length = len(data)
+        if offset + length > self.total_bytes:
+            raise ValueError(
+                f"Write out of bounds: offset {offset} + len {length} > total {self.total_bytes}"
+            )
+
+        with self._lock:
+            self._file.seek(offset)
+            self._file.write(data)
+            self._written_bytes += length
+
+        return length
+
+    def flush(self) -> None:
+        """Flushes written buffers to disk."""
+        with self._lock:
+            if self._file:
+                self._file.flush()
+                try:
+                    os.fsync(self._file.fileno())
+                except OSError:
+                    pass
+
+    def close(self) -> None:
+        """Closes the underlying file handle."""
+        with self._lock:
+            if self._file:
+                try:
+                    self._file.flush()
+                    self._file.close()
+                finally:
+                    self._file = None
+
+    def calculate_checksum(self, algorithm: str = "sha256") -> str:
+        """Calculates file checksum to verify integrity."""
+        self.flush()
+        hasher = hashlib.new(algorithm)
+        with open(self.target_path, "rb") as f:
+            while chunk := f.read(1024 * 1024):  # 1 MB blocks
+                hasher.update(chunk)
+        return hasher.hexdigest()
+
+    def __enter__(self) -> "SparseFileWriter":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()

plexo/proxy/__init__.py

@@ -0,0 +1 @@
+"""Local forward proxy module for zero-touch bandwidth bonding."""

plexo/proxy/server.py

@@ -0,0 +1,170 @@
+"""Local HTTP/HTTPS forward proxy for accelerating terminal tools (pip, git, curl).
+
+Routes requests through the multi-adapter bonding engine or tunnels HTTPS.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+from typing import Optional
+from rich.console import Console
+from ..core.adapter import get_bonded_pool
+
+
+class LocalBondedProxy:
+    """Asynchronous local HTTP/HTTPS accelerator proxy."""
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 8899, console: Optional[Console] = None):
+        self.host = host
+        self.port = port
+        self.console = console or Console()
+        self.server: Optional[asyncio.Server] = None
+        self._adapters = []
+
+    async def start(self) -> None:
+        """Starts the local proxy server."""
+        self._adapters = get_bonded_pool()
+        self.server = await asyncio.start_server(
+            self._handle_client, self.host, self.port
+        )
+        addrs = ", ".join(str(sock.getsockname()) for sock in self.server.sockets)
+        self.console.print(
+            f"[bold green]Plexo Proxy running on {self.host}:{self.port}[/bold green]"
+        )
+        self.console.print(
+            f"[cyan]Bonding across {len(self._adapters)} network interfaces:[/cyan]"
+        )
+        for a in self._adapters:
+            self.console.print(f"  * {a.name} ({a.ip_address})")
+
+        self.console.print(
+            "\n[dim]To use with pip:[/dim]\n"
+            f"  pip install <package> --proxy http://{self.host}:{self.port}\n\n"
+            "[dim]To use globally in terminal:[/dim]\n"
+            f"  $env:HTTPS_PROXY = \"http://{self.host}:{self.port}\"\n"
+        )
+
+        async with self.server:
+            await self.server.serve_forever()
+
+    async def _handle_client(
+        self, client_reader: asyncio.StreamReader, client_writer: asyncio.StreamWriter
+    ) -> None:
+        """Handles client connection (HTTP GET or HTTPS CONNECT)."""
+        try:
+            request_line = await client_reader.readline()
+            if not request_line:
+                client_writer.close()
+                return
+
+            words = request_line.decode("latin1").split()
+            if len(words) < 2:
+                client_writer.close()
+                return
+
+            method, url = words[0], words[1]
+
+            if method.upper() == "CONNECT":
+                # HTTPS Tunneling
+                await self._handle_connect(url, client_reader, client_writer)
+            else:
+                # Plain HTTP proxy
+                await self._handle_http(method, url, request_line, client_reader, client_writer)
+
+        except Exception:
+            try:
+                client_writer.close()
+            except Exception:
+                pass
+
+    async def _handle_connect(
+        self, target: str, client_reader: asyncio.StreamReader, client_writer: asyncio.StreamWriter
+    ) -> None:
+        """Tunnels HTTPS connections directly."""
+        host, port_str = target.split(":") if ":" in target else (target, "443")
+        port = int(port_str)
+
+        try:
+            # Round-robin or primary adapter source IP
+            adapter = self._adapters[0] if self._adapters else None
+            local_addr = (adapter.ip_address, 0) if adapter else None
+
+            remote_reader, remote_writer = await asyncio.open_connection(
+                host, port, local_addr=local_addr
+            )
+
+            client_writer.write(b"HTTP/1.1 200 Connection Established\r\n\r\n")
+            await client_writer.drain()
+
+            # Bidirectional pipe
+            await asyncio.gather(
+                self._pipe(client_reader, remote_writer),
+                self._pipe(remote_reader, client_writer),
+                return_exceptions=True,
+            )
+        except Exception:
+            client_writer.write(b"HTTP/1.1 502 Bad Gateway\r\n\r\n")
+            await client_writer.drain()
+            client_writer.close()
+
+    async def _handle_http(
+        self,
+        method: str,
+        url: str,
+        initial_line: bytes,
+        client_reader: asyncio.StreamReader,
+        client_writer: asyncio.StreamWriter,
+    ) -> None:
+        """Forwards standard HTTP requests."""
+        # Read remaining headers
+        headers = bytearray(initial_line)
+        while True:
+            line = await client_reader.readline()
+            headers.extend(line)
+            if line == b"\r\n" or not line:
+                break
+
+        # Parse host from URL
+        from urllib.parse import urlparse
+        parsed = urlparse(url)
+        host = parsed.hostname or "localhost"
+        port = parsed.port or 80
+
+        try:
+            remote_reader, remote_writer = await asyncio.open_connection(host, port)
+            remote_writer.write(headers)
+            await remote_writer.drain()
+
+            await asyncio.gather(
+                self._pipe(client_reader, remote_writer),
+                self._pipe(remote_reader, client_writer),
+                return_exceptions=True,
+            )
+        except Exception:
+            client_writer.close()
+
+    async def _pipe(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        """Pipes bytes between reader and writer until EOF."""
+        try:
+            while not reader.at_eof():
+                data = await reader.read(65536)
+                if not data:
+                    break
+                writer.write(data)
+                await writer.drain()
+        except Exception:
+            pass
+        finally:
+            try:
+                writer.close()
+            except Exception:
+                pass
+
+
+def run_proxy(host: str = "127.0.0.1", port: int = 8899) -> None:
+    """Synchronous launcher for the proxy server."""
+    proxy = LocalBondedProxy(host=host, port=port)
+    asyncio.run(proxy.start())

plexo/torrent/__init__.py

@@ -0,0 +1 @@
+"""Plexo BitTorrent multi-homing engine."""

plexo/torrent/bencode.py

@@ -0,0 +1,62 @@
+"""Lightweight Bencoding encoder/decoder for BitTorrent metadata."""
+
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+
+def bdecode(data: bytes) -> Any:
+    """Decodes bencoded bytes into Python types."""
+    val, _ = _bdecode_part(data, 0)
+    return val
+
+
+def _bdecode_part(data: bytes, idx: int) -> Tuple[Any, int]:
+    char = data[idx : idx + 1]
+
+    if char == b"i":
+        end = data.index(b"e", idx)
+        return int(data[idx + 1 : end]), end + 1
+
+    if char == b"l":
+        items = []
+        curr = idx + 1
+        while data[curr : curr + 1] != b"e":
+            item, curr = _bdecode_part(data, curr)
+            items.append(item)
+        return items, curr + 1
+
+    if char == b"d":
+        mapping = {}
+        curr = idx + 1
+        while data[curr : curr + 1] != b"e":
+            key, curr = _bdecode_part(data, curr)
+            val, curr = _bdecode_part(data, curr)
+            mapping[key.decode("latin1")] = val
+        return mapping, curr + 1
+
+    # String / Bytes: <length>:<bytes>
+    colon = data.index(b":", idx)
+    length = int(data[idx:colon])
+    start = colon + 1
+    end = start + length
+    return data[start:end], end
+
+
+def bencode(val: Any) -> bytes:
+    """Encodes Python types into bencoded bytes."""
+    if isinstance(val, int):
+        return f"i{val}e".encode("ascii")
+    if isinstance(val, (bytes, bytearray)):
+        return f"{len(val)}:".encode("ascii") + bytes(val)
+    if isinstance(val, str):
+        encoded = val.encode("utf-8")
+        return f"{len(encoded)}:".encode("ascii") + encoded
+    if isinstance(val, list):
+        return b"l" + b"".join(bencode(i) for i in val) + b"e"
+    if isinstance(val, dict):
+        out = b"d"
+        for k in sorted(val.keys()):
+            out += bencode(k) + bencode(val[k])
+        return out + b"e"
+    raise TypeError(f"Cannot bencode type: {type(val)}")