wg-bridge 1.0.3__tar.gz

wg_bridge-1.0.3/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.3
+Name: wg-bridge
+Version: 1.0.3
+Summary: Tunnel WireGuard UDP traffic over a TCP/SSH connection for networks that block UDP
+Author: Wei Liu
+Author-email: Wei Liu <liuwei_berkeley@berkeley.edu>
+Requires-Dist: typer>=0.12.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# wg-bridge
+
+Tunnel WireGuard's UDP traffic over a TCP connection (an SSH tunnel), for networks that block or throttle UDP but allow TCP/SSH.
+
+## How it works
+
+```
+WireGuard client -> UDP -> wg-bridge --client -> TCP -> SSH tunnel -> TCP -> wg-bridge --server -> UDP -> WireGuard server
+```
+
+- **Client** side runs next to your local WireGuard client. It binds the UDP port your WireGuard client talks to, and forwards everything over a TCP connection into an SSH tunnel.
+- **Server** side runs near the actual WireGuard server. It listens for the TCP connection coming out of the SSH tunnel and forwards packets to the real WireGuard UDP endpoint.
+
+You are responsible for setting up the SSH tunnel itself (e.g. `ssh -L <tcp-port>:localhost:<tcp-port> user@server` or a remote forward, depending on your topology) — `wg-bridge` only handles the UDP↔TCP relay on each end.
+
+Each UDP datagram is sent over the TCP stream with a 2-byte length prefix, so datagram boundaries survive the byte-stream relay even when several packets arrive back-to-back (bursty traffic like a VNC/RDP session, not just isolated pings). **This is a wire-format change — the client and server sides must run the same wg-bridge version; an old client cannot talk to a new server or vice versa.**
+
+## Install
+
+### From PyPI
+
+```bash
+pip install wg-bridge
+```
+
+Or, to install it as an isolated global command-line tool rather than into a project environment (recommended for a CLI-only package like this):
+
+```bash
+pipx install wg-bridge
+# or, using uv:
+uv tool install wg-bridge
+```
+
+### From GitHub (without cloning)
+
+Installs the latest code on the default branch directly from the repository:
+
+```bash
+pip install git+https://github.com/liuweiseu/wg-bridge.git
+# or:
+pipx install git+https://github.com/liuweiseu/wg-bridge.git
+# or:
+uv tool install git+https://github.com/liuweiseu/wg-bridge.git
+```
+
+Pin a specific released version by appending `@vX.Y.Z` (see the [releases page](https://github.com/liuweiseu/wg-bridge/releases)), e.g. `git+https://github.com/liuweiseu/wg-bridge.git@v1.0.3`.
+
+### From source
+
+```bash
+git clone https://github.com/liuweiseu/wg-bridge.git
+cd wg-bridge
+uv sync
+```
+
+Every `wg-bridge ...` command shown below becomes `uv run wg-bridge ...` when run this way (unless you've activated the project's `.venv` yourself).
+
+### Shell tab-completion
+
+Once installed by any of the methods above, enable shell tab-completion (bash/zsh/fish/PowerShell) by running once from an interactive shell and restarting your terminal:
+
+```bash
+wg-bridge --install-completion
+```
+
+## Usage
+
+By default `--server` and `--client` detach into the background and hand control of the terminal straight back to you — no `&` or `nohup` needed. Output goes through Python's `logging` module to a `wg-bridge.log` file (the first line logged is always the working mode); use `--status` to check on it and `--stop` to stop it.
+
+On the machine near the WireGuard server:
+
+```bash
+wg-bridge --server --wg-host <wireguard-server-ip> --tcp-port <port> [--wg-port 51820] [--log-file <path>]
+```
+
+```
+$ wg-bridge --server --wg-host 192.168.88.199 --tcp-port 5980
+[INFO] wg-bridge server started in background (PID 39195).
+[INFO] listening on TCP 0.0.0.0:5980 -> forwarding to UDP 192.168.88.199:51820
+[INFO] logs: /path/to/cwd/wg-bridge.log
+```
+
+```
+$ cat wg-bridge.log
+2026-09-09 23:18:47 [INFO] Working mode: server
+2026-09-09 23:18:47 [INFO] Server bridge started: TCP:5980 -> UDP 192.168.88.199:51820
+```
+
+`--log-file` sets the path (directory + filename) of the log file; it defaults to `./wg-bridge.log` in the current directory (its parent directory is created if it doesn't exist yet).
+
+On the machine running the local WireGuard client:
+
+```bash
+wg-bridge --client --tcp-port <port> [--wg-port 51820] [--log-file <path>]
+```
+
+Add `--foreground` to either command to run it attached to the terminal instead (useful for debugging) — `Ctrl-C` stops it. In foreground mode, log lines are also echoed to the console in addition to the log file.
+
+To stop whichever bridge process is currently running on that machine:
+
+```bash
+wg-bridge --stop
+```
+
+To check whether a bridge process is currently running on that machine:
+
+```bash
+wg-bridge --status
+```
+
+```
+$ wg-bridge --status
+[INFO] wg-bridge is running (PID 39195, mode=server)
+[INFO] listening on TCP 0.0.0.0:5980 -> forwarding to UDP 192.168.88.199:51820
+[INFO] logs: /path/to/cwd/wg-bridge.log
+```
+
+| Flag | Mode | Default | Description |
+|---|---|---|---|
+| `--server` | — | — | Run in server mode (near the WireGuard server). |
+| `--client` | — | — | Run in client mode (next to the local WireGuard client). |
+| `--stop` | — | — | Stop the wg-bridge process currently running on this machine. |
+| `--status` | — | — | Show whether wg-bridge is running on this machine, and its bound host/port info if so. |
+| `--foreground` | server/client only | — | Run attached to the terminal instead of detaching into the background. |
+| `--log-file` | server/client only | `./wg-bridge.log` | Path (directory + filename) of the log file. |
+| `--version` | — | — | Print the wg-bridge version and exit. |
+| `--help` / `-h` | — | — | Show this help and exit. |
+| `--install-completion` | — | — | Install shell tab-completion for the detected shell. |
+| `--show-completion` | — | — | Print the completion script for the detected shell, without installing it. |
+| `--wg-host` | server only | `localhost` | WireGuard server address. |
+| `--wg-port` | both | `51820` | WireGuard UDP port. |
+| `--tcp-port` | server/client only | *(required)* | TCP tunnel port; must match the SSH tunnel endpoint and be the same value on both sides. |
+
+Exactly one of `--server`, `--client`, `--stop`, or `--status` is required.
+
+## Notes
+
+- Each side assumes a single active WireGuard peer/session at a time; it does not multiplex multiple peers through one bridge process.
+- Both sides retry automatically if the TCP connection drops.
+- Starting `--server` or `--client` records the running process's PID, its host/port settings, and its log file path in a state file under the system temp directory; starting a second instance while one is already tracked as running is refused until you `--stop` it. `--stop` sends the tracked process a termination signal and clears the state file; `--status` reports it (or reports not running, cleaning up the state file first if it points at a process that's already gone — e.g. after a crash).
+- In the default background mode, if the process fails immediately (e.g. the TCP port is already in use), the command reports the failure and prints the last lines of `wg-bridge.log` instead of claiming success.
+- `wg-bridge.log` is appended to, not truncated, across restarts — each run's own first line is always `Working mode: server`/`Working mode: client`.

wg_bridge-1.0.3/README.md

@@ -0,0 +1,142 @@
+# wg-bridge
+
+Tunnel WireGuard's UDP traffic over a TCP connection (an SSH tunnel), for networks that block or throttle UDP but allow TCP/SSH.
+
+## How it works
+
+```
+WireGuard client -> UDP -> wg-bridge --client -> TCP -> SSH tunnel -> TCP -> wg-bridge --server -> UDP -> WireGuard server
+```
+
+- **Client** side runs next to your local WireGuard client. It binds the UDP port your WireGuard client talks to, and forwards everything over a TCP connection into an SSH tunnel.
+- **Server** side runs near the actual WireGuard server. It listens for the TCP connection coming out of the SSH tunnel and forwards packets to the real WireGuard UDP endpoint.
+
+You are responsible for setting up the SSH tunnel itself (e.g. `ssh -L <tcp-port>:localhost:<tcp-port> user@server` or a remote forward, depending on your topology) — `wg-bridge` only handles the UDP↔TCP relay on each end.
+
+Each UDP datagram is sent over the TCP stream with a 2-byte length prefix, so datagram boundaries survive the byte-stream relay even when several packets arrive back-to-back (bursty traffic like a VNC/RDP session, not just isolated pings). **This is a wire-format change — the client and server sides must run the same wg-bridge version; an old client cannot talk to a new server or vice versa.**
+
+## Install
+
+### From PyPI
+
+```bash
+pip install wg-bridge
+```
+
+Or, to install it as an isolated global command-line tool rather than into a project environment (recommended for a CLI-only package like this):
+
+```bash
+pipx install wg-bridge
+# or, using uv:
+uv tool install wg-bridge
+```
+
+### From GitHub (without cloning)
+
+Installs the latest code on the default branch directly from the repository:
+
+```bash
+pip install git+https://github.com/liuweiseu/wg-bridge.git
+# or:
+pipx install git+https://github.com/liuweiseu/wg-bridge.git
+# or:
+uv tool install git+https://github.com/liuweiseu/wg-bridge.git
+```
+
+Pin a specific released version by appending `@vX.Y.Z` (see the [releases page](https://github.com/liuweiseu/wg-bridge/releases)), e.g. `git+https://github.com/liuweiseu/wg-bridge.git@v1.0.3`.
+
+### From source
+
+```bash
+git clone https://github.com/liuweiseu/wg-bridge.git
+cd wg-bridge
+uv sync
+```
+
+Every `wg-bridge ...` command shown below becomes `uv run wg-bridge ...` when run this way (unless you've activated the project's `.venv` yourself).
+
+### Shell tab-completion
+
+Once installed by any of the methods above, enable shell tab-completion (bash/zsh/fish/PowerShell) by running once from an interactive shell and restarting your terminal:
+
+```bash
+wg-bridge --install-completion
+```
+
+## Usage
+
+By default `--server` and `--client` detach into the background and hand control of the terminal straight back to you — no `&` or `nohup` needed. Output goes through Python's `logging` module to a `wg-bridge.log` file (the first line logged is always the working mode); use `--status` to check on it and `--stop` to stop it.
+
+On the machine near the WireGuard server:
+
+```bash
+wg-bridge --server --wg-host <wireguard-server-ip> --tcp-port <port> [--wg-port 51820] [--log-file <path>]
+```
+
+```
+$ wg-bridge --server --wg-host 192.168.88.199 --tcp-port 5980
+[INFO] wg-bridge server started in background (PID 39195).
+[INFO] listening on TCP 0.0.0.0:5980 -> forwarding to UDP 192.168.88.199:51820
+[INFO] logs: /path/to/cwd/wg-bridge.log
+```
+
+```
+$ cat wg-bridge.log
+2026-09-09 23:18:47 [INFO] Working mode: server
+2026-09-09 23:18:47 [INFO] Server bridge started: TCP:5980 -> UDP 192.168.88.199:51820
+```
+
+`--log-file` sets the path (directory + filename) of the log file; it defaults to `./wg-bridge.log` in the current directory (its parent directory is created if it doesn't exist yet).
+
+On the machine running the local WireGuard client:
+
+```bash
+wg-bridge --client --tcp-port <port> [--wg-port 51820] [--log-file <path>]
+```
+
+Add `--foreground` to either command to run it attached to the terminal instead (useful for debugging) — `Ctrl-C` stops it. In foreground mode, log lines are also echoed to the console in addition to the log file.
+
+To stop whichever bridge process is currently running on that machine:
+
+```bash
+wg-bridge --stop
+```
+
+To check whether a bridge process is currently running on that machine:
+
+```bash
+wg-bridge --status
+```
+
+```
+$ wg-bridge --status
+[INFO] wg-bridge is running (PID 39195, mode=server)
+[INFO] listening on TCP 0.0.0.0:5980 -> forwarding to UDP 192.168.88.199:51820
+[INFO] logs: /path/to/cwd/wg-bridge.log
+```
+
+| Flag | Mode | Default | Description |
+|---|---|---|---|
+| `--server` | — | — | Run in server mode (near the WireGuard server). |
+| `--client` | — | — | Run in client mode (next to the local WireGuard client). |
+| `--stop` | — | — | Stop the wg-bridge process currently running on this machine. |
+| `--status` | — | — | Show whether wg-bridge is running on this machine, and its bound host/port info if so. |
+| `--foreground` | server/client only | — | Run attached to the terminal instead of detaching into the background. |
+| `--log-file` | server/client only | `./wg-bridge.log` | Path (directory + filename) of the log file. |
+| `--version` | — | — | Print the wg-bridge version and exit. |
+| `--help` / `-h` | — | — | Show this help and exit. |
+| `--install-completion` | — | — | Install shell tab-completion for the detected shell. |
+| `--show-completion` | — | — | Print the completion script for the detected shell, without installing it. |
+| `--wg-host` | server only | `localhost` | WireGuard server address. |
+| `--wg-port` | both | `51820` | WireGuard UDP port. |
+| `--tcp-port` | server/client only | *(required)* | TCP tunnel port; must match the SSH tunnel endpoint and be the same value on both sides. |
+
+Exactly one of `--server`, `--client`, `--stop`, or `--status` is required.
+
+## Notes
+
+- Each side assumes a single active WireGuard peer/session at a time; it does not multiplex multiple peers through one bridge process.
+- Both sides retry automatically if the TCP connection drops.
+- Starting `--server` or `--client` records the running process's PID, its host/port settings, and its log file path in a state file under the system temp directory; starting a second instance while one is already tracked as running is refused until you `--stop` it. `--stop` sends the tracked process a termination signal and clears the state file; `--status` reports it (or reports not running, cleaning up the state file first if it points at a process that's already gone — e.g. after a crash).
+- In the default background mode, if the process fails immediately (e.g. the TCP port is already in use), the command reports the failure and prints the last lines of `wg-bridge.log` instead of claiming success.
+- `wg-bridge.log` is appended to, not truncated, across restarts — each run's own first line is always `Working mode: server`/`Working mode: client`.

wg_bridge-1.0.3/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "wg-bridge"
+version = "1.0.3"
+description = "Tunnel WireGuard UDP traffic over a TCP/SSH connection for networks that block UDP"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = ["typer>=0.12.0"]
+
+[[project.authors]]
+name = "Wei Liu"
+email = "liuwei_berkeley@berkeley.edu"
+
+[project.scripts]
+wg-bridge = "wg_bridge:main"
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"

wg_bridge-1.0.3/pyproject.toml.orig

@@ -0,0 +1,17 @@
+[project]
+name = "wg-bridge"
+version = "1.0.3"
+description = "Tunnel WireGuard UDP traffic over a TCP/SSH connection for networks that block UDP"
+readme = "README.md"
+authors = [
+    { name = "Wei Liu", email = "liuwei_berkeley@berkeley.edu" }
+]
+requires-python = ">=3.14"
+dependencies = ["typer>=0.12.0"]
+
+[project.scripts]
+wg-bridge = "wg_bridge:main"
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"

wg_bridge-1.0.3/src/wg_bridge/__init__.py

@@ -0,0 +1,5 @@
+from wg_bridge.cli import app
+
+
+def main() -> None:
+    app()

wg_bridge-1.0.3/src/wg_bridge/__main__.py

@@ -0,0 +1,4 @@
+from wg_bridge import main
+
+if __name__ == "__main__":
+    main()

wg_bridge-1.0.3/src/wg_bridge/cli.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import atexit
+import logging
+import subprocess
+import sys
+import time
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
+
+import typer
+
+from wg_bridge.client import run_client
+from wg_bridge.logging_setup import configure_cli_logging, configure_worker_logging
+from wg_bridge.server import run_server
+from wg_bridge.state import (
+    describe_binding,
+    print_status,
+    process_running,
+    read_state,
+    remove_state,
+    stop_running,
+    write_state,
+)
+
+app = typer.Typer(
+    add_completion=True,
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"wg-bridge {_pkg_version('wg-bridge')}")
+        raise typer.Exit()
+
+
+def _run_in_foreground(mode: str, wg_host: str, wg_port: int, tcp_port: int, log_file: Path) -> None:
+    configure_worker_logging(log_file, mode=mode, console=True)
+    write_state(
+        mode=mode,
+        wg_host=wg_host if mode == "server" else None,
+        wg_port=wg_port,
+        tcp_port=tcp_port,
+        log_path=log_file,
+    )
+    atexit.register(remove_state)
+
+    if mode == "server":
+        run_server(wg_host=wg_host, wg_port=wg_port, tcp_port=tcp_port)
+    else:
+        run_client(wg_port=wg_port, tcp_port=tcp_port)
+
+
+def _start_in_background(mode: str, wg_host: str, wg_port: int, tcp_port: int, log_file: Path) -> None:
+    child_args = [
+        f"--{mode}",
+        "--foreground",
+        "--wg-port",
+        str(wg_port),
+        "--tcp-port",
+        str(tcp_port),
+        "--log-file",
+        str(log_file),
+    ]
+    if mode == "server":
+        child_args += ["--wg-host", wg_host]
+
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "wg_bridge", *child_args],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+
+    time.sleep(0.3)  # give the child a moment to fail fast (e.g. port already in use)
+    if proc.poll() is not None:  # poll() reaps the child if it already exited, unlike a raw kill(pid, 0) liveness check
+        logging.error(
+            "wg-bridge %s failed to start (exit code %s). Last log lines (%s):", mode, proc.returncode, log_file
+        )
+        if log_file.exists():
+            for line in log_file.read_text().splitlines()[-10:]:
+                logging.error("%s", line)
+        raise typer.Exit(1)
+
+    logging.info("wg-bridge %s started in background (PID %d).", mode, proc.pid)
+    logging.info("%s", describe_binding(mode, wg_host, wg_port, tcp_port))
+    logging.info("logs: %s", log_file)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the wg-bridge version and exit.",
+    ),
+    server: bool = typer.Option(
+        False, "--server", help="Run as the server-side bridge, near the WireGuard server."
+    ),
+    client: bool = typer.Option(
+        False, "--client", help="Run as the client-side bridge, next to the local WireGuard client."
+    ),
+    stop: bool = typer.Option(
+        False, "--stop", help="Stop the wg-bridge process currently running on this machine."
+    ),
+    status: bool = typer.Option(
+        False, "--status", help="Show whether wg-bridge is currently running on this machine."
+    ),
+    foreground: bool = typer.Option(
+        False,
+        "--foreground",
+        help="Run in the foreground instead of detaching into the background (useful for debugging).",
+    ),
+    wg_host: str = typer.Option(
+        "localhost", "--wg-host", help="WireGuard server address (server mode only)."
+    ),
+    wg_port: int = typer.Option(
+        51820, "--wg-port", help="WireGuard UDP port."
+    ),
+    tcp_port: int | None = typer.Option(
+        None, "--tcp-port", help="TCP tunnel port used to carry the bridged traffic (required for --server/--client)."
+    ),
+    log_file: Path = typer.Option(
+        Path("./wg-bridge.log"),
+        "--log-file",
+        help="Path (directory + filename) of the log file (server/client mode only). Defaults to ./wg-bridge.log.",
+    ),
+) -> None:
+    configure_cli_logging()
+
+    if sum([server, client, stop, status]) != 1:
+        raise typer.BadParameter("Specify exactly one of --server, --client, --stop, or --status.")
+
+    if stop:
+        stop_running()
+        return
+
+    if status:
+        print_status()
+        return
+
+    if tcp_port is None:
+        raise typer.BadParameter("--tcp-port is required for --server and --client mode.")
+
+    existing_state = read_state()
+    if existing_state is not None and process_running(existing_state.pid):
+        raise typer.BadParameter(
+            f"wg-bridge is already running on this machine (PID {existing_state.pid}). Stop it first with --stop."
+        )
+
+    mode = "server" if server else "client"
+    log_file = log_file.resolve()
+    if foreground:
+        _run_in_foreground(mode, wg_host, wg_port, tcp_port, log_file)
+    else:
+        _start_in_background(mode, wg_host, wg_port, tcp_port, log_file)

wg_bridge-1.0.3/src/wg_bridge/client.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import logging
+import select
+import socket
+import time
+
+from wg_bridge.framing import recv_framed, send_framed
+
+
+def run_client(wg_port: int, tcp_port: int) -> None:
+    udp_sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    udp_sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    udp_sock.bind(("127.0.0.1", wg_port))
+
+    logging.info("UDP:%d -> TCP:%d bridge ready", wg_port, tcp_port)
+
+    while True:
+        try:
+            # Connect out to the SSH tunnel
+            tcp_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            tcp_sock.connect(("127.0.0.1", tcp_port))
+
+            client_addr = None
+            while True:
+                r, _, _ = select.select([udp_sock, tcp_sock], [], [], 1.0)
+                for s in r:
+                    if s is udp_sock:
+                        data, client_addr = udp_sock.recvfrom(65535)
+                        send_framed(tcp_sock, data)
+                    elif s is tcp_sock:
+                        data = recv_framed(tcp_sock)
+                        if client_addr:
+                            udp_sock.sendto(data, client_addr)
+        except Exception:
+            tcp_sock.close()
+            time.sleep(0.5)  # retry gracefully, never crash

wg_bridge-1.0.3/src/wg_bridge/framing.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import socket
+import struct
+
+# Each UDP datagram is prefixed with its length so message boundaries survive
+# the raw TCP byte stream (see run_client/run_server for why this matters).
+_HEADER = struct.Struct("!H")
+MAX_DATAGRAM_SIZE = 2**16 - 1  # fits a 2-byte length prefix; matches the recvfrom(65535) cap
+
+
+def send_framed(sock: socket.socket, data: bytes) -> None:
+    if len(data) > MAX_DATAGRAM_SIZE:
+        raise ValueError(f"datagram too large to frame: {len(data)} bytes")
+    sock.sendall(_HEADER.pack(len(data)) + data)
+
+
+def _recv_exact(sock: socket.socket, size: int) -> bytes:
+    chunks: list[bytes] = []
+    remaining = size
+    while remaining > 0:
+        chunk = sock.recv(remaining)
+        if not chunk:
+            raise ConnectionResetError("connection closed while reading a frame")
+        chunks.append(chunk)
+        remaining -= len(chunk)
+    return b"".join(chunks)
+
+
+def recv_framed(sock: socket.socket) -> bytes:
+    (length,) = _HEADER.unpack(_recv_exact(sock, _HEADER.size))
+    return _recv_exact(sock, length)

wg_bridge-1.0.3/src/wg_bridge/logging_setup.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+
+def configure_worker_logging(log_file: Path, mode: str, console: bool) -> None:
+    """Configure logging for the process that actually runs the bridge loop.
+
+    The first line this writes is always the working mode, before any other
+    log output from run_server/run_client.
+    """
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+
+    file_handler = logging.FileHandler(log_file)
+    file_handler.setFormatter(
+        logging.Formatter("%(asctime)s [%(levelname)s] %(message)s", datefmt="%Y-%m-%d %H:%M:%S")
+    )
+
+    handlers: list[logging.Handler] = [file_handler]
+    if console:
+        console_handler = logging.StreamHandler(sys.stdout)
+        console_handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+        handlers.append(console_handler)
+
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+    root.handlers = handlers
+
+    logging.info("Working mode: %s", mode)
+
+
+def configure_cli_logging() -> None:
+    """Configure logging for one-off CLI commands (--stop/--status/start confirmation)."""
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+    root.handlers = [handler]

wg_bridge-1.0.3/src/wg_bridge/server.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import logging
+import select
+import socket
+import sys
+
+from wg_bridge.framing import recv_framed, send_framed
+
+
+def run_server(wg_host: str, wg_port: int, tcp_port: int) -> None:
+    # 1. Create the TCP listening socket (accepts traffic coming from the SSH tunnel)
+    server_tcp = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server_tcp.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+    try:
+        server_tcp.bind(("0.0.0.0", tcp_port))
+        server_tcp.listen(5)
+        logging.info("Server bridge started: TCP:%d -> UDP %s:%d", tcp_port, wg_host, wg_port)
+    except Exception as e:
+        logging.error("Failed to bind TCP port %d: %s", tcp_port, e)
+        sys.exit(1)
+
+    while True:
+        try:
+            # Wait for the client (connecting in over the SSH tunnel) to connect
+            tcp_conn, client_addr = server_tcp.accept()
+            logging.info("Accepted connection from SSH tunnel: %s", client_addr)
+
+            # Create a UDP socket for this TCP connection, forwarding to WireGuard
+            udp_sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+
+            while True:
+                # Wait for either socket to become readable
+                r, _, _ = select.select([tcp_conn, udp_sock], [], [], 5.0)
+
+                if not r:
+                    continue  # timed out, keep looping
+
+                for s in r:
+                    # Case A: data from the SSH tunnel (TCP) -> forward to WireGuard (UDP)
+                    if s is tcp_conn:
+                        data = recv_framed(tcp_conn)
+                        udp_sock.sendto(data, (wg_host, wg_port))
+
+                    # Case B: response from WireGuard (UDP) -> forward back over the tunnel (TCP)
+                    elif s is udp_sock:
+                        data, _ = udp_sock.recvfrom(65535)
+                        if data:
+                            send_framed(tcp_conn, data)
+
+        except (ConnectionResetError, BrokenPipeError):
+            logging.warning(
+                "Client disconnected or local WireGuard closed; cleaning up and waiting for the next connection..."
+            )
+        except Exception as e:
+            logging.error("Runtime error: %s", e)
+        finally:
+            # Release this connection's resources; the main accept loop keeps running
+            if "tcp_conn" in locals():
+                tcp_conn.close()
+            if "udp_sock" in locals():
+                udp_sock.close()

wg_bridge-1.0.3/src/wg_bridge/state.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+import signal
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+STATE_FILE = Path(tempfile.gettempdir()) / "wg-bridge.json"
+
+
+@dataclass
+class BridgeState:
+    pid: int
+    mode: str  # "server" or "client"
+    wg_host: str | None
+    wg_port: int
+    tcp_port: int
+    log_path: str
+
+
+def write_state(mode: str, wg_port: int, tcp_port: int, log_path: Path, wg_host: str | None = None) -> None:
+    state = BridgeState(
+        pid=os.getpid(),
+        mode=mode,
+        wg_host=wg_host,
+        wg_port=wg_port,
+        tcp_port=tcp_port,
+        log_path=str(log_path),
+    )
+    STATE_FILE.write_text(json.dumps(asdict(state)))
+
+
+def remove_state() -> None:
+    STATE_FILE.unlink(missing_ok=True)
+
+
+def read_state() -> BridgeState | None:
+    try:
+        data = json.loads(STATE_FILE.read_text())
+    except (FileNotFoundError, ValueError):
+        return None
+    try:
+        return BridgeState(**data)
+    except TypeError:
+        return None
+
+
+def describe_binding(mode: str, wg_host: str | None, wg_port: int, tcp_port: int) -> str:
+    if mode == "server":
+        return f"listening on TCP 0.0.0.0:{tcp_port} -> forwarding to UDP {wg_host}:{wg_port}"
+    return f"listening on UDP 127.0.0.1:{wg_port} -> forwarding to TCP 127.0.0.1:{tcp_port}"
+
+
+def process_running(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def stop_running() -> None:
+    state = read_state()
+    if state is None:
+        logging.info("No wg-bridge process is currently tracked on this machine.")
+        return
+
+    if not process_running(state.pid):
+        logging.warning(
+            "State file points to PID %d, but no such process is running. Cleaning up stale state.", state.pid
+        )
+        remove_state()
+        return
+
+    os.kill(state.pid, signal.SIGTERM)
+    remove_state()
+    logging.info("Stopped wg-bridge process (PID %d).", state.pid)
+
+
+def print_status() -> None:
+    state = read_state()
+    if state is None:
+        logging.info("wg-bridge is not running on this machine.")
+        return
+
+    if not process_running(state.pid):
+        logging.warning(
+            "State file points to PID %d, but no such process is running. Cleaning up stale state.", state.pid
+        )
+        remove_state()
+        logging.info("wg-bridge is not running on this machine.")
+        return
+
+    logging.info("wg-bridge is running (PID %d, mode=%s)", state.pid, state.mode)
+    logging.info("%s", describe_binding(state.mode, state.wg_host, state.wg_port, state.tcp_port))
+    logging.info("logs: %s", state.log_path)