Merge branch 'dev'

Author: linuztx

README.md

@@ -9,7 +9,7 @@
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Monthly Downloads](https://pepy.tech/badge/flaredantic/month)](https://pepy.tech/project/flaredantic)
 
-Flaredantic is a Python library that simplifies the process of creating tunnels to expose your local services to the internet. It supports both Cloudflare and Serveo tunneling services, making it a user-friendly alternative to ngrok, localtunnel, and similar tools.
+Flaredantic is a Python library that simplifies the process of creating tunnels to expose your local services to the internet. It supports Cloudflare, Serveo, and Microsoft Dev Tunnel services, making it a user-friendly alternative to ngrok, localtunnel, and similar tools.
 
 </div>
 
@@ -20,7 +20,7 @@ Flaredantic is a Python library that simplifies the process of creating tunnels
 - 🚀 Easy-to-use Python API
 - 💻 Command-line interface (CLI)
 - 📦 Automatic binary management
-- 🔄 Multiple tunnel providers (Cloudflare, Serveo)
+- 🔄 Multiple tunnel providers (Cloudflare, Serveo, Microsoft Dev Tunnels)
 - 🌐 TCP forwarding support (Serveo)
 - 🎯 Cross-platform support (Windows, macOS, Linux)
 - 📱 Android support via Termux
@@ -39,6 +39,8 @@ While tools like ngrok are great, Flaredantic offers several advantages:
 
 Flaredantic makes it dead simple to use tunnels in your Python projects!
 
+> ⚠️ **Warning:** Exposing local services to the internet can be a security risk. Never expose sensitive or unprotected endpoints. Use at your own risk.
+
 ## 🚀 Installation
 
 ```bash
@@ -60,6 +62,9 @@ flare --port 8080 -v
 # Use Serveo tunnel instead
 flare --port 8080 --tunnel serveo
 
+# Use Microsoft Dev Tunnels
+flare --port 8080 --tunnel microsoft
+
 # TCP forwarding with Serveo
 flare --port 5432 --tcp
 ```
@@ -69,7 +74,7 @@ CLI Options:
 -p, --port     Local port to expose (required)
 -t, --timeout  Tunnel start timeout in seconds (default: 30)
 -v, --verbose  Show detailed progress output
---tunnel       Tunnel provider to use [cloudflare, serveo] (default: cloudflare)
+--tunnel       Tunnel provider to use [cloudflare, serveo, microsoft] (default: cloudflare)
 --tcp          Use Serveo with TCP forwarding (overrides --tunnel)
 ```
 
@@ -101,6 +106,19 @@ with ServeoTunnel(config) as tunnel:
     input("Press Enter to stop the tunnel...")
 ```
 
+#### Basic Usage with Microsoft Dev Tunnels
+
+```python
+from flaredantic import MicrosoftTunnel, MicrosoftConfig
+
+# Create a tunnel using Microsoft Dev Tunnels
+config = MicrosoftConfig(port=8080)
+with MicrosoftTunnel(config) as tunnel:
+    print(f"Your service is available at: {tunnel.tunnel_url}")
+    # Your application code here
+    input("Press Enter to stop the tunnel...")
+```
+
 #### TCP Forwarding with Serveo
 
 ```python
@@ -119,6 +137,7 @@ with ServeoTunnel(config) as tunnel:
 ```python
 from flaredantic import FlareTunnel, FlareConfig
 from flaredantic import ServeoTunnel, ServeoConfig
+from flaredantic import MicrosoftTunnel, MicrosoftConfig
 from pathlib import Path
 
 # Configure Cloudflare tunnel with custom settings
@@ -137,8 +156,18 @@ serveo_config = ServeoConfig(
     verbose=True  # Enable detailed logging
 )
 
+# Configure Microsoft Dev Tunnels with custom settings
+microsoft_config = MicrosoftConfig(
+    port=8080,
+    bin_dir=Path.home() / ".my-tunnels",
+    timeout=60,
+    verbose=True,  # Enable detailed logging
+    tunnel_id="flaredantic",  # Custom tunnel ID
+    device_login=True  # Use device login flow
+)
+
 # Create and start tunnel (choose one)
-with FlareTunnel(cloudflare_config) as tunnel:
+with MicrosoftTunnel(microsoft_config) as tunnel:
     print(f"Access your service at: {tunnel.tunnel_url}")
     input("Press Enter to stop the tunnel...")
 ```
@@ -189,10 +218,23 @@ if __name__ == '__main__':
 | verbose | bool | False | Show detailed progress and debug output |
 | tcp | bool | False | Enable TCP forwarding instead of HTTP |
 
+### Microsoft Dev Tunnels Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| port | int | Required | Local port to expose |
+| bin_dir | Path | ~/.flaredantic | Directory for devtunnel binary |
+| timeout | int | 30 | Tunnel start timeout in seconds |
+| verbose | bool | False | Show detailed progress and debug output |
+| tunnel_id | str | "flaredantic" | Custom tunnel ID |
+| device_login | bool | True | Use device login flow |
+
 ## 📦 Requirements
 
 - **Cloudflare tunnel**: No additional requirements (binary auto-downloaded)
 - **Serveo tunnel**: Requires SSH client to be installed
+- **Microsoft Dev Tunnels**: No additional requirements (binary auto-downloaded)
+  - **Note**: Currently only supports Linux and macOS.
 
 > **❗️Note:** Serveo servers might occasionally be unavailable as they are a free service. Flaredantic automatically detects when Serveo is down and provides a clear error message. Consider using Cloudflare tunnels if you need guaranteed availability.
 
@@ -201,5 +243,6 @@ if __name__ == '__main__':
 For more detailed examples and use cases, check out our examples:
 - [Cloudflare Examples](docs/examples/Cloudflare.md) - HTTP Server, Django, FastAPI, Flask
 - [Serveo Examples](docs/examples/Serveo.md) - HTTP, TCP, SSH forwarding, database access
+- [Microsoft Examples](docs/examples/Microsoft.md) - HTTP Server, Custom Tunnel ID, Device Login
 
----
+---

docs/examples/Microsoft.md

@@ -0,0 +1,182 @@
+# Flaredantic Microsoft Dev Tunnels Examples 📚
+
+This document provides various examples of how to use Flaredantic with Microsoft Dev Tunnelss in different scenarios.
+
+## Basic Examples
+
+### Simple HTTP Server
+```python
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+from flaredantic import MicrosoftTunnel, MicrosoftConfig
+import threading
+import time
+
+# Create a basic HTTP server
+server = HTTPServer(('localhost', 8000), SimpleHTTPRequestHandler)
+server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+server_thread.start()
+
+# Create and start tunnel
+config = MicrosoftConfig(port=8000)
+with MicrosoftTunnel(config) as tunnel:
+    print(f"Server accessible at: {tunnel.tunnel_url}")
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("\nStopping server...")
+```
+
+### Custom Tunnel ID
+You can reuse a specific tunnel ID if available:
+```python
+from flaredantic import MicrosoftTunnel, MicrosoftConfig
+
+config = MicrosoftConfig(
+    port=8080,
+    tunnel_id="my-custom-tunnel-id",
+    verbose=True
+)
+
+with MicrosoftTunnel(config) as tunnel:
+    print(f"Tunnel URL: {tunnel.tunnel_url}")
+    input("Press Enter to stop...")
+```
+
+## Account Management
+
+### Changing Accounts / Logging Out
+If you need to switch accounts or force a re-login, you can manually use the binary that `flaredantic` manages.
+
+The binary is located in `~/.flaredantic/microsoft` (or your custom `bin_dir`).
+
+**To logout:**
+```bash
+# Navigate to the binary directory
+cd ~/.flaredantic/
+
+# Run the logout command
+./devtunnel user logout
+```
+
+After logging out, the next time you run your Python script with `MicrosoftTunnel`, it will prompt you for a new device login.
+
+**To check current login status:**
+```bash
+cd ~/.flaredantic/
+./devtunnel user show
+```
+
+## Advanced Examples
+
+### Device Login Flow
+Microsoft Dev Tunnelss support device login authentication (enabled by default):
+```python
+from flaredantic import MicrosoftTunnel, MicrosoftConfig
+
+config = MicrosoftConfig(
+    port=8080,
+    device_login=True,  # Enable device login flow
+    verbose=True       # Show login code and instructions
+)
+
+# First run will prompt: "Browse to https://github.com/login/device and enter code: XXXX"
+with MicrosoftTunnel(config) as tunnel:
+    print(f"Tunnel URL: {tunnel.tunnel_url}")
+    input("Press Enter to stop...")
+```
+
+### FastAPI Integration
+```python
+import uvicorn
+from fastapi import FastAPI
+from flaredantic import MicrosoftTunnel, MicrosoftConfig
+import threading
+
+app = FastAPI()
+
+@app.get("/")
+def read_root():
+    return {"status": "online", "provider": "Microsoft Dev Tunnels"}
+
+def start_tunnel():
+    config = MicrosoftConfig(port=8000)
+    tunnel = MicrosoftTunnel(config)
+    url = tunnel.start()
+    print(f"FastAPI app available at: {url}")
+    return tunnel
+
+if __name__ == "__main__":
+    # Start tunnel in background
+    tunnel = start_tunnel()
+    
+    try:
+        uvicorn.run(app, host="127.0.0.1", port=8000)
+    finally:
+        tunnel.stop()
+```
+
+### Django Integration
+```python
+import os
+import sys
+import time
+import threading
+from flaredantic import MicrosoftTunnel, MicrosoftConfig
+from django.core.management import execute_from_command_line
+
+def run_tunnel():
+    config = MicrosoftConfig(port=8000)
+    with MicrosoftTunnel(config) as tunnel:
+        print(f"Django site available at: {tunnel.tunnel_url}")
+        # Keep tunnel alive
+        try:
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            pass
+
+if __name__ == "__main__":
+    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mysite.settings')
+    
+    # Start tunnel in background
+    tunnel_thread = threading.Thread(target=run_tunnel, daemon=True)
+    tunnel_thread.start()
+    
+    execute_from_command_line(sys.argv)
+```
+
+## Error Handling Examples
+
+### Connection Retry Logic
+```python
+from flaredantic import MicrosoftTunnel, MicrosoftConfig, TunnelError
+import time
+
+def create_tunnel_with_retry(port: int, max_retries: int = 3):
+    config = MicrosoftConfig(port=port, verbose=True)
+    
+    for attempt in range(max_retries):
+        try:
+            tunnel = MicrosoftTunnel(config)
+            tunnel.start()
+            return tunnel
+        except TunnelError as e:
+            if attempt == max_retries - 1:
+                raise
+            print(f"Attempt {attempt + 1} failed: {e}. Retrying...")
+            time.sleep(2)
+```
+
+## Common Issues and Solutions
+
+### Login Required
+If the tunnel fails to start with login errors:
+1. Ensure `verbose=True` is set to see the login code.
+2. Complete the device login flow at https://github.com/login/device.
+3. The token is cached locally, so subsequent runs won't require login.
+
+### Port Conflicts
+If you see "hosting port" errors:
+- Ensure the local service is running on the specified port.
+- Check if another tunnel is already using the same `tunnel_id`.