lange-python 0.3.17__tar.gz → 0.3.19__tar.gz

{lange_python-0.3.17 → lange_python-0.3.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lange-python
-Version: 0.3.17
+Version: 0.3.19
 Summary: A bundeld set of tools, clients for the lange-suite of tools and more.
 Author: contact@robertlange.me
 Requires-Python: >=3.10
@@ -89,3 +89,7 @@ tunnel.stop()
 Tunnel clients also expose a `status` property with one of:
 `"unauthenticated"`, `"off"`, `"pending"`, `"connected"`, or `"failed"`.
 
+The worker connects to `/api/v1/tunnels/worker`, consumes the
+`worker_connected` welcome payload, forwards HTTP bodies as base64-encoded
+bytes, and supports websocket relay sessions through the same control socket.
+

{lange_python-0.3.17 → lange_python-0.3.19}/README.md

@@ -70,3 +70,7 @@ tunnel.stop()
 
 Tunnel clients also expose a `status` property with one of:
 `"unauthenticated"`, `"off"`, `"pending"`, `"connected"`, or `"failed"`.
+
+The worker connects to `/api/v1/tunnels/worker`, consumes the
+`worker_connected` welcome payload, forwards HTTP bodies as base64-encoded
+bytes, and supports websocket relay sessions through the same control socket.

lange_python-0.3.19/lange/tunnel/_client.py

@@ -0,0 +1,685 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import ssl
+import threading
+from typing import Any, Optional
+from urllib.parse import urljoin, urlparse, urlunparse
+
+import httpx
+import websockets
+from httpx import Timeout
+
+from .._util import BaseLangeLabsClient
+from .._util._base_client import _UNSET_API_KEY
+from ._util import _filter_hop_by_hop_headers
+
+logger = logging.getLogger("lange.tunnel")
+HEARTBEAT_INTERVAL_SECONDS = 10.0
+
+
+class Tunnel(BaseLangeLabsClient):
+    """Thread-based tunnel worker client."""
+
+    def __init__(
+        self,
+        host: str = "wss://tunnel.lange-labs.com",
+        api_key: str | None = None,
+        target: str = "http://localhost:80",
+        verify_ssl: bool = True,
+        max_retries: int = 5,
+        retry_delay: float = 5.0,
+        open_timeout: float = 20.0,
+        daemon: bool = True,
+    ) -> None:
+        """Initialize one tunnel worker client."""
+        super().__init__(api_key=api_key, daemon=daemon, host=host)
+        self.target = target.rstrip("/")
+        self.verify_ssl = verify_ssl
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self.open_timeout = open_timeout
+
+        self._max_retry_delay = 60.0
+        self._stop_event = threading.Event()
+        self._reconnect_event = threading.Event()
+        self._connected = False
+        self._remote_address: Optional[str] = None
+        self._remote_address_roundrobin: Optional[str] = None
+        self._worker_index = -1
+        self._pool_size = 0
+        self._reconnect_count = 0
+        self._worker_id: Optional[str] = None
+        self._instance_id: Optional[str] = None
+        self._tunnel_id: Optional[str] = None
+        self._tunnel_name: Optional[str] = None
+        self._max_workers: int = -1
+        self._can_consume_tunnels = False
+        self._lock = threading.Lock()
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._active_ws: Any = None
+        self._ws_sessions: dict[str, Any] = {}
+        self._ws_reader_tasks: dict[str, asyncio.Task[None]] = {}
+
+    @property
+    def connected(self) -> bool:
+        """Get current connection state."""
+        with self._lock:
+            return self._connected
+
+    @property
+    def status(self) -> str:
+        """Get the current tunnel lifecycle status."""
+        with self._lock:
+            return self._status
+
+    @property
+    def remote_address(self) -> Optional[str]:
+        """Get worker-specific public address when provided by the server."""
+        with self._lock:
+            return self._remote_address
+
+    @property
+    def remote_address_roundrobin(self) -> Optional[str]:
+        """Get round-robin public address when provided by the server."""
+        with self._lock:
+            return self._remote_address_roundrobin
+
+    @property
+    def worker_index(self) -> int:
+        """Get current worker index from the latest welcome payload."""
+        with self._lock:
+            return self._worker_index
+
+    @property
+    def pool_size(self) -> int:
+        """Get current worker pool size from the latest welcome payload."""
+        with self._lock:
+            return self._pool_size
+
+    @property
+    def reconnect_count(self) -> int:
+        """Get number of reconnect attempts after the last successful connection."""
+        with self._lock:
+            return self._reconnect_count
+
+    @property
+    def worker_id(self) -> Optional[str]:
+        """Get the worker identifier assigned by the server."""
+        with self._lock:
+            return self._worker_id
+
+    @property
+    def instance_id(self) -> Optional[str]:
+        """Get the API instance identifier from the welcome payload."""
+        with self._lock:
+            return self._instance_id
+
+    @property
+    def tunnel_name(self) -> Optional[str]:
+        """Get the tunnel name from the welcome payload."""
+        with self._lock:
+            return self._tunnel_name
+
+    @property
+    def max_workers(self) -> int:
+        """Get the configured tunnel worker limit from the welcome payload."""
+        with self._lock:
+            return self._max_workers
+
+    @property
+    def can_consume_tunnels(self) -> bool:
+        """Get the worker tunnel-consumption capability from the welcome payload."""
+        with self._lock:
+            return self._can_consume_tunnels
+
+    def run(self) -> None:
+        """Start the worker loop inside the thread."""
+        asyncio.run(self._run_async())
+
+    def stop(self) -> None:
+        """Request a graceful shutdown."""
+        self._stop_event.set()
+
+    def reconnect(self) -> None:
+        """Force a full reconnect cycle."""
+        self._request_reconnect()
+
+    def reload(self, api_key: str | None | object = _UNSET_API_KEY) -> None:
+        """Reload tunnel authentication and restart the connection flow when running."""
+        super().reload(api_key=api_key)
+        self._set_connected(False)
+
+        if self.is_alive() or self._loop is not None:
+            self._request_reconnect()
+            return
+
+        self._set_status(self._status_for_auth())
+
+    async def _run_async(self) -> None:
+        """Run the worker connection loop with reconnect backoff."""
+        tunnel_url = self._build_tunnel_url()
+        ssl_context = self._build_ssl_context(tunnel_url)
+
+        with self._lock:
+            self._loop = asyncio.get_running_loop()
+
+        current_delay = self.retry_delay
+
+        while not self._stop_event.is_set():
+            if self.api_key is None:
+                self._set_connected(False)
+                self._set_status("unauthenticated")
+                await self._wait_for_reconnect_signal()
+                continue
+
+            self._set_status("pending")
+            headers = self._build_connection_headers()
+
+            try:
+                logger.info("Connecting to %s", tunnel_url)
+                async with websockets.connect(
+                    tunnel_url,
+                    additional_headers=headers,
+                    ssl=ssl_context,
+                    proxy=None,
+                    open_timeout=self.open_timeout,
+                ) as ws:
+                    with self._lock:
+                        self._active_ws = ws
+
+                    current_delay = self.retry_delay
+                    await self._consume_welcome(ws)
+
+                    with self._lock:
+                        self._reconnect_count = 0
+
+                    send_lock = asyncio.Lock()
+                    heartbeat_task = asyncio.create_task(
+                        self._send_heartbeats(ws, send_lock)
+                    )
+                    try:
+                        await self._handle_messages(ws, send_lock)
+                    finally:
+                        heartbeat_task.cancel()
+                        await asyncio.gather(heartbeat_task, return_exceptions=True)
+                        await self._close_all_websocket_sessions()
+                        with self._lock:
+                            self._active_ws = None
+                        self._set_connected(False)
+            except websockets.exceptions.ConnectionClosed as exc:
+                self._set_connected(False)
+                self._set_status("failed")
+                logger.warning("Connection closed: %s", exc)
+            except Exception as exc:  # pragma: no cover - network error path
+                self._set_connected(False)
+                self._set_status("failed")
+                logger.error("Connection error: %s", exc)
+            finally:
+                with self._lock:
+                    self._active_ws = None
+
+            if self._stop_event.is_set():
+                break
+
+            if self._reconnect_event.is_set():
+                self._set_connected(False)
+                with self._lock:
+                    self._reconnect_count = 0
+                self._reconnect_event.clear()
+                current_delay = self.retry_delay
+                self._set_status(self._status_for_auth())
+                logger.info("Manual reconnect requested. Reconnecting now.")
+                continue
+
+            with self._lock:
+                self._reconnect_count += 1
+                attempt = self._reconnect_count
+
+            if self.max_retries > 0 and attempt > self.max_retries:
+                self._set_status("failed")
+                logger.error(
+                    "Max reconnection attempts (%s) reached. Giving up.",
+                    self.max_retries,
+                )
+                break
+
+            logger.info("Reconnecting in %.1fs (attempt %s)", current_delay, attempt)
+
+            wait_time = 0.0
+            while (
+                wait_time < current_delay
+                and not self._stop_event.is_set()
+                and not self._reconnect_event.is_set()
+            ):
+                await asyncio.sleep(0.5)
+                wait_time += 0.5
+
+            if self._reconnect_event.is_set():
+                continue
+
+            current_delay = min(current_delay * 2, self._max_retry_delay)
+
+        with self._lock:
+            self._active_ws = None
+            self._loop = None
+            if self._status in {"connected", "pending"}:
+                self._status = self._status_for_auth()
+
+        logger.info("Disconnected from server.")
+
+    async def _consume_welcome(self, ws: Any) -> None:
+        """Read and process the initial welcome message when present."""
+        try:
+            welcome_message = await ws.recv()
+            welcome = json.loads(welcome_message)
+        except Exception:
+            self._set_connected(True)
+            return
+
+        if isinstance(welcome, dict) and welcome.get("type") == "worker_connected":
+            self._set_connected(
+                True,
+                worker_id=str(welcome.get("worker_id") or welcome.get("id") or ""),
+                worker_index=int(welcome.get("worker_index", -1)),
+                instance_id=str(welcome.get("instance_id") or "") or None,
+                tunnel_id=str(welcome.get("tunnel_id") or "") or None,
+                tunnel_name=str(welcome.get("tunnel_name") or "") or None,
+                max_workers=int(welcome.get("max_workers", -1)),
+                can_consume_tunnels=bool(
+                    welcome.get("can_consume_tunnels", False)
+                ),
+            )
+            return
+
+        self._set_connected(True)
+
+    async def _handle_messages(
+        self, ws: Any, send_lock: asyncio.Lock
+    ) -> None:
+        """Handle request and websocket relay messages from the server."""
+        async with httpx.AsyncClient(timeout=Timeout(timeout=15.0)) as http_client:
+            while not self._stop_event.is_set() and not self._reconnect_event.is_set():
+                try:
+                    message = await asyncio.wait_for(ws.recv(), timeout=1.0)
+                except asyncio.TimeoutError:
+                    continue
+                except websockets.exceptions.ConnectionClosed:
+                    break
+
+                try:
+                    payload = json.loads(
+                        message if isinstance(message, str) else message.decode("utf-8")
+                    )
+                    await self._handle_message(ws, http_client, payload, send_lock)
+                except Exception as exc:
+                    logger.error("Error handling message: %s", exc)
+
+    async def _handle_message(
+        self,
+        server_ws: Any,
+        http_client: Any,
+        message: dict[str, Any],
+        send_lock: asyncio.Lock,
+    ) -> None:
+        """Dispatch one incoming server message to the matching handler."""
+        message_type = str(message.get("type", "")).strip().lower()
+        if message_type == "heartbeat_ack":
+            return
+
+        if message_type == "request":
+            response = await self._forward_request(http_client, message)
+            async with send_lock:
+                await server_ws.send(json.dumps(response))
+            return
+
+        if message_type == "ws_open":
+            await self._open_websocket_session(server_ws, message, send_lock)
+            return
+
+        if message_type == "ws_data":
+            await self._forward_websocket_data(message)
+            return
+
+        if message_type == "ws_close":
+            await self._close_websocket_session(message)
+
+    async def _forward_request(
+        self, client: Any, request: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Forward one proxied HTTP request to the configured local target."""
+        request_id = str(request.get("id", ""))
+        method = str(request.get("method", "GET"))
+        path = str(request.get("path", "/"))
+        headers = request.get("headers", {})
+        body_b64 = str(request.get("body", ""))
+
+        body = base64.b64decode(body_b64) if body_b64 else None
+        url = urljoin(f"{self.target}/", path.lstrip("/"))
+        filtered_headers = _filter_hop_by_hop_headers(headers)
+
+        try:
+            response = await client.request(
+                method=method,
+                url=url,
+                headers=filtered_headers,
+                content=body,
+                follow_redirects=True,
+            )
+            return {
+                "type": "response",
+                "tunnel_id": str(request.get("tunnel_id") or self._tunnel_id or ""),
+                "id": request_id,
+                "status": response.status_code,
+                "headers": dict(response.headers.items()),
+                "body": base64.b64encode(response.content).decode("utf-8"),
+                "bodyEncoding": "base64",
+            }
+        except Exception as exc:
+            logger.error("Error forwarding request: %s", exc)
+            error_body = json.dumps({"error": str(exc)}).encode("utf-8")
+            return {
+                "type": "response",
+                "tunnel_id": str(request.get("tunnel_id") or self._tunnel_id or ""),
+                "id": request_id,
+                "status": 502,
+                "headers": {"Content-Type": "application/json"},
+                "body": base64.b64encode(error_body).decode("utf-8"),
+                "bodyEncoding": "base64",
+                "error": str(exc),
+            }
+
+    async def _open_websocket_session(
+        self,
+        server_ws: Any,
+        message: dict[str, Any],
+        send_lock: asyncio.Lock,
+    ) -> None:
+        """Open one websocket connection against the local target service."""
+        session_id = str(message.get("id", "")).strip()
+        if not session_id:
+            return
+
+        target_url = self._build_target_websocket_url(
+            path=str(message.get("path", "/")),
+            query_string=str(message.get("query_string", "") or ""),
+        )
+        headers = _filter_hop_by_hop_headers(message.get("headers", {}))
+
+        try:
+            local_ws = await websockets.connect(
+                target_url,
+                additional_headers=headers,
+                ssl=self._build_ssl_context(target_url),
+                proxy=None,
+                open_timeout=self.open_timeout,
+            )
+        except Exception as exc:
+            async with send_lock:
+                await server_ws.send(
+                    json.dumps(
+                        {
+                            "type": "ws_error",
+                            "tunnel_id": str(
+                                message.get("tunnel_id") or self._tunnel_id or ""
+                            ),
+                            "id": session_id,
+                            "error": str(exc),
+                        }
+                    )
+                )
+            return
+
+        self._ws_sessions[session_id] = local_ws
+        self._ws_reader_tasks[session_id] = asyncio.create_task(
+            self._relay_local_websocket(server_ws, session_id, local_ws, send_lock)
+        )
+        async with send_lock:
+            await server_ws.send(
+                json.dumps(
+                    {
+                        "type": "ws_opened",
+                        "tunnel_id": str(
+                            message.get("tunnel_id") or self._tunnel_id or ""
+                        ),
+                        "id": session_id,
+                    }
+                )
+            )
+
+    async def _forward_websocket_data(self, message: dict[str, Any]) -> None:
+        """Forward one websocket frame from the server to the local target."""
+        session_id = str(message.get("id", "")).strip()
+        local_ws = self._ws_sessions.get(session_id)
+        if local_ws is None:
+            return
+
+        is_binary = bool(message.get("isBinary", False))
+        data = str(message.get("data", ""))
+        if is_binary:
+            await local_ws.send(base64.b64decode(data.encode("ascii")))
+            return
+
+        await local_ws.send(data)
+
+    async def _close_websocket_session(self, message: dict[str, Any]) -> None:
+        """Close one local websocket session at the server's request."""
+        session_id = str(message.get("id", "")).strip()
+        await self._cleanup_websocket_session(
+            session_id=session_id,
+            close_socket=True,
+            code=int(message.get("code") or 1000),
+            reason=str(message.get("reason") or ""),
+        )
+
+    async def _relay_local_websocket(
+        self,
+        server_ws: Any,
+        session_id: str,
+        local_ws: Any,
+        send_lock: asyncio.Lock,
+    ) -> None:
+        """Relay frames from one local websocket back to the server."""
+        try:
+            while True:
+                payload = await local_ws.recv()
+                if isinstance(payload, bytes):
+                    message = {
+                        "type": "ws_data",
+                        "tunnel_id": self._tunnel_id or "",
+                        "id": session_id,
+                        "data": base64.b64encode(payload).decode("ascii"),
+                        "isBinary": True,
+                    }
+                else:
+                    message = {
+                        "type": "ws_data",
+                        "tunnel_id": self._tunnel_id or "",
+                        "id": session_id,
+                        "data": payload,
+                        "isBinary": False,
+                    }
+                async with send_lock:
+                    await server_ws.send(json.dumps(message))
+        except websockets.exceptions.ConnectionClosed as exc:
+            async with send_lock:
+                await server_ws.send(
+                    json.dumps(
+                        {
+                            "type": "ws_close",
+                            "tunnel_id": self._tunnel_id or "",
+                            "id": session_id,
+                            "code": exc.code,
+                            "reason": exc.reason or None,
+                        }
+                    )
+                )
+        except Exception as exc:
+            async with send_lock:
+                await server_ws.send(
+                    json.dumps(
+                        {
+                            "type": "ws_error",
+                            "tunnel_id": self._tunnel_id or "",
+                            "id": session_id,
+                            "error": str(exc),
+                        }
+                    )
+                )
+        finally:
+            await self._cleanup_websocket_session(session_id=session_id)
+
+    async def _cleanup_websocket_session(
+        self,
+        session_id: str,
+        close_socket: bool = False,
+        code: int = 1000,
+        reason: str = "",
+    ) -> None:
+        """Remove one local websocket session and optionally close it."""
+        local_ws = self._ws_sessions.pop(session_id, None)
+        task = self._ws_reader_tasks.pop(session_id, None)
+
+        if close_socket and local_ws is not None:
+            try:
+                await local_ws.close(code=code, reason=reason)
+            except Exception:
+                pass
+
+        current_task = asyncio.current_task()
+        if task is not None and task is not current_task:
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+
+    async def _close_all_websocket_sessions(self) -> None:
+        """Close all tracked local websocket sessions."""
+        for session_id in list(self._ws_sessions):
+            await self._cleanup_websocket_session(session_id, close_socket=True)
+
+    async def _send_heartbeats(self, server_ws: Any, send_lock: asyncio.Lock) -> None:
+        """Send periodic heartbeat messages while the worker socket is active."""
+        while not self._stop_event.is_set() and not self._reconnect_event.is_set():
+            await asyncio.sleep(HEARTBEAT_INTERVAL_SECONDS)
+            if self._tunnel_id is None or self._worker_id is None:
+                continue
+
+            heartbeat = {
+                "type": "heartbeat",
+                "tunnel_id": self._tunnel_id,
+                "id": self._worker_id,
+                "worker_id": self._worker_id,
+            }
+            try:
+                async with send_lock:
+                    await server_ws.send(json.dumps(heartbeat))
+            except websockets.exceptions.ConnectionClosed:
+                return
+
+    def _build_tunnel_url(self) -> str:
+        """Build the worker websocket URL."""
+        return f"{self.host}/api/v1/tunnels/worker"
+
+    def _build_target_websocket_url(self, path: str, query_string: str = "") -> str:
+        """Build the local target websocket URL for one proxied session."""
+        parsed_target = urlparse(self.target)
+        scheme = parsed_target.scheme
+        if scheme == "http":
+            scheme = "ws"
+        elif scheme == "https":
+            scheme = "wss"
+
+        joined_url = urlparse(urljoin(f"{self.target}/", path.lstrip("/")))
+        return urlunparse(
+            (
+                scheme,
+                joined_url.netloc or parsed_target.netloc,
+                joined_url.path,
+                "",
+                query_string,
+                "",
+            )
+        )
+
+    def _set_connected(
+        self,
+        value: bool,
+        remote_address: Optional[str] = None,
+        remote_address_roundrobin: Optional[str] = None,
+        worker_index: int = -1,
+        pool_size: int = 0,
+        worker_id: Optional[str] = None,
+        instance_id: Optional[str] = None,
+        tunnel_id: Optional[str] = None,
+        tunnel_name: Optional[str] = None,
+        max_workers: int = -1,
+        can_consume_tunnels: bool = False,
+    ) -> None:
+        """Update connection state atomically."""
+        with self._lock:
+            self._connected = value
+            self._remote_address = remote_address if value else None
+            self._remote_address_roundrobin = (
+                remote_address_roundrobin if value else None
+            )
+            self._worker_index = worker_index if value else -1
+            self._pool_size = pool_size if value else 0
+            self._worker_id = worker_id if value else None
+            self._instance_id = instance_id if value else None
+            self._tunnel_id = tunnel_id if value else None
+            self._tunnel_name = tunnel_name if value else None
+            self._max_workers = max_workers if value else -1
+            self._can_consume_tunnels = can_consume_tunnels if value else False
+            if value:
+                self._status = "connected"
+            elif self.api_key is None:
+                self._status = "unauthenticated"
+
+    def _set_status(self, status: str) -> None:
+        """Store the current tunnel lifecycle status."""
+        with self._lock:
+            self._status = status
+
+    def _request_reconnect(self) -> None:
+        """Trigger a reconnect cycle and close the active websocket when needed."""
+        self._set_connected(False)
+        with self._lock:
+            self._reconnect_count = 0
+            ws = self._active_ws
+            loop = self._loop
+            self._status = self._status_for_auth()
+        self._reconnect_event.set()
+
+        if ws is not None and loop is not None and loop.is_running():
+            try:
+                future = asyncio.run_coroutine_threadsafe(
+                    ws.close(code=1012, reason="Client reconnect"),
+                    loop,
+                )
+                future.result(timeout=2)
+            except Exception as exc:  # pragma: no cover - best-effort close path
+                logger.debug("Failed to close websocket during reconnect: %s", exc)
+
+    async def _wait_for_reconnect_signal(self) -> None:
+        """Wait until the client is reloaded, stopped, or resumed from an unauthenticated state."""
+        while not self._stop_event.is_set() and not self._reconnect_event.is_set():
+            await asyncio.sleep(0.5)
+
+        if self._reconnect_event.is_set():
+            self._reconnect_event.clear()
+
+    def _build_ssl_context(self, tunnel_url: str) -> Optional[ssl.SSLContext]:
+        """Create an SSL context for secure websocket URLs."""
+        if not tunnel_url.startswith("wss://"):
+            return None
+
+        ssl_context = ssl.create_default_context()
+        ssl_context.set_alpn_protocols(["http/1.1"])
+        if self.verify_ssl:
+            return ssl_context
+
+        ssl_context.check_hostname = False
+        ssl_context.verify_mode = ssl.CERT_NONE
+        return ssl_context

{lange_python-0.3.17 → lange_python-0.3.19}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lange-python"
-version = "0.3.17"
+version = "0.3.19"
 description = "A bundeld set of tools, clients for the lange-suite of tools and more."
 authors = [
     {name = "contact@robertlange.me"}

lange_python-0.3.17/lange/tunnel/_client.py

@@ -1,477 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import base64
-import json
-import logging
-import ssl
-import threading
-from typing import Any, Optional
-from urllib.parse import urljoin
-
-import httpx
-import websockets
-from httpx import Timeout
-from .._util import BaseLangeLabsClient
-from .._util._base_client import _UNSET_API_KEY
-from ._util import _filter_hop_by_hop_headers
-
-logger = logging.getLogger("lange.tunnel")
-
-
-class Tunnel(BaseLangeLabsClient):
-    """
-    Thread-based tunnel worker client.
-
-    Connects to the tunnel runtime WebSocket endpoint and forwards incoming
-    proxy messages to a local HTTP target.
-
-    :param host: Base service URL, e.g. ``wss://example.com``.
-    :param api_key: Bearer token used for worker authentication.
-    :param target: Local HTTP target URL to forward tunnel traffic to.
-    :param verify_ssl: Whether to verify TLS certificates for ``wss://`` hosts.
-    :param max_retries: Maximum reconnect attempts, ``0`` for infinite retries.
-    :param retry_delay: Initial reconnect delay in seconds.
-    :param open_timeout: Timeout in seconds for the WebSocket opening handshake.
-    :param daemon: Whether the worker thread is daemonized.
-    :raises ValueError: If API key is provided but empty.
-    """
-
-    def __init__(
-            self,
-            host: str = "wss://tunnel.lange-labs.com",
-            api_key: str | None = None,
-            target: str = "http://localhost:80",
-            verify_ssl: bool = True,
-            max_retries: int = 5,
-            retry_delay: float = 5.0,
-            open_timeout: float = 20.0,
-            daemon: bool = True,
-    ) -> None:
-        super().__init__(api_key=api_key, daemon=daemon, host=host)
-        self.target = target.rstrip("/")
-        self.verify_ssl = verify_ssl
-        self.max_retries = max_retries
-        self.retry_delay = retry_delay
-        self.open_timeout = open_timeout
-
-        self._max_retry_delay = 60.0
-        self._stop_event = threading.Event()
-        self._reconnect_event = threading.Event()
-        self._connected = False
-        self._remote_address: Optional[str] = None
-        self._remote_address_roundrobin: Optional[str] = None
-        self._worker_index = -1
-        self._pool_size = 0
-        self._reconnect_count = 0
-        self._lock = threading.Lock()
-        self._loop: Optional[asyncio.AbstractEventLoop] = None
-        self._active_ws: Any = None
-
-    @property
-    def connected(self) -> bool:
-        """
-        Get current connection state.
-
-        :returns: ``True`` when a worker socket is currently active.
-        """
-        with self._lock:
-            return self._connected
-
-    @property
-    def status(self) -> str:
-        """
-        Get the current tunnel lifecycle status.
-
-        :returns: Shared client status string.
-        """
-        with self._lock:
-            return self._status
-
-    @property
-    def remote_address(self) -> Optional[str]:
-        """
-        Get worker-specific public address when provided by the server.
-
-        :returns: Worker URL or ``None`` when unavailable.
-        """
-        with self._lock:
-            return self._remote_address
-
-    @property
-    def remote_address_roundrobin(self) -> Optional[str]:
-        """
-        Get round-robin public address when provided by the server.
-
-        :returns: Pool URL or ``None`` when unavailable.
-        """
-        with self._lock:
-            return self._remote_address_roundrobin
-
-    @property
-    def worker_index(self) -> int:
-        """
-        Get current worker index from the latest welcome payload.
-
-        :returns: Worker index, ``-1`` when disconnected.
-        """
-        with self._lock:
-            return self._worker_index
-
-    @property
-    def pool_size(self) -> int:
-        """
-        Get current worker pool size from the latest welcome payload.
-
-        :returns: Worker pool size, ``0`` when disconnected.
-        """
-        with self._lock:
-            return self._pool_size
-
-    @property
-    def reconnect_count(self) -> int:
-        """
-        Get number of reconnect attempts after the last successful connection.
-
-        :returns: Reconnect counter.
-        """
-        with self._lock:
-            return self._reconnect_count
-
-    def run(self) -> None:
-        """
-        Start the worker loop inside the thread.
-
-        :returns: ``None``.
-        """
-        asyncio.run(self._run_async())
-
-    def stop(self) -> None:
-        """
-        Request a graceful shutdown.
-
-        :returns: ``None``.
-        """
-        self._stop_event.set()
-
-    def reconnect(self) -> None:
-        """
-        Force a full reconnect cycle.
-
-        :returns: ``None``.
-        """
-        self._request_reconnect()
-
-    def reload(self, api_key: str | None | object = _UNSET_API_KEY) -> None:
-        """
-        Reload tunnel authentication and restart the connection flow when running.
-
-        :param api_key: Optional replacement API key. Pass ``None`` explicitly to clear authentication.
-        :returns: ``None``.
-        """
-        super().reload(api_key=api_key)
-        self._set_connected(False)
-
-        if self.is_alive() or self._loop is not None:
-            self._request_reconnect()
-            return
-
-        self._set_status(self._status_for_auth())
-
-    async def _run_async(self) -> None:
-        """
-        Run the worker connection loop with reconnect backoff.
-
-        :returns: ``None``.
-        """
-        tunnel_url = self._build_tunnel_url()
-        ssl_context = self._build_ssl_context(tunnel_url)
-
-        with self._lock:
-            self._loop = asyncio.get_running_loop()
-
-        current_delay = self.retry_delay
-
-        while not self._stop_event.is_set():
-            if self.api_key is None:
-                self._set_connected(False)
-                self._set_status("unauthenticated")
-                await self._wait_for_reconnect_signal()
-                continue
-
-            self._set_status("pending")
-            headers = self._build_connection_headers()
-
-            try:
-                logger.info("Connecting to %s", tunnel_url)
-                async with websockets.connect(
-                        tunnel_url,
-                        additional_headers=headers,
-                        ssl=ssl_context,
-                        proxy=None,
-                        open_timeout=self.open_timeout,
-                ) as ws:
-                    with self._lock:
-                        self._active_ws = ws
-
-                    current_delay = self.retry_delay
-                    await self._consume_welcome(ws)
-
-                    with self._lock:
-                        self._reconnect_count = 0
-
-                    try:
-                        await self._handle_messages(ws)
-                    finally:
-                        with self._lock:
-                            self._active_ws = None
-                        self._set_connected(False)
-            except websockets.exceptions.ConnectionClosed as exc:
-                self._set_connected(False)
-                self._set_status("failed")
-                logger.warning("Connection closed: %s", exc)
-            except Exception as exc:  # pragma: no cover - network error path
-                self._set_connected(False)
-                self._set_status("failed")
-                logger.error("Connection error: %s", exc)
-            finally:
-                with self._lock:
-                    self._active_ws = None
-
-            if self._stop_event.is_set():
-                break
-
-            if self._reconnect_event.is_set():
-                self._set_connected(False)
-                with self._lock:
-                    self._reconnect_count = 0
-                self._reconnect_event.clear()
-                current_delay = self.retry_delay
-                self._set_status(self._status_for_auth())
-                logger.info("Manual reconnect requested. Reconnecting now.")
-                continue
-
-            with self._lock:
-                self._reconnect_count += 1
-                attempt = self._reconnect_count
-
-            if self.max_retries > 0 and attempt > self.max_retries:
-                self._set_status("failed")
-                logger.error("Max reconnection attempts (%s) reached. Giving up.", self.max_retries)
-                break
-
-            logger.info("Reconnecting in %.1fs (attempt %s)", current_delay, attempt)
-
-            wait_time = 0.0
-            while (
-                    wait_time < current_delay
-                    and not self._stop_event.is_set()
-                    and not self._reconnect_event.is_set()
-            ):
-                await asyncio.sleep(0.5)
-                wait_time += 0.5
-
-            if self._reconnect_event.is_set():
-                continue
-
-            current_delay = min(current_delay * 2, self._max_retry_delay)
-
-        with self._lock:
-            self._active_ws = None
-            self._loop = None
-            if self._status in {"connected", "pending"}:
-                self._status = self._status_for_auth()
-
-        logger.info("Disconnected from server.")
-
-    async def _consume_welcome(self, ws: Any) -> None:
-        """
-        Read and process the initial welcome message when present.
-
-        :param ws: Active websocket client.
-        :returns: ``None``.
-        """
-        try:
-            welcome_message = await ws.recv()
-            welcome = json.loads(welcome_message)
-        except Exception:
-            self._set_connected(True)
-            return
-
-        if isinstance(welcome, dict) and welcome.get("type") == "welcome":
-            self._set_connected(
-                True,
-                remote_address=str(welcome.get("public_address") or "") or None,
-                remote_address_roundrobin=str(welcome.get("public_address_generic") or "") or None,
-                worker_index=int(welcome.get("worker_index", -1)),
-                pool_size=int(welcome.get("pool_size", 0)),
-            )
-            return
-
-        self._set_connected(True)
-
-    async def _handle_messages(self, ws: Any) -> None:
-        """
-        Handle request/response proxy messages over the worker websocket.
-
-        :param ws: Active websocket client.
-        :returns: ``None``.
-        """
-        async with httpx.AsyncClient(timeout=Timeout(timeout=15.0)) as http_client:
-            while not self._stop_event.is_set() and not self._reconnect_event.is_set():
-                try:
-                    message = await asyncio.wait_for(ws.recv(), timeout=1.0)
-                    request = json.loads(message)
-                    response = await self._forward_request(http_client, request)
-                    await ws.send(json.dumps(response))
-                except asyncio.TimeoutError:
-                    continue
-                except websockets.exceptions.ConnectionClosed:
-                    break
-                except Exception as exc:
-                    logger.error("Error handling message: %s", exc)
-
-    async def _forward_request(self, client: Any, request: dict[str, Any]) -> dict[str, Any]:
-        """
-        Forward a single proxied request to the configured local target.
-
-        :param client: HTTP client supporting ``request``.
-        :param request: Incoming tunnel request payload.
-        :returns: Tunnel response payload.
-        """
-        request_id = str(request.get("id", ""))
-        method = str(request.get("method", "GET"))
-        path = str(request.get("path", "/"))
-        headers = request.get("headers", {})
-        body_b64 = str(request.get("body", ""))
-
-        body = base64.b64decode(body_b64) if body_b64 else None
-
-        url = urljoin(f"{self.target}/", path.lstrip("/"))
-        filtered_headers = _filter_hop_by_hop_headers(headers)
-
-        try:
-            response = await client.request(
-                method=method,
-                url=url,
-                headers=filtered_headers,
-                content=body,
-                follow_redirects=True,
-            )
-            return {
-                "id": request_id,
-                "status": response.status_code,
-                "headers": dict(response.headers.items()),
-                "body": base64.b64encode(response.content).decode("utf-8"),
-            }
-        except Exception as exc:
-            logger.error("Error forwarding request: %s", exc)
-            error_body = json.dumps({"error": str(exc)}).encode("utf-8")
-            return {
-                "id": request_id,
-                "status": 502,
-                "headers": {"Content-Type": "application/json"},
-                "body": base64.b64encode(error_body).decode("utf-8"),
-            }
-
-    def _build_tunnel_url(self) -> str:
-        """
-        Build the worker websocket URL.
-
-        :returns: WebSocket endpoint URL.
-        """
-        return f"{self.host}/api/tunnels/connection"
-
-    def _set_connected(
-            self,
-            value: bool,
-            remote_address: Optional[str] = None,
-            remote_address_roundrobin: Optional[str] = None,
-            worker_index: int = -1,
-            pool_size: int = 0,
-    ) -> None:
-        """
-        Update connection state atomically.
-
-        :param value: New connected state.
-        :param remote_address: Worker URL from welcome message.
-        :param remote_address_roundrobin: Pool URL from welcome message.
-        :param worker_index: Worker index from welcome message.
-        :param pool_size: Pool size from welcome message.
-        :returns: ``None``.
-        """
-        with self._lock:
-            self._connected = value
-            self._remote_address = remote_address if value else None
-            self._remote_address_roundrobin = remote_address_roundrobin if value else None
-            self._worker_index = worker_index if value else -1
-            self._pool_size = pool_size if value else 0
-            if value:
-                self._status = "connected"
-            elif self.api_key is None:
-                self._status = "unauthenticated"
-
-    def _set_status(self, status: str) -> None:
-        """
-        Store the current tunnel lifecycle status.
-
-        :param status: New lifecycle status.
-        :returns: ``None``.
-        """
-        with self._lock:
-            self._status = status
-
-    def _request_reconnect(self) -> None:
-        """
-        Trigger a reconnect cycle and close the active websocket when needed.
-
-        :returns: ``None``.
-        """
-        self._set_connected(False)
-        with self._lock:
-            self._reconnect_count = 0
-            ws = self._active_ws
-            loop = self._loop
-            self._status = self._status_for_auth()
-        self._reconnect_event.set()
-
-        if ws is not None and loop is not None and loop.is_running():
-            try:
-                future = asyncio.run_coroutine_threadsafe(
-                    ws.close(code=1012, reason="Client reconnect"),
-                    loop,
-                )
-                future.result(timeout=2)
-            except Exception as exc:  # pragma: no cover - best-effort close path
-                logger.debug("Failed to close websocket during reconnect: %s", exc)
-
-    async def _wait_for_reconnect_signal(self) -> None:
-        """
-        Wait until the client is reloaded, stopped, or resumed from an unauthenticated state.
-
-        :returns: ``None``.
-        """
-        while not self._stop_event.is_set() and not self._reconnect_event.is_set():
-            await asyncio.sleep(0.5)
-
-        if self._reconnect_event.is_set():
-            self._reconnect_event.clear()
-
-    def _build_ssl_context(self, tunnel_url: str) -> Optional[ssl.SSLContext]:
-        """
-        Create SSL context for secure websocket URLs.
-
-        :param tunnel_url: Resolved websocket URL.
-        :returns: SSL context for ``wss`` or ``None`` for plain ``ws``.
-        """
-        if not tunnel_url.startswith("wss://"):
-            return None
-
-        ssl_context = ssl.create_default_context()
-        ssl_context.set_alpn_protocols(["http/1.1"])
-        if self.verify_ssl:
-            return ssl_context
-
-        ssl_context.check_hostname = False
-        ssl_context.verify_mode = ssl.CERT_NONE
-        return ssl_context