ssh-tunnel-switch 0.1.0__py3-none-any.whl

ssh_tunnel_switch-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: ssh-tunnel-switch
+Version: 0.1.0
+Summary: SSH SOCKS5 tunnel rotation service with an HTTP proxy and REST API
+Project-URL: Homepage, https://github.com/timlaing/ssh-tunnel-switch
+Project-URL: Repository, https://github.com/timlaing/ssh-tunnel-switch
+Project-URL: Issues, https://github.com/timlaing/ssh-tunnel-switch/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: h11<1,>=0.16
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: ruamel-yaml<0.20,>=0.18
+Requires-Dist: typer<1,>=0.15
+Requires-Dist: uvicorn<1,>=0.34
+Provides-Extra: test
+Requires-Dist: pytest-asyncio<2,>=0.25; extra == 'test'
+Requires-Dist: pytest<10,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# SSH Tunnel Switch
+
+Rotate between SSH SOCKS5 tunnels using a REST API or CLI. A built-in HTTP proxy forwards HTTP requests and HTTPS CONNECT traffic through the active tunnel, with remote DNS resolution through SOCKS5.
+
+The server runs independently. It requires Python 3.12+ and OpenSSH; no OpenCode, Node.js, Bun, or plugin is needed.
+
+## Install and run
+
+Install from a checkout until the first PyPI release is available:
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install .
+cp examples/config.yaml config.yaml
+```
+
+After publication, install with `python -m pip install ssh-tunnel-switch`. The executable remains `tunnel-switch`, and Python imports use `tunnel_switch`.
+
+Edit `config.yaml` with your SSH host aliases and the SOCKS, HTTP proxy and API bind IP/port. Only `host` is required for each SSH server. `name` defaults to `host`; `user`, `port` and `identity_file` are optional overrides. When omitted (or null), the SSH command leaves them unset, so the system SSH client inherits settings from `~/.ssh/config` for the account running the service. Without configured SSH values, OpenSSH uses its own defaults. Identity paths relative to the YAML file resolve from its directory; `~` expands. YAML is mandatory for every CLI command. Unknown fields, invalid IPs/ports, duplicate server names and missing identity files are rejected.
+
+A host-only server list can use existing SSH config aliases:
+
+```yaml
+servers:
+  - host: ssh-one
+  - host: ssh-two
+```
+
+Normal `HostName`, `User`, `Port`, `IdentityFile`, `ProxyJump` and other SSH config settings apply. An explicit YAML `user`, `port` or `identity_file` is passed as `-l`, `-p` or `-i`. Existing configurations with named servers and explicit values still work. Effective server names must remain unique, including names derived from host aliases.
+
+Authenticate to each SSH server once using your normal SSH client and verify its host key. The service requires key/agent authentication (`BatchMode=yes`) and known hosts (`StrictHostKeyChecking=yes`). It does not prompt for passwords or accept unknown host keys. The SSH accounts must permit TCP forwarding.
+
+The API token lives in `api.token` in the YAML file. On startup, `serve` generates and saves a random token if the field is missing, null or blank. Existing tokens are reused. In both cases it prints `API token: ...` to the console before starting the API. Generated-token writes are atomic, preserve YAML comments, and save the file with mode 0600. If saving fails, startup fails rather than using an unsaved token.
+
+```sh
+.venv/bin/tunnel-switch validate --config config.yaml
+.venv/bin/tunnel-switch serve --config config.yaml
+```
+
+No token environment variable is used. `status` and `rotate` read the saved YAML token; they do not generate one. `serve` starts the first tunnel unless `start_on_launch: false`. Ctrl-C cleans up its SSH process. Each command supports `--help`; command/configuration/network failures print an error and CLI help with a nonzero exit code.
+
+Run exactly one service process for a given SOCKS socket. The supplied CLI uses one Uvicorn worker, without reload. It manages only SSH processes it spawned. An existing process occupying the SOCKS address is rejected rather than terminated. The cooldown also applies after startup and failed rotations, so an immediate rotation within the default 30 seconds returns 429.
+
+## Use the proxy with any client
+
+Start the service, then configure an HTTP proxy-aware client:
+
+```sh
+curl --proxy http://127.0.0.1:8118 https://example.com/
+```
+
+Alternatively, set `HTTP_PROXY` and `HTTPS_PROXY` to `http://127.0.0.1:8118` for clients that support those variables. Keep local control requests direct using `NO_PROXY=localhost,127.0.0.1,::1` or `curl --noproxy '*'`. SOCKS5-aware clients can use `socks5h://127.0.0.1:1080` directly.
+
+The HTTP proxy defaults to enabled on loopback port 8118. It streams HTTP/1.1 requests and supports HTTPS CONNECT without decrypting TLS. Forwarding fails when SOCKS is unavailable; it never falls back to a direct destination connection. Rotation closes existing tunneled connections. The API remains responsive during rotation. There is no automatic SSH restart loop.
+
+The HTTP and SOCKS listeners are unauthenticated. Keep them on loopback or restrict access with a firewall. The bearer token protects only the REST API. Use a TLS reverse proxy for remote API access. See [security](SECURITY.md).
+
+## REST API and CLI
+
+All endpoints require `Authorization: Bearer <token>`. FastAPI interactive API docs are available at `/docs`.
+
+| Endpoint | Result |
+| --- | --- |
+| `GET /status` | State, connection ID, start time, server, SOCKS and HTTP proxy addresses, and last error |
+| `POST /rotate` | Stops current tunnel, starts next server, returns status after readiness |
+
+Overlapping rotations and cooldown violations return **429**, with `Retry-After`; callers must trigger again later. They are not queued. Startup/SSH failures return **503** and leave the service disconnected; another trigger after the cooldown advances to the next server. A single-server list restarts the same server. Status remains responsive during rotation and returns `state: "rotating"`; connection ID/start time are null until the new tunnel is ready. After SSH exits, status reports disconnected and clears active connection fields. There is no automatic restart loop.
+
+```sh
+.venv/bin/tunnel-switch status --config config.yaml
+.venv/bin/tunnel-switch rotate --config config.yaml
+curl --noproxy '*' -H "Authorization: Bearer <token-from-YAML>" http://127.0.0.1:8765/status
+curl --noproxy '*' -X POST -H "Authorization: Bearer <token-from-YAML>" http://127.0.0.1:8765/rotate
+```
+
+Example connected status:
+
+```json
+{
+  "state": "connected",
+  "connection_id": "9d7e9746-c4e2-4a43-8da5-674ab452cb91",
+  "started_at": "2026-10-14T12:00:00+00:00",
+  "server": "first",
+  "proxy": {"ip": "127.0.0.1", "port": 1080},
+  "http_proxy": {"enabled": true, "ip": "127.0.0.1", "port": 8118},
+  "last_error": null
+}
+```
+
+## Development and deployment
+
+- [Contributing and releases](CONTRIBUTING.md)
+- [Linux systemd deployment](docs/deployment.md)
+- [Security policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE).

ssh_tunnel_switch-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+tunnel_switch/__init__.py,sha256=QOPPZ-4STPtsDN8e-ePWDJOm-gVi9harY0GCAVu4gGU,41
+tunnel_switch/api.py,sha256=Mytz-dLVX2wh6zz-NMcOW9coFGNr4_HJPIuRAqgx_lI,1921
+tunnel_switch/cli.py,sha256=wn4EvzQm1L3paiVPWXELHF6w_RVXmYwSByzYHcWpW8g,2731
+tunnel_switch/config.py,sha256=HhdT_gZn_oDOSi6RQlhS7_BiWAcjz4jCXssM_0_d0xM,4536
+tunnel_switch/http_proxy.py,sha256=DmhEUxO81m6h0-uZXO6syPt9hmm1LfVFfSmx5GOSlDg,10900
+tunnel_switch/tunnel.py,sha256=d77bzZwEE1WfAAEqr-8x-Oyi9fVBUPieVi-2nQpMvVY,6162
+ssh_tunnel_switch-0.1.0.dist-info/METADATA,sha256=fHJW6Yg7T6V3vlXFdkMgN6Nyfj-9Rx51wI3J7SdO1I8,7073
+ssh_tunnel_switch-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+ssh_tunnel_switch-0.1.0.dist-info/entry_points.txt,sha256=ZplYS21XnBdQH_8-bp3ZtyeLVylsFKqeDzuwxADqGHA,57
+ssh_tunnel_switch-0.1.0.dist-info/licenses/LICENSE,sha256=1lM9TSlsMJxz8mNexJ3AlTLUbxpKrak2kpPk3ORC0CU,1066
+ssh_tunnel_switch-0.1.0.dist-info/RECORD,,

ssh_tunnel_switch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

ssh_tunnel_switch-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tunnel-switch = tunnel_switch.cli:main

ssh_tunnel_switch-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Laing
+
+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.

tunnel_switch/__init__.py

@@ -0,0 +1 @@
+"""SSH SOCKS tunnel rotation service."""

tunnel_switch/api.py

@@ -0,0 +1,51 @@
+from contextlib import asynccontextmanager
+import secrets
+from fastapi import Depends, FastAPI, Header, HTTPException
+from .config import Config
+from .http_proxy import HTTPProxyServer
+from .tunnel import RotationRejected, TunnelFailure, TunnelManager
+
+
+def create_app(config: Config, token: str, manager: TunnelManager | None = None) -> FastAPI:
+    if not token:
+        raise ValueError("API token must not be empty")
+    manager = manager or TunnelManager(config)
+    proxy = HTTPProxyServer(config)
+
+    @asynccontextmanager
+    async def lifespan(app):
+        try:
+            if config.start_on_launch:
+                await manager.rotate()
+            await proxy.start()
+            yield
+        finally:
+            try:
+                await proxy.close()
+            finally:
+                await manager.close()
+
+    app = FastAPI(title="Tunnel Switch", lifespan=lifespan)
+    app.state.manager = manager
+    app.state.http_proxy = proxy
+
+    async def authorize(authorization: str | None = Header(default=None)):
+        if authorization is None or not secrets.compare_digest(authorization.encode(), f"Bearer {token}".encode()):
+            raise HTTPException(status_code=401, detail="Invalid bearer token")
+
+    @app.get("/status", dependencies=[Depends(authorize)])
+    async def status():
+        return {**manager.status(), "http_proxy": {
+            "enabled": config.http_proxy.enabled, "ip": str(config.http_proxy.ip),
+            "port": config.http_proxy.port}}
+
+    @app.post("/rotate", dependencies=[Depends(authorize)])
+    async def rotate():
+        try:
+            return await manager.rotate()
+        except RotationRejected as exc:
+            raise HTTPException(status_code=429, detail=str(exc), headers={"Retry-After": str(exc.retry_after)}) from exc
+        except TunnelFailure as exc:
+            raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+    return app

tunnel_switch/cli.py

@@ -0,0 +1,82 @@
+from pathlib import Path
+from typing import Annotated
+import httpx
+import typer
+import uvicorn
+from .api import create_app
+from .config import ensure_api_token, load_config
+
+app = typer.Typer(no_args_is_help=True, help="Manage the SSH SOCKS tunnel rotation API.")
+ConfigOption = Annotated[Path, typer.Option("--config", "-c", help="Required YAML configuration file.")]
+
+
+def settings(path: Path):
+    config = load_config(path)
+    token = config.api.token
+    if not token:
+        raise ValueError("API token is missing from YAML; start the service with serve to generate and save it")
+    return config, token
+
+
+@app.command()
+def validate(config: ConfigOption):
+    """Validate YAML and SSH identity paths."""
+    load_config(config)
+    typer.echo("Configuration valid")
+
+
+@app.command()
+def serve(config: ConfigOption):
+    """Start the API and manage one SSH process; Ctrl-C stops the tunnel."""
+    cfg = load_config(config)
+    token = ensure_api_token(config, cfg)
+    typer.echo(f"API token: {token}")
+    if cfg.http_proxy.enabled:
+        ip = str(cfg.http_proxy.ip)
+        host = f"[{ip}]" if ":" in ip else ip
+        typer.echo(f"HTTP proxy: http://{host}:{cfg.http_proxy.port}")
+    uvicorn.run(create_app(cfg, token), host=str(cfg.api.ip), port=cfg.api.port, workers=1)
+
+
+def request(path: Path, method: str, endpoint: str):
+    cfg, token = settings(path)
+    ip = str(cfg.api.ip)
+    ip = "127.0.0.1" if ip == "0.0.0.0" else "::1" if ip == "::" else ip
+    host = f"[{ip}]" if ":" in ip else ip
+    response = httpx.request(method, f"http://{host}:{cfg.api.port}/{endpoint}",
+                             headers={"Authorization": f"Bearer {token}"},
+                             timeout=cfg.startup_timeout_seconds + cfg.stop_timeout_seconds + 5,
+                             trust_env=False)
+    response.raise_for_status()
+    typer.echo(response.text)
+
+
+@app.command()
+def status(config: ConfigOption):
+    """Display connection ID, start time and current tunnel state."""
+    request(config, "GET", "status")
+
+
+@app.command()
+def rotate(config: ConfigOption):
+    """Stop the current tunnel and start the next configured SSH server."""
+    request(config, "POST", "rotate")
+
+
+def main():
+    try:
+        app(standalone_mode=False)
+    except Exception as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        import click
+        ctx = click.Context(typer.main.get_command(app))
+        from contextlib import redirect_stdout
+        import sys
+        with redirect_stdout(sys.stderr):
+            typer.echo(ctx.get_help(), err=True)
+        typer.echo("Use tunnel-switch COMMAND --help for command options.", err=True)
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":
+    main()

tunnel_switch/config.py

@@ -0,0 +1,118 @@
+from ipaddress import IPv4Address, IPv6Address
+from pathlib import Path
+import yaml
+import os
+import secrets
+import tempfile
+from ruamel.yaml import YAML
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class Server(StrictModel):
+    name: str | None = Field(default=None, min_length=1)
+    host: str = Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9.:%_-]*$")
+    user: str | None = Field(default=None, pattern=r"^[A-Za-z0-9_][A-Za-z0-9_.-]*$")
+    port: int | None = Field(default=None, ge=1, le=65535)
+    identity_file: Path | None = None
+
+    @model_validator(mode="after")
+    def default_name(self):
+        if self.name is None:
+            self.name = self.host
+        return self
+
+
+class Proxy(StrictModel):
+    ip: IPv4Address | IPv6Address = IPv4Address("127.0.0.1")
+    port: int = Field(default=1080, ge=1, le=65535)
+
+
+class HTTPProxy(StrictModel):
+    enabled: bool = True
+    ip: IPv4Address | IPv6Address = IPv4Address("127.0.0.1")
+    port: int = Field(default=8118, ge=1, le=65535)
+    connect_timeout_seconds: float = Field(default=10, gt=0, le=120)
+    idle_timeout_seconds: float = Field(default=120, gt=0)
+    header_limit_bytes: int = Field(default=65536, ge=1024, le=1048576)
+    max_connections: int = Field(default=128, ge=1)
+
+
+class API(StrictModel):
+    ip: IPv4Address | IPv6Address = IPv4Address("127.0.0.1")
+    port: int = Field(default=8765, ge=1, le=65535)
+    token: str | None = Field(default=None, repr=False)
+
+    @field_validator("token", mode="before")
+    @classmethod
+    def empty_token(cls, value):
+        return None if isinstance(value, str) and not value.strip() else value
+
+
+class Config(StrictModel):
+    servers: list[Server] = Field(min_length=1)
+    proxy: Proxy
+    api: API = Field(default_factory=API)
+    http_proxy: HTTPProxy = Field(default_factory=HTTPProxy)
+    cooldown_seconds: float = Field(default=30, ge=0)
+    startup_timeout_seconds: float = Field(default=15, gt=0, le=120)
+    stop_timeout_seconds: float = Field(default=5, gt=0, le=60)
+    start_on_launch: bool = True
+
+    @model_validator(mode="after")
+    def unique_names(self):
+        if len({server.name for server in self.servers}) != len(self.servers):
+            raise ValueError("SSH server names must be unique")
+        listeners = [self.proxy, self.api]
+        if self.http_proxy.enabled:
+            listeners.append(self.http_proxy)
+        for index, left in enumerate(listeners):
+            for right in listeners[index + 1:]:
+                if left.port == right.port and (left.ip == right.ip or
+                        (left.ip.version == right.ip.version and
+                         (left.ip.is_unspecified or right.ip.is_unspecified))):
+                    raise ValueError("API, HTTP proxy and SOCKS proxy must use different sockets")
+        return self
+
+
+def load_config(path: Path) -> Config:
+    config = Config.model_validate(yaml.safe_load(path.read_text()))
+    for server in config.servers:
+        if server.identity_file is not None:
+            identity = server.identity_file.expanduser()
+            server.identity_file = identity if identity.is_absolute() else path.resolve().parent / identity
+            if not server.identity_file.is_file():
+                raise ValueError(f"Identity file does not exist: {server.identity_file}")
+    return config
+
+
+def ensure_api_token(path: Path, config: Config) -> str:
+    """Persist a generated token atomically, retaining YAML comments and values."""
+    if config.api.token:
+        return config.api.token
+    target = path.resolve()
+    yaml_editor = YAML()
+    yaml_editor.preserve_quotes = True
+    document = yaml_editor.load(target.read_text())
+    if document.get("api") is None:
+        document["api"] = {}
+    token = secrets.token_urlsafe(32)
+    document["api"]["token"] = token
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=target.parent,
+                                         prefix=f".{target.name}.", delete=False) as stream:
+            temporary = Path(stream.name)
+            yaml_editor.dump(document, stream)
+            stream.flush()
+            os.fsync(stream.fileno())
+        # The temporary file is mode 0600; replacement keeps the saved token private.
+        os.replace(temporary, target)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    config.api.token = token
+    return token

tunnel_switch/http_proxy.py

@@ -0,0 +1,238 @@
+"""HTTP/1.1 forward proxy and CONNECT bridge over the managed SSH SOCKS5 socket."""
+import asyncio
+from ipaddress import ip_address
+from urllib.parse import urlsplit
+import h11
+from .config import Config
+
+
+class ProxyError(Exception):
+    pass
+
+
+def destination(target: str, connect: bool = False) -> tuple[str, int, str]:
+    url = urlsplit(f"//{target}" if connect else target)
+    if url.username is not None or url.password is not None or url.fragment:
+        raise ValueError("Invalid proxy target")
+    if not url.hostname or (not connect and url.scheme != "http"):
+        raise ValueError("Use an absolute HTTP URL or CONNECT for HTTPS")
+    if connect and (url.path or url.query or url.port is None):
+        raise ValueError("CONNECT requires host:port")
+    port = url.port if url.port is not None else 80
+    if not 1 <= port <= 65535:
+        raise ValueError("Invalid destination port")
+    path = (url.path or "/") + (f"?{url.query}" if url.query else "")
+    return url.hostname, port, path
+
+
+def headers_for_forwarding(headers, *, host: str | None = None):
+    names = {name.lower() for name, _ in headers}
+    if {b"content-length", b"transfer-encoding"} <= names:
+        raise ValueError("Ambiguous HTTP body framing")
+    connection_tokens = {
+        item.strip().lower() for name, value in headers if name.lower() == b"connection"
+        for item in value.split(b",")
+    }
+    if connection_tokens & {b"host", b"content-length", b"transfer-encoding"}:
+        raise ValueError("Invalid Connection header")
+    stripped = connection_tokens | {b"connection", b"proxy-connection", b"proxy-authorization",
+                                    b"proxy-authenticate", b"keep-alive", b"upgrade"}
+    if host is not None:
+        stripped.add(b"host")
+    result = [(name, value) for name, value in headers if name.lower() not in stripped]
+    if host is not None:
+        result.append((b"host", host.encode("ascii")))
+    result.append((b"connection", b"close"))
+    return result
+
+
+class HTTPProxyServer:
+    def __init__(self, config: Config):
+        self.config = config
+        self.server = None
+        self._tasks = set()
+        self._closing = False
+
+    async def start(self):
+        if self.config.http_proxy.enabled:
+            self.server = await asyncio.start_server(
+                self._accept, str(self.config.http_proxy.ip), self.config.http_proxy.port,
+                limit=self.config.http_proxy.header_limit_bytes)
+
+    async def close(self):
+        self._closing = True
+        if self.server:
+            self.server.close()
+        tasks = list(self._tasks)
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        if self.server:
+            await self.server.wait_closed()
+
+    async def _socks(self, host: str, port: int):
+        proxy_ip = str(self.config.proxy.ip)
+        proxy_ip = "127.0.0.1" if proxy_ip == "0.0.0.0" else "::1" if proxy_ip == "::" else proxy_ip
+        reader, writer = await asyncio.open_connection(proxy_ip, self.config.proxy.port)
+        try:
+            writer.write(b"\x05\x01\x00")
+            await writer.drain()
+            if await reader.readexactly(2) != b"\x05\x00":
+                raise ProxyError("SOCKS authentication negotiation failed")
+            try:
+                address = ip_address(host)
+                encoded = (b"\x01" if address.version == 4 else b"\x04") + address.packed
+            except ValueError:
+                name = host.encode("idna")
+                if not 1 <= len(name) <= 255:
+                    raise ProxyError("Destination hostname too long")
+                encoded = b"\x03" + bytes([len(name)]) + name
+            writer.write(b"\x05\x01\x00" + encoded + port.to_bytes(2, "big"))
+            await writer.drain()
+            reply = await reader.readexactly(4)
+            if reply[:3] != b"\x05\x00\x00":
+                raise ProxyError("SOCKS destination connection failed")
+            if reply[3] == 1:
+                length = 4
+            elif reply[3] == 4:
+                length = 16
+            elif reply[3] == 3:
+                length = (await reader.readexactly(1))[0]
+            else:
+                raise ProxyError("Invalid SOCKS address type")
+            await reader.readexactly(length + 2)
+            return reader, writer
+        except BaseException:
+            writer.close()
+            await writer.wait_closed()
+            raise
+
+    async def _read_event(self, connection, reader):
+        while True:
+            event = connection.next_event()
+            if event is not h11.NEED_DATA:
+                return event
+            data = await asyncio.wait_for(reader.read(65536), self.config.http_proxy.idle_timeout_seconds)
+            connection.receive_data(data)
+
+    async def _relay_connect(self, client_reader, client_writer, upstream_reader, upstream_writer):
+        async def pump(reader, writer):
+            while data := await asyncio.wait_for(reader.read(65536), self.config.http_proxy.idle_timeout_seconds):
+                writer.write(data)
+                await writer.drain()
+            if writer.can_write_eof():
+                writer.write_eof()
+                await writer.drain()
+        tasks = [asyncio.create_task(pump(client_reader, upstream_writer)),
+                 asyncio.create_task(pump(upstream_reader, client_writer))]
+        try:
+            done, _ = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+            for task in done:
+                task.result()
+            if tasks[1] not in done:
+                await tasks[1]
+        finally:
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def _forward_http(self, request, inbound, reader, writer, upstream_reader, upstream_writer, path, authority):
+        outbound = h11.Connection(h11.CLIENT)
+        upstream_writer.write(outbound.send(h11.Request(
+            method=request.method, target=path.encode("ascii"),
+            headers=headers_for_forwarding(request.headers, host=authority))))
+        await upstream_writer.drain()
+
+        async def send_body():
+            while True:
+                event = await self._read_event(inbound, reader)
+                if not isinstance(event, (h11.Data, h11.EndOfMessage)):
+                    raise ProxyError("Incomplete HTTP request body")
+                upstream_writer.write(outbound.send(event))
+                await upstream_writer.drain()
+                if isinstance(event, h11.EndOfMessage):
+                    return
+
+        async def receive_response():
+            while True:
+                event = await self._read_event(outbound, upstream_reader)
+                if isinstance(event, (h11.Response, h11.InformationalResponse)):
+                    if event.status_code == 101:
+                        raise ProxyError("HTTP Upgrade is unsupported; use CONNECT")
+                    event = type(event)(status_code=event.status_code, reason=event.reason,
+                                       headers=headers_for_forwarding(event.headers))
+                elif not isinstance(event, (h11.Data, h11.EndOfMessage)):
+                    raise ProxyError("Incomplete upstream response")
+                writer.write(inbound.send(event))
+                await writer.drain()
+                if isinstance(event, h11.EndOfMessage):
+                    return
+
+        tasks = [asyncio.create_task(send_body()), asyncio.create_task(receive_response())]
+        try:
+            # The response may finish before the request body (e.g. an upstream rejection).
+            done, _ = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+            for task in done:
+                task.result()
+            if tasks[1] not in done:
+                await tasks[1]
+        finally:
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def _accept(self, reader, writer):
+        if self._closing or len(self._tasks) >= self.config.http_proxy.max_connections:
+            writer.write(b"HTTP/1.1 503 Service Unavailable\r\nContent-Length: 0\r\nConnection: close\r\n\r\n")
+            await writer.drain()
+            writer.close()
+            await writer.wait_closed()
+            return
+        task = asyncio.current_task()
+        self._tasks.add(task)
+        upstream_writer = None
+        inbound = h11.Connection(h11.SERVER)
+        connected = False
+        status = 400
+        try:
+            raw = await asyncio.wait_for(reader.readuntil(b"\r\n\r\n"), self.config.http_proxy.idle_timeout_seconds)
+            inbound.receive_data(raw)
+            request = inbound.next_event()
+            if not isinstance(request, h11.Request):
+                raise ValueError("Invalid request")
+            connect = request.method == b"CONNECT"
+            host, port, path = destination(request.target.decode("ascii"), connect)
+            headers_for_forwarding(request.headers)  # Validate before connecting.
+            status = 502
+            upstream_reader, upstream_writer = await asyncio.wait_for(
+                self._socks(host, port), self.config.http_proxy.connect_timeout_seconds)
+            if connect:
+                writer.write(inbound.send(h11.Response(status_code=200, headers=[], reason=b"Connection Established")))
+                await writer.drain()
+                connected = True
+                await self._relay_connect(reader, writer, upstream_reader, upstream_writer)
+            else:
+                authority = f"[{host}]" if ":" in host else host.encode("idna").decode("ascii")
+                if port != 80:
+                    authority += f":{port}"
+                await self._forward_http(request, inbound, reader, writer, upstream_reader, upstream_writer, path, authority)
+        except (OSError, TimeoutError, ValueError, ProxyError, h11.ProtocolError,
+                asyncio.IncompleteReadError, asyncio.LimitOverrunError):
+            # Never append an HTTP error after a response or tunnel has begun.
+            if not connected and inbound.our_state in (h11.IDLE, h11.SEND_RESPONSE):
+                reason = b"Bad Request" if status == 400 else b"Bad Gateway"
+                writer.write(b"HTTP/1.1 " + str(status).encode() + b" " + reason
+                             + b"\r\nContent-Length: 0\r\nConnection: close\r\n\r\n")
+                try:
+                    await writer.drain()
+                except OSError:
+                    pass
+        finally:
+            for stream in (upstream_writer, writer):
+                if stream:
+                    stream.close()
+                    try:
+                        await stream.wait_closed()
+                    except OSError:
+                        pass
+            self._tasks.discard(task)

tunnel_switch/tunnel.py

@@ -0,0 +1,153 @@
+import asyncio
+from datetime import datetime, timezone
+import socket
+import time
+from uuid import uuid4
+from .config import Config, Server
+
+
+class RotationRejected(Exception):
+    def __init__(self, message: str, retry_after: int = 1):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class TunnelFailure(Exception):
+    pass
+
+
+class TunnelManager:
+    def __init__(self, config: Config):
+        self.config = config
+        self.process = None
+        self.connection_id = None
+        self.started_at = None
+        self.server_name = None
+        self.last_error = None
+        self._index = -1
+        self._busy = False
+        self._last_rotation = None
+
+    def status(self) -> dict:
+        alive = self.process is not None and self.process.returncode is None
+        return {
+            "state": "rotating" if self._busy else "connected" if alive else "disconnected",
+            "connection_id": self.connection_id if alive else None,
+            "started_at": self.started_at.isoformat() if alive and self.started_at else None,
+            "server": self.server_name if alive else None,
+            "proxy": self.config.proxy.model_dump(mode="json"),
+            "last_error": self.last_error,
+        }
+
+    def command(self, server: Server) -> list[str]:
+        ip = str(self.config.proxy.ip)
+        bind = f"[{ip}]" if ":" in ip else ip
+        args = ["ssh", "-N", "-T", "-D", f"{bind}:{self.config.proxy.port}",
+                "-o", "BatchMode=yes",
+                "-o", "StrictHostKeyChecking=yes", "-o", "ExitOnForwardFailure=yes",
+                "-o", "ControlMaster=no", "-o", "ControlPath=none",
+                "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=3",
+                "-o", f"ConnectTimeout={int(self.config.startup_timeout_seconds) or 1}"]
+        if server.port is not None:
+            args.extend(["-p", str(server.port)])
+        if server.user is not None:
+            args.extend(["-l", server.user])
+        if server.identity_file:
+            args.extend(["-i", str(server.identity_file)])
+        return [*args, "--", server.host]
+
+    async def _stop(self):
+        process = self.process
+        if process is None:
+            return
+        if process.returncode is None:
+            try:
+                process.terminate()
+            except ProcessLookupError:
+                pass
+            try:
+                await asyncio.wait_for(process.wait(), self.config.stop_timeout_seconds)
+            except TimeoutError:
+                try:
+                    process.kill()
+                except ProcessLookupError:
+                    pass
+                await process.wait()
+        self.process = None
+        self.connection_id = self.started_at = self.server_name = None
+
+    async def _ready(self):
+        ip = str(self.config.proxy.ip)
+        if ip == "0.0.0.0":
+            ip = "127.0.0.1"
+        elif ip == "::":
+            ip = "::1"
+        writer = None
+        try:
+            reader, writer = await asyncio.wait_for(asyncio.open_connection(ip, self.config.proxy.port), 0.5)
+            writer.write(b"\x05\x01\x00")
+            await writer.drain()
+            return await asyncio.wait_for(reader.readexactly(2), 0.5) == b"\x05\x00"
+        except (OSError, TimeoutError, asyncio.IncompleteReadError):
+            return False
+        finally:
+            if writer:
+                writer.close()
+                await writer.wait_closed()
+
+    def _ensure_socket_free(self):
+        family = socket.AF_INET6 if self.config.proxy.ip.version == 6 else socket.AF_INET
+        with socket.socket(family) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.bind((str(self.config.proxy.ip), self.config.proxy.port))
+            except OSError as exc:
+                raise TunnelFailure("SOCKS bind address is already occupied or unavailable") from exc
+
+    async def rotate(self) -> dict:
+        # No await before admission: atomic within the single service event loop.
+        if self._busy:
+            raise RotationRejected("Tunnel rotation already in progress")
+        now = time.monotonic()
+        if self._last_rotation is not None:
+            remaining = self.config.cooldown_seconds - (now - self._last_rotation)
+            if remaining > 0:
+                raise RotationRejected("Tunnel rotation cooldown active", int(remaining) + 1)
+        self._busy = True
+        self.last_error = None
+        try:
+            await self._stop()
+            self._ensure_socket_free()
+            self._index = (self._index + 1) % len(self.config.servers)
+            server = self.config.servers[self._index]
+            self.process = await asyncio.create_subprocess_exec(
+                *self.command(server), stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.DEVNULL, stderr=asyncio.subprocess.DEVNULL)
+            deadline = time.monotonic() + self.config.startup_timeout_seconds
+            while time.monotonic() < deadline:
+                if self.process.returncode is not None:
+                    raise TunnelFailure(f"SSH exited with code {self.process.returncode}; check authentication, known_hosts and forwarding permissions")
+                if await self._ready():
+                    await asyncio.sleep(0.05)
+                    if self.process.returncode is None:
+                        self.connection_id = str(uuid4())
+                        self.started_at = datetime.now(timezone.utc)
+                        self.server_name = server.name
+                        break
+                await asyncio.sleep(0.1)
+            else:
+                raise TunnelFailure("SSH SOCKS startup timed out")
+        except asyncio.CancelledError:
+            await self._stop()
+            raise
+        except Exception as exc:
+            self.last_error = str(exc)
+            await self._stop()
+            raise TunnelFailure(str(exc)) from exc
+        finally:
+            self._last_rotation = time.monotonic()
+            self._busy = False
+        return self.status()
+
+    async def close(self):
+        await self._stop()