suxitunnel 0.1.1__tar.gz → 0.1.3__tar.gz

{suxitunnel-0.1.1 → suxitunnel-0.1.3}/.gitignore

@@ -48,3 +48,7 @@ build/
 
 # Local cloudflared downloads
 .cloudflare-tunnel/
+cloudflared
+cloudflared.exe
+
+.claude/settings.local.json

{suxitunnel-0.1.1 → suxitunnel-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: suxitunnel
-Version: 0.1.1
+Version: 0.1.3
 Summary: A simple Python library to expose local servers using Cloudflare Tunnel
 Project-URL: Homepage, https://github.com/sadwx/suxitunnel
 Project-URL: Repository, https://github.com/sadwx/suxitunnel
@@ -35,6 +35,21 @@ pip install suxitunnel
 
 ## Quick Start
 
+### Command Line
+
+```bash
+# Expose local port 8000 (random URL)
+suxitunnel --port 8000
+
+# Or use short form
+suxitunnel -p 8000
+
+# Use a named tunnel with dedicated URL (requires Cloudflare account)
+suxitunnel --port 8000 --tunnel-token YOUR_TOKEN
+```
+
+### Python API
+
 ```python
 from suxitunnel import Tunnel
 
@@ -57,6 +72,8 @@ That's it! No configuration, no authentication, no manual setup.
 - 🌍 **Global CDN** - Fast access from anywhere in the world
 - 📦 **Auto-install** - Automatically downloads cloudflared if needed
 - 🐍 **Simple API** - Clean, Pythonic interface
+- 💻 **CLI Support** - Use from command line or as a library
+- 🏷️ **Named Tunnels** - Support for dedicated URLs with tunnel tokens
 
 ## Usage
 
@@ -162,7 +179,31 @@ tunnel = Tunnel(8000, auto_download=False)
 
 ## API Reference
 
-### `Tunnel(port, host="localhost", cloudflared_path=None, auto_download=True)`
+### Command Line Interface
+
+```bash
+suxitunnel [-h] -p PORT [--tunnel-token TUNNEL_TOKEN] [--local-https]
+```
+
+**Arguments:**
+- `-p, --port PORT`: Local port to expose (required)
+- `--tunnel-token TOKEN`: Cloudflare tunnel token for named tunnels (optional)
+- `--local-https`: Connect to local server via HTTPS (for self-signed certs)
+- `-h, --help`: Show help message
+
+**Examples:**
+```bash
+# Quick tunnel with random URL
+suxitunnel --port 8000
+
+# Named tunnel with dedicated URL
+suxitunnel --port 8000 --tunnel-token eyJhIjoiNz...
+
+# Local HTTPS server (e.g., .NET Core with HTTPS)
+suxitunnel --port 5001 --local-https
+```
+
+### `Tunnel(port, host="localhost", cloudflared_path=None, auto_download=True, tunnel_token=None, local_https=False)`
 
 Create a tunnel to expose a local port.
 
@@ -171,19 +212,28 @@ Create a tunnel to expose a local port.
 - `host` (str): Local hostname (default: "localhost")
 - `cloudflared_path` (str): Path to cloudflared binary (auto-detected if None)
 - `auto_download` (bool): Auto-download cloudflared if not found (default: True)
+- `tunnel_token` (str): Cloudflare tunnel token for named tunnels (optional)
+- `local_https` (bool): Set to True if local server uses HTTPS (default: False)
 
 **Attributes:**
 - `url` (str): Public HTTPS URL for the tunnel
 - `port` (int): Local port being exposed
 - `host` (str): Local hostname
+- `tunnel_token` (str): Tunnel token if using named tunnel
 - `is_alive()` (bool): Check if tunnel is running
 - `close()`: Close the tunnel
 
 **Example:**
 ```python
+# Quick tunnel (random URL)
 tunnel = Tunnel(8000)
 print(tunnel.url)  # https://abc123.trycloudflare.com
 tunnel.close()
+
+# Named tunnel (dedicated URL)
+tunnel = Tunnel(8000, tunnel_token="your-token")
+print(tunnel.url)  # https://your-configured-domain.com
+tunnel.close()
 ```
 
 ### `open_tunnel(port, host="localhost")`
@@ -216,7 +266,7 @@ Your App (localhost:8000) → cloudflared → Cloudflare Edge → Internet
 
 ### Cloudflared Binary
 
-The library automatically downloads the `cloudflared` binary on first use if it's not already installed. The binary is saved to `~/.cloudflare-tunnel/`.
+The library automatically downloads the `cloudflared` binary on first use if it's not already installed. The binary is saved to the library's installation directory.
 
 Supported platforms:
 - Linux (x64, ARM64)
@@ -237,12 +287,18 @@ Supported platforms:
 
 ## Limitations
 
-1. **Random URLs**: Each tunnel gets a random `*.trycloudflare.com` URL (no custom domains)
+**Quick Tunnels (default):**
+1. **Random URLs**: Each tunnel gets a random `*.trycloudflare.com` URL
 2. **Temporary**: Tunnels are meant for development/testing, not production
 3. **No persistence**: URL changes each time you create a new tunnel
 4. **Rate limits**: Subject to Cloudflare's fair use policy
 
-For production use with custom domains, see the full [cloudflared documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
+**Named Tunnels (with `--tunnel-token`):**
+- Requires a free Cloudflare account
+- Provides persistent, dedicated URLs
+- Better suited for staging/production environments
+
+For setting up named tunnels, see the [Cloudflare Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
 
 ## Security Considerations
 

{suxitunnel-0.1.1 → suxitunnel-0.1.3}/README.md

@@ -12,6 +12,21 @@ pip install suxitunnel
 
 ## Quick Start
 
+### Command Line
+
+```bash
+# Expose local port 8000 (random URL)
+suxitunnel --port 8000
+
+# Or use short form
+suxitunnel -p 8000
+
+# Use a named tunnel with dedicated URL (requires Cloudflare account)
+suxitunnel --port 8000 --tunnel-token YOUR_TOKEN
+```
+
+### Python API
+
 ```python
 from suxitunnel import Tunnel
 
@@ -34,6 +49,8 @@ That's it! No configuration, no authentication, no manual setup.
 - 🌍 **Global CDN** - Fast access from anywhere in the world
 - 📦 **Auto-install** - Automatically downloads cloudflared if needed
 - 🐍 **Simple API** - Clean, Pythonic interface
+- 💻 **CLI Support** - Use from command line or as a library
+- 🏷️ **Named Tunnels** - Support for dedicated URLs with tunnel tokens
 
 ## Usage
 
@@ -139,7 +156,31 @@ tunnel = Tunnel(8000, auto_download=False)
 
 ## API Reference
 
-### `Tunnel(port, host="localhost", cloudflared_path=None, auto_download=True)`
+### Command Line Interface
+
+```bash
+suxitunnel [-h] -p PORT [--tunnel-token TUNNEL_TOKEN] [--local-https]
+```
+
+**Arguments:**
+- `-p, --port PORT`: Local port to expose (required)
+- `--tunnel-token TOKEN`: Cloudflare tunnel token for named tunnels (optional)
+- `--local-https`: Connect to local server via HTTPS (for self-signed certs)
+- `-h, --help`: Show help message
+
+**Examples:**
+```bash
+# Quick tunnel with random URL
+suxitunnel --port 8000
+
+# Named tunnel with dedicated URL
+suxitunnel --port 8000 --tunnel-token eyJhIjoiNz...
+
+# Local HTTPS server (e.g., .NET Core with HTTPS)
+suxitunnel --port 5001 --local-https
+```
+
+### `Tunnel(port, host="localhost", cloudflared_path=None, auto_download=True, tunnel_token=None, local_https=False)`
 
 Create a tunnel to expose a local port.
 
@@ -148,19 +189,28 @@ Create a tunnel to expose a local port.
 - `host` (str): Local hostname (default: "localhost")
 - `cloudflared_path` (str): Path to cloudflared binary (auto-detected if None)
 - `auto_download` (bool): Auto-download cloudflared if not found (default: True)
+- `tunnel_token` (str): Cloudflare tunnel token for named tunnels (optional)
+- `local_https` (bool): Set to True if local server uses HTTPS (default: False)
 
 **Attributes:**
 - `url` (str): Public HTTPS URL for the tunnel
 - `port` (int): Local port being exposed
 - `host` (str): Local hostname
+- `tunnel_token` (str): Tunnel token if using named tunnel
 - `is_alive()` (bool): Check if tunnel is running
 - `close()`: Close the tunnel
 
 **Example:**
 ```python
+# Quick tunnel (random URL)
 tunnel = Tunnel(8000)
 print(tunnel.url)  # https://abc123.trycloudflare.com
 tunnel.close()
+
+# Named tunnel (dedicated URL)
+tunnel = Tunnel(8000, tunnel_token="your-token")
+print(tunnel.url)  # https://your-configured-domain.com
+tunnel.close()
 ```
 
 ### `open_tunnel(port, host="localhost")`
@@ -193,7 +243,7 @@ Your App (localhost:8000) → cloudflared → Cloudflare Edge → Internet
 
 ### Cloudflared Binary
 
-The library automatically downloads the `cloudflared` binary on first use if it's not already installed. The binary is saved to `~/.cloudflare-tunnel/`.
+The library automatically downloads the `cloudflared` binary on first use if it's not already installed. The binary is saved to the library's installation directory.
 
 Supported platforms:
 - Linux (x64, ARM64)
@@ -214,12 +264,18 @@ Supported platforms:
 
 ## Limitations
 
-1. **Random URLs**: Each tunnel gets a random `*.trycloudflare.com` URL (no custom domains)
+**Quick Tunnels (default):**
+1. **Random URLs**: Each tunnel gets a random `*.trycloudflare.com` URL
 2. **Temporary**: Tunnels are meant for development/testing, not production
 3. **No persistence**: URL changes each time you create a new tunnel
 4. **Rate limits**: Subject to Cloudflare's fair use policy
 
-For production use with custom domains, see the full [cloudflared documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
+**Named Tunnels (with `--tunnel-token`):**
+- Requires a free Cloudflare account
+- Provides persistent, dedicated URLs
+- Better suited for staging/production environments
+
+For setting up named tunnels, see the [Cloudflare Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
 
 ## Security Considerations
 

{suxitunnel-0.1.1 → suxitunnel-0.1.3}/__init__.py

@@ -3,7 +3,7 @@ suxitunnel
 A simple Python library to expose local servers using Cloudflare Tunnel
 """
 
-from .suxitunnel import Tunnel, TunnelError, open_tunnel
+from suxitunnel import Tunnel, TunnelError, open_tunnel
 
 __version__ = "0.1.0"
 __all__ = ["Tunnel", "TunnelError", "open_tunnel"]

{suxitunnel-0.1.1 → suxitunnel-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "suxitunnel"
-version = "0.1.1"
+version = "0.1.3"
 description = "A simple Python library to expose local servers using Cloudflare Tunnel"
 readme = "README.md"
 license = "MIT"
@@ -22,6 +22,9 @@ dependencies = [
     "requests>=2.32.0",
 ]
 
+[project.scripts]
+suxitunnel = "suxitunnel:main"
+
 [project.urls]
 Homepage = "https://github.com/sadwx/suxitunnel"
 Repository = "https://github.com/sadwx/suxitunnel"
@@ -47,5 +50,9 @@ include = [
 [dependency-groups]
 dev = [
     "build>=1.4.0",
+    "fastapi>=0.128.0",
+    "flask>=3.1.2",
+    "pytest>=9.0.2",
     "twine>=6.2.0",
+    "uvicorn>=0.40.0",
 ]

{suxitunnel-0.1.1 → suxitunnel-0.1.3}/suxitunnel.py

@@ -51,19 +51,25 @@ class Tunnel:
         port: int,
         host: str = "localhost",
         cloudflared_path: Optional[str] = None,
-        auto_download: bool = True
+        auto_download: bool = True,
+        tunnel_token: Optional[str] = None,
+        local_https: bool = False
     ):
         """
         Create a tunnel to expose a local port.
-        
+
         Args:
             port: Local port to expose (e.g., 8000)
             host: Local host (default: "localhost")
             cloudflared_path: Path to cloudflared binary (auto-detected if None)
             auto_download: Automatically download cloudflared if not found
+            tunnel_token: Cloudflare tunnel token for named tunnels (optional)
+            local_https: Set to True if local server uses HTTPS (default: False)
         """
         self.port = port
         self.host = host
+        self.tunnel_token = tunnel_token
+        self.local_https = local_https
         self.url: Optional[str] = None
         self._process: Optional[subprocess.Popen] = None
         self._ready = threading.Event()
@@ -86,8 +92,20 @@ class Tunnel:
         # Start the tunnel
         self._start()
     
+    def _get_library_dir(self) -> Path:
+        """Get the directory where the library is located"""
+        return Path(__file__).parent
+
     def _find_cloudflared(self) -> Optional[str]:
         """Try to find cloudflared in common locations"""
+        system = platform.system().lower()
+        binary_name = "cloudflared.exe" if system == "windows" else "cloudflared"
+
+        # First check the library directory (where downloaded binaries are stored)
+        lib_dir_path = self._get_library_dir() / binary_name
+        if lib_dir_path.exists():
+            return str(lib_dir_path)
+
         # Check if in PATH
         try:
             result = subprocess.run(
@@ -99,29 +117,31 @@ class Tunnel:
                 return "cloudflared"
         except (FileNotFoundError, subprocess.TimeoutExpired):
             pass
-        
+
         # Check common install locations
         possible_paths = [
             "/usr/local/bin/cloudflared",
             "/usr/bin/cloudflared",
             str(Path.home() / "bin" / "cloudflared"),
             str(Path.home() / ".local" / "bin" / "cloudflared"),
+            # Legacy download location
+            str(Path.home() / ".cloudflare-tunnel" / binary_name),
         ]
-        
+
         for path in possible_paths:
             if Path(path).exists():
                 return path
-        
+
         return None
     
     def _download_cloudflared(self) -> str:
         """Download cloudflared binary for the current platform"""
         system = platform.system().lower()
         machine = platform.machine().lower()
-        
+
         # Determine download URL
         base_url = "https://github.com/cloudflare/cloudflared/releases/latest/download"
-        
+
         if system == "darwin":  # macOS
             if "arm" in machine or "aarch64" in machine:
                 filename = "cloudflared-darwin-arm64.tgz"
@@ -136,13 +156,12 @@ class Tunnel:
             filename = "cloudflared-windows-amd64.exe"
         else:
             raise TunnelError(f"Unsupported platform: {system} {machine}")
-        
+
         download_url = f"{base_url}/{filename}"
-        
-        # Download location
-        download_dir = Path.home() / ".cloudflare-tunnel"
-        download_dir.mkdir(parents=True, exist_ok=True)
-        
+
+        # Download to the library directory
+        download_dir = self._get_library_dir()
+
         if filename.endswith(".tgz"):
             archive_path = download_dir / filename
             binary_path = download_dir / "cloudflared"
@@ -150,7 +169,7 @@ class Tunnel:
             binary_path = download_dir / "cloudflared.exe"
         else:
             binary_path = download_dir / "cloudflared"
-        
+
         # Check if already downloaded
         if binary_path.exists():
             return str(binary_path)
@@ -190,14 +209,29 @@ class Tunnel:
     
     def _start(self):
         """Start the cloudflared tunnel"""
-        local_url = f"http://{self.host}:{self.port}"
-        
-        # Use Cloudflare Quick Tunnels (no authentication required!)
-        cmd = [
-            self.cloudflared_path,
-            "tunnel",
-            "--url", local_url
-        ]
+        protocol = "https" if self.local_https else "http"
+        local_url = f"{protocol}://{self.host}:{self.port}"
+
+        if self.tunnel_token:
+            # Named tunnel with token
+            cmd = [
+                self.cloudflared_path,
+                "tunnel",
+                "--url", local_url,
+                "run",
+                "--token", self.tunnel_token
+            ]
+        else:
+            # Quick tunnel (no authentication required)
+            cmd = [
+                self.cloudflared_path,
+                "tunnel",
+                "--url", local_url
+            ]
+
+        # Add --no-tls-verify for local HTTPS servers with self-signed certs
+        if self.local_https:
+            cmd.append("--no-tls-verify")
         
         try:
             self._process = subprocess.Popen(
@@ -278,19 +312,77 @@ class Tunnel:
         return f"<Tunnel port={self.port} url={self.url} status={status}>"
 
 
+def parse_args(args: list[str] | None = None):
+    """Parse command line arguments for the CLI."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="suxitunnel",
+        description="Expose local servers via Cloudflare Tunnel"
+    )
+    parser.add_argument(
+        "-p", "--port",
+        type=int,
+        required=True,
+        help="Local port to expose"
+    )
+    parser.add_argument(
+        "--tunnel-token",
+        type=str,
+        default=None,
+        help="Cloudflare tunnel token for named tunnels (optional)"
+    )
+    parser.add_argument(
+        "--local-https",
+        action="store_true",
+        default=False,
+        help="Use HTTPS to connect to local server (for servers with self-signed certs)"
+    )
+
+    return parser.parse_args(args)
+
+
 def open_tunnel(port: int, host: str = "localhost") -> Tunnel:
     """
     Convenience function to create a tunnel.
-    
+
     Args:
         port: Local port to expose
         host: Local host (default: "localhost")
-    
+
     Returns:
         Tunnel instance
-    
+
     Example:
         tunnel = open_tunnel(8000)
         print(f"Public URL: {tunnel.url}")
     """
     return Tunnel(port=port, host=host)
+
+
+def main(args: list[str] | None = None) -> None:
+    """CLI entry point for suxitunnel."""
+    parsed = parse_args(args)
+
+    tunnel = Tunnel(
+        port=parsed.port,
+        tunnel_token=parsed.tunnel_token,
+        local_https=parsed.local_https
+    )
+
+    print(f"Tunnel URL: {tunnel.url}")
+    print("Press Ctrl+C to stop the tunnel")
+
+    try:
+        while tunnel.is_alive():
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        tunnel.close()
+
+    raise SystemExit(0)
+
+
+if __name__ == "__main__":
+    main()