mytunnelSDK 1.2.0__tar.gz

mytunnelsdk-1.2.0/LICENSE

@@ -0,0 +1,13 @@
+Custom License
+
+You are permitted to use, copy, and modify this software for personal or internal business purposes. 
+
+You are NOT permitted to redistribute, sub-license, or sell this software or any derivatives of this software in any form, whether modified or unmodified, without explicit prior written permission from the author.
+
+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.

mytunnelsdk-1.2.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: mytunnelSDK
+Version: 1.2.0
+Summary: A Python SDK for ...
+Author-email: Bhargav Barman <bhargavbprd@gmail.com>
+License: Custom
+Keywords: sdk,api
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: websocket-client>=1.6.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: license-file
+
+# Tunnel SDK
+
+This is the production-ready Python SDK for the Tunnel Gateway. It allows you to establish secure WebSocket tunnels and seamlessly proxy HTTP traffic to your local development server.
+
+## Features
+
+* **Thread-safe**: Runs in the background without blocking your main application loop. No `asyncio` required!
+* **Header Authentication**: Secures your API key in HTTP headers (`Authorization: Bearer`), preventing exposure in URL logs.
+* **Payload Compression**: Transparent zlib compression for data exchange over WebSocket, boosting bandwidth efficiency and speed.
+* **Connection Pooling**: Optimized HTTP connection pooling with keep-alive limits for high-concurrency dispatching.
+* **Automated Reconnection**: Built-in exponential backoff means you don't have to manually manage network hiccups.
+* **Smart Streaming**: Automatically switches to chunked streaming for large files, keeping memory overhead low.
+* **Context Manager**: Start and stop the tunnel cleanly using `with Tunnel.from_env() as tunnel:`.
+* **Events API**: Listen to hooks like `on_connect`, `on_disconnect`, and `on_error`.
+
+## Quick Start
+
+Create a `.env` file in your root folder:
+```env
+TUNNEL_API_KEY=your-secret-key
+TUNNEL_TARGET_PATH=/api
+TUNNEL_PORT=5000
+```
+
+Run the tunnel:
+```python
+from tunnel_sdk import Tunnel
+
+with Tunnel.from_env() as tunnel:
+    # This blocks until interrupted!
+    tunnel.wait()
+```
+
+When connected, you'll see a success message like:
+```
+============================================================
+TUNNEL CONNECTED SUCCESSFULLY!
+Public URL : https://your-gateway.com/api
+Forwarding to : http://127.0.0.1:5000
+============================================================
+```
+
+## SDK Information
+
+The SDK provides an API to access current connection statistics and configuration info:
+
+```python
+from tunnel_sdk import Tunnel
+
+with Tunnel.from_env() as tunnel:
+    # Print SDK info as a dictionary
+    print(tunnel.sd.info())
+    
+    tunnel.wait()
+```
+
+The dictionary returned by `tunnel.sd.info()` contains information like:
+* `sdk_version`: The SDK version.
+* `protocol_version`: The protocol version.
+* `is_connected`: Whether the tunnel is currently connected.
+* `uptime`: The time in seconds the tunnel has been running.
+* `reconnect_count`: The number of times the tunnel has reconnected.
+* `statistics`: A dictionary containing stats like requests handled, bytes uploaded/downloaded, and active requests.
+
+## Structure
+
+* `client.py` - The main `Tunnel` interface.
+* `connection.py` - WebSocket loop and reconnect logic.
+* `dispatcher.py` - HTTP request proxying via `httpx`.
+* `protocol.py` - Data structures and base64 encoders.
+* `config.py` - Environment loader.
+
+For full API reference, see `docs/sdk_reference.md` in the project root.

mytunnelsdk-1.2.0/README.md

@@ -0,0 +1,73 @@
+# Tunnel SDK
+
+This is the production-ready Python SDK for the Tunnel Gateway. It allows you to establish secure WebSocket tunnels and seamlessly proxy HTTP traffic to your local development server.
+
+## Features
+
+* **Thread-safe**: Runs in the background without blocking your main application loop. No `asyncio` required!
+* **Header Authentication**: Secures your API key in HTTP headers (`Authorization: Bearer`), preventing exposure in URL logs.
+* **Payload Compression**: Transparent zlib compression for data exchange over WebSocket, boosting bandwidth efficiency and speed.
+* **Connection Pooling**: Optimized HTTP connection pooling with keep-alive limits for high-concurrency dispatching.
+* **Automated Reconnection**: Built-in exponential backoff means you don't have to manually manage network hiccups.
+* **Smart Streaming**: Automatically switches to chunked streaming for large files, keeping memory overhead low.
+* **Context Manager**: Start and stop the tunnel cleanly using `with Tunnel.from_env() as tunnel:`.
+* **Events API**: Listen to hooks like `on_connect`, `on_disconnect`, and `on_error`.
+
+## Quick Start
+
+Create a `.env` file in your root folder:
+```env
+TUNNEL_API_KEY=your-secret-key
+TUNNEL_TARGET_PATH=/api
+TUNNEL_PORT=5000
+```
+
+Run the tunnel:
+```python
+from tunnel_sdk import Tunnel
+
+with Tunnel.from_env() as tunnel:
+    # This blocks until interrupted!
+    tunnel.wait()
+```
+
+When connected, you'll see a success message like:
+```
+============================================================
+TUNNEL CONNECTED SUCCESSFULLY!
+Public URL : https://your-gateway.com/api
+Forwarding to : http://127.0.0.1:5000
+============================================================
+```
+
+## SDK Information
+
+The SDK provides an API to access current connection statistics and configuration info:
+
+```python
+from tunnel_sdk import Tunnel
+
+with Tunnel.from_env() as tunnel:
+    # Print SDK info as a dictionary
+    print(tunnel.sd.info())
+    
+    tunnel.wait()
+```
+
+The dictionary returned by `tunnel.sd.info()` contains information like:
+* `sdk_version`: The SDK version.
+* `protocol_version`: The protocol version.
+* `is_connected`: Whether the tunnel is currently connected.
+* `uptime`: The time in seconds the tunnel has been running.
+* `reconnect_count`: The number of times the tunnel has reconnected.
+* `statistics`: A dictionary containing stats like requests handled, bytes uploaded/downloaded, and active requests.
+
+## Structure
+
+* `client.py` - The main `Tunnel` interface.
+* `connection.py` - WebSocket loop and reconnect logic.
+* `dispatcher.py` - HTTP request proxying via `httpx`.
+* `protocol.py` - Data structures and base64 encoders.
+* `config.py` - Environment loader.
+
+For full API reference, see `docs/sdk_reference.md` in the project root.

mytunnelsdk-1.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mytunnelSDK"
+version = "1.2.0"
+description = "A Python SDK for ..."
+readme = "README.md"
+requires-python = ">=3.9"
+
+authors = [
+    { name = "Bhargav Barman", email = "bhargavbprd@gmail.com" }
+]
+
+license = { text = "Custom" }
+
+dependencies = [
+    "requests>=2.31.0",
+    "httpx>=0.24.0",
+    "websocket-client>=1.6.0",
+    "python-dotenv>=1.0.0",
+]
+
+keywords = [
+    "sdk",
+    "api",
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

mytunnelsdk-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mytunnelsdk-1.2.0/src/mytunnelSDK.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: mytunnelSDK
+Version: 1.2.0
+Summary: A Python SDK for ...
+Author-email: Bhargav Barman <bhargavbprd@gmail.com>
+License: Custom
+Keywords: sdk,api
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: websocket-client>=1.6.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: license-file
+
+# Tunnel SDK
+
+This is the production-ready Python SDK for the Tunnel Gateway. It allows you to establish secure WebSocket tunnels and seamlessly proxy HTTP traffic to your local development server.
+
+## Features
+
+* **Thread-safe**: Runs in the background without blocking your main application loop. No `asyncio` required!
+* **Header Authentication**: Secures your API key in HTTP headers (`Authorization: Bearer`), preventing exposure in URL logs.
+* **Payload Compression**: Transparent zlib compression for data exchange over WebSocket, boosting bandwidth efficiency and speed.
+* **Connection Pooling**: Optimized HTTP connection pooling with keep-alive limits for high-concurrency dispatching.
+* **Automated Reconnection**: Built-in exponential backoff means you don't have to manually manage network hiccups.
+* **Smart Streaming**: Automatically switches to chunked streaming for large files, keeping memory overhead low.
+* **Context Manager**: Start and stop the tunnel cleanly using `with Tunnel.from_env() as tunnel:`.
+* **Events API**: Listen to hooks like `on_connect`, `on_disconnect`, and `on_error`.
+
+## Quick Start
+
+Create a `.env` file in your root folder:
+```env
+TUNNEL_API_KEY=your-secret-key
+TUNNEL_TARGET_PATH=/api
+TUNNEL_PORT=5000
+```
+
+Run the tunnel:
+```python
+from tunnel_sdk import Tunnel
+
+with Tunnel.from_env() as tunnel:
+    # This blocks until interrupted!
+    tunnel.wait()
+```
+
+When connected, you'll see a success message like:
+```
+============================================================
+TUNNEL CONNECTED SUCCESSFULLY!
+Public URL : https://your-gateway.com/api
+Forwarding to : http://127.0.0.1:5000
+============================================================
+```
+
+## SDK Information
+
+The SDK provides an API to access current connection statistics and configuration info:
+
+```python
+from tunnel_sdk import Tunnel
+
+with Tunnel.from_env() as tunnel:
+    # Print SDK info as a dictionary
+    print(tunnel.sd.info())
+    
+    tunnel.wait()
+```
+
+The dictionary returned by `tunnel.sd.info()` contains information like:
+* `sdk_version`: The SDK version.
+* `protocol_version`: The protocol version.
+* `is_connected`: Whether the tunnel is currently connected.
+* `uptime`: The time in seconds the tunnel has been running.
+* `reconnect_count`: The number of times the tunnel has reconnected.
+* `statistics`: A dictionary containing stats like requests handled, bytes uploaded/downloaded, and active requests.
+
+## Structure
+
+* `client.py` - The main `Tunnel` interface.
+* `connection.py` - WebSocket loop and reconnect logic.
+* `dispatcher.py` - HTTP request proxying via `httpx`.
+* `protocol.py` - Data structures and base64 encoders.
+* `config.py` - Environment loader.
+
+For full API reference, see `docs/sdk_reference.md` in the project root.

mytunnelsdk-1.2.0/src/mytunnelSDK.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/mytunnelSDK.egg-info/PKG-INFO
+src/mytunnelSDK.egg-info/SOURCES.txt
+src/mytunnelSDK.egg-info/dependency_links.txt
+src/mytunnelSDK.egg-info/requires.txt
+src/mytunnelSDK.egg-info/top_level.txt
+src/tunnel_sdk/__init__.py
+src/tunnel_sdk/client.py
+src/tunnel_sdk/config.py
+src/tunnel_sdk/connection.py
+src/tunnel_sdk/dispatcher.py
+src/tunnel_sdk/events.py
+src/tunnel_sdk/exceptions.py
+src/tunnel_sdk/protocol.py
+src/tunnel_sdk/stats.py

mytunnelsdk-1.2.0/src/mytunnelSDK.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mytunnelsdk-1.2.0/src/mytunnelSDK.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.31.0
+httpx>=0.24.0
+websocket-client>=1.6.0
+python-dotenv>=1.0.0

mytunnelsdk-1.2.0/src/mytunnelSDK.egg-info/top_level.txt

@@ -0,0 +1 @@
+tunnel_sdk

mytunnelsdk-1.2.0/src/tunnel_sdk/__init__.py

@@ -0,0 +1,23 @@
+"""
+Tunnel Gateway Python SDK
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A production-quality Python SDK for the Tunnel Gateway.
+"""
+
+from mysdk.src.tunnel_sdk.client import Tunnel
+from mysdk.src.tunnel_sdk.config import TunnelConfig
+from mysdk.src.tunnel_sdk.exceptions import (
+    TunnelError, AuthenticationError, ConnectionError,
+    ProtocolError, TimeoutError
+)
+
+__all__ = [
+    "Tunnel",
+    "TunnelConfig",
+    "TunnelError",
+    "AuthenticationError",
+    "ConnectionError",
+    "ProtocolError",
+    "TimeoutError"
+]

mytunnelsdk-1.2.0/src/tunnel_sdk/client.py

@@ -0,0 +1,201 @@
+"""
+The main Tunnel client class for the SDK.
+"""
+import threading
+import time
+import logging
+import os
+from typing import Optional, Callable
+
+from mysdk.src.tunnel_sdk.config import TunnelConfig
+from mysdk.src.tunnel_sdk.stats import TunnelStats
+from mysdk.src.tunnel_sdk.events import EventEmitter
+from mysdk.src.tunnel_sdk.connection import TunnelConnection
+from mysdk.src.tunnel_sdk.dispatcher import RequestDispatcher
+from mysdk.src.tunnel_sdk.protocol import PROTOCOL_VERSION
+
+__version__ = "1.2.0"
+
+logger = logging.getLogger("tunnel_sdk")
+
+class SDKInfo:
+    def __init__(self, tunnel: 'Tunnel'):
+        self._tunnel = tunnel
+        
+    def info(self) -> dict:
+        return {
+            "sdk_version": self._tunnel.sdk_version,
+            "protocol_version": self._tunnel.protocol_version,
+            "gateway_version": self._tunnel.gateway_version,
+            "is_connected": self._tunnel.is_connected,
+            "uptime": self._tunnel.uptime,
+            "reconnect_count": self._tunnel.reconnect_count,
+            "statistics": self._tunnel.statistics,
+        }
+
+class Tunnel:
+    def __init__(self, api_key: str = None, target_path: str = None, gateway: str = None, port: int = None, local_url: str = None, **kwargs):
+        # Support default from env if not provided
+        if gateway is None: gateway = os.environ.get("TUNNEL_GATEWAY", "wss://tunnel-g09n.onrender.com")
+        if api_key is None: api_key = os.environ.get("TUNNEL_API_KEY")
+        if target_path is None: target_path = os.environ.get("TUNNEL_TARGET_PATH")
+        
+        if port is None: port = int(os.environ.get("TUNNEL_PORT", 5000))
+        if local_url is None: local_url = os.environ.get("TUNNEL_LOCAL_URL")
+        
+        if not local_url:
+            local_url = f"http://127.0.0.1:{port}"
+        
+        if not api_key or not target_path:
+            raise ValueError("api_key and target_path must be provided or set in environment variables")
+            
+        self.config = TunnelConfig(
+            api_key=api_key,
+            target_path=target_path,
+            gateway=gateway,
+            local_url=local_url,
+            port=port,
+            **kwargs
+        )
+        self.stats = TunnelStats()
+        self.events = EventEmitter()
+        
+        self._connection = TunnelConnection(self.config, self.stats, self.events)
+        self._dispatcher: Optional[RequestDispatcher] = None
+        self._main_thread: Optional[threading.Thread] = None
+        
+        # To handle graceful shutdown
+        self._is_running = False
+        
+        # SDK Info API
+        self.sd = SDKInfo(self)
+
+    @classmethod
+    def from_env(cls, **kwargs) -> "Tunnel":
+        config = TunnelConfig.from_env()
+        return cls(
+            api_key=config.api_key,
+            target_path=config.target_path,
+            gateway=config.gateway,
+            local_url=config.local_url,
+            port=config.port,
+            **kwargs
+        )
+
+    def on(self, event: str, callback: Callable) -> None:
+        """Register an event callback."""
+        self.events.on(event, callback)
+
+    def off(self, event: str, callback: Callable) -> None:
+        """Unregister an event callback."""
+        self.events.off(event, callback)
+
+    def start(self, port: Optional[int] = None, local_url: Optional[str] = None) -> None:
+        """Starts the tunnel in a background thread."""
+        if self._is_running:
+            return
+            
+        url_to_use = local_url or self.config.local_url
+        if port is not None:
+            url_to_use = f"http://127.0.0.1:{port}"
+            
+        if not url_to_use:
+            raise ValueError("local_url or port must be provided either in Tunnel() or start()")
+            
+        self._is_running = True
+        self._dispatcher = RequestDispatcher(
+            local_url=url_to_use,
+            ws_send_func=self._connection.send,
+            stats=self.stats,
+            events=self.events
+        )
+        self._connection.dispatcher = self._dispatcher
+        
+        self._main_thread = threading.Thread(target=self._connection.start, daemon=True)
+        self._main_thread.start()
+        logger.info("Tunnel background thread started.")
+
+    def run(self, port: Optional[int] = None, local_url: Optional[str] = None) -> None:
+        """Starts the tunnel and blocks the current thread until stopped."""
+        self.start(port=port, local_url=local_url)
+        self.wait()
+
+    def stop(self) -> None:
+        """Stops the tunnel and performs graceful shutdown."""
+        if not self._is_running:
+            return
+            
+        self._is_running = False
+        logger.info("Stopping tunnel...")
+        
+        self._connection.stop()
+        if self._dispatcher:
+            self._dispatcher.shutdown()
+            
+        if self._main_thread and self._main_thread.is_alive():
+            self._main_thread.join(timeout=5.0)
+
+    def restart(self, port: Optional[int] = None, local_url: Optional[str] = None) -> None:
+        """Restarts the tunnel connection."""
+        self.stop()
+        # Wait a moment for resources to clean up
+        time.sleep(1)
+        self.start(port=port, local_url=local_url)
+
+    def wait(self) -> None:
+        """Blocks until the tunnel is stopped."""
+        try:
+            while self._is_running and self._main_thread and self._main_thread.is_alive():
+                time.sleep(1.0)
+        except KeyboardInterrupt:
+            logger.info("Keyboard interrupt received.")
+            self.stop()
+
+    def __enter__(self):
+        self.start()
+        return self
+        
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.stop()
+    
+    # Properties
+    @property
+    def is_connected(self) -> bool:
+        return self._connection.connected
+
+    @property
+    def gateway_version(self) -> Optional[str]:
+        # Would be fetched via admin info or headers, but not required right now
+        return None
+
+    @property
+    def protocol_version(self) -> str:
+        return PROTOCOL_VERSION
+
+    @property
+    def sdk_version(self) -> str:
+        return __version__
+
+    @property
+    def last_error(self) -> Optional[Exception]:
+        return None # Could store the last error caught in connection.py
+
+    @property
+    def reconnect_count(self) -> int:
+        return self.stats.reconnect_count
+
+    @property
+    def uptime(self) -> float:
+        return self.stats.uptime
+
+    @property
+    def statistics(self) -> dict:
+        return {
+            "requests_handled": self.stats.requests_handled,
+            "active_requests": self.stats.active_requests,
+            "bytes_uploaded": self.stats.bytes_uploaded,
+            "bytes_downloaded": self.stats.bytes_downloaded,
+            "reconnect_count": self.stats.reconnect_count,
+            "uptime": self.stats.uptime,
+            "last_heartbeat_latency": self.stats.last_heartbeat_latency,
+        }

mytunnelsdk-1.2.0/src/tunnel_sdk/config.py

@@ -0,0 +1,51 @@
+"""
+Configuration models for the Tunnel SDK.
+"""
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+from dotenv import load_dotenv
+
+@dataclass
+class TunnelConfig:
+    api_key: str
+    target_path: str
+    gateway: str = "wss://tunnel-g09n.onrender.com"
+    local_url: Optional[str] = None
+    port: int = 5000
+    
+    # Optional parameters
+    max_reconnects: int = -1  # -1 for infinite
+    reconnect_base_delay: float = 1.0
+    reconnect_max_delay: float = 60.0
+    ping_timeout: float = 45.0
+    proxy_timeout: float = 30.0
+    
+    @classmethod
+    def from_env(cls) -> "TunnelConfig":
+        """Loads configuration from environment variables (including .env file)."""
+        load_dotenv()  # Load variables from .env if present
+        
+        gateway = os.environ.get("TUNNEL_GATEWAY", "wss://tunnel-g09n.onrender.com")
+        api_key = os.environ.get("TUNNEL_API_KEY")
+        target_path = os.environ.get("TUNNEL_TARGET_PATH")
+        
+        port_str = os.environ.get("TUNNEL_PORT", "5000")
+        port = int(port_str)
+        
+        local_url = os.environ.get("TUNNEL_LOCAL_URL")
+        if not local_url:
+            local_url = f"http://127.0.0.1:{port}"
+        
+        if not api_key:
+            raise ValueError("TUNNEL_API_KEY environment variable is missing")
+        if not target_path:
+            raise ValueError("TUNNEL_TARGET_PATH environment variable is missing")
+            
+        return cls(
+            api_key=api_key,
+            target_path=target_path,
+            gateway=gateway,
+            local_url=local_url,
+            port=port
+        )

mytunnelsdk-1.2.0/src/tunnel_sdk/connection.py

@@ -0,0 +1,201 @@
+"""
+WebSocket connection manager with reconnection logic.
+"""
+import json
+import threading
+import time
+import urllib.parse
+import websocket
+import logging
+from typing import Optional
+
+from mysdk.src.tunnel_sdk.config import TunnelConfig
+from mysdk.src.tunnel_sdk.events import EventEmitter
+from mysdk.src.tunnel_sdk.stats import TunnelStats
+from mysdk.src.tunnel_sdk.protocol import PROTOCOL_VERSION, build_pong, parse_message
+
+class Colors:
+    GREEN = '\033[92m'
+    RED = '\033[91m'
+    YELLOW = '\033[93m'
+    CYAN = '\033[96m'
+    RESET = '\033[0m'
+
+logger = logging.getLogger("tunnel_sdk.connection")
+
+class TunnelConnection:
+    def __init__(self, config: TunnelConfig, stats: TunnelStats, events: EventEmitter):
+        self.config = config
+        self.stats = stats
+        self.events = events
+        self.ws_app: Optional[websocket.WebSocketApp] = None
+        self.ws_thread: Optional[threading.Thread] = None
+        
+        self.dispatcher = None # Injected by client
+        
+        self._stop_event = threading.Event()
+        self._reconnect_lock = threading.Lock()
+        
+        self.connected = False
+        self.last_ping_time = 0.0
+
+    def get_url(self) -> str:
+        params = {
+            "target_path": self.config.target_path,
+            "protocol_version": PROTOCOL_VERSION
+        }
+        query = urllib.parse.urlencode(params)
+        base = self.config.gateway
+        if not base.endswith("/"):
+            base += "/"
+        return f"{base}ws/tunnel?{query}"
+
+    def start(self):
+        self._stop_event.clear()
+        self._connect_loop()
+
+    def _connect_loop(self):
+        attempt = 0
+        while not self._stop_event.is_set():
+            url = self.get_url()
+            
+            if attempt == 0:
+                self._wake_gateway()
+                if self._stop_event.is_set():
+                    break
+                
+            logger.info(f"Connecting to {self.config.gateway} as {self.config.target_path}")
+            
+            if attempt > 0:
+                self.events.emit("on_reconnect_attempt", attempt)
+                self.stats.inc_reconnect()
+            
+            headers = [
+                f"Authorization: Bearer {self.config.api_key}",
+                f"X-API-Key: {self.config.api_key}"
+            ]
+            self.ws_app = websocket.WebSocketApp(
+                url,
+                header=headers,
+                on_open=self._on_open,
+                on_message=self._on_message,
+                on_error=self._on_error,
+                on_close=self._on_close
+            )
+            
+            # This blocks until disconnected
+            self.ws_app.run_forever()
+            
+            if self._stop_event.is_set():
+                break
+                
+            self.connected = False
+            
+            if self.config.max_reconnects != -1 and attempt >= self.config.max_reconnects:
+                self.events.emit("on_reconnect_failed")
+                logger.error("Max reconnects reached. Stopping.")
+                break
+                
+            # Backoff
+            delay = min(self.config.reconnect_base_delay * (2 ** attempt), self.config.reconnect_max_delay)
+            logger.info(f"Reconnecting in {delay} seconds...")
+            attempt += 1
+            time.sleep(delay)
+
+    def _wake_gateway(self):
+        """Sends a proactive HTTP request to wake up the gateway (e.g., if hosted on Render free tier)."""
+        base_url = self.config.gateway.replace("wss://", "https://").replace("ws://", "http://").rstrip("/")
+        if "localhost" in base_url or "127.0.0.1" in base_url or base_url == "https://test":
+            return
+        wake_url = f"{base_url}/wake"
+        
+        print("Checking if Gateway is awake (this may take 30-50s if Render is sleeping)...")
+        try:
+            import httpx
+            with httpx.Client(timeout=10.0) as client:
+                resp = client.get(wake_url)
+                if resp.status_code == 200:
+                    print("Gateway is awake!")
+        except Exception as e:
+            logger.warning(f"Wake probe failed (will try websocket anyway): {e}")
+
+    def stop(self):
+        self._stop_event.set()
+        if self.ws_app:
+            self.ws_app.close()
+            
+    def send(self, data: str):
+        if self.ws_app and self.connected:
+            self.ws_app.send(data)
+
+    def _on_open(self, ws):
+        self.connected = True
+        self.events.emit("on_connect")
+        
+        # Determine the public HTTP URL for user convenience
+        base_url = self.config.gateway.replace("wss://", "https://").replace("ws://", "http://").rstrip("/")
+        public_url = f"{base_url}{self.config.target_path}"
+        local_url = self.config.local_url or "your local server"
+        
+        def print_success():
+            time.sleep(0.5)
+            if self.connected:
+                print(f"\n{Colors.GREEN}" + "="*60)
+                print("🚀 TUNNEL CONNECTED SUCCESSFULLY!")
+                print(f"🌍 Public URL : {Colors.CYAN}{public_url}{Colors.GREEN}")
+                print(f"🏠 Forwarding to : {Colors.CYAN}{local_url}{Colors.GREEN}")
+                print("="*60 + f"{Colors.RESET}\n")
+                logger.info(f"Tunnel connected successfully. Proxying {public_url} -> {local_url}")
+
+        threading.Thread(target=print_success, daemon=True).start()
+
+    def _on_message(self, ws, message):
+        try:
+            msg = parse_message(message)
+        except Exception as e:
+            logger.error(f"Error parsing message: {e}")
+            return
+            
+        mtype = msg.get("type")
+        
+        # Check for immediate connection error frame
+        if "error" in msg:
+            error_msg = msg['error']
+            logger.error(f"Gateway Error: {error_msg}")
+            print(f"\n{Colors.RED}❌ TUNNEL ERROR: {error_msg}{Colors.RESET}\n")
+            self.events.emit("on_error", Exception(error_msg))
+            return
+
+        if mtype == "ping":
+            if self.last_ping_time > 0:
+                latency = time.time() - self.last_ping_time
+                self.stats.set_latency(latency)
+            self.last_ping_time = time.time()
+            self.send(build_pong())
+        
+        elif mtype == "req_single":
+            if self.dispatcher:
+                self.dispatcher.dispatch_single(msg)
+                
+        elif mtype == "req_start":
+            if self.dispatcher:
+                self.dispatcher.dispatch_start(msg)
+                
+        elif mtype == "req_chunk":
+            if self.dispatcher:
+                self.dispatcher.dispatch_chunk(msg)
+                
+        elif mtype == "req_end":
+            if self.dispatcher:
+                self.dispatcher.dispatch_end(msg)
+        else:
+            logger.warning(f"Unknown message type: {mtype}")
+
+    def _on_error(self, ws, error):
+        logger.error(f"WebSocket Error: {error}")
+        self.events.emit("on_error", error)
+
+    def _on_close(self, ws, close_status_code, close_msg):
+        self.connected = False
+        self.events.emit("on_disconnect")
+        logger.info(f"Tunnel disconnected: {close_status_code} - {close_msg}")

mytunnelsdk-1.2.0/src/tunnel_sdk/dispatcher.py

@@ -0,0 +1,188 @@
+"""
+Dispatches incoming WebSocket messages to the local HTTP server.
+"""
+import threading
+import queue
+import time
+import httpx
+import logging
+import urllib.parse
+from typing import Dict, Any, Callable
+
+from mysdk.src.tunnel_sdk.protocol import (
+    decode_base64, decode_payload, build_res_single, build_res_start, 
+    build_res_chunk, build_res_end
+)
+
+logger = logging.getLogger("tunnel_sdk.dispatcher")
+
+class RequestDispatcher:
+    def __init__(self, local_url: str, ws_send_func: Callable[[str], None], stats, events):
+        self.local_url = local_url.rstrip("/")
+        self.ws_send_func = ws_send_func
+        self.stats = stats
+        self.events = events
+        limits = httpx.Limits(max_keepalive_connections=20, max_connections=100)
+        self.http_client = httpx.Client(timeout=None, limits=limits)
+        self.executor = threading.concurrent.futures.ThreadPoolExecutor(max_workers=50) if hasattr(threading, 'concurrent') else None
+        
+        # In Python standard library, ThreadPoolExecutor is in concurrent.futures
+        import concurrent.futures
+        self.executor = concurrent.futures.ThreadPoolExecutor(max_workers=50)
+        
+        # req_id -> Queue for streaming chunks
+        self.streaming_queues: Dict[str, queue.Queue] = {}
+        # req_id -> StopEvent to signal end of stream
+        self.streaming_events: Dict[str, threading.Event] = {}
+
+    def shutdown(self):
+        self.executor.shutdown(wait=False)
+        self.http_client.close()
+
+    def dispatch_single(self, msg: Dict[str, Any]):
+        self.executor.submit(self._handle_single, msg)
+
+    def dispatch_start(self, msg: Dict[str, Any]):
+        req_id = msg["req_id"]
+        q = queue.Queue(maxsize=100)
+        ev = threading.Event()
+        self.streaming_queues[req_id] = q
+        self.streaming_events[req_id] = ev
+        self.executor.submit(self._handle_stream, msg, q, ev)
+
+    def dispatch_chunk(self, msg: Dict[str, Any]):
+        req_id = msg["req_id"]
+        if req_id in self.streaming_queues:
+            self.streaming_queues[req_id].put(
+                decode_payload(msg["data"], compressed=msg.get("compressed", False))
+            )
+
+    def dispatch_end(self, msg: Dict[str, Any]):
+        req_id = msg["req_id"]
+        if req_id in self.streaming_events:
+            self.streaming_events[req_id].set()
+
+    def _build_url(self, subpath: str, query: str) -> str:
+        url = self.local_url + subpath
+        if query:
+            url += "?" + query
+        return url
+
+    def _filter_headers(self, headers: Dict[str, str]) -> Dict[str, str]:
+        # Filter out headers that shouldn't be forwarded to local
+        filtered = {}
+        for k, v in headers.items():
+            k_lower = k.lower()
+            if k_lower not in ("host", "connection", "upgrade"):
+                filtered[k] = v
+        return filtered
+
+    def _handle_single(self, msg: Dict[str, Any]):
+        req_id = msg["req_id"]
+        try:
+            self.stats.inc_active_requests()
+            self.events.emit("on_request_start", req_id)
+            
+            url = self._build_url(msg["subpath"], msg["query"])
+            headers = self._filter_headers(msg.get("headers", {}))
+            body_bytes = decode_payload(msg.get("body", ""), compressed=msg.get("compressed", False)) if msg.get("body") else None
+            
+            if body_bytes:
+                self.stats.add_bytes_downloaded(len(body_bytes))
+
+            for attempt in range(6):
+                try:
+                    resp = self.http_client.request(
+                        method=msg["method"],
+                        url=url,
+                        headers=headers,
+                        content=body_bytes,
+                        follow_redirects=False
+                    )
+                    break
+                except (httpx.HTTPError, OSError) as e:
+                    if attempt == 5:
+                        raise
+                    time.sleep(0.5)
+            
+            resp_body = resp.content
+            self.stats.add_bytes_uploaded(len(resp_body))
+            
+            res_msg = build_res_single(
+                req_id=req_id,
+                status=resp.status_code,
+                headers=dict(resp.headers),
+                body=resp_body
+            )
+            self.ws_send_func(res_msg)
+            
+        except Exception as e:
+            logger.error(f"Error handling single request {req_id}: {e}")
+            res_msg = build_res_single(req_id, 502, {}, str(e).encode('utf-8'))
+            self.ws_send_func(res_msg)
+        finally:
+            self.stats.dec_active_requests()
+            self.events.emit("on_request_end", req_id)
+
+    def _handle_stream(self, msg: Dict[str, Any], q: queue.Queue, ev: threading.Event):
+        req_id = msg["req_id"]
+        try:
+            self.stats.inc_active_requests()
+            self.events.emit("on_request_start", req_id)
+            
+            url = self._build_url(msg["subpath"], msg["query"])
+            headers = self._filter_headers(msg.get("headers", {}))
+
+            def chunk_generator():
+                while True:
+                    try:
+                        chunk = q.get(timeout=0.1)
+                        self.stats.add_bytes_downloaded(len(chunk))
+                        yield chunk
+                    except queue.Empty:
+                        if ev.is_set() and q.empty():
+                            break
+                        continue
+
+            req = self.http_client.build_request(
+                method=msg["method"],
+                url=url,
+                headers=headers,
+                content=chunk_generator()
+            )
+            
+            for attempt in range(6):
+                try:
+                    resp = self.http_client.send(req, stream=True, follow_redirects=False)
+                    break
+                except (httpx.HTTPError, OSError) as e:
+                    if attempt == 5:
+                        raise
+                    time.sleep(0.5)
+            
+            # Send res_start
+            start_msg = build_res_start(
+                req_id=req_id,
+                status=resp.status_code,
+                headers=dict(resp.headers)
+            )
+            self.ws_send_func(start_msg)
+            
+            # Send chunks
+            for chunk in resp.iter_bytes(chunk_size=32768):
+                if chunk:
+                    self.stats.add_bytes_uploaded(len(chunk))
+                    self.ws_send_func(build_res_chunk(req_id, chunk))
+                    
+            # Send res_end
+            self.ws_send_func(build_res_end(req_id))
+            resp.close()
+
+        except Exception as e:
+            logger.error(f"Error handling streaming request {req_id}: {e}")
+            self.ws_send_func(build_res_single(req_id, 502, {}, str(e).encode('utf-8')))
+        finally:
+            self.stats.dec_active_requests()
+            self.events.emit("on_request_end", req_id)
+            self.streaming_queues.pop(req_id, None)
+            self.streaming_events.pop(req_id, None)

mytunnelsdk-1.2.0/src/tunnel_sdk/events.py

@@ -0,0 +1,31 @@
+"""
+Event emitter for SDK callbacks.
+"""
+from typing import Callable, Dict, List, Any
+
+class EventEmitter:
+    def __init__(self):
+        self._listeners: Dict[str, List[Callable]] = {}
+
+    def on(self, event: str, callback: Callable) -> None:
+        """Register a callback for an event."""
+        if event not in self._listeners:
+            self._listeners[event] = []
+        self._listeners[event].append(callback)
+
+    def off(self, event: str, callback: Callable) -> None:
+        """Unregister a callback for an event."""
+        if event in self._listeners:
+            try:
+                self._listeners[event].remove(callback)
+            except ValueError:
+                pass
+
+    def emit(self, event: str, *args: Any, **kwargs: Any) -> None:
+        """Emit an event, calling all registered callbacks synchronously."""
+        for callback in self._listeners.get(event, []):
+            try:
+                callback(*args, **kwargs)
+            except Exception:
+                # User callbacks shouldn't crash the SDK loop
+                pass

mytunnelsdk-1.2.0/src/tunnel_sdk/exceptions.py

@@ -0,0 +1,23 @@
+"""
+Custom exceptions for the Tunnel SDK.
+"""
+
+class TunnelError(Exception):
+    """Base exception for all Tunnel SDK errors."""
+    pass
+
+class AuthenticationError(TunnelError):
+    """Raised when the API key is invalid."""
+    pass
+
+class ConnectionError(TunnelError):
+    """Raised when the WebSocket connection fails or drops unexpectedly."""
+    pass
+
+class ProtocolError(TunnelError):
+    """Raised when the gateway sends malformed or incompatible protocol messages."""
+    pass
+
+class TimeoutError(TunnelError):
+    """Raised when heartbeat or proxy requests time out."""
+    pass

mytunnelsdk-1.2.0/src/tunnel_sdk/protocol.py

@@ -0,0 +1,98 @@
+"""
+Protocol utilities for encoding, decoding, and parsing Tunnel Gateway messages.
+"""
+import base64
+import json
+import zlib
+from typing import Dict, Any, Optional, Tuple
+
+from mysdk.src.tunnel_sdk.exceptions import ProtocolError
+
+PROTOCOL_VERSION = 1.2
+
+def decode_base64(data: str) -> bytes:
+    """Decodes a base64 string to bytes."""
+    try:
+        return base64.b64decode(data)
+    except Exception as e:
+        raise ProtocolError(f"Failed to decode base64 data: {e}")
+
+def encode_base64(data: bytes) -> str:
+    """Encodes bytes to a base64 string."""
+    try:
+        return base64.b64encode(data).decode('ascii')
+    except Exception as e:
+        raise ProtocolError(f"Failed to encode base64 data: {e}")
+
+def encode_payload(data: bytes, compress: bool = True) -> Tuple[str, bool]:
+    """Encode raw bytes to a base64 string, optionally compressing with zlib if beneficial."""
+    if not data:
+        return "", False
+    if compress and len(data) >= 64:
+        try:
+            compressed = zlib.compress(data)
+            if len(compressed) < len(data):
+                return encode_base64(compressed), True
+        except Exception:
+            pass
+    return encode_base64(data), False
+
+def decode_payload(data: str, compressed: bool = False) -> bytes:
+    """Decode a base64 string back to raw bytes, decompressing if compressed."""
+    if not data:
+        return b""
+    raw = decode_base64(data)
+    if compressed:
+        try:
+            return zlib.decompress(raw)
+        except Exception as e:
+            raise ProtocolError(f"Failed to decompress payload: {e}") from e
+    return raw
+
+def parse_message(raw_msg: str) -> Dict[str, Any]:
+    """Parses a raw WebSocket message string into a JSON dictionary."""
+    try:
+        return json.loads(raw_msg)
+    except json.JSONDecodeError as e:
+        raise ProtocolError(f"Invalid JSON in message: {e}")
+
+def build_pong() -> str:
+    return json.dumps({"type": "pong"})
+
+def build_res_single(req_id: str, status: int, headers: Dict[str, str], body: bytes) -> str:
+    encoded_body, compressed = encode_payload(body, compress=True)
+    payload = {
+        "type": "res_single",
+        "req_id": req_id,
+        "status": status,
+        "headers": headers,
+        "body": encoded_body
+    }
+    if compressed:
+        payload["compressed"] = True
+    return json.dumps(payload)
+
+def build_res_start(req_id: str, status: int, headers: Dict[str, str]) -> str:
+    return json.dumps({
+        "type": "res_start",
+        "req_id": req_id,
+        "status": status,
+        "headers": headers
+    })
+
+def build_res_chunk(req_id: str, chunk: bytes) -> str:
+    encoded_data, compressed = encode_payload(chunk, compress=True)
+    payload = {
+        "type": "res_chunk",
+        "req_id": req_id,
+        "data": encoded_data
+    }
+    if compressed:
+        payload["compressed"] = True
+    return json.dumps(payload)
+
+def build_res_end(req_id: str) -> str:
+    return json.dumps({
+        "type": "res_end",
+        "req_id": req_id
+    })

mytunnelsdk-1.2.0/src/tunnel_sdk/stats.py

@@ -0,0 +1,45 @@
+"""
+Thread-safe statistics tracking.
+"""
+import threading
+import time
+
+class TunnelStats:
+    def __init__(self):
+        self._lock = threading.Lock()
+        self.requests_handled = 0
+        self.active_requests = 0
+        self.bytes_uploaded = 0
+        self.bytes_downloaded = 0
+        self.reconnect_count = 0
+        self.start_time = time.time()
+        self.last_heartbeat_latency = 0.0
+        
+    @property
+    def uptime(self) -> float:
+        return time.time() - self.start_time
+
+    def inc_active_requests(self):
+        with self._lock:
+            self.active_requests += 1
+
+    def dec_active_requests(self):
+        with self._lock:
+            self.active_requests = max(0, self.active_requests - 1)
+            self.requests_handled += 1
+
+    def add_bytes_uploaded(self, count: int):
+        with self._lock:
+            self.bytes_uploaded += count
+            
+    def add_bytes_downloaded(self, count: int):
+        with self._lock:
+            self.bytes_downloaded += count
+            
+    def inc_reconnect(self):
+        with self._lock:
+            self.reconnect_count += 1
+            
+    def set_latency(self, latency: float):
+        with self._lock:
+            self.last_heartbeat_latency = latency