synth-ai 0.4.1__py3-none-any.whl → 0.4.4__py3-none-any.whl

synth_ai/sdk/tunnels/__init__.py

@@ -0,0 +1,118 @@
+"""Cloudflare tunnel helpers for exposing local APIs.
+
+This module provides high-level and low-level tunnel management for
+exposing local task apps to the internet via Cloudflare tunnels.
+
+**Recommended:** Use `TunneledLocalAPI` for a clean, one-liner experience:
+
+    from synth_ai.sdk.tunnels import TunneledLocalAPI, TunnelBackend
+
+    # Managed tunnel (stable subdomain, requires API key)
+    tunnel = await TunneledLocalAPI.create(
+        local_port=8001,
+        backend=TunnelBackend.CloudflareManagedTunnel,
+        api_key="sk_live_...",
+        env_api_key="env_key_...",
+        progress=True,  # Print status updates
+    )
+
+    # Quick tunnel (random subdomain, no API key needed)
+    tunnel = await TunneledLocalAPI.create(
+        local_port=8001,
+        backend=TunnelBackend.CloudflareQuickTunnel,
+        progress=True,
+    )
+
+    print(f"Local API exposed at: {tunnel.url}")
+
+    # Use the URL for remote jobs
+    job = PromptLearningJob.from_dict(config, task_app_url=tunnel.url)
+
+    # Clean up when done
+    tunnel.close()
+
+**Low-level:** For more control, use the individual functions:
+
+    from synth_ai.sdk.tunnels import (
+        rotate_tunnel,
+        open_managed_tunnel,
+        track_process,
+        verify_tunnel_dns_resolution,
+    )
+
+    # Get a managed tunnel from backend
+    tunnel = await rotate_tunnel(API_KEY, port=8001, reason="demo")
+
+    # Start cloudflared with the token
+    proc = track_process(open_managed_tunnel(tunnel['tunnel_token']))
+
+    # Verify the tunnel is ready
+    await verify_tunnel_dns_resolution(f"https://{tunnel['hostname']}")
+
+Note:
+    Processes registered with track_process() are automatically cleaned up
+    when Python exits (via atexit). You can also call cleanup_all() manually.
+"""
+
+from __future__ import annotations
+
+# Re-export from cloudflare.py (no wrappers - these are the actual functions)
+from synth_ai.core.integrations.cloudflare import (
+    # Tunnel lifecycle
+    create_tunnel,
+    open_managed_tunnel,
+    open_quick_tunnel,
+    open_quick_tunnel_with_dns_verification,
+    rotate_tunnel,
+    stop_tunnel,
+    # Verification
+    verify_tunnel_dns_resolution,
+    wait_for_health_check,
+    # Installation
+    ensure_cloudflared_installed,
+    get_cloudflared_path,
+    require_cloudflared,
+    # Discovery
+    fetch_managed_tunnels,
+    ManagedTunnelRecord,
+)
+
+# New: process tracking with atexit cleanup
+from synth_ai.sdk.tunnels.cleanup import cleanup_all, track_process, tracked_processes
+
+# New: port management utilities (was private in in_process.py)
+from synth_ai.sdk.tunnels.ports import find_available_port, is_port_available, kill_port
+
+# New: high-level tunnel abstraction
+from synth_ai.sdk.tunnels.tunneled_api import TunneledLocalAPI, TunnelBackend
+
+__all__ = [
+    # High-level (RECOMMENDED)
+    "TunneledLocalAPI",
+    "TunnelBackend",
+    # Tunnel lifecycle
+    "rotate_tunnel",
+    "create_tunnel",
+    "open_managed_tunnel",
+    "open_quick_tunnel",
+    "open_quick_tunnel_with_dns_verification",
+    "stop_tunnel",
+    # Verification
+    "verify_tunnel_dns_resolution",
+    "wait_for_health_check",
+    # Installation
+    "require_cloudflared",
+    "ensure_cloudflared_installed",
+    "get_cloudflared_path",
+    # Discovery
+    "fetch_managed_tunnels",
+    "ManagedTunnelRecord",
+    # Process tracking (NEW)
+    "track_process",
+    "cleanup_all",
+    "tracked_processes",
+    # Port management (NEW - was private)
+    "kill_port",
+    "is_port_available",
+    "find_available_port",
+]

synth_ai/sdk/tunnels/cleanup.py

@@ -0,0 +1,83 @@
+"""Process tracking with automatic atexit cleanup.
+
+This module provides a simple way to track cloudflared processes and ensure
+they are terminated when Python exits (via atexit) or when cleanup_all() is
+called explicitly.
+
+Example:
+    from synth_ai.sdk.tunnels import open_managed_tunnel, track_process
+
+    # Start a cloudflared process and track it
+    proc = track_process(open_managed_tunnel(tunnel_token))
+
+    # Process will be automatically terminated when Python exits
+    # Or you can clean up early:
+    # cleanup_all()
+"""
+
+from __future__ import annotations
+
+import atexit
+import subprocess
+from typing import List
+
+# Global state - tracked processes for cleanup
+_tracked: List[subprocess.Popen] = []
+_cleanup_registered = False
+
+
+def tracked_processes() -> List[subprocess.Popen]:
+    """Return list of currently tracked processes (read-only copy).
+
+    Returns:
+        List of subprocess.Popen objects being tracked
+    """
+    return list(_tracked)
+
+
+def track_process(proc: subprocess.Popen) -> subprocess.Popen:
+    """Track a cloudflared process for automatic cleanup on exit.
+
+    Args:
+        proc: Process returned by open_managed_tunnel() or similar
+
+    Returns:
+        The same process (for chaining)
+
+    Example:
+        from synth_ai.sdk.tunnels import open_managed_tunnel, track_process
+
+        proc = track_process(open_managed_tunnel(token))
+        # proc will be terminated automatically when Python exits
+    """
+    global _cleanup_registered
+    _tracked.append(proc)
+
+    if not _cleanup_registered:
+        atexit.register(cleanup_all)
+        _cleanup_registered = True
+
+    return proc
+
+
+def cleanup_all() -> None:
+    """Stop all tracked cloudflared processes.
+
+    This is called automatically on Python exit via atexit.
+    You can also call it manually to clean up early.
+
+    Processes are terminated gracefully (SIGTERM), with a fallback
+    to SIGKILL if they don't exit within 5 seconds.
+    """
+    for proc in _tracked:
+        try:
+            if proc.poll() is None:  # Still running
+                proc.terminate()
+                try:
+                    proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                    proc.wait()
+        except Exception:
+            pass  # Best effort cleanup
+    _tracked.clear()

synth_ai/sdk/tunnels/ports.py

@@ -0,0 +1,120 @@
+"""Port management utilities.
+
+This module provides utilities for checking port availability and
+killing processes that are using specific ports.
+
+Example:
+    from synth_ai.sdk.tunnels import kill_port, is_port_available, find_available_port
+
+    # Check if port is available
+    if not is_port_available(8001):
+        kill_port(8001)  # Free the port
+
+    # Or find an available port automatically
+    port = find_available_port(8001)
+"""
+
+from __future__ import annotations
+
+import socket
+import subprocess
+import sys
+
+
+def is_port_available(port: int, host: str = "127.0.0.1") -> bool:
+    """Check if a port is available for binding.
+
+    Args:
+        port: Port number to check
+        host: Host to check (default: 127.0.0.1)
+
+    Returns:
+        True if the port is available, False if in use
+    """
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            sock.bind((host, port))
+            return True
+    except OSError:
+        return False
+
+
+def find_available_port(
+    start_port: int, host: str = "127.0.0.1", max_attempts: int = 100
+) -> int:
+    """Find an available port starting from start_port.
+
+    Args:
+        start_port: Port number to start searching from
+        host: Host to check (default: 127.0.0.1)
+        max_attempts: Maximum number of ports to try
+
+    Returns:
+        First available port number
+
+    Raises:
+        RuntimeError: If no available port found within max_attempts
+    """
+    for offset in range(max_attempts):
+        port = start_port + offset
+        if is_port_available(port, host):
+            return port
+    raise RuntimeError(f"No available port found starting from {start_port}")
+
+
+def kill_port(port: int, host: str = "127.0.0.1") -> bool:
+    """Kill any process using the specified port.
+
+    This is a best-effort operation that attempts to free a port by
+    terminating whatever process is using it. Use with caution.
+
+    Args:
+        port: Port number to free
+        host: Host (unused, for API consistency)
+
+    Returns:
+        True if a process was killed, False if port was already free
+
+    Note:
+        This may not work on all systems or require elevated privileges.
+        Prefer using find_available_port() instead when possible.
+    """
+    if is_port_available(port, host):
+        return False  # Already free
+
+    try:
+        if sys.platform == "win32":
+            # Windows: use netstat + taskkill
+            result = subprocess.run(
+                ["netstat", "-ano"], capture_output=True, text=True, check=False
+            )
+            for line in result.stdout.splitlines():
+                if f":{port}" in line and "LISTENING" in line:
+                    parts = line.split()
+                    if len(parts) > 4:
+                        pid = parts[-1]
+                        subprocess.run(
+                            ["taskkill", "/F", "/PID", pid],
+                            capture_output=True,
+                            check=False,
+                        )
+                        return True
+        else:
+            # Unix-like (macOS, Linux): use lsof + kill
+            result = subprocess.run(
+                ["lsof", "-ti", f":{port}"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.stdout.strip():
+                for pid in result.stdout.strip().split():
+                    subprocess.run(
+                        ["kill", "-9", pid], capture_output=True, check=False
+                    )
+                return True
+    except Exception:
+        pass
+
+    return False

synth_ai/sdk/tunnels/tunneled_api.py

@@ -0,0 +1,363 @@
+"""High-level tunnel management for exposing local APIs.
+
+This module provides a clean abstraction for setting up Cloudflare tunnels
+to expose local APIs to the internet.
+
+Example:
+    from synth_ai.sdk.tunnels import TunneledLocalAPI, TunnelBackend
+
+    # Managed tunnel (stable subdomain, requires API key)
+    tunnel = await TunneledLocalAPI.create(
+        local_port=8001,
+        backend=TunnelBackend.CloudflareManagedTunnel,
+        api_key="sk_live_...",
+        env_api_key="env_key_...",
+    )
+
+    # Quick tunnel (random subdomain, no API key needed)
+    tunnel = await TunneledLocalAPI.create(
+        local_port=8001,
+        backend=TunnelBackend.CloudflareQuickTunnel,
+    )
+
+    print(f"Local API exposed at: {tunnel.url}")
+
+    # Use the URL for remote jobs
+    job = PromptLearningJob.from_dict(
+        config_dict={...},
+        task_app_url=tunnel.url,
+    )
+
+    # Clean up when done
+    tunnel.close()
+
+See Also:
+    - `synth_ai.sdk.tunnels`: Lower-level tunnel functions
+    - `synth_ai.core.integrations.cloudflare`: Core tunnel implementation
+"""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+from synth_ai.core.telemetry import log_info
+
+
+class TunnelBackend(str, Enum):
+    """Supported tunnel backends for exposing local APIs.
+
+    Attributes:
+        CloudflareManagedTunnel: Managed tunnel via Synth backend.
+            - Stable subdomains (e.g., task-1234-5678.usesynth.ai)
+            - Requires Synth API key
+            - Associated with your organization
+            - Best for production jobs
+
+        CloudflareQuickTunnel: Anonymous tunnel via trycloudflare.com.
+            - Random subdomains that change each time
+            - No API key required
+            - Not associated with any organization
+            - Best for quick local testing
+    """
+
+    CloudflareManagedTunnel = "cloudflare_managed"
+    CloudflareQuickTunnel = "cloudflare_quick"
+
+
+@dataclass
+class TunneledLocalAPI:
+    """A managed tunnel exposing a local API to the internet.
+
+    This class provides a clean interface for:
+    1. Provisioning a Cloudflare tunnel (managed or quick)
+    2. Starting the cloudflared process
+    3. Verifying DNS resolution and connectivity
+    4. Tracking the process for cleanup
+
+    Use `TunneledLocalAPI.create()` with a `TunnelBackend` to provision a tunnel.
+
+    Attributes:
+        url: Public HTTPS URL for the tunnel (e.g., "https://task-1234-5678.usesynth.ai")
+        hostname: Hostname without protocol (e.g., "task-1234-5678.usesynth.ai")
+        local_port: Local port being tunneled
+        backend: The tunnel backend used (CloudflareManagedTunnel or CloudflareQuickTunnel)
+        process: The cloudflared subprocess (for advanced use)
+
+    Example:
+        >>> from synth_ai.sdk.tunnels import TunneledLocalAPI, TunnelBackend
+        >>> tunnel = await TunneledLocalAPI.create(
+        ...     local_port=8001,
+        ...     backend=TunnelBackend.CloudflareManagedTunnel,
+        ...     api_key="sk_live_...",
+        ...     env_api_key="env_key_...",
+        ... )
+        >>> print(tunnel.url)
+        https://task-1234-5678.usesynth.ai
+        >>> tunnel.close()
+    """
+
+    url: str
+    hostname: str
+    local_port: int
+    backend: TunnelBackend
+    process: Optional[subprocess.Popen] = None
+    tunnel_token: Optional[str] = field(default=None, repr=False)
+    _raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    async def create(
+        cls,
+        local_port: int,
+        backend: TunnelBackend = TunnelBackend.CloudflareManagedTunnel,
+        *,
+        api_key: Optional[str] = None,
+        env_api_key: Optional[str] = None,
+        reason: Optional[str] = None,
+        backend_url: Optional[str] = None,
+        verify_dns: bool = True,
+        progress: bool = False,
+    ) -> "TunneledLocalAPI":
+        """Create a tunnel to expose a local API.
+
+        This is the main entry point for creating tunnels. It handles:
+        1. Requesting a tunnel (from Synth backend for managed, or trycloudflare for quick)
+        2. Starting the cloudflared process
+        3. Waiting for DNS propagation
+        4. Verifying HTTP connectivity
+        5. Registering for automatic cleanup
+
+        Args:
+            local_port: Local port to tunnel (e.g., 8001)
+            backend: Tunnel backend to use. Defaults to CloudflareManagedTunnel.
+                - CloudflareManagedTunnel: Stable subdomain, requires api_key
+                - CloudflareQuickTunnel: Random subdomain, no api_key needed
+            api_key: Synth API key for authentication (required for managed tunnels)
+            env_api_key: API key for the local task app (for health checks).
+                Defaults to ENVIRONMENT_API_KEY env var.
+            reason: Optional reason for creating tunnel (for logging, managed only)
+            backend_url: Optional backend URL (defaults to production, managed only)
+            verify_dns: Whether to verify DNS resolution after creating tunnel.
+                Set to False if you're sure DNS will work (e.g., reusing subdomain).
+            progress: If True, print status updates during setup
+
+        Returns:
+            TunneledLocalAPI instance with .url, .hostname, .close(), etc.
+
+        Raises:
+            ValueError: If api_key is missing for managed tunnels
+            RuntimeError: If tunnel creation or verification fails
+
+        Example:
+            >>> # Managed tunnel (stable subdomain)
+            >>> tunnel = await TunneledLocalAPI.create(
+            ...     local_port=8001,
+            ...     backend=TunnelBackend.CloudflareManagedTunnel,
+            ...     api_key="sk_live_...",
+            ...     progress=True,
+            ... )
+            Provisioning managed tunnel for port 8001...
+            Starting cloudflared...
+            Tunnel ready: https://task-1234-5678.usesynth.ai
+
+            >>> # Quick tunnel (random subdomain)
+            >>> tunnel = await TunneledLocalAPI.create(
+            ...     local_port=8001,
+            ...     backend=TunnelBackend.CloudflareQuickTunnel,
+            ...     progress=True,
+            ... )
+            Starting quick tunnel for port 8001...
+            Tunnel ready: https://random-words.trycloudflare.com
+        """
+        import os
+
+        from .cleanup import track_process
+
+        # Resolve env_api_key from environment if not provided
+        if env_api_key is None:
+            env_api_key = os.environ.get("ENVIRONMENT_API_KEY")
+
+        if backend == TunnelBackend.CloudflareManagedTunnel:
+            return await cls._create_managed(
+                local_port=local_port,
+                api_key=api_key,
+                env_api_key=env_api_key,
+                reason=reason,
+                backend_url=backend_url,
+                verify_dns=verify_dns,
+                progress=progress,
+                track_process=track_process,
+            )
+        elif backend == TunnelBackend.CloudflareQuickTunnel:
+            return await cls._create_quick(
+                local_port=local_port,
+                env_api_key=env_api_key,
+                progress=progress,
+                track_process=track_process,
+            )
+        else:
+            raise ValueError(f"Unsupported tunnel backend: {backend}")
+
+    @classmethod
+    async def _create_managed(
+        cls,
+        local_port: int,
+        api_key: Optional[str],
+        env_api_key: Optional[str],
+        reason: Optional[str],
+        backend_url: Optional[str],
+        verify_dns: bool,
+        progress: bool,
+        track_process,
+    ) -> "TunneledLocalAPI":
+        """Internal: Create a managed tunnel via Synth backend."""
+        from synth_ai.core.integrations.cloudflare import (
+            open_managed_tunnel_with_connection_wait,
+            rotate_tunnel,
+            verify_tunnel_dns_resolution,
+        )
+
+        if not api_key:
+            raise ValueError(
+                "api_key is required for CloudflareManagedTunnel. "
+                "Use CloudflareQuickTunnel for anonymous tunnels."
+            )
+
+        # Step 1: Provision tunnel from backend
+        if progress:
+            print(f"Provisioning managed tunnel for port {local_port}...")
+
+        tunnel_data = await rotate_tunnel(
+            api_key,
+            local_port,
+            reason=reason,
+            backend_url=backend_url,
+        )
+
+        hostname = tunnel_data["hostname"]
+        tunnel_token = tunnel_data["tunnel_token"]
+        url = f"https://{hostname}"
+
+        log_info(
+            "TunneledLocalAPI.create: managed tunnel provisioned",
+            ctx={"hostname": hostname, "local_port": local_port},
+        )
+
+        # Step 2: Start cloudflared and WAIT for it to connect
+        # This is critical - DNS only resolves after cloudflared connects to Cloudflare's edge
+        if progress:
+            print(f"Starting cloudflared for {hostname}...")
+            print("Waiting for cloudflared to connect to Cloudflare edge...")
+
+        proc = await open_managed_tunnel_with_connection_wait(
+            tunnel_token,
+            timeout_seconds=30.0,
+        )
+        track_process(proc)
+
+        log_info(
+            "TunneledLocalAPI.create: cloudflared connected",
+            ctx={"hostname": hostname},
+        )
+
+        # Step 3: Verify DNS resolution and connectivity (if requested)
+        # DNS should now resolve quickly since cloudflared is connected
+        if verify_dns:
+            dns_verified = tunnel_data.get("dns_verified", False)
+            if not dns_verified:
+                if progress:
+                    print("Verifying DNS propagation...")
+
+                await verify_tunnel_dns_resolution(
+                    url,
+                    name="tunnel",
+                    timeout_seconds=60.0,  # Reduced from 90s since cloudflared is already connected
+                    api_key=env_api_key,
+                )
+
+        if progress:
+            print(f"Tunnel ready: {url}")
+
+        return cls(
+            url=url,
+            hostname=hostname,
+            local_port=local_port,
+            backend=TunnelBackend.CloudflareManagedTunnel,
+            process=proc,
+            tunnel_token=tunnel_token,
+            _raw=tunnel_data,
+        )
+
+    @classmethod
+    async def _create_quick(
+        cls,
+        local_port: int,
+        env_api_key: Optional[str],
+        progress: bool,
+        track_process,
+    ) -> "TunneledLocalAPI":
+        """Internal: Create a quick (anonymous) tunnel via trycloudflare.com."""
+        from synth_ai.core.integrations.cloudflare import (
+            open_quick_tunnel_with_dns_verification,
+        )
+
+        if progress:
+            print(f"Starting quick tunnel for port {local_port}...")
+
+        url, proc = await open_quick_tunnel_with_dns_verification(
+            port=local_port,
+            api_key=env_api_key,
+        )
+
+        track_process(proc)
+
+        # Extract hostname from URL
+        hostname = url.replace("https://", "").replace("http://", "").rstrip("/")
+
+        log_info(
+            "TunneledLocalAPI.create: quick tunnel ready",
+            ctx={"hostname": hostname, "local_port": local_port},
+        )
+
+        if progress:
+            print(f"Tunnel ready: {url}")
+
+        return cls(
+            url=url,
+            hostname=hostname,
+            local_port=local_port,
+            backend=TunnelBackend.CloudflareQuickTunnel,
+            process=proc,
+            tunnel_token=None,
+            _raw={},
+        )
+
+    def close(self) -> None:
+        """Close the tunnel and terminate the cloudflared process.
+
+        This is called automatically when the process exits (via atexit),
+        but you can call it explicitly for earlier cleanup.
+        """
+        from synth_ai.core.integrations.cloudflare import stop_tunnel
+
+        if self.process:
+            stop_tunnel(self.process)
+            self.process = None
+            log_info(
+                "TunneledLocalAPI.close: tunnel closed",
+                ctx={"hostname": self.hostname, "backend": self.backend.value},
+            )
+
+    def __enter__(self) -> "TunneledLocalAPI":
+        """Context manager entry (for sync use after async creation)."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Context manager exit - closes tunnel."""
+        self.close()
+
+
+__all__ = ["TunneledLocalAPI", "TunnelBackend"]