websocket-tunnel 0.1.0__tar.gz

websocket_tunnel-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch: # allow manual runs for testing the pipeline
+
+permissions:
+  contents: read
+  # Trusted publishing (OIDC) needs the id-token permission. If you prefer an
+  # API token instead, remove this line, add the PYPI_TOKEN secret and pass it
+  # to the publish step via env: UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}.
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Verify tag matches package version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(uv run python -c 'from websocket_tunnel import __version__; print(__version__)')"
+          if [ "$tag" != "$version" ]; then
+            echo "::error::tag v${tag} does not match package version ${version}"
+            exit 1
+          fi
+          echo "releasing websocket-tunnel ${version}"
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

websocket_tunnel-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.coverage
+dist/
+build/

websocket_tunnel-0.1.0/LICENSE

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

websocket_tunnel-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: websocket-tunnel
+Version: 0.1.0
+Summary: A frp-like intranet penetration tool with WebSocket transport (TCP passthrough).
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: websockets>=14
+Description-Content-Type: text/markdown
+
+# websocket-tunnel
+
+一个类似 frp 的内网穿透工具：Python + uv 实现，传输层使用 WebSocket 多路复用，
+支持任意 TCP 服务（HTTP/HTTPS/SSH/MySQL 等）的字节流透传。构建产物通过
+`uv build` 生成，安装后提供 `wtunnel` CLI，分为 `server` 与 `client` 两种模式。
+
+与 frp 的主要差异：**代理不区分服务端/客户端**。代理条目可以声明在任意节点的
+配置中，监听端（listen）与后端（backend）分别用 `local` / `peer` 指定在哪一侧，
+因此以下四种组合全部支持：
+
+| listen 侧 | backend 侧 | 用途 |
+| --- | --- | --- |
+| server | client | 经典 frp：把内网服务暴露到公网服务器端口 |
+| client | server | 反向：把服务端网络里的服务映射到客户端本地端口 |
+| server | server | 服务端本机端口转发（不占用隧道） |
+| client | client | 客户端本机端口转发（不占用隧道） |
+
+## 安装
+
+要求 Python >= 3.11 与 [uv](https://docs.astral.sh/uv/)。
+
+```bash
+uv sync            # 开发环境（含测试依赖）
+uv build           # 构建 sdist + wheel
+uv run wtunnel --version
+```
+
+也可以把 wheel 安装到任意环境：
+
+```bash
+uv pip install dist/websocket_tunnel-0.1.0-py3-none-any.whl
+wtunnel --version
+```
+
+## 快速开始
+
+### 1. 启动服务端
+
+```bash
+wtunnel server -c examples/server.toml
+```
+
+### 2. 启动客户端
+
+```bash
+wtunnel client -c examples/client.toml
+```
+
+客户端默认把本机 `127.0.0.1:3000` 暴露到服务端的 `0.0.0.0:8080`，访问
+`http://<server>:8080` 即可到达客户端内网的服务。
+
+## CLI 参数
+
+```text
+wtunnel server -c server.toml [--listen HOST:PORT] [--token TOKEN]
+                       [--tls-cert PATH --tls-key PATH] [-v]
+wtunnel client -c client.toml [--server HOST:PORT] [--token TOKEN]
+                       [--tls] [--tls-skip-verify] [-v]
+```
+
+CLI 参数覆盖配置文件中的同名项；`-v` 输出 DEBUG 日志。
+
+## 配置参考
+
+`server.toml`：
+
+```toml
+listen = "0.0.0.0:7000"          # 控制端口（ws/wss）
+token = "secret"                 # 可选，共享认证 token
+tls = { cert = "server.crt", key = "server.key" }   # 可选，启用 wss
+
+[[proxies]]
+name = "web"
+listen = "0.0.0.0:8080"
+listen_side = "local"            # "local" | "peer"
+backend = "127.0.0.1:3000"
+backend_side = "peer"
+```
+
+`client.toml`：
+
+```toml
+server = "127.0.0.1:7000"        # 服务端地址
+token = "secret"
+tls = false                      # true 时使用 wss
+tls_skip_verify = false          # 自签证书时设为 true
+
+[[proxies]]
+name = "web"
+listen = "0.0.0.0:8080"
+listen_side = "peer"
+backend = "127.0.0.1:3000"
+backend_side = "local"
+```
+
+`listen` / `backend` 均为 `host:port`，IPv6 使用 `[::1]:8080` 形式。backend 可以
+指向任意可达地址（含内网 IP 的外部服务端口），不限于 localhost。
+
+## 传输与协议概要
+
+- 每对节点一条 WebSocket 长连接（client 主动连接 server），控制消息与所有数据流
+  在其上多路复用；每条 TCP 流分配独立 stream id。
+- 二进制帧：首字节为消息类型；控制消息为 JSON，数据帧为
+  `stream_id`(4 字节大端) + 数据块（默认 32 KiB）。
+- 支持半关闭：任一方向 EOF 只关闭对应方向，保证 HTTP/1.0 与 keep-alive 响应完整。
+- 握手时校验共享 token（失败即断开）；服务端可选 wss，客户端可跳过证书校验。
+- client 断线自动重连（指数退避 1s→30s），重连后双方重新注册代理并重新绑定监听。
+
+## 开发与测试
+
+```bash
+uv run pytest          # 单元 + 集成测试
+uv build               # 构建发布产物
+```
+
+## 发布到 PyPI
+
+打上 `v` 开头的 tag 并推送即触发 GitHub Actions 发布：
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+工作流（`.github/workflows/release.yml`）会校验 tag 与包版本一致、运行测试、
+`uv build` 构建后通过 trusted publishing（OIDC）发布到 PyPI。首次使用前需要在
+PyPI 项目页配置 Trusted Publisher：仓库 `8DE4732A/websocket-tunnel`、
+工作流名 `Publish to PyPI`。若改用 API token，删除 workflow 中 `id-token: write`
+权限，并配置 `PYPI_TOKEN` secret 传给 `uv publish`。
+
+## 安全说明
+
+共享 token 即信任边界：持有 token 的 client 可以请求服务端绑定任意监听端口。
+公网部署请务必启用 wss（或搭配其他加密隧道）并妥善保管 token。v1 暂不提供
+mTLS、证书固定与配置热加载。

websocket_tunnel-0.1.0/README.md

@@ -0,0 +1,135 @@
+# websocket-tunnel
+
+一个类似 frp 的内网穿透工具：Python + uv 实现，传输层使用 WebSocket 多路复用，
+支持任意 TCP 服务（HTTP/HTTPS/SSH/MySQL 等）的字节流透传。构建产物通过
+`uv build` 生成，安装后提供 `wtunnel` CLI，分为 `server` 与 `client` 两种模式。
+
+与 frp 的主要差异：**代理不区分服务端/客户端**。代理条目可以声明在任意节点的
+配置中，监听端（listen）与后端（backend）分别用 `local` / `peer` 指定在哪一侧，
+因此以下四种组合全部支持：
+
+| listen 侧 | backend 侧 | 用途 |
+| --- | --- | --- |
+| server | client | 经典 frp：把内网服务暴露到公网服务器端口 |
+| client | server | 反向：把服务端网络里的服务映射到客户端本地端口 |
+| server | server | 服务端本机端口转发（不占用隧道） |
+| client | client | 客户端本机端口转发（不占用隧道） |
+
+## 安装
+
+要求 Python >= 3.11 与 [uv](https://docs.astral.sh/uv/)。
+
+```bash
+uv sync            # 开发环境（含测试依赖）
+uv build           # 构建 sdist + wheel
+uv run wtunnel --version
+```
+
+也可以把 wheel 安装到任意环境：
+
+```bash
+uv pip install dist/websocket_tunnel-0.1.0-py3-none-any.whl
+wtunnel --version
+```
+
+## 快速开始
+
+### 1. 启动服务端
+
+```bash
+wtunnel server -c examples/server.toml
+```
+
+### 2. 启动客户端
+
+```bash
+wtunnel client -c examples/client.toml
+```
+
+客户端默认把本机 `127.0.0.1:3000` 暴露到服务端的 `0.0.0.0:8080`，访问
+`http://<server>:8080` 即可到达客户端内网的服务。
+
+## CLI 参数
+
+```text
+wtunnel server -c server.toml [--listen HOST:PORT] [--token TOKEN]
+                       [--tls-cert PATH --tls-key PATH] [-v]
+wtunnel client -c client.toml [--server HOST:PORT] [--token TOKEN]
+                       [--tls] [--tls-skip-verify] [-v]
+```
+
+CLI 参数覆盖配置文件中的同名项；`-v` 输出 DEBUG 日志。
+
+## 配置参考
+
+`server.toml`：
+
+```toml
+listen = "0.0.0.0:7000"          # 控制端口（ws/wss）
+token = "secret"                 # 可选，共享认证 token
+tls = { cert = "server.crt", key = "server.key" }   # 可选，启用 wss
+
+[[proxies]]
+name = "web"
+listen = "0.0.0.0:8080"
+listen_side = "local"            # "local" | "peer"
+backend = "127.0.0.1:3000"
+backend_side = "peer"
+```
+
+`client.toml`：
+
+```toml
+server = "127.0.0.1:7000"        # 服务端地址
+token = "secret"
+tls = false                      # true 时使用 wss
+tls_skip_verify = false          # 自签证书时设为 true
+
+[[proxies]]
+name = "web"
+listen = "0.0.0.0:8080"
+listen_side = "peer"
+backend = "127.0.0.1:3000"
+backend_side = "local"
+```
+
+`listen` / `backend` 均为 `host:port`，IPv6 使用 `[::1]:8080` 形式。backend 可以
+指向任意可达地址（含内网 IP 的外部服务端口），不限于 localhost。
+
+## 传输与协议概要
+
+- 每对节点一条 WebSocket 长连接（client 主动连接 server），控制消息与所有数据流
+  在其上多路复用；每条 TCP 流分配独立 stream id。
+- 二进制帧：首字节为消息类型；控制消息为 JSON，数据帧为
+  `stream_id`(4 字节大端) + 数据块（默认 32 KiB）。
+- 支持半关闭：任一方向 EOF 只关闭对应方向，保证 HTTP/1.0 与 keep-alive 响应完整。
+- 握手时校验共享 token（失败即断开）；服务端可选 wss，客户端可跳过证书校验。
+- client 断线自动重连（指数退避 1s→30s），重连后双方重新注册代理并重新绑定监听。
+
+## 开发与测试
+
+```bash
+uv run pytest          # 单元 + 集成测试
+uv build               # 构建发布产物
+```
+
+## 发布到 PyPI
+
+打上 `v` 开头的 tag 并推送即触发 GitHub Actions 发布：
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+工作流（`.github/workflows/release.yml`）会校验 tag 与包版本一致、运行测试、
+`uv build` 构建后通过 trusted publishing（OIDC）发布到 PyPI。首次使用前需要在
+PyPI 项目页配置 Trusted Publisher：仓库 `8DE4732A/websocket-tunnel`、
+工作流名 `Publish to PyPI`。若改用 API token，删除 workflow 中 `id-token: write`
+权限，并配置 `PYPI_TOKEN` secret 传给 `uv publish`。
+
+## 安全说明
+
+共享 token 即信任边界：持有 token 的 client 可以请求服务端绑定任意监听端口。
+公网部署请务必启用 wss（或搭配其他加密隧道）并妥善保管 token。v1 暂不提供
+mTLS、证书固定与配置热加载。

websocket_tunnel-0.1.0/examples/client.toml

@@ -0,0 +1,28 @@
+# Tunnel client configuration.
+server = "127.0.0.1:7000"
+token = "change-me"
+
+# Use wss transport and skip certificate verification (self-signed certs).
+# tls = true
+# tls_skip_verify = true
+
+# Proxies are declared from the client's point of view: "local" = this node
+# (the client), "peer" = the other node (the tunnel server).
+
+# Classic frp scenario: expose a service on the client's machine at a port
+# on the server (0.0.0.0:8080 here).
+[[proxies]]
+name = "web"
+listen = "0.0.0.0:8080"
+listen_side = "peer"
+backend = "127.0.0.1:3000"
+backend_side = "local"
+
+# Reverse scenario: listen on the client's machine and forward to a service
+# on the server's machine.
+# [[proxies]]
+# name = "db-on-server"
+# listen = "127.0.0.1:3307"
+# listen_side = "local"
+# backend = "127.0.0.1:3306"
+# backend_side = "peer"

websocket_tunnel-0.1.0/examples/server.toml

@@ -0,0 +1,27 @@
+# Tunnel server configuration.
+listen = "0.0.0.0:7000"
+token = "change-me"
+
+# Optional TLS (wss). Uncomment and provide cert/key files to enable.
+# tls = { cert = "server.crt", key = "server.key" }
+
+# The server may also declare proxies. Sides are relative to the declaring
+# node: "local" = this node, "peer" = the other node (the connected client).
+
+# Example: expose a service that runs on the SERVER's machine through the
+# tunnel, listening on the CLIENT's machine at 127.0.0.1:3307.
+[[proxies]]
+name = "mysql-on-server"
+listen = "127.0.0.1:3307"
+listen_side = "peer"
+backend = "127.0.0.1:3306"
+backend_side = "local"
+
+# Example: a classic frp-style forward declared by the server
+# (listener on the server, backend on the client):
+# [[proxies]]
+# name = "web-on-client"
+# listen = "0.0.0.0:8080"
+# listen_side = "local"
+# backend = "127.0.0.1:3000"
+# backend_side = "peer"

websocket_tunnel-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "websocket-tunnel"
+version = "0.1.0"
+description = "A frp-like intranet penetration tool with WebSocket transport (TCP passthrough)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "websockets>=14",
+]
+
+[project.scripts]
+wtunnel = "websocket_tunnel.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/websocket_tunnel"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "trustme>=1.1",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

websocket_tunnel-0.1.0/src/websocket_tunnel/__init__.py

@@ -0,0 +1,3 @@
+"""websocket-tunnel: a frp-like intranet penetration tool over WebSocket."""
+
+__version__ = "0.1.0"

websocket_tunnel-0.1.0/src/websocket_tunnel/cli.py

@@ -0,0 +1,81 @@
+"""Command line interface for wtunnel."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+from . import __version__
+from .client import TunnelClient
+from .config import ConfigError, load_client_config, load_server_config
+from .server import TunnelServer
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="wtunnel",
+        description="WebSocket-based intranet penetration tool (frp-like).",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    server = subparsers.add_parser("server", help="run the tunnel server")
+    server.add_argument("-c", "--config", type=Path, required=True, help="path to server TOML config")
+    server.add_argument("--listen", metavar="HOST:PORT", help="override listen address")
+    server.add_argument("--token", help="override shared auth token")
+    server.add_argument("--tls-cert", metavar="PATH", help="override TLS certificate path")
+    server.add_argument("--tls-key", metavar="PATH", help="override TLS private key path")
+    server.add_argument("-v", "--verbose", action="count", default=0, help="increase log verbosity (repeatable)")
+
+    client = subparsers.add_parser("client", help="run the tunnel client")
+    client.add_argument("-c", "--config", type=Path, required=True, help="path to client TOML config")
+    client.add_argument("--server", metavar="HOST:PORT", help="override tunnel server address")
+    client.add_argument("--token", help="override shared auth token")
+    client.add_argument("--tls", action="store_true", default=None, help="override: use wss transport")
+    client.add_argument(
+        "--tls-skip-verify",
+        action="store_true",
+        default=None,
+        help="override: skip TLS certificate verification",
+    )
+    client.add_argument("-v", "--verbose", action="count", default=0, help="increase log verbosity (repeatable)")
+    return parser
+
+
+def _setup_logging(verbosity: int) -> None:
+    level = logging.DEBUG if verbosity else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s %(levelname)-7s %(name)s: %(message)s",
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    _setup_logging(args.verbose)
+    try:
+        if args.command == "server":
+            config = load_server_config(
+                args.config,
+                listen=args.listen,
+                token=args.token,
+                tls_cert=args.tls_cert,
+                tls_key=args.tls_key,
+            )
+            return asyncio.run(TunnelServer(config).run())
+        config = load_client_config(
+            args.config,
+            server=args.server,
+            token=args.token,
+            tls=args.tls,
+            tls_skip_verify=args.tls_skip_verify,
+        )
+        return asyncio.run(TunnelClient(config).run())
+    except ConfigError as exc:
+        print(f"wtunnel: configuration error: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 0

websocket_tunnel-0.1.0/src/websocket_tunnel/client.py

@@ -0,0 +1,115 @@
+"""Tunnel client: connects to a tunnel server and reconnects on failure."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import ssl
+
+import websockets
+from websockets.asyncio.client import connect
+
+from .config import ClientConfig, split_host_port
+from .protocol import MAX_CONTROL_SIZE
+from .session import Session
+
+CONNECT_TIMEOUT = 15.0
+RECONNECT_BASE = 1.0
+RECONNECT_MAX = 30.0
+RECONNECT_AFTER_SESSION = 1.0
+
+
+def _ws_url(host: str, port: int, secure: bool) -> str:
+    if ":" in host and not host.startswith("["):
+        host = f"[{host}]"
+    scheme = "wss" if secure else "ws"
+    return f"{scheme}://{host}:{port}/"
+
+
+class TunnelClient:
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config
+        self._log = logging.getLogger("wtunnel.client")
+        self._session: Session | None = None
+        self._stopping = False
+        self._stop_wait = asyncio.Event()
+        self.ready_event = asyncio.Event()
+
+    async def run(self) -> None:
+        backoff = RECONNECT_BASE
+        while not self._stopping:
+            try:
+                ws = await asyncio.wait_for(self._connect(), CONNECT_TIMEOUT)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                self._log.warning(
+                    "connect to %s failed: %s; retrying in %.1fs", self._config.server, exc, backoff
+                )
+                await self._sleep_until_stop_or(backoff)
+                backoff = min(backoff * 2, RECONNECT_MAX)
+                continue
+            backoff = RECONNECT_BASE
+            self.ready_event = asyncio.Event()
+            session = Session(
+                ws,
+                role="client",
+                own_name="client",
+                own_proxies=self._config.proxies,
+                token=self._config.token,
+                ready_event=self.ready_event,
+                logger=self._log,
+            )
+            self._session = session
+            try:
+                await session.run()
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                self._log.warning("session failed: %s", exc)
+            finally:
+                self._session = None
+                try:
+                    await ws.close()
+                except Exception:
+                    pass
+            if self._stopping:
+                break
+            self._log.info("session ended; reconnecting in %.1fs", RECONNECT_AFTER_SESSION)
+            await self._sleep_until_stop_or(RECONNECT_AFTER_SESSION)
+
+    async def _connect(self) -> websockets.asyncio.client.ClientConnection:
+        ssl_context = self._build_ssl()
+        host, port = split_host_port(self._config.server)
+        uri = _ws_url(host, port, ssl_context is not None)
+        return await connect(
+            uri,
+            ssl=ssl_context,
+            max_size=MAX_CONTROL_SIZE,
+            ping_interval=20,
+            ping_timeout=20,
+            close_timeout=1,
+            compression=None,
+        )
+
+    def _build_ssl(self) -> ssl.SSLContext | None:
+        if not self._config.tls:
+            return None
+        context = ssl.create_default_context()
+        if self._config.tls_skip_verify:
+            context.check_hostname = False
+            context.verify_mode = ssl.CERT_NONE
+        return context
+
+    async def _sleep_until_stop_or(self, seconds: float) -> None:
+        try:
+            await asyncio.wait_for(self._stop_wait.wait(), timeout=seconds)
+        except asyncio.TimeoutError:
+            pass
+
+    async def stop(self) -> None:
+        self._stopping = True
+        self._stop_wait.set()
+        session = self._session
+        if session is not None:
+            await session.close()