ssh-auto-forward 0.0.2__tar.gz → 0.0.3__tar.gz

{ssh_auto_forward-0.0.2 → ssh_auto_forward-0.0.3}/.github/workflows/test.yml

@@ -14,6 +14,10 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - run: pip install uv
-      - run: uv sync
-      - run: uv run pytest tests/
+      - run: uv sync --dev
+      - run: uv run pytest tests/ -v
+      - name: Build Docker test image
+        run: docker compose -f docker/docker-compose.yml build
+      - name: Run integration tests with Docker
+        run: uv run pytest tests_integration/ -v
       - run: uv run ruff check ssh_auto_forward/

{ssh_auto_forward-0.0.2 → ssh_auto_forward-0.0.3}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: test setup shell coverage publish-build publish-test publish publish-clean run
+.PHONY: test setup shell coverage publish-build publish-test publish publish-clean run docker-build docker-up docker-down
 
 test:
 	uv run pytest
@@ -25,4 +25,17 @@ publish-clean:
 	rm -r dist/
 
 run:
+	uv run python -m ssh_auto_forward.cli
+
+hetzner:
 	uv run python -m ssh_auto_forward.cli hetzner
+
+
+docker-build:
+	docker compose -f docker/docker-compose.yml build
+
+docker-up:
+	docker compose -f docker/docker-compose.yml up -d --build
+
+docker-down:
+	docker compose -f docker/docker-compose.yml down

ssh_auto_forward-0.0.3/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: ssh-auto-forward
+Version: 0.0.3
+Summary: Auto-forward SSH ports
+Author: alexe
+License: WTFPL
+Keywords: port-forwarding,remote-development,ssh,tunnel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: paramiko>=3.4.0
+Requires-Dist: textual>=8.0.0
+Description-Content-Type: text/markdown
+
+# SSH Auto Port Forwarder
+
+Automatically detect and forward ports from a remote SSH server to your local machine. Similar to VS Code's port forwarding feature, but fully automatic.
+
+![Dashboard](docs/dashboard.svg)
+
+## Features
+
+- Interactive TUI dashboard - View and manage tunnels in real-time
+- Automatically discovers listening ports on the remote server
+- Shows process names for each forwarded port
+- Forwards ports to your local machine via SSH tunneling
+- Handles port conflicts by finding alternative local ports
+- Auto-detects new ports and starts forwarding
+- Auto-detects closed ports and stops forwarding
+- Reads connection details from your SSH config
+- Skips well-known ports (< 1000) by default
+- Configurable max auto-forward port (default: 10000)
+
+## Installation
+
+### With uv (recommended):
+
+```bash
+uvx ssh-auto-forward hetzner
+```
+
+### Install with pip:
+
+```bash
+pip install ssh-auto-forward
+```
+
+### Install locally:
+
+```bash
+cd portforwards
+uv sync
+```
+
+## Running
+
+### Dashboard mode (default):
+
+```bash
+ssh-auto-forward hetzner
+```
+
+### CLI mode (headless):
+
+```bash
+ssh-auto-forward hetzner --cli
+```
+
+### With uvx (no installation):
+
+```bash
+uvx ssh-auto-forward hetzner
+```
+
+## Dashboard Controls
+
+| Key | Action |
+|-----|--------|
+| X / Enter | Toggle port (open if closed, close if opened) |
+| O | Open URL in browser (for forwarded ports) |
+| R | Refresh port list |
+| L | Toggle log panel |
+| Q | Quit |
+
+## Options
+
+```
+-v, --verbose              Enable verbose logging
+-i, --interval SECS        Scan interval in seconds (default: 5)
+-p, --port-range MIN:MAX   Local port range for remapping (default: 3000:10000)
+-s, --skip PORTS           Comma-separated ports to skip (default: all ports < 1000)
+-c, --config PATH          Path to SSH config file
+-m, --max-auto-port PORT   Maximum port to auto-forward (default: 10000)
+--include-configs          Include ports already forwarded via SSH config LocalForward
+--cli                      Run in CLI mode instead of dashboard
+--version                  Show version and exit
+```
+
+## Examples
+
+```bash
+# Dashboard mode (default)
+ssh-auto-forward hetzner
+
+# CLI mode
+ssh-auto-forward hetzner --cli
+
+# Scan every 3 seconds
+ssh-auto-forward hetzner -i 3
+
+# Use specific port range
+ssh-auto-forward hetzner -p 4000:9000
+
+# Skip specific ports
+ssh-auto-forward hetzner -s 22,80,443
+
+# Verbose mode
+ssh-auto-forward hetzner -v
+
+# Only auto-forward ports up to 5000 (higher ports shown but not auto-forwarded)
+ssh-auto-forward hetzner -m 5000
+
+# Include ports already forwarded via SSH config LocalForward
+ssh-auto-forward hetzner --include-configs
+```
+
+## Performance
+
+Throughput is 150-190 MB/s for large file transfers (45-70% of native `ssh -L`). HTML page latency is 2-3 ms median at up to 10 req/s with zero failures. The overhead comes from paramiko (Python) vs OpenSSH (C) - negligible for interactive use like web browsing.
+
+See [benchmarks/](benchmarks/) for full methodology and results.
+
+## How it works
+
+1. Connects to your remote server using your SSH config
+2. Runs `ss -tlnp` on the remote to find listening ports
+3. Creates SSH tunnels for each discovered port
+4. Continuously monitors for new/closed ports
+5. Handles port conflicts on your local machine
+
+### SSH Config Integration
+
+The tool reads your SSH config file (`~/.ssh/config`) for connection details. It also respects `LocalForward` directives:
+
+```ssh
+Host myserver
+    HostName example.com
+    User myuser
+    LocalForward 8080 localhost:8080  # This port is excluded by default
+    LocalForward 3000 localhost:3000
+```
+
+By default, ports that are already forwarded via `LocalForward` are **excluded** from the dashboard list since they're handled by SSH itself. Use `--include-configs` to show them.
+
+## Status messages
+
+```
+✓ Connected!
+✓ Forwarding port 2999 (python3)
+✓ Forwarding port 7681 (ttyd)
+✓ Forwarding remote port 19840 -> local port 3000 (node)
+✗ Remote port 2999 is no longer listening, stopping tunnel
+```
+
+## Testing
+
+Start a test server on your remote machine:
+
+```bash
+ssh hetzner "python3 -m http.server 9999 --bind 127.0.0.1 &"
+```
+
+Then run `ssh-auto-forward hetzner` and access it locally:
+
+```bash
+curl http://localhost:9999/
+```
+
+## Stopping
+
+- Dashboard: Press `Q`
+- CLI mode: Press `Ctrl+C`
+
+## Requirements
+
+- Python 3.10+
+- paramiko
+- textual (for TUI dashboard)
+- Remote server must have `ss` or `netstat` command available
+
+## Tests
+
+### Unit tests (run locally, no SSH required):
+
+```bash
+uv run pytest tests/ -v
+```
+
+### Integration tests (Docker, default):
+
+```bash
+uv run pytest tests_integration/ -v
+```
+
+This starts a Docker container with SSH server and tests against it.
+
+### Integration tests (real SSH server):
+
+```bash
+SSH_AUTO_FORWARD_TEST_HOST=your-server uv run pytest tests_integration/ -v
+```

ssh_auto_forward-0.0.3/README.md

@@ -0,0 +1,197 @@
+# SSH Auto Port Forwarder
+
+Automatically detect and forward ports from a remote SSH server to your local machine. Similar to VS Code's port forwarding feature, but fully automatic.
+
+![Dashboard](docs/dashboard.svg)
+
+## Features
+
+- Interactive TUI dashboard - View and manage tunnels in real-time
+- Automatically discovers listening ports on the remote server
+- Shows process names for each forwarded port
+- Forwards ports to your local machine via SSH tunneling
+- Handles port conflicts by finding alternative local ports
+- Auto-detects new ports and starts forwarding
+- Auto-detects closed ports and stops forwarding
+- Reads connection details from your SSH config
+- Skips well-known ports (< 1000) by default
+- Configurable max auto-forward port (default: 10000)
+
+## Installation
+
+### With uv (recommended):
+
+```bash
+uvx ssh-auto-forward hetzner
+```
+
+### Install with pip:
+
+```bash
+pip install ssh-auto-forward
+```
+
+### Install locally:
+
+```bash
+cd portforwards
+uv sync
+```
+
+## Running
+
+### Dashboard mode (default):
+
+```bash
+ssh-auto-forward hetzner
+```
+
+### CLI mode (headless):
+
+```bash
+ssh-auto-forward hetzner --cli
+```
+
+### With uvx (no installation):
+
+```bash
+uvx ssh-auto-forward hetzner
+```
+
+## Dashboard Controls
+
+| Key | Action |
+|-----|--------|
+| X / Enter | Toggle port (open if closed, close if opened) |
+| O | Open URL in browser (for forwarded ports) |
+| R | Refresh port list |
+| L | Toggle log panel |
+| Q | Quit |
+
+## Options
+
+```
+-v, --verbose              Enable verbose logging
+-i, --interval SECS        Scan interval in seconds (default: 5)
+-p, --port-range MIN:MAX   Local port range for remapping (default: 3000:10000)
+-s, --skip PORTS           Comma-separated ports to skip (default: all ports < 1000)
+-c, --config PATH          Path to SSH config file
+-m, --max-auto-port PORT   Maximum port to auto-forward (default: 10000)
+--include-configs          Include ports already forwarded via SSH config LocalForward
+--cli                      Run in CLI mode instead of dashboard
+--version                  Show version and exit
+```
+
+## Examples
+
+```bash
+# Dashboard mode (default)
+ssh-auto-forward hetzner
+
+# CLI mode
+ssh-auto-forward hetzner --cli
+
+# Scan every 3 seconds
+ssh-auto-forward hetzner -i 3
+
+# Use specific port range
+ssh-auto-forward hetzner -p 4000:9000
+
+# Skip specific ports
+ssh-auto-forward hetzner -s 22,80,443
+
+# Verbose mode
+ssh-auto-forward hetzner -v
+
+# Only auto-forward ports up to 5000 (higher ports shown but not auto-forwarded)
+ssh-auto-forward hetzner -m 5000
+
+# Include ports already forwarded via SSH config LocalForward
+ssh-auto-forward hetzner --include-configs
+```
+
+## Performance
+
+Throughput is 150-190 MB/s for large file transfers (45-70% of native `ssh -L`). HTML page latency is 2-3 ms median at up to 10 req/s with zero failures. The overhead comes from paramiko (Python) vs OpenSSH (C) - negligible for interactive use like web browsing.
+
+See [benchmarks/](benchmarks/) for full methodology and results.
+
+## How it works
+
+1. Connects to your remote server using your SSH config
+2. Runs `ss -tlnp` on the remote to find listening ports
+3. Creates SSH tunnels for each discovered port
+4. Continuously monitors for new/closed ports
+5. Handles port conflicts on your local machine
+
+### SSH Config Integration
+
+The tool reads your SSH config file (`~/.ssh/config`) for connection details. It also respects `LocalForward` directives:
+
+```ssh
+Host myserver
+    HostName example.com
+    User myuser
+    LocalForward 8080 localhost:8080  # This port is excluded by default
+    LocalForward 3000 localhost:3000
+```
+
+By default, ports that are already forwarded via `LocalForward` are **excluded** from the dashboard list since they're handled by SSH itself. Use `--include-configs` to show them.
+
+## Status messages
+
+```
+✓ Connected!
+✓ Forwarding port 2999 (python3)
+✓ Forwarding port 7681 (ttyd)
+✓ Forwarding remote port 19840 -> local port 3000 (node)
+✗ Remote port 2999 is no longer listening, stopping tunnel
+```
+
+## Testing
+
+Start a test server on your remote machine:
+
+```bash
+ssh hetzner "python3 -m http.server 9999 --bind 127.0.0.1 &"
+```
+
+Then run `ssh-auto-forward hetzner` and access it locally:
+
+```bash
+curl http://localhost:9999/
+```
+
+## Stopping
+
+- Dashboard: Press `Q`
+- CLI mode: Press `Ctrl+C`
+
+## Requirements
+
+- Python 3.10+
+- paramiko
+- textual (for TUI dashboard)
+- Remote server must have `ss` or `netstat` command available
+
+## Tests
+
+### Unit tests (run locally, no SSH required):
+
+```bash
+uv run pytest tests/ -v
+```
+
+### Integration tests (Docker, default):
+
+```bash
+uv run pytest tests_integration/ -v
+```
+
+This starts a Docker container with SSH server and tests against it.
+
+### Integration tests (real SSH server):
+
+```bash
+SSH_AUTO_FORWARD_TEST_HOST=your-server uv run pytest tests_integration/ -v
+```

ssh_auto_forward-0.0.3/benchmarks/README.md

@@ -0,0 +1,139 @@
+# Benchmarks
+
+Measures the throughput and latency of ssh-auto-forward compared to native `ssh -L` port forwarding.
+
+## Architecture
+
+The benchmarks use three separate processes to mirror real-world usage:
+
+```
+Process 1: Docker container           Process 2: Tunnel              Process 3: Client
++--------------------------+          +---------------------+        +------------------+
+| SSH server (port 22)     |<-------->| ssh-auto-forward    |        | Python HTTP      |
+| nginx        (port 8081) |  SSH     | --cli               |        | client           |
+| darkhttpd    (port 8082) |  tunnel  | (or native ssh -L)  |<------>| (urllib)         |
+| python http  (port 8080) |          +---------------------+        +------------------+
+| stream gen   (port 8083) |          binds local ports              downloads through
++--------------------------+          8080-8083                       localhost tunnel
+     Only port 22 exposed
+```
+
+Only SSH port 22 is exposed from the Docker container. All HTTP traffic goes through the SSH tunnel, just like a real user would experience.
+
+- Process 1 (Docker): Runs `panubo/sshd` with nginx, darkhttpd, python http.server, and a streaming generator
+- Process 2 (Tunnel): Either `ssh-auto-forward --cli` (our tool with dashboard) or native `ssh -L` (baseline)
+- Process 3 (Client): Python `urllib` making HTTP requests through the tunnel, like a browser would
+
+## Test Data
+
+| File | Size | Source |
+|------|------|--------|
+| `10mb.bin` | 10 MB | Pre-generated on disk (`dd if=/dev/urandom`) |
+| `100mb.bin` | 100 MB | Pre-generated on disk |
+| `1gb.bin` | 1 GB | Pre-generated on disk |
+| 10 GB stream | 10 GB | Generated on the fly by `stream_generator.py` |
+| `small/page_*.html` | ~10 KB each, 1000 files | Pre-generated HTML with random content |
+
+## Benchmarks
+
+### 1. Large File Downloads (`bench_large_files.py`)
+
+Downloads pre-generated files (10 MB, 100 MB, 1 GB) and a 10 GB on-the-fly stream through each HTTP server.
+
+One ssh-auto-forward tunnel stays open for all tests to match real usage (the user starts the dashboard once and uses it for all downloads).
+
+| Server | File | ssh-auto-forward | native ssh -L |
+|--------|------|-----------------|---------------|
+| nginx | 10 MB | 121.7 MB/s | 164.4 MB/s |
+| nginx | 100 MB | 158.1 MB/s | 287.1 MB/s |
+| nginx | 1 GB | 141.6 MB/s | 269.9 MB/s |
+| darkhttpd | 10 MB | 106.1 MB/s | 235.3 MB/s |
+| darkhttpd | 100 MB | 192.8 MB/s | 299.4 MB/s |
+| darkhttpd | 1 GB | 152.6 MB/s | 316.9 MB/s |
+| python | 10 MB | 131.4 MB/s | 191.8 MB/s |
+| python | 100 MB | 192.9 MB/s | 353.0 MB/s |
+| python | 1 GB | 149.9 MB/s | 383.9 MB/s |
+
+10 GB streaming:
+
+| Tunnel | Throughput | Time |
+|--------|-----------|------|
+| ssh-auto-forward | 151.6 MB/s | 67.6s |
+| native ssh -L | 220.7 MB/s | 46.4s |
+
+ssh-auto-forward achieves 45-70% of native ssh throughput for large transfers. The overhead comes from paramiko's Python-based SSH implementation vs OpenSSH's C implementation.
+
+### 2. HTML Stress Test (`bench_html_stress.py`)
+
+Fires HTTP requests for ~10 KB HTML pages at a controlled rate. Tests whether the tunnel can sustain the target request rate without failures.
+
+Realistic browsing (1 req/s, 30 requests):
+
+| Server | Tunnel | Actual RPS | p50 | p95 | p99 | Failed |
+|--------|--------|-----------|-----|-----|-----|--------|
+| nginx | ssh-auto-fwd | 1.0 r/s | 3 ms | 18 ms | 25 ms | 0 |
+| darkhttpd | ssh-auto-fwd | 1.0 r/s | 3 ms | 7 ms | 20 ms | 0 |
+| python | ssh-auto-fwd | 1.0 r/s | 3 ms | 4 ms | 19 ms | 0 |
+| nginx | native ssh | 1.0 r/s | 2 ms | 2 ms | 3 ms | 0 |
+| darkhttpd | native ssh | 1.0 r/s | 2 ms | 2 ms | 3 ms | 0 |
+| python | native ssh | 1.0 r/s | 2 ms | 3 ms | 4 ms | 0 |
+
+Stress test (10 req/s, 100 requests):
+
+| Server | Tunnel | Actual RPS | p50 | p95 | p99 | Failed |
+|--------|--------|-----------|-----|-----|-----|--------|
+| nginx | ssh-auto-fwd | 10.1 r/s | 3 ms | 4 ms | 34 ms | 0 |
+| darkhttpd | ssh-auto-fwd | 10.1 r/s | 2 ms | 5 ms | 21 ms | 0 |
+| python | ssh-auto-fwd | 10.1 r/s | 3 ms | 9 ms | 38 ms | 0 |
+| nginx | native ssh | 10.1 r/s | 2 ms | 2 ms | 2 ms | 0 |
+| darkhttpd | native ssh | 10.1 r/s | 1 ms | 2 ms | 2 ms | 0 |
+| python | native ssh | 10.1 r/s | 2 ms | 2 ms | 3 ms | 0 |
+
+Both tunnels handle 10 req/s with zero failures. ssh-auto-forward adds ~1 ms median latency overhead. Tail latency (p99) is higher at ~20-38 ms vs ~2-3 ms for native ssh, likely due to paramiko's Python event loop.
+
+### 3. Buffer Size Sweep (`bench_buffer_sweep.py`)
+
+Tests the impact of the internal pipe buffer size on throughput (100 MB file through nginx).
+
+| Buffer Size | Throughput | Time |
+|------------|-----------|------|
+| 4,096 bytes | 65.1 MB/s | 1.53s |
+| 16,384 bytes | 151.9 MB/s | 0.66s |
+| 65,536 bytes | 179.6 MB/s | 0.56s |
+
+Increasing the buffer from 4 KB to 64 KB gives a 2.8x throughput improvement. The default was changed from 4096 to 65536 as part of the forwarder fix.
+
+## Running
+
+Prerequisites: Docker, SSH key in `~/.ssh/`
+
+```bash
+# Run all benchmarks
+uv run python benchmarks/bench_large_files.py
+uv run python benchmarks/bench_html_stress.py
+uv run python benchmarks/bench_buffer_sweep.py
+```
+
+Results are saved as JSON in `benchmarks/results_*.json`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `bench_large_files.py` | Large file download benchmark (10 MB - 10 GB) |
+| `bench_html_stress.py` | HTML page stress test (1 and 10 req/s) |
+| `bench_buffer_sweep.py` | Buffer size comparison (4 KB, 16 KB, 64 KB) |
+| `bench_common.py` | Shared infrastructure: Docker, tunnels, download clients |
+| `tunnel_helper.py` | Subprocess that runs the ssh-auto-forward CLI or direct SSHTunnel |
+| `download_helper.py` | Subprocess that downloads files (single, many, stress modes) |
+| `Dockerfile` | Docker image with SSH + HTTP servers and test data |
+| `nginx-benchmark.conf` | nginx configuration for benchmark serving |
+| `stream_generator.py` | HTTP server that generates large responses on the fly |
+
+## Key Findings
+
+1. ssh-auto-forward works correctly -zero failures across all tests, no truncated responses (after the `sendall` fix)
+2. Throughput is 45-70% of native ssh for bulk transfers -the overhead is paramiko (Python) vs OpenSSH (C)
+3. Latency is excellent for interactive use -2-3 ms median for HTML page requests
+4. Buffer size matters -increasing from 4 KB to 64 KB gave 2.8x throughput improvement
+5. Handles 10 req/s stress test with zero failures -more than sufficient for web browsing use cases

ssh_auto_forward-0.0.3/benchmarks/WINDOWS_PERFORMANCE_LIMITATION.md

@@ -0,0 +1,68 @@
+# Remote Benchmark Results
+
+## Host
+- Remote: hetzner (Hetzner VPS)
+- Local: Windows (MinGW64)
+
+## Native SSH Performance (baseline)
+
+| File | Throughput | Time |
+|------|------------|------|
+| 100KB | ~10 MB/s | ~0.01s |
+| 500KB | ~11 MB/s | ~0.04s |
+| 1MB | ~12 MB/s | ~0.08s |
+| 5MB | ~12 MB/s | ~0.4s |
+| 10MB | ~12 MB/s | ~0.8s |
+| 50MB | ~11 MB/s | ~4.5s |
+| 100MB | ~12 MB/s | ~8.5s |
+
+Native SSH `-L` works perfectly and consistently across all file sizes.
+
+## ssh-auto-forward Performance (After Fix)
+
+| File | Throughput | Time | Status |
+|------|------------|------|--------|
+| 100KB | ~10 MB/s | ~0.01s | Fixed |
+| 500KB | ~11 MB/s | ~0.04s | Fixed |
+| 1MB | ~12 MB/s | ~0.08s | Fixed |
+| 5MB | ~12 MB/s | ~0.4s | Fixed |
+| 10MB | ~11.6 MB/s | ~0.9s | Fixed |
+| 50MB | ~11.5 MB/s | ~4.4s | Fixed |
+| 100MB | ~11.8 MB/s | ~8.6s | Fixed |
+
+## The Fix
+
+The Windows performance issue was fixed by using `select.select()` with Paramiko channel's `fileno()` method:
+
+```python
+# Get the channel's file descriptor (works on all platforms)
+chan_fd = chan.fileno()
+
+# Use select to wait for data on either socket or channel
+rlist, _, _ = select.select([sock, chan_fd], [], [], timeout)
+```
+
+This approach:
+- Works cross-platform (Windows ARM64, AMD64, Linux)
+- Achieves ~98% of native SSH performance
+- Eliminates the polling overhead that caused the 200x slowdown
+
+## Previous Windows Performance Limitation (RESOLVED)
+
+ssh-auto-forward on Windows previously experienced significant performance degradation (~200x slower than native SSH) due to:
+
+1. `select.select()` limitation on Windows: Python's `select` module on Windows only works with sockets, not with Paramiko SSH channel objects directly.
+
+2. Previous workaround overhead: The old implementation used polling (`select` on socket + `chan.recv_ready()` for channel), which added significant latency.
+
+3. Solution: Paramiko channels provide a `fileno()` method that returns a valid file descriptor that works with `select()` on all platforms.
+
+## Recommendation
+
+The Windows performance limitation is now RESOLVED. ssh-auto-forward performs comparably to native SSH on all platforms:
+
+- Windows ARM64: ~11-12 MB/s (98% of native SSH)
+- Windows AMD64: ~11-12 MB/s (98% of native SSH)
+- Linux: Similar performance (uses same code path)
+
+The tool is now recommended for all platforms for its automatic port detection and dashboard features.